Cerebro 🧠

Persistent code-knowledge memory across AI chat sessions.

Every new chat re-analyzes your project's folders from scratch to understand it, burning tokens re-discovering what a previous chat already learned. Cerebro caches the understanding — not just the files — in a small SQLite "brain" that lives outside the chat. New sessions query it instead of re-reading folders.

Instead of reading 50 files (~100k tokens) to understand a project, the model makes one cerebro_map() call (~2-3k tokens) plus a few targeted lookups.

How it works

Three layers of "traces", cheapest first:

1. Structural map (free, no LLM) — tree-sitter extracts symbols + imports and builds a dependency graph. Imports resolve both relative paths and tsconfig / jsconfig path aliases (@/...), so Next.js / NestJS monorepos get real edges. PageRank ranks the most important modules. Each file is hashed so changes are detectable. Languages: Python, JavaScript / TypeScript (incl. JSX/TSX) and Dart / Flutter.
2. Cached summaries (the big saver) — as a chat understands a file, it calls cerebro_record(path, summary) to store a 1-3 sentence English summary (English tokenizes ~15-30% cheaper than Spanish). Future sessions reuse it.
3. Freshness — each summary is tied to the file's hash. If the file changed, the trace is flagged stale so only that file gets re-read.

Why not Dijkstra? Code knowledge is a relevance problem, not a shortest-path one. The useful algorithms are graph traversal (BFS/DFS, for impact) and centrality (PageRank, for ranking) — not weighted routing.

MCP tools

Tool	Purpose
cerebro_map(top=30)	Cheap project overview, modules ranked by centrality. Call first.
cerebro_get(path)	Summary + symbols + dependencies of a file, without reading it.
cerebro_search(query)	Hybrid semantic + keyword search; semantic hits resolve to the exact symbol (path:line), not just the file.
cerebro_record(path, summary)	Leave a trace: store your understanding of a file.
cerebro_note(content, topic?)	Record a decision / domain rule / gotcha (the why).
cerebro_recall(query?)	Recall decisions recorded by past sessions.
cerebro_stale()	Files changed since last index + stale summaries.
cerebro_sync()	Catch branch switch / git pull / external edits and reindex them.
cerebro_reindex(paths?)	Refresh the structural index (only changed files).
cerebro_impact(path)	Transitive blast radius: everything that (in)directly imports a file.
cerebro_cycles()	Circular-import groups (architecture smell).
cerebro_orphans(prefix?)	Code files nothing imports — dead-code candidates (file-level).
cerebro_dead_symbols(prefix?)	Unused-export candidates: functions/classes/methods referenced nowhere in their own project, inside files that are imported (symbol-level dead code).
cerebro_callers(name)	Call sites of a symbol (who calls it, with enclosing fn + line).
cerebro_calls(path)	Internal functions a file calls (outgoing call edges).

Install

One command (published on PyPI) — add the MCP server to Claude Code:

claude mcp add cerebro -- uvx cerebro-code-memory

Or install the full Claude Code plugin (MCP server + session hooks + cerebro-first subagents):

/plugin marketplace add marcodavidd020/cerebro-code-memory
/plugin install cerebro@cerebro

Requires Python ≥ 3.10. Point Cerebro at a repo with CEREBRO_ROOT=/path/to/repo; it also auto-detects the nearest ancestor .cerebro/ brain (handy in monorepos).

Quick start

One command onboards any repo — it indexes and prints the exact registration line:

uv tool install --from . cerebro          # installs the `cerebro` command globally (dev)
cd /path/to/your/repo
cerebro setup --summarize --embed          # index (+ warm summaries / semantic index), then prints next steps

cerebro setup is idempotent. Then run the claude mcp add … line it prints, reload your editor, and the cerebro_* tools are available in chat.

Unified CLI

cerebro                 # no args -> MCP server (stdio); this is what the registration runs
cerebro setup           # index this repo + print MCP registration
cerebro index [--force] # build/refresh the index
cerebro search <query>  # hybrid semantic + keyword search
cerebro map             # project overview
cerebro graph           # interactive dependency-graph HTML
cerebro obsidian        # export an Obsidian vault
cerebro summarize / embed
cerebro impact / cycles / orphans / callers / calls / recall
cerebro doc-audit <vault>   # living docs: flag knowledge notes whose referenced code changed

Living documentation (doc-audit)

cerebro doc-audit <markdown-vault> cross-checks a curated knowledge vault against the code index: it parses each note's code references (path:line, backticked symbols) and the note's ultima_verificacion/fecha, then flags notes whose referenced files changed after they were verified, moved/were deleted, or mention a symbol that no longer exists. --aliases maps wiki app names to repo dirs (backend_app=fenix-store-backend,…); --fix patches stale notes' frontmatter to estado: revisar. This is the bridge between an auto-fresh code index and a human-curated wiki — documentation that can't silently rot.

cerebro doc-refresh <note> closes the loop: it re-audits one stale note against the live code and prints a briefing — current symbols, summary and dependents for each reference, plus the new location of any moved file — exactly the context an agent needs to propose the update (self-healing docs, human-reviewed).

Without a global install, prefix any command with uv run (e.g. uv run cerebro setup).

Point Cerebro at a specific repo with CEREBRO_ROOT=/path/to/repo. It honors .gitignore plus an optional .cerebroignore (same syntax) for excluding heavy non-source dirs (backup/, **/uploads/, …) without touching your VCS config. node_modules/, .next/, dist/, build/ are ignored by default.

Works on monorepos: index the whole thing at once (a single brain at the root, with cross-package alias resolution) or per sub-app (CEREBRO_ROOT per package).

Register with Claude Code

claude mcp add cerebro -- uv --directory /path/to/cerebro run cerebro

Set CEREBRO_ROOT to the project you want the brain to cover. See plugin/ for the optional Claude Code plugin that auto-injects the map at session start and flags edited files as stale.

Scope (MVP)

In: structural map, cached summaries, freshness, keyword search, tsconfig/jsconfig alias resolution, .cerebroignore, batch summary warming (cerebro-summarize, via headless claude -p — no API key), a decision log (cerebro_note / cerebro_recall, surfaced at session start), and git-aware freshness (cerebro_sync catches branch switch / pull / external edits across nested repos), and optional local semantic search (cerebro-embed + --extra semantic: model2vec embeddings — one vector per symbol — no torch, no API key, nothing leaves the machine — cerebro_search becomes hybrid semantic + keyword and lands on the exact symbol (path:line), not just the file), and visualizations (cerebro-graph → self-contained interactive HTML dependency graph; cerebro-export-obsidian → an Obsidian vault where imports are [[links]]), and architecture insights (cerebro_impact transitive blast radius, cerebro_cycles circular imports, cerebro_orphans dead-code candidates), and a symbol-level call graph (cerebro_callers / cerebro_calls, tree-sitter name-resolved). Deferred to v2: a live file watcher, and LSP-backed call graph for type-precise resolution (the current call graph resolves by name).

License

MIT © 2026 Marco Toledo — see LICENSE.