Brain — cited answers from your governed knowledge base

Ask your knowledge brain a question and get an answer grounded in your governed

corpus, where every claim carries a qmd:// citation. The brain does not paraphrase

from memory — it retrieves governed memories and cites them, so any answer is

verifiable after the fact.

Overview

This is the read surface of the Governed Second Brain: your files are compiled into

governed memories, governed by deterministic code, and retrieved with citations

by qmd. The brain_search MCP tool fronts that retrieval. The job here is to turn a

natural-language question into a cited answer — and to refuse to answer beyond what the

citations support.

Prerequisites

• The governed-second-brain plugin is installed, which auto-wires the local

governed-brain MCP server.

• qmd is on your PATH (the local retrieval engine). Search runs in-process

against your local ~/.teamkb index — no network, no API key, no token.

Instructions

Step 1: Search the governed corpus

Call brain_search with the user's question as query. Keep scope at its

default (curated) unless the user explicitly asks for inbox/archived material —

curated is the governed, promoted knowledge.

brain_search({ query: "the user's question, lightly cleaned up", scope: "curated" })

The tool returns { source, results: [{ citation, snippet, score, collection }] }.

Each citation is a qmd://COLLECTION/FILENAME URI — the receipt for that hit.

Step 2: Answer ONLY from the cited results

• Synthesize a direct answer from the returned snippets.
• Attach the qmd:// citation to every claim, inline — for example:

The proxy reverse-proxies the API (qmd://kb-curated/system-map.md).

• If two hits conflict, surface both with their citations rather than silently

picking one — the governance layer tracks contradictions; do not paper over them.

• Do not add knowledge the citations do not support. Any reasoning beyond the

corpus must be labeled clearly as inference, not the brain's answer.

Step 3: Handle an empty result honestly

If results is empty, say so plainly: the brain has nothing governed on that topic.

Do not fall back to general knowledge and present it as the brain's answer.

Optionally note that the topic may need to be captured (run /brain-save).

Brain Save — write a fact into your brain (governed)

This is the write side of the brain. /brain reads; /brain-save writes. Use it to tell the brain

to remember a specific fact going forward — without re-running a full compile — or to retire a memory

that's no longer true.

Overview

The brain learns in two ways: a bulk compile ingests a whole corpus at once, and /brain-save

adds (or retires) a single item on demand. Either way, governance stays in code: this skill

captures a candidate, then runs the deterministic govern step (dedupe → policy → promotion) that

decides what actually gets stored — and writes a SHA-256 hash-chained audit event for the decision. You

are proposing an item for the brain to keep; the deterministic curator owns whether and how it lands.

Why this never auto-fires

disable-model-invocation: true means Claude will not trigger this from conversation — it runs only

when you explicitly type it. Writing to your durable brain is a deliberate act, not a chat side

effect. Everything here is local and single-user: there is no server, no token, no role — you own

the brain, and the only gate on a write is that you asked for it.

Prerequisites

• The governed-second-brain plugin is installed (it auto-wires the local governed-brain MCP server

with the capture + govern tools).

• qmd is on your PATH so the govern step can refresh the search index after a promotion. If qmd is

absent, capture + govern + the audit receipt still complete; only fresh-search visibility waits.

Instructions

Save a new fact (capture → govern)

1. Confirm it's worth keeping — "Would I benefit from finding this in 30 days?" Skip ephemeral

debugging steps, throwaway preferences, secrets, or anything already in a CLAUDE.md/README.

1. Pick a category: decision, pattern, convention, architecture, troubleshooting,

onboarding, or reference.

1. Call brain_capture with { title, content, category, filePaths? }. It appends the candidate to

the local spool (the model's proposal).

1. Call brain_govern to drain the spool through the deterministic pipeline (dedupe →

policy/secret-detection → promotion). It returns what was promoted, rejected, flagged, and

deduplicated, and writes the hash-chained audit event for each decision.

Retire an outdated memory

1. Find the memory's UUID