Brain Ask

Two commands that both produce a composed artifact rather than a list of hits: brain ask writes one cited answer, brain audio writes a two-host script (and optionally synthesizes it). Both are grounded strictly in the user's own corpus, and both require a local Ollama.

ask vs search vs graph

Reach for the manual search-then-read loop in consult-brain when you need raw documents in your context — voice mimicry, verbatim quoting, drafting. Reach for brain ask when the deliverable is the answer itself and the user wants to see where each claim came from.

recall vs ask — who does the reading

Both are bounded; they differ in where the reading happens.

• brain ask does the reading on local Ollama and returns one composed answer (~1–2k tokens). The source text never enters your context. Choose it when the answer is the deliverable and you don't need the raw prose.
• brain recall --budget N puts the passages themselves in your context, packed to fit within N tokens with [N] citations. Choose it when you must reason over, quote, or write from the actual wording — ask's synthesis would have already thrown that away.

Rule of thumb: if you would have followed ask with "now show me the source", you wanted recall. If the chat model (Ollama) is down, ask exits non-zero. If only the embedder is down, ask, brain search and brain recall all fall back to text-only matching and say so (ask prints Retrieval: text-only under the answer and "fallback": "fts_only" in --json; recall's header ends , text-only). They are the fallback, not a brain show loop. brain recall shares every filter with brain search; the full cost-ordered table lives in consult-brain, which is the one place it is maintained.

consult-brain also documents these two commands as part of its own workflow; that is deliberate overlap, not a conflict. Use this skill when synthesis is the point of the request.

brain ask

brain ask "what tradeoffs did we weigh on the retention policy"
brain ask "how did the migration plan change" --explain
brain ask "what is my position on on-call rotation" --no-loop
brain ask "who owns the ingest pipeline" --mode fuse -n 8
brain ask "summarize the pricing debate" --max-iter 2 --json

Default to plain brain ask. Add --explain when the user questions how an answer was reached, and --no-loop when they want speed over coverage. The three graph-backed modes (auto, fuse, local) need the Apache AGE image and a built graph; on a plain install, stay on hybrid.

Reading the citations

The answer carries inline [N] markers, each mapping to one of the user's documents. Two rules:

• Never restate a claim the answer did not cite. An uncited sentence is the model's connective tissue, not something the corpus says. Do not promote it to a fact in your reply.
• Always offer the underlying document. When the user pushes on a specific [N], hand them brain show <id> (see consult-brain) rather than re-summarizing what you already summarized.

An answer that says "the corpus does not cover this" is a correct answer. Do not re-run with broader flags until something appears — that manufactures confidence the documents do not support.

brain audio

brain audio --person "Jordan Alvarez"
brain audio --topic "platform migration" --turns 12
brain audio --topic "hiring" --out /tmp/hiring-overview
brain audio --person "Jordan Alvarez" --tts 'shell:/path/to/tts.sh'
brain audio --topic "pricing" --json

Exactly one of --person or --topic is required:

• --person builds a themes overview (graph themes mode).
• --topic builds a community-level overview (graph global mode) and needs brain graphrag communities build to have run first.

--turns caps the dialogue (positive even integer). --out sets the artifact base path, defaulting under $BRAIN_HOME/audio/. --tts synthesizes audio through a pluggable backend spec. --json prints the script and writes no files at all.

The .json and .md artifacts are written before TTS runs, so a failing TTS backend still leaves the script behind.

When it fails

brain ask exits non-zero rather than returning a partial answer. That is deliberate — a half-retrieved synthesis reads exactly like a complete one. Treat a non-zero exit as "no answer", never as "try harder".

Safety rules

• Only snippets reach the LLM in ask, and only entity names plus document summaries in audio — never full bodies. Do not work around that by pasting document bodies into a prompt yourself.
• brain audio artifacts land in the gitignored audio/ directory. Never commit them. They are generated, personal, and often large; they do not belong in version control under any circumstance.
• brain audio writes files by default. Use --json when the user only wants to read the script, and confirm before pointing --out anywhere outside the default directory.
• There is no MCP tool for brain audio — it is CLI-only. Do not claim otherwise or invent a tool name for it.
• Never present a brain ask answer as your own reasoning. It is a synthesis over the user's documents; say so, and keep the citations attached when you relay it.
• Both commands are read-only against the corpus. Neither ingests, edits, nor deletes anything, so a failed run never needs cleanup.