Team knowledge and the code index

Added in 1.1.0. Not available in 1.0.0 — what changes on upgrade.

Knowledge is a team’s memory of the code: what was found out, why it was done this way and what to check next time. It is needed first of all by an AI agent, which otherwise starts from scratch every time, but a human sees it on the same screen - the Knowledge tab in the repository.

Records and drafts work in any edition. Only the team counter roll-up and the dead knowledge report (Pro) and the draft limit (Max) are paid.

What the tab shows

• Index - all knowledge of the repository: a fragment of the record, the declared surfacing mechanisms, and a “will not surface” marker on a record whose mechanism this server version does not support. Such a record comes back to life on its own after an upgrade, with nothing to rebuild.
• Drafts - immature records. A draft is visible to the whole team at once, before the branch is merged: otherwise one branch’s finding would never reach the next one. From there a batch is sent out - as files into the very branch it was written from.
• My counters - how many times a record was shown to you personally and how many times you opened it: “shown twelve times, never opened”. That is the proof that the memory works, and the first sign that it is dead.

How knowledge gets into the repository

A long-lived record lives as a file in .gitriver/knowledge/, while counters and drafts live in the database: a counter cannot be put into git, as every read would produce a commit.

Knowledge goes out as a batch and through an ordinary pull request - it has no approval flow of its own. Branch protection, CODEOWNERS and merge checks apply to it like to any other request. A record is scanned for secrets on intake.

What to write down. Whatever saves time next time: the reason behind a non-obvious decision, an environment pitfall, a procedure that cannot be derived from the code. A retelling of the code does not qualify - it is visible anyway, and memory nobody opens only gets in the way of finding what matters.

Dead knowledge report (Pro)

The team roll-up shows every record in the index, including one that was never shown - as a zero row. Otherwise the main disease of memory stays invisible: a record that never surfaced is simply absent from the show counters.

Dead knowledge is records that do not work. The report on the “By team” tab names not only them but also the reason:

Reason	What it means	What fixes it
Shown, not opened	The surfacing condition fires where the record is not needed. The most expensive disease: such a record spends the agent’s attention at every step	Rewrite the surfacing condition or retire the record
Cannot surface	This server version supports none of the declared mechanisms; the report names which ones are missing	Upgrade the instance - the record revives on its own
Never surfaced	The mechanism is supported, but its condition never occurred	Widen the condition or retire the record

The thresholds are stated in the report itself: a record counts as sick if it was shown at least three times without a single open, or it never surfaced in a week. Custom thresholds are set with min_shown and min_age_days.

---

Code index (Pro)

The Symbols tab answers three questions about the repository’s code: where a symbol is, what it calls and who calls it. The server builds the shared map of names once for the whole team, and it is available without cloning the repository.

This is not code search. Search answers “where does this string occur” and shows a declaration, a call and a word in a comment alike. The index answers about relations - “who will be broken by editing this function” - and search cannot give that answer.

Nor is it a replacement for an IDE. A call relation is stored by name, without type inference: “who calls push” will show calls of same-named methods of different types. For unique names the answer is precise, for short ones it is noisy. The index is valuable where there is no IDE: in the browser, when working through someone else’s repository, and for an AI agent that sees the repository through the API.

What the tab shows

Start typing a name - the search matches on the beginning of the name. For a found symbol you see its kind (function, method, struct, trait), the parent block and the path with a line number: the link goes straight into the code. Select a symbol and two lists appear next to it: what it calls (with repeat counts: a loop of fifty calls is one row with a counter) and who calls it.

When the answer carries a caveat

The index catches up with the tree on its own: it reconciles with the repository on read and computes the difference. If the catch-up did not finish, the answer is marked “the index is catching up with the tree” - an important difference from “nothing found”: the same question asked again will answer more fully. A separate “index incomplete” marker means the repository hit the index size limit and part of the code did not make it in.

Rust, Python, JavaScript and TypeScript are parsed. Files in other languages do not enter the index.