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. In local mode you own the brain outright — no server, token, or role; the only gate is

that you asked. In team mode the same deliberate-act rule holds, and the server additionally

enforces your role (a member proposes; an admin governs and retires).

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.

• Works in both modes. In local mode (default, no TEAMKBAPIURL) all the tools below run

in-process. In team mode (TEAMKBAPIURL set) the brain is governed centrally on the server:

you propose with brain_capture and the server disposes (govern runs server-side, so there

is no client braingovern); braintransition is exposed but admin-only (a member gets a clear

403); brainstatus and brainaudit_verify are not exposed in team mode. Use /brain to query.

Instructions

Save a new fact (capture → govern)

First, search the brain (search-before-save). Call brain_search with

{ query: "", scope: "all" } and summarize what the brain already knows

from the qmd:// hits. If the fact is already covered, stop and say so — don't duplicate it (the

inbox does not dedupe at intake; only promotion dedupes, so this pre-save search is what keeps the

inbox from piling up). An empty results list (e.g. qmd isn't on PATH, or the brain is empty)

means no known coverage — proceed to capture; it is not a block. Then capture only the

genuinely-new delta:

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?, sessionId?, learningIndex? }.

In team mode, SessionEnd/autocapture must pass sessionId + learningIndex (0..4) so each

learning is its own idempotency slot (re-distill of slot i collapses; slots stay distinct). For

one-off manual facts, omit both (id falls back to content). The team inbox does dedupe at

intake (id-first, then content-hash) — pre-save search still reduces noise. Local mode still

spool-captures as before.

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 (via /brain search or brain_status).
2. Call brain_transition with { memoryId, to, reason, actor }. Valid moves:

active → {deprecated, superseded, archived}, deprecated → {active, archived},

superseded → archived. Every transition writes a hash-chained audit event.

> Team mode: brain_transition is admin-only — a member token gets a clear 403 and nothing is

> applied. (In local mode you are always the owner, so it always works.)

Check brain health

Call brain_status to see counts by lifecycle state and recent rejection feedback before or after

a batch of saves.

Verify the receipts

Call brainauditverify to check the audit trail's integrity — the SHA-256 hash chain and the

external anchor log. It reports any tamper, including a silent rewrite of history that the chain alone

would miss (caught by cross-checking the anchored snapshots that govern commits to git). Use it whenever

you need to prove the record wasn't altered.

Output

• After a save: report what brain_govern returned — promoted vs. rejected vs. duplicate — and that the

decision was recorded in the audit chain.

• After a retire: report the new lifecycle state and confirm an audit event was written.
• After a status check: summarize counts by lifecycle state and any recent rejections.

Examples

Save a decision:

/brain-save I'm going Apache-2.0 across the stack so the public can self-host.

→ brain_capture({ title: "License: Apache-2.0 across the stack",
                  content: "...", category: "decision" })
→ brain_govern()
→ Promoted 1 (qmd://kb-decisions/license-apache-2-0.md); 0 rejected, 0 duplicate.
  Audit event written.

Retire a superseded memory:

/brain-save retire memory 9c2e… — superseded by the new deploy runbook.

→ brain_transition({ memoryId: "9c2e…", to: "archived",
                     reason: "Superseded by the new deploy runbook", actor: "me" })
→ Memory 9c2e… → archived; audit event written.

Error Handling

Guardrails

• Never save content containing secrets, tokens, or credentials.
• reason on a retire must be a real, human-readable justification — it lands in the permanent audit

trail.

• A govern rejection is the system working as designed, not a bug to work around.

Resources

• Bob's Big Brain — the stack and its governance thesis.
• The read counterpart: the /brain skill (cited queries).