brain

name	brain
description	Answers questions about your own systems, notes, decisions, runbooks, and conventions from your governed knowledge brain, returning a qmd:// citation for every claim — receipts, not recall. Use when you want to know what your brain has captured about your own architecture, infrastructure, decisions, or conventions (e.g. "what does my system map say about the proxy", "why did I pick Apache-2.0", "what's my deploy runbook"). Trigger with "/brain", "ask the brain", "what do I know about", or "check my knowledge base".
allowed-tools	mcp__governed-brain__brain_search
version	1.2.0
author	Jeremy Longshore <[e-mail]>
license	Apache-2.0
compatibility	Designed for Claude Code; ships with the bobs-big-brain (governed-brain) plugin, which auto-wires the governed-brain MCP server. Works in both modes: local (in-process, needs qmd on PATH) and team (proxies to your team brain when TEAMKB_API_URL is set). Same brain_search either way.
tags	["brain","knowledge","search","citations","governance","local-first","team"]
argument-hint	[question]

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 Bob's Big Brain: your files are compiled into governed memories, governed by deterministic code, and retrieved with citations by Tobi's qmd (OSS). The brain_search MCP tool fronts that retrieval. Your product surround is INTKB govern + ICO compile + this plugin — not a fork of qmd.

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 bobs-big-brain / governed-brain plugin is installed (MCP governed-brain).
• Mode is automatic. In local mode (default) search runs in-process against your local ~/.teamkb index — no network, no API key; a compatible qmd binary must be available (prefer monorepo pin @tobilu/qmd via the Registrar / installer). Operators can use scripts/bbb-qmd from bobs-big-brain-registrar so XDG points at the team index, not personal ~/.cache/qmd. In team mode (TEAMKB_API_URL set) search proxies to the team brain. Every hit is a qmd:// citation.

Instructions

Step 1: Search the governed corpus

Retrieval is Tobi's qmd (BM25 keyword via the MCP). Prefer short keyword queries over full sentences.

1. Derive 1–4 distinctive nouns/verbs from the user question (drop what/why/how, articles, auxiliaries, prepositions).
2. Call brain_search with those keywords and scope: "curated" (default promoted knowledge).

brain_search({ query: "SOPS age secrets", scope: "curated" })

The tool returns { source, results: [{ citation, snippet, score, collection }] }. Each citation is a qmd://COLLECTION/FILENAME URI — the receipt for that hit.

Empty-result ladder (do not stop after one miss):

1. Keyword retry (curated): only if the first call was still a long natural-language sentence (you skipped deriving 1–4 keywords). Re-run with 1–4 keywords only. Skip this step when the first query was already keyword-style — do not re-call with the same tokens.
2. Scope retry (all): if curated is still empty, re-run the same keywords with scope: "all". Do not use inbox/archived unless the user asks.
3. Only after curated+keywords and all+keywords are empty → Step 3 (honest refuse).

brain_search({ query: "shipped week", scope: "curated" })
// if empty (keywords already used):
brain_search({ query: "shipped week", scope: "all" })

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 still empty after the empty-result ladder in Step 1, 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).

Output

1. A short, direct answer.
2. Each load-bearing claim followed by its qmd:// citation.
3. A closing Sources list of the distinct qmd:// URIs used.

Examples

Cited answer:

/brain what does my system map say about the proxy?

→ The proxy is the single ingress; it reverse-proxies each domain to its service
  and must be reloaded, not restarted, after edits (qmd://kb-curated/system-map.md).

Sources:
- qmd://kb-curated/system-map.md

Empty result (honest refusal):

/brain what is my refund policy?

→ The brain has nothing governed on a refund policy. I won't guess from general
  knowledge. If this should be in your brain, capture it with /brain-save.

Error Handling

Situation	Response
brain_search returns empty results	Run the empty-result ladder (keywords → scope all); only then refuse. Do not fabricate.
qmd missing / index empty	Retrieval degrades to empty. Tell operator: install @tobilu/qmd, run INTKB pnpm search-canary -- --heal or bbb-qmd status.
MCP tool unavailable	Plugin not enabled; install/enable bobs-big-brain / governed-brain.
User asks to write/capture	Out of scope here — direct them to /brain-save.

Guardrails

• Read-only. This skill never writes to the corpus — capture and governance live in /brain-save.
• Never invent a qmd:// URI. Cite only URIs returned by brain_search.
• Prefer fewer, well-cited claims over a broad answer that cannot be anchored.
• Do not conflate this product with IRSB / Moat / Scout (separate stack).
• Provenance ≠ truth. Promotion receipts record each memory's capture channel (or unattested) and an origin-token hash — that proves WHERE a capture came from, not that its content is true. An authenticated insider can still have saved poisoned content with a valid origin; weigh cited answers accordingly and rely on govern policy, human review, and supersession as the content-quality gates.

Resources

• Bob's Big Brain umbrella — stack map.
• bobs-big-brain-plugin — this plugin.
• bobs-big-brain-registrar — govern layer (Bob's Big Brain Registrar) + bbb-qmd.
• tobi/qmd (npm @tobilu/qmd) — retrieve engine (OSS; we pin, we do not fork).
• bobs-big-brain-compiler — compile layer (Bob's Big Brain Compiler).
• The write counterpart: the /brain-save skill (governed capture).