Coding Agents — Knowledge That Compounds Across People

Someone works out why a thing is the way it is. Six weeks later a person on another team, who has never met them, opens that file — and has no way to know it was ever worked out. Neither does their agent, which proposes the approach that was already ruled out.

That is not a session-memory problem and a rules file does not fix it. A CLAUDE.md holds what you remembered to write, in your repo, for your agent: it does not cross people, it does not expire when the system changes, and it carries no source anyone can check. Your coding agent is, however, the best instrument for both halves of the actual fix — it is present at the second the knowledge is created, and it is the thing asking for it at the moment of the next change.

Your coding agent already has DocBrain's tools. The docbrain-mcp server (MIT, in crates/) gives Claude Code, Cursor, and any MCP-compatible editor twelve tools. These five are the ones this page's workflow uses; the full table is at the end:

Tool	Direction	What it does
docbrain_context	read	What the org already knows about the files you are about to change — decisions, caveats and constraints captured against those exact paths, with a warning first if any of it has since gone stale
docbrain_ask	read	Cited answers from your org's memory, in the editor
docbrain_suggest_capture	read	Checks whether documentation gaps exist for a file or function
docbrain_annotate	write	Files a knowledge fragment (a decision, fix, or caveat) tied to a file and line range
docbrain_commit_capture	write	Captures the why behind a change at commit time

Most teams wire these up and only ever use ask. The write path is where the leverage is: the moment your agent helps you fix something is the one moment the knowledge exists, is fresh, and costs nothing to keep. Sessions end, terminal scrollback dies, and the fix your agent found never reaches the teammate who hits the same error next month — unless the agent files it.

The missing piece is not a feature. It's standing instructions — and a skill that carries them, so nobody has to remember to write them.

Setup

Register the MCP server in your editor (Claude Code shown; Cursor and others use their equivalent MCP config):

claude mcp add docbrain \
  --env DOCBRAIN_API_KEY=db_sk_... \
  --env DOCBRAIN_SERVER_URL=https://docbrain.your-org.internal \
  -- docbrain-mcp

Use a scoped key

Give the agent a key with capture permission but nothing more. Write tools are permission-gated server-side — a read-only key can ask but cannot file captures.

Capturing Knowledge with Premises

When calling docbrain_annotate or docbrain_commit_capture, agents may include an optional premises array to link captured knowledge to verifiable facts about your codebase:

{
  "file_path": "src/handlers/payment.rs",
  "annotation": "This API expects a Stripe webhook signature in X-Stripe-Signature header...",
  "premises": [
    {
      "premise_type": "path",
      "expression": "src/config/stripe_keys.env"
    },
    {
      "premise_type": "path",
      "expression": "docs/webhook-integration.md"
    }
  ]
}

Premise Types (v1):

• path — A file path that must exist in a connected source. DocBrain monitors this path against your git sources' file listings (see PREMISE_MONITOR_ENABLED). If the path is verified at capture and later disappears, the annotation fires a premise.broken event. Paths never found at capture remain dormant — they do not alert.

Other Premise Types:

Other premise_type values are accepted and recorded but not currently validated. They remain in dormant state and never trigger alerts. This allows agents to encode additional premise types for future validation.

Malformed Premises:

If an array item is missing required fields (premise_type, expression) or has invalid types, it is skipped silently — the capture does not fail. This allows robust agent capture even if premise formatting is incorrect.

Commit captures declare theirs by listing the files:

docbrain_commit_capture records why a change was made. Every path in its file_paths list becomes a path premise on the server, so the capture is checked against the files it describes and is flagged when one of them moves or disappears — send the file list, or nothing will ever be able to tell whether the reasoning still holds. Its premises array is for what the reasoning rests on beyond the files the commit touched.

The skill

docbrain-capture is a Claude Code skill that does the write path for you. When a conversation has produced knowledge that is written nowhere — a decision and why, a fix that took digging, a caveat, a procedure (how we deploy, rotate, roll back, get access), how a system is actually wired — it:

1. checks DocBrain first (docbrain_context for the files concerned, or docbrain_ask), and offers an update instead of a duplicate when the knowledge already exists;
2. drafts one capture per fact in your team's words: what, why, how — the exact command, path, flag or value — anchored to the file and line range it concerns, with the premises it rests on declared (paths that must exist), so DocBrain can flag it the day one of them disappears;
3. shows the draft exactly as it will be sent and waits for your yes;
4. writes it with docbrain_annotate (or docbrain_commit_capture for the why of a commit) and reports what DocBrain answered: the capture's id and any warning — it is served at once.

It offers itself once, at a natural breakpoint, never mid-task, and a "no" ends it. Nothing leaves the session unapproved. It never captures secrets, tokens, hostnames from .env files, customer or personal names, logs or chatter.

Install it

For the whole team, from the repository you work in:

claude plugin marketplace add docbrain-ai/docbrain --scope project
claude plugin install docbrain@docbrain --scope project

The install asks for your DocBrain server URL and an API key with capture permission (docbrain token create --name "Claude Code" --role editor) and connects the MCP server for you — no .mcp.json to write; pass --config server_url=… --config api_key=… to answer without a prompt. Both commands write to .claude/settings.json — the marketplace under extraKnownMarketplaces, the plugin under enabledPlugins; commit that file and everyone who trusts the project has the skill; the key stays in each person's own keychain. Invoke it as /docbrain:docbrain-capture, or say "capture this", "write this down", "document how we did that".

Prefer a plain directory? Copy plugins/docbrain/skills/docbrain-capture into your repository's .claude/skills/ and invoke it as /docbrain-capture. The skill's template and three finished captures are in its resources/ directory.

What counts as adoption is not the number of captures but the number that later answer a question or get corrected by their premises — measure that, not volume.

The snippet

Without the skill (Cursor, other editors, or a team that prefers prose), add this to your project's CLAUDE.md (or global ~/.claude/CLAUDE.md):

## DocBrain
Before editing files you have not worked in before, call docbrain_context with
their repo-relative paths and read what comes back first. Pass bare paths —
`src/auth/session.rs`, not `src/auth/session.rs:42`.

When we resolve an error, discover non-obvious behavior, or make a decision a
future engineer would need, do this before the task ends:
1. Call docbrain_context for the files involved and read what is already
   recorded there.
2. If it is not there, draft a short capture — what broke, the fix, the trap
   to avoid — and show it to me for approval before calling docbrain_annotate.
Never include secrets, tokens, hostnames from .env files, or customer data in
a capture. When in doubt, leave it out.

If the docbrain tools are not available in this session, say so plainly and
stop there. Do not fall back to searching the repository and then report that
nothing is recorded — captured decisions do not live in the repo, so an
absent connector looks exactly like an empty knowledge base and is not one.

Cursor users: the same text goes in .cursor/rules/docbrain.mdc with alwaysApply: true.

Open the workspace at the folder that holds the config

MCP connector config is workspace-root scoped in every editor that reads it — .mcp.json, .vscode/mcp.json, .cursor/mcp.json are all found relative to the folder you opened, not to the file you are editing. Open a monorepo's parent directory instead of the service folder and the server never loads.

That failure is silent and it is worse than an error, which is why the last paragraph of the snippet exists. Observed: with the connector unloaded, an agent searched the repository, found no captured decisions there — correctly, they are not stored there — and answered "the org knows nothing about this file yet" about a file carrying a live pinned decision and an out-of-date warning. A missing connector reads as an empty knowledge base unless the agent is told to distinguish them.

Check before you rely on an answer: your editor's MCP panel should list docbrain and its tools. If it does not, you are looking at the wrong workspace root, not at an org that has recorded nothing.

What happens

1. Before your agent edits a file, it asks what the org already knows about it (docbrain_context). A caveat a teammate filed last quarter surfaces before the mistake, not in the post-mortem.
2. You and your agent fix something real.
3. The agent asks DocBrain whether that knowledge already exists (docbrain_context for the files involved — a lookup in the record, not a guess).
4. If the org doesn't have it, the agent drafts a capture and asks you first. You see exactly what leaves the machine.
5. A capture you approve is served at once, anchored to the file and line range it came from, and labelled with who wrote it and what checks it. One that declares a premise reads Checked against code: DocBrain re-verifies it against your codebase, flags it the moment it stops being true, and tells you once. One anchored to nothing checkable is served too, labelled Not checked against code, so every reader knows.

What a capture never holds

A capture is shared with everyone who can read its space, so DocBrain checks every capture for secrets before it is saved. Two checks run. A fixed check recognises the shapes of private keys, access tokens and API keys in published formats, connection strings and links with a password, signed links and long random-looking values, also through common encodings and tricks such as invisible characters, look-alike letters and spaced-out text, and together with your other captures from the last 24 hours. Then the language model your DocBrain is configured with reads the capture's text and lists any password, key or token written in it, including one written in plain words and values the text calls test, example or sample values. Write where a secret lives (${DB_PASSWORD}, <password>, "in the team vault") instead of a value. The capture's text is sent to that model's provider for this check.

If a capture you write holds a secret, it is not saved, and you are told what kind it looked like. After three of these in ten minutes, capturing pauses for ten minutes. When DocBrain writes a summary for you (from a chat thread or a CI run), it removes the secret, keeps the rest, and tells you what kind was removed.

If the model cannot be reached, a capture is saved after the fixed check and checked by the model as soon as it is back; if a secret is then found, the capture is withdrawn (a summary has the secret removed), the answers that used it are cleaned, and you are told. Until then it may be served. When the detection rules, the model or its instructions change, every existing capture is checked again. Every answer and reply is checked again for the fixed shapes just before it is sent; plain-word passwords are checked in captures, not in answers.

What we cannot promise: a secret described in words, a value deliberately disguised in small pieces, or a value deliberately split around a note can pass. Every capture says who wrote it, is visible only to its space, and can be withdrawn at once or erased by an admin. Never put a secret in a capture. If one was ever served, treat it as exposed and rotate it.

Refused or redacted

• A capture a person writes (the console, the CLI, docbrain_annotate, docbrain_commit_capture, docbrain_revise) is refused when it holds a secret: nothing is saved, and the reply names the kind of secret and the field it was in, never the value. Remove the value and send again, saying where the secret lives instead. Do not encode, split, space out or reword the value to get past the check. Repeated refusals count toward the pause.
• A summary DocBrain writes (a chat-thread capture, a CI run analysis) is redacted: the secret is replaced by a marker such as [removed: password], the rest is kept, and the person who asked is told the kind that was removed. These never pause anyone.

The model check

The second check uses your configured fast model. Each capture's text is sent to that model's provider; choose a local provider if capture text must not leave your network. The check's time budget is CAPTURE_SECRET_CHECK_TIMEOUT_SECS (default 10 seconds; see the configuration reference). A weaker model finds less: the fixed check does not depend on the model, the plain-word check does.

Custom secret rules

An admin can add a rule for a secret shape your organisation uses (Govern → Quality, rule type Secret Pattern).

• Dry run before save. A rule is checked before it can be saved: DocBrain shows how often it matches ordinary notes and existing captures, and refuses a rule that is invalid, too slow, or would refuse too many ordinary notes. The save goes through only after the admin has seen that check. The same applies to enabling or importing a rule.
• Second decision on what it withdrew. When a saved rule matches existing captures, they are withdrawn and wait for an admin's decision on that rule version ("Waiting for your decision"): Remove the values (Confirm) removes them for good — a capture a person wrote stays withdrawn without them, a summary DocBrain made is served again — or Restore these captures (Decline) serves them again as written. An admin can also confirm or restore a single capture from the captures list.
• Restored values are shown for that rule version. After a restore, the values that rule matched in the restored captures when the decision was made are no longer masked by it, in those captures and in the answers and sources served from them, for as long as the rule stays at that version (see the limits below).
• A new rule version checks again. Editing a rule makes a new version: every capture is checked again under it, and restorations made under the old version do not carry over.
• A person must decide. An admin key with no user behind it (a keyless key) cannot create, change, enable, delete or import a secret rule, and cannot confirm or restore what one withdrew; use a key created by a signed-in admin. Every decision names the admin who made it.

What DocBrain keeps of a finding

Never the secret. A finding is stored as a keyed fingerprint (HMAC-SHA256 under the deployment's fingerprint key), so someone holding the database or a backup cannot guess a short value from it. The key is generated on first start (Docker Compose: the docbrain-keys volume; Helm: its own Secret, kept on uninstall) unless you supply one, and is never stored in the database. Back it up, separately from the database backups: a lost or changed key reopens every restored or declined finding. See the fingerprint key.

Honest limits

• Detection recognises shapes and, through the model, written credentials. A secret described in words, a short value with nothing around it, or one deliberately disguised or split into pieces can pass.
• The model is not deterministic, and a weaker configured model detects less.
• While the model is unreachable or over budget, a capture is saved after the fixed check and may be served until the model checks it. Answers already given are cleaned when a secret is found, but replies already sent to chat, MCP clients and webhooks cannot be recalled.
• Answers are checked for the fixed shapes only; plain-word passwords are checked in captures, not in answers.
• Ingested documents keep their secrets at their source; DocBrain removes recognised secrets from what it serves, and the source system is where they must be removed.
• Links are not followed: a link to a paste or file share that holds a secret is served as a link.
• A restore covers less than everything: it exempts only the values present when the admin decided (a value found later at the same rule version stays masked); the question as stored and shown keeps [removed: …]; copies DocBrain wrote itself (summaries) stay redacted; and passages DocBrain joins from references are checked without the exemption. Each of these masks more, never less.
• What contains these limits: a capture is visible only to its space, says who wrote it, and can be withdrawn at once or erased by an admin. If a secret was ever served, treat it as exposed and rotate it.

All twelve tools

The five above are the ones this page's workflow uses. The MCP server declares twelve; the rest are the same capabilities the API and CLI expose, reachable from the editor. Direction is read unless marked write — write tools require editor role or above, and the server refuses them below that.

Tool	Direction	What it does
docbrain_context	read	What the organization already knows about the files you are about to change — decisions, caveats and constraints against those exact paths, with a stale-knowledge warning first
docbrain_ask	read	Ask a question about your organization's knowledge; cited answer, or an honest "not in the record"
docbrain_incident	read	Incident-mode search — prioritises runbooks, past incident resolutions, on-call procedures and troubleshooting guides over general documentation
docbrain_suggest_capture	read	Whether a documentation gap exists for a file or function, before you write a capture nobody needs
docbrain_freshness	read	Freshness report — which documentation has gone stale, and how stale
docbrain_autopilot_gaps	read	Documentation gaps Autopilot has detected and clustered from unanswered questions
docbrain_autopilot_summary	read	Autopilot status: total, open and critical gaps, drafts generated, drafts published
docbrain_feedback	read	Submit feedback on an answer. Read-direction because it changes no documentation — it feeds answer quality
docbrain_annotate	write	File a knowledge fragment — a decision, fix or caveat — tied to a file and line range
docbrain_commit_capture	write	Capture the why behind a change at commit time, grounded in the diff and the commit message
docbrain_revise	write	Edit or withdraw a capture you recorded (its id comes from docbrain_context); a summary DocBrain wrote can only be withdrawn
docbrain_autopilot_generate	write	Generate a documentation draft for a specific gap cluster. Routes to human review; nothing publishes unattended

Nothing here can change your source systems. There is no tool that edits a Confluence page, closes a ticket or posts to a channel — the write tools write knowledge fragments into DocBrain's own corpus and nowhere else.

Privacy properties

• Nothing is automatic. The agent proposes; the person who did the work approves every capture, visibly, in the session. No admin queue stands between that yes and the answer.
• The session never uploads. Only the approved capture crosses the wire — not your transcript, not your code, not your prompts.
• The client is auditable. Every line of code that touches your session is MIT-licensed in crates/docbrain-mcp.
• Captures are attributed and falsifiable. Every capture says who wrote its words — Recorded by , or Summarised by DocBrain from for a summary DocBrain wrote — and what checks it, derived by the server, never from anything the client claims. Its author can edit or withdraw it at any time (delete only until it has been used), an admin can erase it, and a key with no user cannot write one.

Honest limitations

Agents follow standing instructions probabilistically — some sessions will forget to check. Treat the snippet as a habit-builder, not a guarantee: teams that also mention it in code review ("did the agent capture this?") see far higher capture rates. If your editor supports session-end hooks, a one-line reminder hook makes the check near-deterministic.