Related Pages

Related topics: System Architecture & Data Flow, Claude Code Plugin, Agents & Common Failure Modes

Introduction & Installation

What is Cerebro

Cerebro is a local Model Context Protocol (MCP) server that gives an AI coding assistant persistent memory of a codebase. Instead of re-reading folders every time a new chat session begins, the assistant queries a pre-built, local SQLite "brain" that contains the project's structure, file summaries, and previously captured notes. The result is cheaper context and faster, more grounded answers across sessions.

The tool is distributed as the Python package cerebro-code-memory and ships with a CLI plus an MCP server entry point. Versioning follows semantic versioning; the latest tracked release is v0.2.2, which fixed a summarizer that could save stderr-style hook output as a real file summary. Source: pyproject.toml:1-40

Cerebro is designed to be 100% local: the brain lives on the user's machine, no remote service is required, and the tool integrates with Claude Code as an MCP provider.

Core Capabilities

The product is organized around three behaviors, all visible in the CLI surface in cli.py:

• Summarize — produce compact, structured summaries of files so future sessions can skip reading them line-by-line. Source: src/cerebro/cli.py:1-120
• Query / serve — expose the cached brain to an MCP-capable client so the assistant can look up files, summaries, and notes on demand. Source: src/cerebro/mcp_server.py:1-80
• Auto-record (since v0.2.0) — a SessionEnd hook re-summarizes files that went stale during the session, opted into via CEREBRO_AUTORECORD=N. Source: src/cerebro/cli.py:120-200

A newer convenience flag, cerebro summarize --stale, was introduced alongside auto-record to let users refresh only the files whose cached summary is out of date. The release notes for v0.2.0 also describe polyrepo auto-detect, where the brain location is resolved by walking up parent directories until a suitable root is found. Source: README.md:1-60

Installation

Prerequisites

• Python 3.9 or newer on the host (a v0.2.1 fix ensured the SessionEnd plugin no longer crashes under the system /usr/bin/python3 3.9.6, which rejected PEP 604 str | None syntax without from __future__ import annotations). Source: pyproject.toml:10-30
• An MCP-capable client such as Claude Code.
• Optional: uv/uvx for zero-install execution.

Install via uvx (recommended)

The fastest path is to register the MCP server with Claude Code directly, which pulls and runs the package on demand:

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

This is the one-liner shown in the project's release notes. Source: README.md:20-40

Install from PyPI

If you prefer a managed install:

pip install cerebro-code-memory

This installs the cerebro console script defined in pyproject.toml, which dispatches to cerebro.cli:main. Source: src/cerebro/cli.py:1-40

Install from source

For contributors or users who want the latest unreleased changes:

git clone https://github.com/marcodavidd020/cerebro-code-memory
cd cerebro-code-memory
pip install -e .

The -e flag installs in editable mode so source edits take effect immediately.

First-Run Setup

After installation, initialize a brain for the current project. From inside a checkout of any codebase:

cerebro init
cerebro summarize

cerebro init writes a brain file at the location resolved by paths.py, which walks up parent directories to support monorepos and polyrepo layouts introduced in v0.2.0. cerebro summarize then populates file summaries that future sessions will reuse. Source: src/cerebro/paths.py:1-60

Optional environment variables that change runtime behavior:

Configuration values are loaded centrally so CLI, server, and hooks see consistent state. Source: src/cerebro/config.py:1-80

Verifying the Install

To confirm the MCP server registers with Claude Code:

claude mcp list

You should see cerebro listed alongside its uvx cerebro-code-memory command. To smoke-test the brain itself, run cerebro status which reports the brain path, the number of files indexed, and the staleness of each summary. Source: src/cerebro/cli.py:40-120

Architecture at a Glance

flowchart LR
  User[User / Claude Code] -->|MCP request| Server[cerebro mcp_server]
  Server --> Brain[(SQLite brain on disk)]
  CLI[cerebro CLI] -->|summarize / init| Brain
  Hook[SessionEnd hook] -->|auto-record stale| Brain
  Server -->|context snippets| User

The CLI populates the brain; the MCP server reads from it; the optional SessionEnd hook keeps it fresh. Everything funnels through the same storage abstraction defined in the package's __init__. Source: src/cerebro/__init__.py:1-30

When Things Go Wrong

Two failure modes have appeared in recent releases and are worth noting during installation:

• Hook crashes on old Python (v0.2.1): if a SessionEnd hook fails to import because the interpreter is too old, the plugin silently disables itself. Upgrading Python or using uvx (which provisions a modern interpreter) resolves it.
• Garbage summaries from misbehaving hooks (v0.2.2): a third-party hook that emits text to stdout on exit could be captured verbatim as a file summary. The fix added a _is_valid_summary() validator that rejects empty or hook-banner output before persisting. Source: src/cerebro/mcp_server.py:80-160

If summaries look wrong after upgrading, re-running cerebro summarize --stale refreshes only the affected entries.

Next Steps

With Cerebro installed and a brain initialized, the recommended reading order is:

1. The CLI Reference page for the full set of cerebro subcommands and flags.
2. The Brain & Storage page for the SQLite schema and paths.py resolution rules.
3. The MCP Tools page for the tools exposed to Claude Code and example queries.

Together these cover everything needed to operate Cerebro in a single-repo or polyrepo workflow.

Related Pages

Related topics: Introduction & Installation, Core Features & MCP Tools

System Architecture & Data Flow

Cerebro is an MCP (Model Context Protocol) server that provides persistent code-knowledge memory across AI chat sessions. It caches a codebase's structure and accumulated understanding into a local SQLite "brain", so a new session can query prior knowledge instead of re-reading folders. The design is intentionally token-cheap and 100% local, with no network round-trips for storage. (v0.1.0)

High-Level Architecture

The system is organized as a small set of cooperating modules around one SQLite store:

• MCP entry point – exposes Cerebro's tools to the host (Claude Code) over the Model Context Protocol.
• Indexer (indexer.py) – walks the project tree and records structured facts about files.
• Summarizer (summarizer.py) – produces a free-text summary per file by invoking headless claude -p.
• Database layer (db.py) – owns the SQLite schema and all CRUD helpers.
• Graph modules (graph.py, callgraph.py, tsconfig.py, gitsync.py) – enrich the brain with structural data (import edges, TS path aliases, remote sync metadata).
• CLI (cli.py) – exposes maintenance commands such as cerebro summarize --stale.
• SessionEnd hook (hooks/cerebro-session-end.py) – runs after each Claude session to keep the brain fresh.

Source: src/cerebro/db.py:1-50 Source: src/cerebro/indexer.py:1-50 Source: src/cerebro/cli.py:1-80 Source: src/cerebro/hooks/cerebro-session-end.py:1-40

Core Data Flow

Cerebro has two complementary paths: a build path (write to the brain) and a query path (read from the brain during a chat). The build path is driven by the indexer, the summarizer, and the SessionEnd hook; the query path is driven by MCP tool calls.

flowchart LR
    A[Project tree] --> B[indexer.py]
    B --> C[(SQLite brain<br/>db.py)]
    S[headless claude -p] --> D[summarizer.py]
    D --> C
    H[SessionEnd hook] --> D
    H --> C
    M[MCP client] -->|tool call| E[MCP server]
    E --> C
    C -->|rows + summaries| M

Key invariants of this flow:

• The summarizer is the only writer of free-text file summaries, and summarize_one() now validates every output via _is_valid_summary() so that hook-error blocks (for example from a misbehaving UserPromptSubmit hook like claude-mem) cannot be saved verbatim as a file's summary. (v0.2.2)
• Stale summaries are detected by comparing the file's on-disk state against what is recorded in the brain; cerebro summarize --stale re-summarizes only those. (v0.2.0)
• Auto-record is opt-in: when CEREBRO_AUTORECORD=N is set, the SessionEnd hook will re-summarize stale files so the next session reuses fresh traces; otherwise the brain is fully manual. (v0.2.0)

Source: src/cerebro/summarizer.py:1-120 Source: src/cerebro/db.py:50-220 Source: src/cerebro/cli.py:80-200

Persistence Model

The brain is a single SQLite file resolved relative to the project root. Cerebro supports polyrepo layouts by walking up from the current working directory until it finds an existing brain or an obvious project marker, so a single repo never accidentally splits the store across subfolders. (v0.2.0)

The on-disk model is intentionally narrow:

• One row per tracked file, keyed by a repository-relative path.
• Columns capture the path, a content fingerprint (hash), language hints, a last-seen timestamp, and the LLM-generated summary.
• A "stale" derivation is computed on demand from the file's current fingerprint vs. the stored one, rather than maintained as a separate queue table.

The graph/callgraph, tsconfig, and gitsync modules sit on top of this file table. They read the file rows and write derived edges (imports, call sites, TS aliases, sync state) without duplicating source text, keeping the canonical store compact and single-sourced.

Source: src/cerebro/db.py:50-320 Source: src/cerebro/graph.py:1-120 Source: src/cerebro/callgraph.py:1-120 Source: src/cerebro/tsconfig.py:1-120 Source: src/cerebro/gitsync.py:1-120

Session Lifecycle Integration

Cerebro ships a Claude Code plugin hook (cerebro-session-end.py) that fires when a chat session ends. The hook triggers the auto-record path, re-summarizing any files whose summary went stale during the session so the next session reuses fresh traces instead of re-reading. (v0.2.0)

A known historical pitfall: the hook used PEP 604 union syntax (str | None) without from __future__ import annotations, which crashed at import under Python 3.9.6 (the system /usr/bin/python3) with TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'. (v0.2.1) Because the hook runs outside the project's venv, it must remain compatible with whatever interpreter Claude Code invokes — a constraint worth remembering when modifying it.

Source: src/cerebro/hooks/cerebro-session-end.py:1-60

Known Sharp Edges

• Hook output pollution: before v0.2.2, if another UserPromptSubmit hook printed a block notice to stdout and exited 0, that text was captured as the file's summary. _is_valid_summary() now rejects such garbage output. (v0.2.2)
• Brain resolution in polyrepos: walking up directories means a nested repo will share the nearest ancestor's brain. This is by design for polyrepo setups, but can surprise users who expect per-folder isolation. (v0.2.0)
• Auto-record is opt-in: by default, summaries do not refresh at session end; users must explicitly set CEREBRO_AUTORECORD=N (counter-intuitively the non-default) to enable it. (v0.2.0)
• Local-only by contract: the design is 100% local and token-cheap, so any feature that would require remote storage or large context re-ingestion is intentionally out of scope. (v0.1.0)

Related Pages

Related topics: System Architecture & Data Flow, Claude Code Plugin, Agents & Common Failure Modes

Core Features & MCP Tools

cerebro-code-memory is an MCP (Model Context Protocol) server that gives AI chat sessions persistent, local, token-cheap memory of a codebase. Instead of re-reading files every session, an assistant queries a pre-built SQLite "brain" containing structural snapshots, summaries, embeddings, and curated insights. This page covers the core MCP tools exposed to clients and the underlying subsystems that power them.

Server Architecture and Tool Surface

The MCP server is registered with clients (e.g., Claude Code) through the standard MCP install command and runs entirely locally:

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

Source: README (v0.1.0 release notes)

server.py is the entry point that registers tool handlers and dispatches requests to the data and analysis layers. Each tool corresponds to a method on the MCP server, which in turn delegates to specialized modules such as summarizer.py, summaries.py, embeddings.py, and insights.py. Source: src/cerebro/server.py.

The tool surface is intentionally narrow and read-mostly, designed to be cheap to call from a chat session:

Source: src/cerebro/apiroutes.py, src/cerebro/summaries.py, src/cerebro/insights.py, src/cerebro/embeddings.py, src/cerebro/summarizer.py.

Reading Tools: Querying the Brain

Read-side tools are designed so a session can recover context with a single round-trip.

• Structure lookups resolve a file path within the active repository. Since v0.2.0 the brain is resolved by walking up from the current working directory until a known marker is found, so monorepos and nested git worktrees are supported without configuration. Source: v0.2.0 release notes.
• Summary lookups return the cached natural-language summary for a file. If no summary exists the server can either return a "stale / missing" marker or trigger the summarizer, depending on configuration. Source: src/cerebro/summaries.py.
• Insight lookups return developer-authored notes (intent, gotchas, invariants) attached to files or symbols. These are written manually or via tooling and persisted in the same SQLite database. Source: src/cerebro/insights.py.
• Embedding search returns the top-k files whose stored embedding is closest to a query embedding. This is the primary mechanism for "find code that does X" queries without scanning directories. Source: src/cerebro/embeddings.py.

Because all reads hit SQLite, the round-trip cost is dominated by embedding similarity computation, not filesystem traversal — the core token-saving claim of the project.

Writing Tools: Summarization and Staleness

The only substantive write path is summarize, implemented in summarizer.py. It shells out to headless Claude to produce a per-file summary, then stores it through summaries.py.

cerebro summarize <path>          # summarize one file
cerebro summarize --stale         # re-summarize files whose summary is stale

Source: v0.2.0 release notes.

summarize_one() previously accepted any non-empty stdout from claude -p if the exit code was 0. In mixed-hook environments (for example, when another plugin's UserPromptSubmit hook fails), Claude can emit a block notice on stdout that then gets persisted verbatim as the file's summary. As of v0.2.2 the function gates results through a new _is_valid_summary() validator before writing, so a hook-error payload can no longer silently overwrite a real summary. Source: v0.2.2 release notes, src/cerebro/summarizer.py.

A summary is marked stale when the underlying file has changed since the summary was recorded. The SessionEnd hook, when enabled via CEREBRO_AUTORECORD=N, walks the set of files touched in the session and re-summarizes any that became stale, so the next session reuses fresh traces instead of re-reading. Source: v0.2.0 release notes, src/cerebro/summaries.py.

Plugin Hooks and Runtime Compatibility

Two Claude Code plugin hooks ship with the project: cerebro-session-end.py and the auto-record wiring. They must run on whatever Python the host invokes, which is not always the project's pinned interpreter. In v0.2.1 the SessionEnd hook crashed at import under the system /usr/bin/python3 (3.9.6) because it used PEP 604 union syntax (str | None) without from __future__ import annotations:

TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'

The fix was to add from __future__ import annotations (or equivalent) so the unions are evaluated lazily. This is now the canonical pattern for any new hook code so it works under Python 3.9 as well as 3.10+. Source: v0.2.1 release notes.

Data Flow Summary

The end-to-end flow for a typical "what does this file do?" query:

flowchart LR
    A[Chat session] -->|MCP tool call| B[server.py]
    B --> C[apiroutes.py]
    C --> D{summaries.py / insights.py / embeddings.py}
    D -->|SQLite brain| E[(Local SQLite)]
    E --> D --> C --> B --> A
    A -. SessionEnd .-> F[summarizer.py]
    F -->|claude -p + _is_valid_summary| D

Source: src/cerebro/server.py, src/cerebro/apiroutes.py, src/cerebro/summaries.py, src/cerebro/summarizer.py.

The split between read tools (server, apiroutes, summaries, insights, embeddings) and the single write tool (summarizer) is deliberate: it keeps the hot path cheap while still allowing the brain to self-heal at session boundaries.

Related Pages

Related topics: Introduction & Installation, Core Features & MCP Tools

Claude Code Plugin, Agents & Common Failure Modes

The cerebro-code-memory repository ships a Claude Code plugin that wires an MCP (Model Context Protocol) server and a set of lifecycle hooks into the host editor. This page documents the plugin layout, the role of each hook, the embedded agent-style entry points exposed to Claude, and the failure modes that have surfaced in the field (and how recent releases addressed them).

Plugin Layout and Manifest

The plugin is rooted under plugin/ and is split into three declarative manifests plus a hooks/ directory containing executable scripts.

The hooks.json file is the orchestration layer: it is the only file that knows which lifecycle event triggers which script, while the individual scripts remain focused on a single responsibility. Source: plugin/hooks/hooks.json.

Hooks and Their Lifecycle Role

Three hook scripts are shipped today:

• cerebro-first.py — Bound to SessionStart. It primes the brain for the upcoming session by loading any cached summaries that match the working tree so the first prompt already benefits from prior context.
• cerebro-session-end.py — Bound to SessionEnd. When CEREBRO_AUTORECORD is set to N, it re-summarizes files whose summary went stale during the session so the next session reuses fresh traces instead of re-reading the codebase.
• cerebro-mark-used.py — Bound to UserPromptSubmit. It marks which files were touched in the prompt, allowing later staleness checks to know what to refresh.

The hooks are intentionally thin: they shell out to the cerebro CLI rather than re-implement its logic, which keeps the plugin decoupled from the MCP server's storage internals. Source: plugin/hooks/cerebro-session-end.py, plugin/hooks/cerebro-first.py, plugin/hooks/cerebro-mark-used.py.

Agent Surface via the MCP Server

There is no separate "agent" binary in this repository. The agent surface is the set of tools the MCP server exposes, declared in plugin/.mcp.json and implemented inside src/cerebrum/. The plugin effectively turns Claude into a Cerebro-aware agent that can:

1. search the SQLite brain by symbol, path, or free-text summary.
2. read a stored summary without touching the filesystem.
3. record newly learned facts back into the brain.
4. summarize files (and, since 0.2.0, re-summarize stale files via --stale).

Because the tools are MCP-native, they are consumed identically whether Claude Code, the Claude CLI, or another MCP-compatible client invokes them.

Common Failure Modes

Three failure modes have been documented in the release notes and are worth anticipating when operating the plugin.

1. Hook crashes on Python <3.10

The cerebro-session-end.py hook uses PEP 604 union syntax (str | None). On systems where the hook is launched by /usr/bin/python3 (e.g. Python 3.9.6), the import fails with TypeError: unsupported operand type(s) for |: 'type' and 'NoneType', and the SessionEnd step silently dies. Release 0.2.1 added from __future__ import annotations to the hook so the annotations are evaluated lazily and the crash no longer occurs on 3.9. Source: plugin/hooks/cerebro-session-end.py.

2. Summaries poisoned by hook-error output

summarize_one() historically accepted any stdout that claude -p emitted on exit code 0. If another plugin's hook (notably a misbehaving UserPromptSubmit from claude-mem) wrote a block notice to stdout, that text was saved verbatim as a file summary, silently corrupting the brain. Release 0.2.2 introduced _is_valid_summary() in src/cerebrum/summarizer.py to reject such payloads before they are persisted. Source: src/cerebrum/summarizer.py.

3. Polyrepo brain resolution

For monorepos, cerebro walks up from the cwd to find the nearest brain. If the plugin's SessionStart hook is launched before that walk completes, cerebro-first.py may hydrate against a parent project instead of the active sub-project. The auto-detect added in 0.2.0 mitigates this by resolving the brain relative to the event's working directory rather than the shell's cwd at install time. Source: plugin/hooks/hooks.json.

Operational Recommendations

• Pin a Python ≥3.10 interpreter for hook execution when possible, or rely on the from __future__ import annotations guard shipped in 0.2.1.
• Keep CEREBRO_AUTORECORD opt-in; running auto-record in CI or in noisy multi-hook environments can compound the hook-error contamination described above.
• Treat _is_valid_summary() as a contract when adding new summarizer backends: any new path that bypasses validation can re-introduce the 0.2.2 bug.
• Audit hooks.json whenever a new hook script is added so lifecycle ordering (SessionStart → UserPromptSubmit → SessionEnd) remains intact; mis-ordered hooks break staleness tracking because cerebro-mark-used.py runs before the prompt is fully processed.

Doramagic Pitfall Log

Found 11 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Cerebro 0.1.0
• User impact: Upgrade or migration may change expected behavior: Cerebro 0.1.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Cerebro 0.1.0. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/marcodavidd020/cerebro-code-memory/releases/tag/v0.1.0

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Cerebro 0.2.0
• User impact: Upgrade or migration may change expected behavior: Cerebro 0.2.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Cerebro 0.2.0. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/marcodavidd020/cerebro-code-memory/releases/tag/v0.2.0

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/marcodavidd020/cerebro-code-memory

4. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/marcodavidd020/cerebro-code-memory

5. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Developers should check this runtime risk before relying on the project: Cerebro 0.2.1
• User impact: Upgrade or migration may change expected behavior: Cerebro 0.2.1
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Cerebro 0.2.1. Context: Observed when using python
• Evidence: failure_mode_cluster:github_release | https://github.com/marcodavidd020/cerebro-code-memory/releases/tag/v0.2.1

6. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/marcodavidd020/cerebro-code-memory

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/marcodavidd020/cerebro-code-memory

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/marcodavidd020/cerebro-code-memory

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/marcodavidd020/cerebro-code-memory

10. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/marcodavidd020/cerebro-code-memory

11. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: Developers should check this maintenance risk before relying on the project: v0.2.2
• User impact: Upgrade or migration may change expected behavior: v0.2.2
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.2.2. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/marcodavidd020/cerebro-code-memory/releases/tag/v0.2.2

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using cerebro-code-memory with real data or production workflows.

• v0.2.2 - github / github_release
• Cerebro 0.2.1 - github / github_release
• Cerebro 0.2.0 - github / github_release
• Cerebro 0.1.0 - github / github_release
• Configuration risk requires verification - GitHub / issue