brain-mcp
Copies Claude Code and Codex sessions before auto-deletion and answers with a hash-backed citation or an abstention.
- 81 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Hooks copy every session transcript to disk, and transcripts can hold secrets and private code.
- The server reads the Claude Code, Codex and Pi home directories and writes to `~/.brain`.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/brain-mcpDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Hooks copy every session transcript to disk, and transcripts can hold secrets and private code.
- The server reads the Claude Code, Codex and Pi home directories and writes to `~/.brain`.
This is third-party code. Review the repository files before installing.
What it does
brain-mcp writes agent session history to a local disk and serves it over MCP. Claude Code deletes session files older than `cleanupPeriodDays` (30 days by default) at startup, and the recorder copies them first: the whole session, including subagent transcripts and saved tool output. Copies live in `~/.brain/lake` as append-only files with a sha256 manifest, and search runs on a DuckDB index. Every hit arrives with a file, a line range and a hash, so an answer can be checked with `sed` and `shasum`. When nothing matches, the server says so and lists the sources it searched. `brain-mcp restore` puts a deleted session back so it can be resumed with `claude --resume`.
Who it is for. People who use Claude Code or Codex daily and do not want to lose old decisions, commands and discussions when history is purged.
Good fit when
- You are looking for how a failing migration was fixed six weeks ago, and Claude Code already deleted that session.
- You need a quote with line numbers and a hash that a colleague can verify without access to your database.
- You want to know which sessions the agent deleted over recent weeks and bring one back.
- One history should cover Claude Code, Codex and Pi, with no three separate archives.
Not a fit when
- Transcripts contain secrets and you are not ready to keep copies of them on disk.
- You need history synced across machines or a cloud backup without configuring it yourself.
- Your sessions are short and you never reopen them.
Example request
Search the recorded sessions for the failing migration discussion and show a quote with file, lines and hash.MCP
- Transport
- stdio
- Authentication
- not required
Limitations
The recorder stores full transcripts, and they include paths, code fragments and anything you pasted into a chat. Protect `~/.brain` the way you protect your home folder. During the first index build DuckDB downloads its full-text search extension once from its own extension repository. The package has no telemetry, no cloud and no HTTP client. `brain-mcp backup` copies data elsewhere, and restore works only through the CLI. The `unknown` status marks an unmeasured source and must not be read as healthy.
How to disable. Remove the plugin or MCP entry and clear the hooks with the command from the documentation. Delete the `~/.brain` directory with session copies separately once you no longer need it.
FAQ
Which MCP tools are there?
Seven: `brain_search` searches everything recorded, `brain_get` returns raw lines with hash verification, `brain_recent` shows recent activity, `brain_sessions` builds session cards per day, `brain_health` reports freshness and what agents deleted, and `brain_capture_status` shows whether capture is moving.
How do I bring back a deleted session?
Run `brain-mcp restore --list`, pick an id and run `brain-mcp restore <id>`. It writes the session back byte for byte and never overwrites differing files. The `--dry-run` and `--to <dir>` flags let you preview the result first.
Where does the recorder get sessions?
Claude Code is captured with Stop and SessionEnd hooks, while Codex and Pi are read by a poll every 60 seconds. The paths are `~/.claude/projects`, `~/.codex/sessions` and `~/.pi/agent/sessions`.
What if health shows unknown?
The status means the source was not measured. Run `brain-mcp doctor`: it reports capture state, freshness and whether the extension cache is present.
How do I back up the store?
`brain-mcp backup <dest>` syncs the lake and manifest to the destination and re-hashes sampled files there. The check can fail, and that is by design.
Discussion
No questions or reviews yet.
Related
MCP serversClaude History MCP indexes past Claude Code chats, extracts decisions and error fixes and injects project context
Long-term memory for Claude Code, Cursor and Codex: the agent saves decisions and finds them again in later sessions
Local search across your whole Claude Code session history: decisions, commands, variable values and code you already wrote, through 13 MCP tools
An MCP server that preserves Claude Code context between sessions: decisions, checkpoints and a file cache kept in local SQLite.
MemoMind MCP gives Claude Code project memory, with stored facts, events and conclusions visible in a local dashboard.
An MCP server that keeps project decisions in Redis or Valkey and brings them back in new sessions and after compaction.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| brain-mcp (this card) | no | not required | 81 | |
| Claude-Mem | no | 116,457 | saves observations from sessions and feeds them to new ones; brain-mcp keeps the original bytes and answers with a verifiable citation | |
| Episodic Memory | no | 499 | searches agent conversations by meaning; brain-mcp keeps byte-exact copies after auto-deletion and can restore sessions |
README in short
Install with `pipx` or `uvx`, then `brain-mcp install cc` adds the Claude Code hooks and a 60-second scheduler. The server runs over stdio with `brain-mcp serve`. A Claude Code plugin variant exists too.