using-terse-brain

name	using-terse-brain
description	Build and maintain a durable personal knowledge base ("brain") in a TERSE store. Use when the user asks about `terse-brain`, research wiki, llm-wiki, source-cited notes, or long-lived knowledge that compounds across sessions — not a scratchpad and not the generic `default` TERSE namespace.
metadata	{"openclaw":{"requires":{"bins":["terse-brain","terse-mcp"]}}}

Using terse-brain

terse-brain is a TERSE-native, single-operator knowledge base modelled on Andrej Karpathy's llm-wiki gist. Raw files stay on disk under raw/; you distill structure into # Wiki. Bookkeeping (index, log, schema, provenance) is typed TERSE instead of hand-edited markdown.

Critical: use the brain namespace

One MCP server (terse-mcp) can expose many namespaces — each is a different store file:

Namespace	Typical store	Purpose
default	~/.terse/state.terse	generic session state
memory	mapped memory store	durable agent memory (if installed)
brain	operator's brain.terse	this product — research wiki

Always pass namespace="brain" on terse_command / terse_info when working on the knowledge base. Never write wiki claims into default or memory.

If unsure which namespaces exist:

terse_info()

If brain is missing or errors as unmapped, tell the operator to run:

terse-brain wire --store /path/to/brain.terse
# or from the brain directory:
terse-brain wire

That command requires terse-mcp on PATH and is idempotent.

Iron rule: declarations are fire-and-forget

A TERSE declaration always succeeds when it parses. There are no partial application mysteries and no need to re-query "to confirm" what you just wrote.

• Do not attach a queries read-back after a successful ingest or fix batch. Trust the store.
• If the tool returns a syntax error, fix the declaration and resubmit. Parsable state that was already loaded remains loaded.
• Use queries only for discovery: answering a question, cold orientation, or recovery after an empty result. Never for write verification.

What lives in a brain

Four top-level containers, always:

• # Schema — node kinds, required attributes, status vocabulary, log-entry shape. Documentation you can query when unsure.
• # Raw — provenance only (sha256, size, kind, origin). Full document bytes live in the raw/ directory on disk — not as TERSE body text. CLI registers Raw; agents do not invent Raw dumps.
• # Wiki — LLM-owned distillation: ## Entities, ## Concepts, ## Claims, ## Synthesis.
• # Log — append-only journal (op:, when:, often ref: @Raw…).

There is no # Index — use ? [DEPTH 2; CONTAINERS] when discovering, not after every write.

Exemplar: how to find answers

When the user asks a research question against the brain:

1. Confirm the right store (once per session if needed)

terse_info()   # look for namespace "brain"

2. Orient only if cold — shallow map, not a full dump:

terse_command(
  namespace="brain",
  queries="? [DEPTH 2; CONTAINERS]"
)

3. Pull targeted facts (prefer narrow queries):

terse_command(
  namespace="brain",
  queries="""
? Wiki.Claims.* [WHERE Its.source]
? Wiki [CONTAINS "attention"]
? Wiki.Entities.Vashti [DEPTH 2]
? Raw [DEPTH 1]
"""
)

4. Answer in natural language with citations like @Raw.paper-name or @Wiki.Claims.…. Prefer claims and entities over re-reading entire raw files.

5. Optionally file the answer so the next session compounds (declarations only — no verify query):

terse_command(
  namespace="brain",
  declarations="""
# Wiki.Synthesis
## why attention scales badly(born: 2026-07-19; question: "why is attention quadratic?") [MERGED]
\"\"\"
…answer body citing @Wiki.Claims… and @Raw…\"\"\"

# Log
## 2026-07-19T15-00-00-000000(op: query; when: 2026-07-19; note: "filed synthesis") [LAST]
"""
)

Do not search namespace="default" for brain facts.

The four workflows

Everything brain-related runs through terse_command with namespace="brain". Prefer one call per turn.

1. Ingest — write once, trust the store

1. Operator (or you ask them): terse-brain register-source <file> — copies into raw/, writes # Raw + log (deterministic).
2. Read the source body from the raw file path / tool return.
3. Emit one batched declarations-only terse_command with namespace="brain". Leave queries empty.

# Wiki.Concepts
## attention(born: 2026-07-19) [MERGED]
"The mechanism that lets a model weigh which parts of its input matter."

# Wiki.Claims
## attention is quadratic(source: @Raw.transformers-paper; confidence: 0.95; born: 2026-07-19) [MERGED]
"Vanilla self-attention is O(n^2) in the sequence length."

# Log
## 2026-07-19T14-02-11-000000(op: ingest; ref: @Raw.transformers-paper; when: 2026-07-19) [LAST]

Contradictions: flag the older claim disputed in the same (or a later) declarations batch — still no verify query.

2. Query — see exemplar above

3. Lint — deterministic checks then agent fixes

1. Operator: terse-brain lint --format terse
2. Apply fix declarations on namespace="brain" (no verify query).

Code	Kind	Fix idiom
BRAIN-A	dangling-ref	Add missing node or remove bad @
BRAIN-B	orphan	Link concept or [REMOVED]
BRAIN-C	raw-drift	Operator / re-register source
BRAIN-D	log-integrity	Do not rewrite history; note entry
BRAIN-E	schema-violation	Add required attr with [MERGED]
BRAIN-F	unsourced-claim	Add source: @Raw.<name>

4. Recovery — empty result is a hint

• Wrong namespace? → terse_info(), then namespace="brain"
• Wrong path? → ? [DEPTH 2; CONTAINERS]
• Schema? → ? Schema [DEPTH 3]
• Recent ops? → ? Log [LAST 10]

Conventions

• namespace="brain" for all brain tools calls.
• Writes are trusted. No post-write query.
• Queries are for discovery / answers.
• Cite with @Raw.<name>. Lint enforces claim sources (BRAIN-F).
• Raw = files + thin provenance; Wiki = distillation.
• Status flags (disputed, superseded, stale), not silent deletes.

Diagram artifact (brain_diagram MCP tool)

When the operator wants a shareable / screenshot-ready view of the brain (or you need a visual deliverable):

Call the terse-brain MCP tool (not terse_command):

brain_diagram()
# or brain_diagram(store="/path/to/brain.terse", out="/path/to/out.html")

What it produces (be explicit with the user):

• An artifact-ready, self-contained HTML file (graph JSON embedded).
• Optional companion .json next to it.
• Open in any browser — no app server after generation.
• Needs network once for the force-graph CDN script.
• UI: Force (Obsidian-style) and Rings (Raw → Wiki layers).
• Snapshot at generation time — re-run after the brain changes.

CLI equivalent: terse-brain diagram --store … --out …

Do not invent a live graph by dumping the whole Wiki into chat.

Operator install (for agents to recommend)

pip install terse-mcp terse-brain
# host plugin (Claude/Grok/OpenClaw): install from terse-brain/plugin/
cd /path/to/my-brain
terse-brain init
terse-brain wire          # maps brain → ./brain.terse (needs terse-mcp)
terse-brain doctor        # verify

General TERSE syntax: MCP resources terse://spec/quickstart and terse://spec/full (from the terse MCP server).