{ "markdown": "\n\n# brain-mcp — the recorder for your AI conversations\n\n**Your AI history is being deleted right now.** Claude Code deletes session files older\nthan `cleanupPeriodDays` (default **30**) at startup. Run this and see your own cliff edge:\n\n```bash\n# macOS\nfind ~/.claude/projects -name '*.jsonl' -exec stat -f '%Sm %N' -t '%Y-%m-%d' {} + | sort | head -3\n# Linux\nfind ~/.claude/projects -name '*.jsonl' -printf '%TY-%Tm-%Td %p\\n' | sort | head -3\n```\n\nThe oldest date you see is where your history ends. brain-mcp records it before it goes —\nbyte-exact, content-hashed, locally — and makes it queryable with citations you can verify\nwith `sed` and `shasum`.\n\n## Install\n\n```bash\npipx install brain-mcp --pre # or: uvx brain-mcp\nbrain-mcp install cc # CC hooks + 60-second scheduler\nbrain-mcp serve # the MCP server (stdio) — add to your client config\n```\n\nOr as a Claude Code plugin (hooks + server in one step):\n\n```\n/plugin marketplace add mordechaipotash/brain-marketplace\n/plugin install brain\n```\n\n## What it does\n\n- **Captures at source.** Claude Code via Stop/SessionEnd hooks (line-deltas + a final\n snapshot); Codex and Pi via a 60-second poll-scan. One spool, one floor.\n- **Keeps the bytes.** The floor is `~/.brain/lake//.jsonl` — append-only,\n byte-identical to the original, with an append-only sha256 manifest. Nothing is parsed\n and discarded; the DuckDB index is a cache, fully re-derivable from the lake.\n- **Cites or abstains.** Every search hit carries `{file, line span, sha256}` — checkable\n by anyone with `sed -n 'A,Bp' file | shasum -a 256`, no database required. Zero hits\n return an explicit abstention naming the lanes and dates actually searched.\n- **Reports health honestly.** `fresh` = the floor holds everything the agent's files show;\n `stale` = the agent has content the recorder missed; **`unknown` = unmeasured, not\n healthy** — never folded into \"looks fine\".\n- **Backs up verifiably.** `brain-mcp backup ` syncs lake+manifest and re-hashes\n sampled files at the destination. The verify can fail; that is the point.\n- **Zero network calls at runtime.** No telemetry, no cloud, no accounts. Verify it:\n there is no httpx/requests import in this package.\n\n## The 7 MCP tools\n\n| tool | what |\n|---|---|\n| `brain_search` | BM25 over everything recorded; cited hits or an explicit abstention |\n| `brain_get` | the raw lines behind a citation, with sha verification |\n| `brain_recent` | time-ordered recent activity, every row cited |\n| `brain_sessions` | session cards per day/agent |\n| `brain_health` | per-lane origin-vs-floor freshness; unknown ≠ healthy |\n| `brain_capture_status` | is the machinery itself moving (spool, heartbeats, floor) |\n| `brain_backup` | verified backup; writes only outside the floor |\n\n## 🤖 For AI Assistants\n\n*You're reading this because your human runs THE RECORDER and gave you access to their\nAI history. This is the honesty contract.*\n\n**The one rule: everything you state from these tools is either CITED or ABSTAINED —\nthere is no third state.** A cited claim carries a checkable pointer (file + line span +\nsha256); verify it with `brain_get(expect_sha256=...)` before building on it. An\nabstention means \"not found above threshold in the lanes and dates the tool measured\" —\nit does NOT mean \"it never happened\". Never fill an abstention with your own guess.\n\n- Present recall as their words, dated: *\"On 2026-08-19 you wrote: '…' (sess-7f2a.jsonl:412)\"* —\n never as your own knowledge. One claim, one citation.\n- `verified: false` from brain_get means the floor changed since indexing. Say so plainly.\n- A health response containing any `unknown` lane is never \"everything looks fine\".\n The honest sentence is: \"2 lanes fresh, 1 stale, 1 unmeasured.\"\n- \"What do I think about X\" → `brain_search(query, role=\"user\")`. \"How did my thinking\n evolve\" → add `order=\"time_asc\"` and read the citations in time order. The server has\n no opinion about your human's mind; it has their words, with receipts.\n\n## The floor format\n\n```\n~/.brain/\n spool// hooks + scanner write here (atomic, dot-tmp invisible)\n lake//.jsonl THE FLOOR: append-only, byte-identical to the origin;\n a rewrite opens .g2.jsonl — old kept, never deleted\n manifest/manifest.jsonl one versioned line per chunk: byte range, line range, sha256\n offsets// hook fast-path line counters\n health/*.last_run side-effect heartbeats (mtimes are the proof, never a report)\n brain.duckdb the index — a cache, re-derivable from lake/ + manifest/\n```\n\nWhere your agents keep their transcripts: Claude Code `~/.claude/projects/**/*.jsonl`\n(rolling window!), Codex `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`, Pi\n`~/.pi/agent/sessions/**/*.jsonl`.\n\n## Other verbs\n\n```bash\nbrain-mcp record # one capture tick (the scheduler runs this every 60s)\nbrain-mcp health [--exit-nonzero-on-stale] # cron-able\nbrain-mcp doctor # capture status + health summary\nbrain-mcp redact --lines A B --reason \"...\" # tombstone a secret; audited in manifest\nbrain-mcp migrate-v1 # import v1 data (marked v1_derived)\nbrain-mcp uninstall # removes hooks + scheduler; your floor is KEPT\n```\n\n## v1 → v2\n\nv2 is a rebuild around one principle: **capture the bytes first; derive everything else.**\nv1 parsed conversations into a parquet and discarded the originals — v2's floor makes that\nstructurally impossible. v1's 25 tools became 7: the synthesis tools (\"cognitive patterns\",\n\"switching cost\") are gone because a claim that can't carry a line-span citation isn't one\nthis server makes. Migration: `brain-mcp migrate-v1` — v1 rows are kept, marked as derived,\nand floor-backed rows win wherever the source still exists.\n\nWindows: out of scope for v2.0. Scheduling is LaunchAgent (macOS) / systemd user timer (Linux).\n\nMIT.\n", "bytes": 6073, "sha": "2c0c98de34a3120c8888248feac0ce6fc7d5e9a7f5ce469551fee7667e4f6da8", "repo_slug": "mordechaipotash/brain-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_mordechaipotash_brain_mcp_19d841bd/readme" }