# https://github.com/marcodavidd020/cerebro-code-memory 项目说明书

生成时间：2026-07-05 12:47:34 UTC

## 目录

- [项目概述与安装指南](#page-1)
- [系统架构与核心模块](#page-2)
- [CLI 命令与 MCP 工具](#page-3)
- [Claude Code 插件与自动化钩子](#page-4)

<a id='page-1'></a>

## 项目概述与安装指南

### 相关页面

相关主题：[系统架构与核心模块](#page-2), [Claude Code 插件与自动化钩子](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/README.md)
- [USAGE.md](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/USAGE.md)
- [pyproject.toml](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/pyproject.toml)
- [src/cerebro/__init__.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/__init__.py)
- [src/cerebro/config.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/config.py)
- [CLAUDE.md](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/CLAUDE.md)
</details>

# 项目概述与安装指南

## 项目定位与核心价值

`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 服务器：

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

资料来源：[README.md:60-66]()

### 方式二：作为 Python 包安装

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

```bash
pip install cerebro-code-memory
```

资料来源：[pyproject.toml:1-30]()

### 方式三：从源码构建

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

## 配置与基本使用

### 关键环境变量

| 变量 | 默认值 | 作用 |
| --- | --- | --- |
| `CEREBRO_AUTORECORD` | 启用 | 控制 SessionEnd 时是否自动重新摘要陈旧文件 |
| `CEREBRO_DB_PATH` | 自动解析 | 指定 brain SQLite 数据库的存储位置 |

资料来源：[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]()

## 版本演进一览

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

| 版本 | 主要变化 |
| --- | --- |
| 0.1.0 | 首个公开版本，提供基础 SQLite brain 与 MCP 服务器 |
| 0.2.0 | 引入 Auto-record、Polyrepo 自动识别、`--stale` 子命令 |
| 0.2.1 | 修复 Python 3.9 下 SessionEnd 钩子导入崩溃 |
| 0.2.2 | 摘要器增加合法性校验，过滤钩子错误输出 |

资料来源：[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]()

---

<a id='page-2'></a>

## 系统架构与核心模块

### 相关页面

相关主题：[项目概述与安装指南](#page-1), [CLI 命令与 MCP 工具](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/cerebro/server.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/server.py)
- [src/cerebro/db.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/db.py)
- [src/cerebro/indexer.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/indexer.py)
- [src/cerebro/callgraph.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/callgraph.py)
- [src/cerebro/embeddings.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/embeddings.py)
- [src/cerebro/graph.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/graph.py)
- [src/cerebro/summarizer.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/summarizer.py)
- [src/cerebro/polyrepo.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/polyrepo.py)
- [src/cerebro/hooks/cerebro_session_end.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/hooks/cerebro_session_end.py)
</details>

# 系统架构与核心模块

## 总体定位与设计目标

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]()。

## 数据流总览

```mermaid
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` 钩子保证记忆新鲜。理解这些模块的边界与协作方式，是后续扩展自定义检索策略或接入新编码器的前提。

---

<a id='page-3'></a>

## CLI 命令与 MCP 工具

### 相关页面

相关主题：[系统架构与核心模块](#page-2), [Claude Code 插件与自动化钩子](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/cerebro/cli.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/cli.py)
- [src/cerebro/apiroutes.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/apiroutes.py)
- [src/cerebro/summarizer.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/summarizer.py)
- [src/cerebro/summaries.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/summaries.py)
- [src/cerebro/notes.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/notes.py)
- [src/cerebro/insights.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/src/cerebro/insights.py)
</details>

# CLI 命令与 MCP 工具

## 概览

Cerebro 通过两条主要接口对外暴露能力：一条是基于 `click` 的 CLI（命令行），另一条是 Model Context Protocol（[MCP](https://modelcontextprotocol.io)）服务器。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` 组函数定义，常用子命令包括：

| 子命令 | 作用 | 关键参数 |
| --- | --- | --- |
| `summarize` | 调用 headless `claude -p` 重新生成文件摘要 | `--stale`（仅重算过期摘要） |
| `search` | 在已记录的摘要/笔记中按关键词检索 | `--limit`、`--kind` |
| `note` | 直接向脑中添加一条文本笔记 | `--file`、`--body` |
| `insight` | 记录一条跨文件洞察/模式 | `--title`、`--body` |
| `serve` | 启动 MCP 服务器（默认 stdio 传输） | `--transport` |
| `mcp add` | 便捷包装 `claude mcp add cerebro -- uvx cerebro-code-memory` | — |

`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）形式注册，每个工具对应一次结构化调用。下表汇总了主要工具及其参数：

| 工具名 | 用途 | 主要参数 | 触发模块 |
| --- | --- | --- | --- |
| `search_summaries` | 在文件摘要中关键词检索 | `query`、`limit` | `summaries.search()` |
| `get_summary` | 读取单文件摘要 | `path` | `summaries.get()` |
| `add_note` | 新增针对文件或主题的笔记 | `path?`、`body`、`tags?` | `notes.add()` |
| `list_notes` | 列出某范围下的笔记 | `path?`、`limit` | `notes.list()` |
| `add_insight` | 写入跨文件洞察 | `title`、`body`、`related?` | `insights.add()` |
| `list_insights` | 列出洞察条目 | `limit` | `insights.list()` |
| `summarize_file` | 立即重算某个文件的摘要 | `path`、`force?` | `summarizer.summarize_one()` |

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

资料来源：[src/cerebro/apiroutes.py:50-180]()、`[src/cerebro/summaries.py:1-90]()`

## 核心工作流

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

```mermaid
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]()`

---

<a id='page-4'></a>

## Claude Code 插件与自动化钩子

### 相关页面

相关主题：[项目概述与安装指南](#page-1), [CLI 命令与 MCP 工具](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [.claude-plugin/marketplace.json](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/.claude-plugin/marketplace.json)
- [plugin/.claude-plugin/plugin.json](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/plugin/.claude-plugin/plugin.json)
- [plugin/.mcp.json](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/plugin/.mcp.json)
- [plugin/hooks/hooks.json](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/plugin/hooks/hooks.json)
- [plugin/hooks/cerebro-first.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/plugin/hooks/cerebro-first.py)
- [plugin/hooks/cerebro-mark-used.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/plugin/hooks/cerebro-mark-used.py)
- [plugin/hooks/cerebro-session-end.py](https://github.com/marcodavidd020/cerebro-code-memory/blob/main/plugin/hooks/cerebro-session-end.py)
</details>

# Claude Code 插件与自动化钩子

## 概述与作用范围

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 脚本：

| 事件 | 钩子脚本 | 触发时机 |
|---|---|---|
| SessionStart | `cerebro-first.py` | 新会话首条用户消息前注入上下文 |
| PostToolUse | `cerebro-mark-used.py` | 每次 MCP 工具调用后标记被读文件 |
| SessionEnd | `cerebro-session-end.py` | 会话退出时按需自动重摘要陈旧条目 |

资料来源：[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]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: marcodavidd020/cerebro-code-memory; human_manual_source: deepwiki_human_wiki -->