brain-query

name	brain-query
description	Search and synthesize knowledge across all brain vaults. Use when the user asks to search the brain/knowledge base, find what they know about a topic, recall a decision/pattern/lesson, or run /brain-query.

Brain Query

Search and synthesize knowledge across all brain vaults.

Trigger

Activate when the user asks to:

• Search the brain/knowledge base
• Find what they know about a topic
• Recall a decision, pattern, or lesson
• Run /brain-query

Workflow

Service-first gate

First read ~/.brain/registry.yaml. If settings.local_brain_service is absent, ask the human which behavior they want, then write the selected setting before choosing the query path. The choices are: enable and configure the Docker service, keep local workflows with future setup suggestions, or keep local workflows without suggestions.

After the setting exists, check settings.local_brain_service.enabled. It must be boolean true; strings such as "true" or "false" do not enable service routing. If enabled, check whether the configured service is reachable with GET <base_url>/v1/status, using the token from settings.local_brain_service.api_token or from the configured api_token_env environment variable. Only use loopback URLs unless settings.local_brain_service.allow_remote: true is explicitly configured. Reject service URLs with credentials, query strings, fragments, or non-root paths. If enabled and reachable, use the service-backed semantic search path first: prefer the registered MCP tool brain_search when available and authorized, otherwise use POST <base_url>/v1/search/run from the host. This is the default brain-check path and uses the container-managed vector index when embeddings are enabled. Use brain_query or POST <base_url>/v1/query/run only for exact/read-only compatibility lookup when semantic search is unavailable, returns insufficient results, or the human explicitly asks for exact/raw lookup. Do not assume a Local Brain CLI is installed on PATH. Do not also perform the manual file-search workflow below for the same query unless the service is unavailable, returns insufficient results, or the human explicitly requests the non-service path.

If the service is disabled or not reachable, continue with the manual file-search workflow below. The Docker service is optional and absence of the service is not an error.

If service mode is disabled and settings.local_brain_service.suggest_setup is not false, you may briefly offer to configure the optional Docker stack when queries are repeated, broad, or would benefit from service-backed query/embedding/MCP support. Do not block the query if the human declines.

1. Load the registry (optional)

Try to read ~/.brain/registry.yaml. If the file is absent or empty, operate in store mode (registry-free): search the brain-owned knowledge store at ~/.brain/knowledge (layout: <scope>/<section>/<slug>.md where scope is common or a project slug and section is one of decisions, lessons, runbooks, context). index.md files at each level are Maps of Content (MOCs) that summarise the scope; read them for orientation but do not return them as matches.

When a registry IS present, resolve each vault with a .brain/manifest.yaml and use its index and knowledge paths as described below.

Default scope for store-mode search is active: articles with no status frontmatter, or with status: active or status: corroborated, are included. Articles with status: superseded, status: deprecated, status: historical, or any other value are excluded from the default scope.

2. Manual fallback search strategy (index-first, no vector DB)

Following Karpathy's insight: "I thought I had to reach for fancy RAG, but the LLM has been pretty good about auto-maintaining index files."

Step 1 — Index scan (registry mode): Read each vault's index file. Use the index to identify which knowledge articles are likely relevant to the query.

Step 1 — Store scan (store mode): Read ~/.brain/knowledge/index.md (global MOC) and the relevant <scope>/index.md files to identify likely articles.

Step 2 — Article read: Read the identified articles. Follow related links and vault:// URIs (registry mode) or relative paths (store mode) to find connected knowledge.

Step 3 — Capture search (always, regardless of mode): Search ~/.brain/capture/inbox/ and ~/.brain/capture/daily/ for raw captures that may contain relevant information not yet compiled into knowledge.

3. Synthesize and cite

Combine findings into a clear answer. Always cite sources:

Based on your knowledge base:

- [Topic X](vault://engineering/knowledge/k8s-networking.md): ...
- [Decision Y](vault://my-vault/knowledge/invoicing-workflow.md): ...
- [Raw capture](~/.brain/capture/daily/2026-04-05.md): ...

4. Optionally file the answer

If the synthesized answer is itself valuable knowledge (connects dots that weren't connected before), offer to file it as a new knowledge article via the brain-compile workflow.

Search tools

Use standard file tools — no special infrastructure needed:

• Grep: search file contents across vault knowledge directories
• Glob: find articles by filename patterns
• Read: read index files and articles

For vaults with many articles, read the index first to narrow the search before reading individual files.

Cross-vault queries

A query like "what do I know about Keycloak?" should search:

• engineering vault (infrastructure knowledge)
• work vault (customer implementations)
• my-vault vault (business operations)
• ~/.brain/capture/daily/ (recent uncategorized captures)

Use vault:// URIs in citations so the user can navigate to the source.

Important

• Always search across ALL vaults, not just the one matching cwd
• Cite sources — never present knowledge without attribution
• If nothing is found, say so clearly rather than hallucinating
• Prefer compiled knowledge articles over raw captures (higher signal)
• Suggest /brain-compile if relevant captures exist but haven't been compiled yet