The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Brain — the recorder listing page.
Your AI history is being deleted right now. Claude Code deletes session files older
than cleanupPeriodDays (default 30) at startup. Run this and see your own cliff edge:
The oldest date you see is where your history ends. brain-mcp records it before it goes —
byte-exact, content-hashed, locally — and makes it queryable with citations you can verify
with sed and shasum.
Or as a Claude Code plugin (hooks + server in one step):
~/.brain/lake/<lane>/<session>.jsonl — append-only,
byte-identical to the original, with an append-only sha256 manifest. Nothing is parsed
and discarded; the DuckDB index is a cache, fully re-derivable from the lake.{file, line span, sha256} — checkable
by anyone with sed -n 'A,Bp' file | shasum -a 256, no database required. Zero hits
return an explicit abstention naming the lanes and dates actually searched.fresh = the floor holds everything the agent's files show;
stale = the agent has content the recorder missed; unknown = unmeasured, not
healthy — never folded into "looks fine".brain-mcp backup <dest> syncs lake+manifest and re-hashes
sampled files at the destination. The verify can fail; that is the point.| tool | what |
|---|---|
brain_search | BM25 over everything recorded; cited hits or an explicit abstention |
brain_get | the raw lines behind a citation, with sha verification |
brain_recent | time-ordered recent activity, every row cited |
brain_sessions | session cards per day/agent |
brain_health | per-lane origin-vs-floor freshness; unknown ≠ healthy |
brain_capture_status | is the machinery itself moving (spool, heartbeats, floor) |
brain_backup | verified backup; writes only outside the floor |
You're reading this because your human runs THE RECORDER and gave you access to their AI history. This is the honesty contract.
The one rule: everything you state from these tools is either CITED or ABSTAINED —
there is no third state. A cited claim carries a checkable pointer (file + line span +
sha256); verify it with brain_get(expect_sha256=...) before building on it. An
abstention means "not found above threshold in the lanes and dates the tool measured" —
it does NOT mean "it never happened". Never fill an abstention with your own guess.
verified: false from brain_get means the floor changed since indexing. Say so plainly.unknown lane is never "everything looks fine".
The honest sentence is: "2 lanes fresh, 1 stale, 1 unmeasured."brain_search(query, role="user"). "How did my thinking
evolve" → add order="time_asc" and read the citations in time order. The server has
no opinion about your human's mind; it has their words, with receipts.Where your agents keep their transcripts: Claude Code ~/.claude/projects/**/*.jsonl
(rolling window!), Codex ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl, Pi
~/.pi/agent/sessions/**/*.jsonl.
v2 is a rebuild around one principle: capture the bytes first; derive everything else.
v1 parsed conversations into a parquet and discarded the originals — v2's floor makes that
structurally impossible. v1's 25 tools became 7: the synthesis tools ("cognitive patterns",
"switching cost") are gone because a claim that can't carry a line-span citation isn't one
this server makes. Migration: brain-mcp migrate-v1 — v1 rows are kept, marked as derived,
and floor-backed rows win wherever the source still exists.
Windows: out of scope for v2.0. Scheduling is LaunchAgent (macOS) / systemd user timer (Linux).
MIT.