brain — the recorder
Records your Claude Code, Codex and Pi history before deletion. Cited-or-abstain recall.
Open source Open in the app JSON README (API)
About
Records your Claude Code, Codex and Pi history before deletion. Cited-or-abstain recall.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- mordechaipotash
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 2.0.0b3
- Stars
- 69
- Forks
- 16
- Open pull requests
- 3
- Last push
- 2026-08-20T11:31:17Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:50
- Updated
- 2026-08-29 04:00:50
- Origin id
io.github.mordechaipotash/brain-mcp
README
<!-- mcp-name: io.github.mordechaipotash/brain-mcp -->
# brain-mcp — the recorder for your AI conversations
**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:
```bash
# macOS
find ~/.claude/projects -name '*.jsonl' -exec stat -f '%Sm %N' -t '%Y-%m-%d' {} + | sort | head -3
# Linux
find ~/.claude/projects -name '*.jsonl' -printf '%TY-%Tm-%Td %p\n' | sort | head -3
```
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`.
## Install
```bash
pipx install brain-mcp --pre # or: uvx brain-mcp
brain-mcp install cc # CC hooks + 60-second scheduler
brain-mcp serve # the MCP server (stdio) — add to your client config
```
Or as a Claude Code plugin (hooks + server in one step):
```
/plugin marketplace add mordechaipotash/brain-marketplace
/plugin install brain
```
## What it does
- **Captures at source.** Claude Code via Stop/SessionEnd hooks (line-deltas + a final
snapshot); Codex and Pi via a 60-second poll-scan. One spool, one floor.
- **Keeps the bytes.** The floor is `~/.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.
- **Cites or abstains.** Every search hit carries `{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.
- **Reports health honestly.** `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".
- **Backs up verifiably.** `brain-mcp backup <dest>` syncs lake+manifest and re-hashes
sampled files at the destination. The verify can fail; that is the point.
- **Zero network calls at runtime.** No telemetry, no cloud, no accounts. Verify it:
there is no httpx/requests import in this package.
## The 7 MCP tools
| 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 |
## 🤖 For AI Assistants
*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.
- Present recall as their words, dated: *"On 2026-08-19 you wrote: '…' (sess-7f2a.jsonl:412)"* —
never as your own knowledge. One claim, one citation.
- `verified: false` from brain_get means the floor changed since indexing. Say so plainly.
- A health response containing any `unknown` lane is never "everything looks fine".
The honest sentence is: "2 lanes fresh, 1 stale, 1 unmeasured."
- "What do I think about X" → `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.
## The floor format
```
~/.brain/
spool/<lane>/ hooks + scanner write here (atomic, dot-tmp invisible)
lake/<lane>/<session>.jsonl THE FLOOR: append-only, byte-identical to the origin;
a rewrite opens <session>.g2.jsonl — old kept, never deleted
manifest/manifest.jsonl one versioned line per chunk: byte range, line range, sha256
offsets/<lane>/<session> hook fast-path line counters
health/*.last_run side-effect heartbeats (mtimes are the proof, never a report)
brain.duckdb the index — a cache, re-derivable from lake/ + manifest/
```
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`.
## Other verbs
```bash
brain-mcp record # one capture tick (the scheduler runs this every 60s)
brain-mcp health [--exit-nonzero-on-stale] # cron-able
brain-mcp doctor # capture status + health summary
brain-mcp redact <file> --lines A B --reason "..." # tombstone a secret; audited in manifest
brain-mcp migrate-v1 <all_conversations.parquet> # import v1 data (marked v1_derived)
brain-mcp uninstall # removes hooks + scheduler; your floor is KEPT
```
## v1 → v2
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.