Give your agents a knowledge base
Eight steps, start to finish: connect an agent, teach it to orient before it writes, publish each of the three shapes, revise without rewriting, and keep the vocabulary from fragmenting. If you want the argument for why rather than the procedure for how, read the agent memory page first.
From zero to a working knowledge base
Steps one and two are setup and take a couple of minutes. Step three is the habit that decides whether any of the rest is worth having. Four through six are the three shapes; seven and eight are the upkeep.
01Install the plugin
Two commands. The first adds the marketplace, the second installs the knowledge-base plugin.
claude plugin marketplace add GitianDocs/gitian-tools
claude plugin install gitian-kb@gitian-toolsTwo siblings live in the same marketplace and are installed the same way: gitian-docs keeps your annotations and paired docs in sync as you change code, and gitian-spec makes a spec request land as a knowledge-base doc instead of a loose markdown file. Install whichever you want — they share one connection.
02Connect, in your browser
Nothing to paste. The first tool call answers with a 401 carrying discovery metadata; your client registers itself, opens a browser tab, and you approve access there. From then on the token is managed for you.
To confirm it worked, ask your agent to search the knowledge base. An empty result is a successful connection — you haven't published anything yet.
If you are wiring this into CI, there is no browser to consent in, so mint a personal access token in Settings instead. It is shown once, prefixed gkb_, and only its hash is stored.
claude mcp add --transport http gitian https://gitian.dev/api/mcp \
--header "Authorization: Bearer gkb_…"03Orient before you write
The single habit that decides whether your knowledge base stays useful: read before publishing. An agent that publishes first creates a near-duplicate of something you already have, under a slightly different slug, with slightly different words.
So at the start of real work, have the agent search for the topic at hand, look at what relates to the best hit, and read the live vocabulary before it links or invents a topic. When the work is tied to a repository, it should also check which in-flight plans have already claimed the paths it is about to touch.
The plugin does most of this for you. A session hook preloads the repo, branch, and date, and advisory nudges fire when a session looks like it's about to publish without having oriented.
04Publish your first memory
A memory is one atomic, durable fact worth surviving across sessions. Name it by what it states, not where it came from: ci-flaky-oauth-token, never note-1 or tuesday-findings. The slug is the retrieval key, so a vague one is a lost memory.
Four types keep them sortable: user for who you are and how you work, feedback for guidance you have given the agent, project for facts about the work that aren't derivable from the code, and reference for pointers to things that live elsewhere.
Keep the body to the fact and why it matters. If you find yourself writing sections, you wanted a doc.
05Publish a doc with a real manifest
A doc is a long-form artifact with a lifecycle: a spec, plan, design, handoff, or recap. What makes it worth more than a markdown file is the manifest: status and impl_status for where it stands, files for the paths it will touch, commits for what landed, plus next_steps and blockers.
Fill those in honestly, including the empty ones. A null renders as an em dash rather than a hidden row, so a manifest full of dashes is visible as an unfinished manifest. That's the point.
Declaring files does real work beyond documentation: those paths become file intents, and the next agent that publishes a plan overlapping them gets told, by path, which plan it is colliding with.
Never omit the summary. It is what search results, relatedness panels, and the next agent's orientation sweep all read first.
06Keep a journal entry as you go
An entry is a dated running record for a scope. It is not a summary written at the end of the day. Append to it as meaningful things happen, including the pivots: the approach you abandoned is usually more valuable to the next session than the one that worked.
One entry exists per scope and date, and the slug is derived rather than supplied. Appending is safe under concurrency: the write re-reads and re-merges if two agents land at once, and list fields merge rather than replace, so nothing already written is dropped.
07Revise without rewriting
Nothing is ever overwritten. Publishing the same slug with changed content appends a revision and leaves the previous one readable; publishing identical content is a genuine no-op and burns no revision. Deleting is a tombstone, and republishing the slug brings it back.
When only the manifest changes, such as a status flip or an added commit, change only the manifest. Re-sending an entire long body to edit one field is how bodies get truncated, and it is the one failure mode this system takes seriously: a shrink measured against the previous revision is warned about, and a large one is rejected outright unless you say the replacement was deliberate.
Deleting is rarer than it looks. A superseded doc is usually better served by a status change and a pointer to what replaced it, because the reasoning that got abandoned is still reasoning.
08Curate the vocabulary
Topics are how anything gets found later. Link one to three primary topics for what an item is about, and secondary ones for what it merely touches. Read the live vocabulary first and prefer an existing topic over a new one — a near-synonym costs you the connection you were trying to make.
A novel slug mints itself immediately as organic and is live in relatedness right away. That's deliberate: there is no approval queue standing between an agent and a useful link. Your job is the review pass — promote the ones that earned it to curated, veto the ones that didn't, and merge the synonyms. A merge is one reversible alias row; nothing is rewritten and nothing is deleted.
Every response carries a vocabulary revision counter. When it changes, something was minted, promoted, vetoed, or merged. Re-read the vocabulary before the next publish. When it hasn't moved, skip the read.
What not to publish
A knowledge base that records everything is as useless as one that records nothing, because the signal drowns. Four things do not belong in it:
| the code | Anything the repository already states: structure, call graphs, what a function does. Read the code; it is more accurate than a description of it. |
|---|---|
| git history | What changed and when. The log has it, with authorship and diffs you can't reproduce in prose. |
| the conversation | Facts that only matter inside one session. If it won't be true or useful next week, it isn't a memory. |
| the summary | A restatement of a doc you already published. Revise that doc instead: update over create. |
What does belong: the decision and the reasoning behind it, the constraint you discovered the hard way, the approach you rejected and why, and the fact that took three days to learn and would take three days to learn again.
Where to go next
The agent memory page covers the model in depth — relatedness math, freshness decay, provenance classes, and what happens when several agents write at once. The MCP server page covers the wire: transport, the response envelope, the OAuth contract, and the tool families. For the other half of gitian, the annotation reference covers the syntax you put in code comments.