内容
# Cerebro
**跨会话的持久化代码知识记忆。**
每个新的聊天会话都会从头开始重新分析项目的目录，以了解项目，这会消耗大量令牌。Cerebro 会缓存**理解**内容，而不仅仅是文件，在一个小型 SQLite “大脑”中，该大脑位于**外部**聊天会话之外。新的会话会**查询**它，而不是重新读取目录。
与理解一个项目相关的文件数量（约 100k 令牌）相比，模型只需进行一次 `cerebro_map()` 调用（约 2-3k 令牌），再加上几个有针对性的查找。
## 工作原理
三层“跟踪”，最便宜的优先：
1. **结构图谱**（免费，无大语言模型）— `tree-sitter` 提取符号 + 导入并构建依赖关系图。导入可以解析相对路径和 **tsconfig / jsconfig 路径别名**（`@/...`），因此 Next.js / NestJS 多个仓库可以获得真正的边。**PageRank** 对最重要的模块进行排名。每个文件都经过哈希处理，以便检测更改。支持的语言：Python、JavaScript / TypeScript（包括 JSX/TSX）和 Dart / Flutter。
2. **缓存摘要**（最大的节省）— 当聊天理解一个文件时，它会调用 `cerebro_record(path, summary)` 以存储 1-3 个句子的**英文**摘要（英文令牌化成本比西班牙语低约 15-30%）。未来会话会重用它。
3. **新鲜度** — 每个摘要都与文件的哈希值绑定。如果文件更改，则跟踪被标记为**过时**，因此只有该文件被重新读取。
> 为什么不使用迪杰斯特拉算法？代码知识是一个**相关性**问题，而不是最短路径问题。有用的算法是图遍历（BFS/DFS，用于影响）和中心度（PageRank，用于排名）— 而不是加权路由。
## MCP 工具
| 工具 | 用途 |
|------|---------|
| `cerebro_map(top=30)` | 廉价的项目概览，按中心度排名的模块。**首先调用。** |
| `cerebro_get(path)` | 文件的摘要 + 符号 + 依赖关系，无需读取文件。 |
| `cerebro_search(query)` | 混合语义 + 关键词搜索；语义匹配解析为精确符号（`path:line`），而不仅仅是文件。 |
| `cerebro_record(path, summary)` | 留下痕迹：存储您对文件的理解。 |
| `cerebro_note(content, topic?)` | 记录决策 / 领域规则 / 易错点（**原因**）。 |
| `cerebro_recall(query?)` | 回忆过去会话记录的决策。 |
| `cerebro_stale()` | 自上次索引以来更改的文件 + 过时的摘要。 |
| `cerebro_sync()` | 捕获分支切换 / git 拉取 / 外部编辑并重新索引它们。 |
| `cerebro_reindex(paths?)` | 刷新结构索引（仅更改的文件）。 |
| `cerebro_impact(path)` | 传递性影响范围：间接导入文件的全部内容。 |
| `cerebro_cycles()` | 循环导入组（架构异味）。 |
| `cerebro_orphans(prefix?)` | 代码文件中没有任何导入 — 死亡代码候选者（文件级别）。 |
| `cerebro_dead_symbols(prefix?)` | 未使用的导出候选者：自身项目中无引用的函数/类/方法，在被导入的文件中（符号级死亡代码）。 |
| `cerebro_callers(name)` | 符号的调用站点（谁调用它，带有封闭函数 + 行号）。 |
| `cerebro_calls(path)` | 文件调用的内部函数（传出调用边）。 |
## 安装
**一条命令**（已在 PyPI 上发布）— 将 MCP 服务器添加到 Claude Code：
```bash
claude mcp add cerebro -- uvx cerebro-code-memory
```
或者安装完整的 **Claude Code 插件**（MCP 服务器 + 会话钩子 + cerebro-first 子代理）：
```bash
/plugin marketplace add marcodavidd020/cerebro-code-memory
/plugin install cerebro@cerebro
```
需要 Python ≥ 3.10。将 Cerebro 指向一个仓库，设置 `CEREBRO_ROOT=/path/to/repo`; 它还会自动检测最近的祖先 `.cerebro/` 大脑（在 monorepos 中很方便）。
## 快速开始
一条命令即可启动任何仓库 — 它会索引并打印确切的注册行：
```bash
uv tool install --from . cerebro # 全局安装 `cerebro` 命令（开发）
cd /path/to/your/repo
cerebro setup --summarize --embed # 索引（+ 预热摘要 / 语义索引），然后打印下一步骤
```
`cerebro setup` 是幂等的。然后运行它打印的 `claude mcp add …` 行，重新加载编辑器，`cerebro_*` 工具在聊天中可用。
## 统一 CLI
```
cerebro # 无参数 -> MCP 服务器（stdio）；这是注册运行的内容
cerebro setup # 索引此仓库 + 打印 MCP 注册
cerebro index [--force] # 构建/刷新索引
cerebro search <query> # 混合语义 + 关键词搜索
cerebro map # 项目概览
cerebro graph # 交互式依赖关系图 HTML
cerebro obsidian # 导出 Obsidian 保险库
cerebro summarize / embed
cerebro impact / cycles / orphans / callers / calls / recall
cerebro doc-audit <vault> # 实时文档：标记引用代码已更改的知识笔记
```
### 实时文档（`doc-audit`）
`cerebro doc-audit <markdown-vault>` 会将精选的知识保险库与代码索引进行交叉检查：它会解析每个笔记的代码引用（`path:line`，带反引号的符号）和笔记的 `ultima_verificacion`/`fecha`，然后标记引用文件**在验证后更改**、**移动/删除**或提及**不再存在的符号**的笔记。`--aliases` 会将 wiki 应用名称映射到仓库目录（`backend_app=fenix-store-backend,…`）；`--fix` 会将过时笔记的前置事项修补为 `estado: revisar`。这是自动刷新代码索引和人工策划的 wiki 之间的桥梁 — 不会静默腐烂的文档。
`cerebro doc-refresh <note>` 闭环：它会针对**实时**代码重新审计一个过时的笔记并打印简报 — 当前符号、摘要和每个引用的依赖项，以及任何移动文件的新位置 — 正是代理需要更新的上下文（自愈文档，人类审查）。
如果没有全局安装，请在命令前加上 `uv run`（例如 `uv run cerebro setup`）。
将 Cerebro 指向特定仓库，设置 `CEREBRO_ROOT=/path/to/repo`。它遵循 `.gitignore` 和可选的 **`.cerebroignore`**（相同的语法）以排除繁重的非源目录（`backup/`、`**/uploads/`等）而不影响您的 VCS 配置。`node_modules/`、`dist/`、`build/` 默认被忽略。
适用于 monorepos：一次索引整个项目（单个大脑位于根目录，具有跨包别名解析）或每个子应用（每个包的 `CEREBRO_ROOT`）。
### 在 Claude Code 中注册
```bash
claude mcp add cerebro -- uv --directory /path/to/cerebro run cerebro
```
设置 `CEREBRO_ROOT` 为您希望大脑涵盖的项目。参见 `plugin/` 以获取可选的 Claude Code 插件，该插件会在会话启动时自动注入映射并将编辑的文件标记为过时。
## 范围（MVP）
包括：结构图谱、缓存摘要、新鲜度、关键词搜索、tsconfig/jsconfig 别名解析、`.cerebroignore`、批量摘要预热（`cerebro-summarize`，通过无头 `claude -p` — 无 API 密钥）、决策日志（`cerebro_note` / `cerebro_recall`，在会话启动时显示）和 git 感知新鲜度（`cerebro_sync` 捕获分支切换 / 拉取 / 外部编辑，跨嵌套仓库），以及可选的本地语义搜索（`cerebro-embed` + `--extra semantic`：模型2vec 嵌入 — 每个符号一个向量 — 无 torch，无 API 密钥，机器上没有任何内容离开 — `cerebro_search` 成为混合语义 + 关键词并落在精确符号（`path:line`）上，而不是仅仅是文件），以及可视化（`cerebro-graph` → 自包含交互式 HTML 依赖关系图；`cerebro-export-obsidian` → Obsidian 保险库，其中导入是 `[[链接]]`），以及架构洞察（`cerebro_impact` 传递影响范围，`cerebro_cycles` 循环导入，`cerebro_orphans` 死亡代码候选者），以及符号级调用图（`cerebro_callers` / `cerebro_calls`，树状解析器名称解析）。推迟到 v2：实时文件监视器和 LSP 支持的调用图，用于类型精确解析（当前调用图按名称解析）。
## 许可证
MIT © 2026 Marco Toledo — 请参阅 [LICENSE](LICENSE)。
