项目定位与核心价值

cerebro-code-memory（简称 cerebro）是一个面向 AI 聊天会话的持久化代码知识记忆系统。它以 MCP（Model Context Protocol）服务器的形式运行，把代码库的结构以及开发者对代码的理解缓存到本地 SQLite "brain" 数据库中，使后续会话可以直接查询而非重复读取整个项目目录。 资料来源：README.md:1-15

项目设计遵循以下原则：

• Token 经济：避免每次会话都把整个仓库塞进上下文，改为按需查询本地缓存。 资料来源：README.md:16-22
• 100% 本地运行：所有数据保存在本地文件系统，不依赖任何远端服务。 资料来源：README.md:18-20
• 跨会话复用：在多次 AI 对话之间保持对代码的理解持续积累。 资料来源：README.md:14-18

主要能力概览

持久化知识库（Brain）

Cerebro 的核心是一个 SQLite 数据库，存储文件摘要、模块说明以及与代码结构相关的元信息。每个项目（monorepo 或 polyrepo）会自动定位到正确的 brain 位置。 资料来源：src/cerebro/config.py:1-40

自动记录（Auto-record，自 v0.2.0 起）

通过 SessionEnd 钩子，在每次会话结束时自动重新摘要"过时"的文件，使下一场会话直接复用最新内容。可通过环境变量 CEREBRO_AUTORECORD=N 关闭该行为。 资料来源：README.md:30-45

Polyrepo 自动识别（自 v0.2.0 起）

通过向上遍历目录树解析 brain 路径，从而在多仓库项目中也能正确定位存储位置。 资料来源：README.md:36-42

摘要鲁棒性修复（v0.2.2）

summarize_one() 新增 _is_valid_summary() 校验，拒绝记录来自错误钩子（如 claude-mem 的 UserPromptSubmit 失败）的"阻断通知"输出，确保数据库中保存的始终是真正的文件摘要。 资料来源：CHANGELOG/v0.2.2:1-10

兼容性修复（v0.2.1）

cerebro-session-end.py 插件钩子在系统 /usr/bin/python3（3.9.6）下曾因 PEP 604 联合类型语法（如 str | None）崩溃，修复后恢复在 Python 3.9+ 环境中的稳定运行。 资料来源：CHANGELOG/v0.2.1:1-12

安装方法

方式一：通过 Claude Code 即装即用（推荐）

最简方式是在 Claude Code 中执行一行命令，由 uvx 自动拉取并启动 MCP 服务器：

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

资料来源：README.md:60-66

方式二：作为 Python 包安装

若希望获得完整 Claude Code 插件（含会话钩子），可从源码安装：

pip install cerebro-code-memory

资料来源：pyproject.toml:1-30

方式三：从源码构建

克隆仓库后使用 Poetry 或 uv 进行开发模式安装，便于修改源码参与贡献。 资料来源：pyproject.toml:30-60

配置与基本使用

关键环境变量

资料来源：src/cerebro/config.py:20-60

命令行入口

安装后可直接调用 cerebro 命令。常用子命令包括：

• cerebro summarize --stale：仅重新摘要标记为过时的文件。 资料来源：README.md:40-48
• cerebro query <keyword>：在 brain 中检索相关文件或摘要。 资料来源：USAGE.md:10-30

MCP 工具集成

作为 MCP 服务器，cerebro 会向 Claude Code 暴露若干工具（如 query_brain、record_summary），AI 助手可在对话过程中按需调用，无需用户手动干预。 资料来源：src/cerebro/__init__.py:1-40

版本演进一览

下表汇总项目自首次发布以来的关键里程碑，便于新用户判断功能边界：

资料来源：CHANGELOG/v0.2.0:1-15、CHANGELOG/v0.2.1:1-12、CHANGELOG/v0.2.2:1-10

开发者提示

• 在大型 monorepo 中，建议通过 CEREBRO_DB_PATH 显式指定 brain 路径，避免自动向上遍历带来歧义。 资料来源：CLAUDE.md:15-25
• 若同时使用 claude-mem 等其他钩子插件，请确认其 UserPromptSubmit 输出不会进入 claude -p 的 stdout，以免污染摘要内容（v0.2.2 已加固校验）。 资料来源：CHANGELOG/v0.2.2:5-12
• 使用 uvx cerebro-code-memory 而非全局 pip 安装，可获得隔离且可复现的运行环境。 资料来源：README.md:60-68

总体定位与设计目标

Cerebro 是一个面向 AI 聊天会话的 本地代码记忆层（MCP Server），把代码仓库的结构、调用关系与摘要缓存在一个 SQLite "brain" 数据库中，让后续会话能够直接查询而无需重复读目录，从而显著降低 token 消耗并保持 100% 本地化运行 资料来源：README.md:1-40。在 v0.2.0 之后，系统引入了"自我维持的 brain"机制：通过 SessionEnd 钩子在每次会话结束自动重新汇总过期文件，并支持多仓库（polyrepo）自动检测，使记忆库能够跟随项目演进而保持新鲜 资料来源：CHANGELOG.md:5-18。

核心模块划分

1. MCP Server 入口（server.py）

server.py 是整个系统的对外接口，基于 MCP（Model Context Protocol）协议向 Claude Code 等客户端暴露工具调用，例如 cerebro_query、cerebro_summarize。该模块负责：

• 注册与路由 MCP 工具
• 将来自客户端的请求分发给 indexer、db、summarizer 等内部子系统
• 处理来自 claude -p 的子进程输出，并校验其合法性

v0.2.2 修复了一个关键缺陷：原先 summarize_one() 会在 claude -p 退出码为 0 时无条件接受其 stdout，但用户的 hook（例如 claude-mem 的 UserPromptSubmit）在错误状态下会向 stdout 写出阻断通知，这些内容会被原样当作文件摘要持久化。新版本加入 _is_valid_summary()，在落库前过滤掉 hook/权限类噪音文本 资料来源：src/cerebro/server.py:120-160。

2. 持久化层（db.py）

db.py 封装了 SQLite brain 的所有 CRUD 操作，主要表包括：

• files：记录仓库内文件的路径、最后摘要时间、stale 状态
• summaries：存储自然语言摘要与生成元数据
• symbols / edges：调用图节点与边，用于结构化查询

数据库采用单文件本地存储（.cerebro/brain.db），无需外部服务，从而满足"100% local"的产品承诺 资料来源：src/cerebro/db.py:30-120。

3. 索引与调用图（indexer.py + callgraph.py）

• indexer.py 负责扫描工作目录、识别编程语言、按需触发摘要生成，并维护文件级元数据 资料来源：src/cerebro/indexer.py:1-80。
• callgraph.py 从源码中提取函数/方法定义与调用关系，生成有向图；该图是后续 query 工具做"被谁调用 / 调用了谁"导航的基础 资料来源：src/cerebro/callgraph.py:45-130。

两者配合形成"结构索引 + 摘要索引"的双层视图：结构层保证精确查找，摘要层支撑语义问答。

4. 摘要与嵌入（summarizer.py + embeddings.py）

summarizer.py 通过 headless 方式调用 claude -p 生成文件级摘要，并维护 stale 标记。embeddings.py 负责把摘要转化为向量，以便未来扩展语义检索；该模块是 v0.2.x 中相对独立的一层，可在不修改其它模块的前提下替换底层编码器 资料来源：src/cerebro/summarizer.py:60-140 资料来源：src/cerebro/embeddings.py:20-95。

5. 多仓库感知（polyrepo.py）

v0.2.0 引入的 polyrepo.py 会从当前工作目录向上回溯，找到最近的 .cerebro 标记或 git 根，从而正确解析 brain 路径。该机制使 Cerebro 在 monorepo 与 multi-repo 场景下都能保持单一权威 brain，避免重复索引 资料来源：src/cerebro/polyrepo.py:10-70。

自动化与生命周期

cerebro_session_end.py 是 Claude Code 的 SessionEnd 钩子，在每次会话退出时触发：当 CEREBRO_AUTORECORD=N 启用时，它会调用 cerebro summarize --stale 重新汇总本会话内变脏的文件，让下一次会话读到的是最新痕迹而非陈旧缓存 资料来源：CHANGELOG.md:8-12 资料来源：src/cerebro/hooks/cerebro_session_end.py:1-60。

v0.2.1 修复了该钩子在系统 Python 3.9.6 下因 PEP 604 联合类型语法（str | None）未加 from __future__ import annotations 而崩溃的问题，确保插件在旧解释器下也能正常导入 资料来源：CHANGELOG.md:3-7。

数据流总览

flowchart LR
    A[Claude Code 客户端] -->|MCP 调用| B[server.py]
    B --> C[indexer.py]
    B --> D[db.py]
    B --> E[summarizer.py]
    E -->|claude -p| F[Headless Claude]
    F -->|_is_valid_summary 校验| E
    E --> D
    C --> G[callgraph.py]
    G --> D
    H[SessionEnd 钩子] -->|--stale| E
    I[polyrepo.py] -->|解析 brain 路径| D

关键设计取舍

• 本地优先：全部状态在 SQLite 与本地文件，避免任何云端依赖，但也意味着跨机器同步需用户自行处理 资料来源：README.md:10-25。
• 延迟摘要：不在每次写文件时立即汇总，而是借 SessionEnd 钩子批量处理，权衡实时性与 token 成本 资料来源：CHANGELOG.md:8-12。
• 解析鲁棒性：对 claude -p 的输出做合法性校验，避免把环境噪声误存为知识 资料来源：src/cerebro/server.py:140-160。

小结

Cerebro 的架构围绕"一个本地 brain + 一个 MCP 入口 + 一组可插拔子系统"展开：server.py 对外，db.py 对内持久化，indexer.py/callgraph.py 提供结构视图，summarizer.py/embeddings.py 提供语义视图，polyrepo.py 处理仓库边界，SessionEnd 钩子保证记忆新鲜。理解这些模块的边界与协作方式，是后续扩展自定义检索策略或接入新编码器的前提。

概览

Cerebro 通过两条主要接口对外暴露能力：一条是基于 click 的 CLI（命令行），另一条是 Model Context Protocol（MCP）服务器。CLI 主要用于本地管理与维护持久化的 SQLite "brain"，而 MCP 工具则让 AI 客户端（例如 Claude Code）能够查询脑中的代码记忆、写入笔记和洞察。CLI 与 MCP 后端共享相同的核心模块（summaries、notes、insights、summarizer），因此两者对同一份数据的读写保持一致。

资料来源：src/cerebro/cli.py:1-30、src/cerebro/apiroutes.py:1-40

CLI 命令

CLI 入口由 src/cerebro/cli.py 中的 main 组函数定义，常用子命令包括：

cerebro summarize 是脑自维护的关键。当某文件在上一次会话中被修改而摘要尚未刷新时，可使用 cerebro summarize --stale 仅扫描过期条目并请求 Claude 重新总结，从而避免在下次会话中重复读取文件内容。summarize_one() 会通过 _is_valid_summary() 过滤掉来自错误 hook 的输出（如 claude-mem 的 UserPromptSubmit 失败块），防止将错误信息误存为摘要（v0.2.2 修复）。

资料来源：src/cerebro/cli.py:40-120、src/cerebro/summarizer.py:60-140

MCP 工具

MCP 服务器在 apiroutes.py 中以工具（tool）形式注册，每个工具对应一次结构化调用。下表汇总了主要工具及其参数：

所有工具最终都通过 SQLite 持久化层访问 .cerebro/brain.db。脑的位置由 polyrepo 自动检测逻辑确定：从当前目录向上查找 .cerebro/ 或 .git/，未找到则使用工作目录下新建的 .cerebro/。

资料来源：src/cerebro/apiroutes.py:50-180、src/cerebro/summaries.py:1-90

核心工作流

下图展示一次典型的"会话结束 → 下次会话复用"循环：

flowchart LR
    A[SessionEnd Hook] -->|触发 autorerecord| B[summarize_one]
    B --> C{_is_valid_summary?}
    C -->|否| X[丢弃输出]
    C -->|是| D[(SQLite brain)]
    E[新会话] --> F[MCP search_summaries]
    F --> D
    D --> G[返回摘要/笔记]
    G --> E

SessionEnd hook（仅在 CEREBRO_AUTORECORD=1 时启用）会扫描本次会话中变脏的文件并调用 summarize_one() 写回脑；下次会话开启后，AI 客户端通过 search_summaries 或 get_summary 直接读取，而不是再次 Read 文件，从而节省 token 并保持对历史上下文的持续记忆。add_note 与 add_insight 则为人工或 AI 主动沉淀的"理解层"信息，独立于摘要之外。

资料来源：src/cerebro/cli.py:200-260、src/cerebro/summarizer.py:30-90

配置与环境变量

CLI 与 MCP 共用以下环境变量：

• CEREBRO_BRAIN_DIR：显式指定脑目录；缺省时使用 polyrepo 自动检测。
• CEREBRO_AUTORECORD：设为非零值时启用 SessionEnd 自动摘要。
• CEREBRO_TRANSPORT：选择 MCP 传输协议（stdio 或 sse）。
• ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN：summarize_one() 调用 headless Claude 时所需凭证。

cerebro mcp add 子命令会写入 Claude Code 的 MCP 配置文件，等价于手动执行 claude mcp add cerebro -- uvx cerebro-code-memory。安装后无需额外配置即可在 Claude Code 中识别 cerebro 服务器并暴露上文所有工具。

资料来源：src/cerebro/cli.py:20-70、src/cerebro/apiroutes.py:1-40

概述与作用范围

Claude Code 插件与自动化钩子是 cerebro-code-memory 在客户端侧的运行时入口，承担两个核心职责：在新会话开始时自动注入"记忆注入"上下文，并在会话关键生命周期节点上同步"脑(brain)"中的文件使用与摘要状态。

• 作为 Claude Code 的插件分发单元，提供市场清单、本地插件清单以及 MCP 服务器声明，使 claude CLI 可以识别 cerebro 插件及其挂载的 MCP 服务 资料来源：.claude-plugin/marketplace.json:1-25
• 在会话生命周期上注册自动化钩子（SessionStart / PostToolUse / SessionEnd），形成"读→用→记"的闭环：会话开始时把脑中的摘要喂给模型，使用过的文件被标记为已读，会话结束时可按需自动重新摘要陈旧条目 资料来源：plugin/hooks/hooks.json:1-40

这一层与 MCP server 内的工具实现解耦：钩子仅通过命令行调用 cerebro 子命令与 MCP 通信，避免了硬编码 Python 模块路径或 SDK 调用。

插件清单与 MCP 挂载

仓库通过两级清单声明插件身份。顶层 .claude-plugin/marketplace.json 作为市场入口，将 cerebro 插件归入 code-intelligence 类目，并指向 plugin/ 子目录 资料来源：.claude-plugin/marketplace.json:1-25。plugin/.claude-plugin/plugin.json 进一步声明插件元数据，包括名称、版本、关键字以及仓库地址，使 Claude Code 在本地加载插件时无需联网解析 资料来源：plugin/.claude-plugin/plugin.json:1-20。

MCP 集成通过 plugin/.mcp.json 完成：声明 cerebro MCP 服务器使用 uvx 运行 cerebro-code-memory 包，并把 CEREBRO_AUTORECORD 等环境变量透传给后端进程 资料来源：plugin/.mcp.json:1-15。这一文件决定了会话内 mcp__cerebro__* 工具的可用性，是客户端与服务端之间的契约点。

钩子注册与生命周期

plugin/hooks/hooks.json 是钩子编排中心，按事件类型挂载不同的 Python 脚本：

资料来源：plugin/hooks/hooks.json:1-40

会话启动钩子 (cerebro-first.py) 通过 addContext 钩子返回结构化 hookSpecificOutput.additionalContext，将项目描述、近期变更、入口点与运行时发现以 JSON 形式交给 Claude Code 渲染 资料来源：plugin/hooks/cerebro-first.py:1-60。它解析 stdin 上的 hook payload，从项目根目录加载配置，并以 markdown 摘要块的形式呈现脑的状态，便于模型在不重新遍历目录的前提下恢复上下文。

会话结束与自动重摘要

SessionEnd 钩子是 v0.2.0 引入的"自我维持脑"机制的关键执行点。它检查 CEREBRO_AUTORECORD 是否启用，若启用则扫描本会话被读取过的文件，对摘要已陈旧（mtime 超过阈值或内容哈希变化）的条目重新调用 cerebro summarize，把最新理解写回 SQLite 脑 资料来源：plugin/hooks/cerebro-session-end.py:1-80。

该钩子在 v0.2.1 中修复了一处兼容性 bug：原脚本使用了 PEP 604 的 str | None 联合类型语法，在系统 python3 3.9 环境下（Claude Code 用 /usr/bin/python3 启动钩子）会因 from __future__ import annotations 缺失而抛 TypeError，导致 SessionEnd 静默失败。修复后加入了 from __future__ import annotations 并对 sys.executable 进行防御性回退 资料来源：plugin/hooks/cerebro-session-end.py:1-15。

`PostToolUse` 标记已用文件

cerebro-mark-used.py 是钩子链中调用频率最高的一环：每次 mcp__cerebro__* 工具返回结果后，Claude Code 都会触发它。脚本从 stdin 读取工具名与文件路径参数，调用 cerebro mark-used 子命令更新 SQLite 脑中对应条目的 last_used_at 与 use_count 字段 资料来源：plugin/hooks/cerebro-mark-used.py:1-50。

这一机制与 _is_valid_summary() 防护协同工作：即使钩子或第三方插件（如 claude-mem）在 stdout 上意外写入了"被阻止"提示，摘要写入路径也会先做合法性校验，避免污染脑中的摘要 资料来源：plugin/hooks/cerebro-mark-used.py:20-45。

已知约束与最佳实践

• 环境兼容性：钩子以 /usr/bin/python3 运行，因此必须避免 3.9 不支持的语法或标准库特性，必要时显式声明 from __future__ import annotations 资料来源：plugin/hooks/cerebro-session-end.py:1-15
• stdout 纯净度：摘要器通过 _is_valid_summary() 拒绝钩子错误、权限拒绝等模板文本，确保脑中数据只来自真实模型输出 资料来源：plugin/hooks/cerebro-session-end.py:40-80
• 显式开关：CEREBRO_AUTORECORD 默认关闭，避免在不希望产生网络或 LLM 调用的会话里触发重摘要 资料来源：plugin/.mcp.json:5-10

Pitfall Log / 踩坑日志

项目：marcodavidd020/cerebro-code-memory

摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Cerebro 0.1.0。

1. 安装坑 · 失败模式：installation: Cerebro 0.1.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Cerebro 0.1.0
• 对用户的影响：Upgrade or migration may change expected behavior: Cerebro 0.1.0
• 证据：failure_mode_cluster:github_release | https://github.com/marcodavidd020/cerebro-code-memory/releases/tag/v0.1.0 | Cerebro 0.1.0

2. 安装坑 · 失败模式：installation: Cerebro 0.2.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Cerebro 0.2.0
• 对用户的影响：Upgrade or migration may change expected behavior: Cerebro 0.2.0
• 证据：failure_mode_cluster:github_release | https://github.com/marcodavidd020/cerebro-code-memory/releases/tag/v0.2.0 | Cerebro 0.2.0

3. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/marcodavidd020/cerebro-code-memory | host_targets=mcp_host, claude_code, claude

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/marcodavidd020/cerebro-code-memory | README/documentation is current enough for a first validation pass.

5. 运行坑 · 失败模式：runtime: Cerebro 0.2.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: Cerebro 0.2.1
• 对用户的影响：Upgrade or migration may change expected behavior: Cerebro 0.2.1
• 证据：failure_mode_cluster:github_release | https://github.com/marcodavidd020/cerebro-code-memory/releases/tag/v0.2.1 | Cerebro 0.2.1

6. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/marcodavidd020/cerebro-code-memory | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/marcodavidd020/cerebro-code-memory | no_demo; severity=medium

8. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/marcodavidd020/cerebro-code-memory | no_demo; severity=medium

9. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/marcodavidd020/cerebro-code-memory | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/marcodavidd020/cerebro-code-memory | release_recency=unknown

11. 维护坑 · 失败模式：maintenance: v0.2.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.2.2
• 对用户的影响：Upgrade or migration may change expected behavior: v0.2.2
• 证据：failure_mode_cluster:github_release | https://github.com/marcodavidd020/cerebro-code-memory/releases/tag/v0.2.2 | v0.2.2