The knowledge base

Every item is one of three kinds, each with a fixed shape, so an agent never has to invent a schema. A fact that took three days to learn is still a memory; a multi-day effort with a status is a doc even if its write-up is one paragraph.

Memory

One atomic fact worth keeping across sessions. The slug is how it is found, so name it by what it states: ci-flaky-oauth-token, never note-1. Its type is user, feedback, project or reference. Keep the body to the fact and why it matters.

Doc

A spec, plan, design, handoff or recap. Its manifest tracks status, impl_status, files, commits, next_steps and blockers; an empty field shows as a dash, so an unfinished manifest looks unfinished. The paths in files are recorded as intents: the next agent whose plan touches them is told which plan it overlaps. Always write a summary, because search results and related panels show it first.

Journal entry

A dated running record for a scope, one per scope and day, with a slug derived for you. Add to it as things happen, including the approach you dropped. Two agents adding at once do not lose each other's work.

What not to write

What the code or git history already says, what only mattered inside one session, and a summary of a doc you already have (revise the doc instead). Write the decision and its reasons, the constraint learned the hard way, and the approach you rejected and why.

Items link topics: topics for what an item is about (one to three) and mentions for what it only touches. Naming a new topic creates it on the spot, with no approval step, as a stub with no description. In the web app you describe the ones worth keeping, retire the ones that are not, and merge synonyms. A merge rewrites nothing and can be undone.

Two items are related by the topics they share, and rare topics count more than umbrella ones: a topic linked to nearly everything adds almost nothing. An explicit related entry or a [[wikilink]] in the body makes two items related at full strength. Relatedness is worked out when you ask, so an item published a moment ago is already connected.

Agents read the live vocabulary before naming a topic and prefer an existing one over a near-synonym. Every response carries vocab_rev; when it changes, the vocabulary changed.

Search runs full-text and meaning together, so a paraphrase finds an item that shares none of its words. Every write is embedded in the background. Where that is unavailable, or a knowledge base turns it off in Settings, search falls back to full-text alone, still best match first.

A search covers every knowledge base you can read and labels each hit with the one it came from. From a hit, an agent asks for its neighbours to see what relates to it.

• Nothing is overwritten. Publishing a changed item adds a revision and keeps the old one readable; publishing identical content changes nothing.
• Every revision records who wrote it. A shared item names who created it, who edited it last, and everyone who contributed.
• Any two adjacent revisions can be diffed in the web app.
• It survives /compact: compaction drops the conversation, not what was published.
• Retracting an item leaves its history; publishing the slug again brings it back. A retraction can redirect to the item that replaces it.

To change part of an item, agents patch it rather than resend it: patch_doc and patch_memory take the changed fields and a quoted edit to the body. A write states the revision it was based on (base_rev), so a change that landed in between is refused instead of overwritten. A body that shrinks against its last revision draws a warning, and a large cut is refused unless the agent says it was intended.

A category files an item under one tab in the web app; an item has at most one. Each category has a name and a short prompt that tells agents what belongs in it. Categories are never created automatically: you make them in the web app, or an agent does with publish_category. In an org knowledge base, only the org's admin can.

An item that names a category that does not exist yet keeps the name, with a warning, and is filed once the category is made.

Who can read and write which knowledge base is on Teams.