brain — the recorder — Claude Code MCP server: what it does
Records Claude, Codex and Pi sessions before cleanup deletes them, then makes them searchable with citations you can verify.
claude mcp add --env BRAIN_HOME=<BRAIN_HOME> --transport stdio brain-the-recorder -- uvx brain-mcpWhat brain — the recorder does
Claude wipes session files older than cleanupPeriodDays (default 30) at startup. brain-mcp gets there first: Stop and SessionEnd hooks write line-deltas plus a final snapshot, and a 60-second poll-scan sweeps the whole session folder, subagent transcripts, .meta.json and tool-results/ included. Codex and Pi land in the same spool through the scanner.
Everything goes to ~/.brain/lake/<lane>/<session>.jsonl — append-only, byte-identical to the origin, with an append-only sha256 manifest. The DuckDB index is a cache and can be rebuilt from the lake and manifest. Search returns BM25 hits carrying {file, line span, sha256}, checkable with sed and shasum; zero hits produce an explicit abstention naming the lanes and dates that were searched.
One thing to plan for: the package installs via pipx or uvx, and the first index build makes DuckDB download its full-text-search extension fts from DuckDB's own repository, cached under ~/.duckdb. On an air-gapped machine that fetch has to be arranged beforehand, or the index never gets built. There is no telemetry and no cloud in the package.
What it helps with
- restore a Claude session that cleanup already deleted
- find a past exchange with a citation you can verify by hash
- see exactly which sessions and files the agents removed
- back up the history with re-hashing at the destination
- tell fresh lanes apart from stale and unmeasured ones
Example prompts for the agent
- Search my history for what I wrote about the migration:
brain_search(query="migration", role="user") - Show me what the agents deleted with
brain_health - Restore a session:
brain-mcp restore --list, thenbrain-mcp restore <id>
How to install brain — the recorder
Platform CLI
claude mcp add --env BRAIN_HOME=<BRAIN_HOME> --transport stdio brain-the-recorder -- uvx brain-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from brain-mcp <command>
Platform CLI
codex mcp add brain-the-recorder --env BRAIN_HOME=<BRAIN_HOME> -- uvx brain-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from brain-mcp <command>
Config file
{
"mcpServers": {
"brain-the-recorder": {
"command": "uvx",
"args": [
"brain-mcp"
],
"env": {
"BRAIN_HOME": "<BRAIN_HOME>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from brain-mcp <command>
Config file
{
"servers": {
"brain-the-recorder": {
"type": "stdio",
"command": "uvx",
"args": [
"brain-mcp"
],
"env": {
"BRAIN_HOME": "<BRAIN_HOME>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from brain-mcp <command>
Platform CLI
gemini mcp add -e BRAIN_HOME=<BRAIN_HOME> brain-the-recorder uvx brain-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from brain-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about brain — the recorder
How do I install brain — the recorder in Claude Code?
As a plugin: run /plugin marketplace add mordechaipotash/brain-marketplace, then /plugin install brain. That sets up the hooks and the server in one step.
What does brain — the recorder do?
It captures Claude, Codex and Pi sessions before deletion, indexes them, and answers searches with citations verifiable by hash. It also reports what the agents removed and can write a session back.
What does it need to run?
Install the package with pipx or uvx. On the first index build DuckDB downloads its fts extension from DuckDB's repository and caches it under ~/.duckdb.
