Getting Team Knowledge Into a Shared Agent Layer
Capture knowledge where it is already produced rather than asking people to write it separately: decision records, pull request discussions, incident write-ups and existing documentation. Assign ownership per area, and give every entry a review date, because a shared layer fails from staleness long before it fails from search quality.
Why these projects stall
The technical half of a shared knowledge layer is well understood. Index documents, embed them, search them, return passages. It works.
The half that fails is upstream, and it fails the same way in most organisations.
Nobody writes things down. Not from laziness. Writing an explanation competes with shipping, and shipping wins every week. A system that requires a new writing habit is asking for the scarcest thing in the building.
What was written goes stale. A document describing last year's architecture is not neutral. It is worse than nothing, because it produces confident, well-cited, wrong answers, and the citation makes them harder to challenge.
Nobody owns any of it. Knowledge without an owner has no one responsible for noticing that it is now false.
The valuable material is in the wrong shape. The best knowledge in a company is in pull request discussions, incident retrospectives and decisions made in chat. It is unstructured, buried, and never written for retrieval.
Which reframes the problem. You are not building a search system. You are building a capture and maintenance system, and search is the part you get for free at the end.
Capture from what already exists
The reliable move is to stop asking for new writing and start indexing what people already produce as a byproduct of work.
Decision records. If a team writes them, they are the single highest value input: they contain the reasoning, the alternatives and the constraints, which is exactly what is absent from the code. If a team does not write them, a short template attached to the pull request that makes the decision is a smaller ask than a documentation practice.
Pull request discussions. Why a change was made, what was rejected in review, what the author was worried about. Already written, already dated, already attached to code.
Incident write-ups. What broke, why, and what was changed. Unusually high signal because they were written when the details mattered.
Existing documentation, with a bias toward recently touched files. Age is a usable proxy for reliability when nothing better exists.
Support and question threads. The recurring questions are precisely the queries the system will receive.
None of this requires anyone to write anything new. It requires connecting sources that already accumulate, which is a one-off engineering task rather than a permanent change to how people work.
Give every entry an owner and a review date
An owner is a name, not a team, because shared ownership of knowledge is the same as none. A review date turns staleness from an invisible condition into a scheduled item: when it passes, the entry is confirmed, corrected or removed. Entries whose date has expired should surface as a defect list, not as a quiet background concern, because that is the only mechanism that catches rot before it produces a wrong answer.
Shared, private, and the reason both are needed
Not everything should be visible to everyone, and pretending otherwise is what stalls adoption in most organisations.
Security procedures, unreleased work, customer specifics, compensation, anything under an agreement. If the only option is a fully shared pool, teams respond by not contributing the material that matters, and the layer fills with the harmless subset.
So the boundary has to exist in the system rather than in people's judgement. Some material is genuinely common to the organisation. Some belongs to one team. Some is personal working knowledge that should stay that way.
That separation is what RDK is built around: private chunks are encrypted and stay private, shared material is retrievable across a team, and stacked retrieval resolves most queries before a model is involved at all, so the common questions cost almost nothing and never leave the boundary they belong to.
The practical sequence, if you are starting: connect two sources that already exist rather than designing a taxonomy. Assign owners for the areas that produce the most repeated questions. Put review dates on everything from the first day, because retrofitting them is much harder than starting with them. Then measure which questions get asked and let that decide what to capture next.
The systems that survive are the ones where contribution is a byproduct and staleness is a visible defect. Search quality is the part that was never going to be the problem.
Frequently asked questions
- Why do shared knowledge systems for agents fail?
- Almost never on retrieval quality. They fail because nobody writes things down, because what was written goes stale, because no one owns any of it, and because the most valuable material sits in pull requests and incident write-ups rather than in documents.
- How do you get knowledge into the system without new process?
- Capture from artifacts people already produce: decision records, pull request discussions, incident write-ups, recently touched documentation and recurring support threads. This is a one-off engineering task rather than a permanent change to how people work.
- What makes stale knowledge worse than missing knowledge?
- A missing answer is obviously missing. A stale one produces a confident, well-cited, wrong answer, and the citation makes it harder to challenge. Give every entry an owner and a review date so expiry surfaces as a defect rather than as an invisible condition.
- Should all team knowledge be shared with every agent?
- No, and insisting on it is what stalls adoption. Security procedures, unreleased work, customer specifics and anything under agreement need to stay bounded. If the only option is a fully shared pool, teams contribute the harmless subset and withhold what matters.