内容
# Cerebro
**人工智能聊天会话中的持久代码知识记忆。**
每个新的聊天会话都会从头开始重新分析项目的目录，以了解项目，这会消耗大量令牌，重复发现前一个聊天会话已经学习过的内容。Cerebro 会将**理解**（而不仅仅是文件）缓存在一个小型 SQLite “大脑”中，该大脑位于**聊天会话之外**。新的聊天会话会**查询**它，而不是重新读取目录。
与其读取 50 个文件（约 100k 令牌）来理解一个项目，模型只需进行一次 `cerebro_map()` 调用（约 2-3k 令牌），再加上几个有针对性的查找。
## 工作原理
三种“跟踪”层次，从最便宜到最昂贵：
1. **结构图**（免费，无 LLM）— `tree-sitter` 提取符号和导入，并构建依赖图。导入可以解析相对路径和 **tsconfig / jsconfig 路径别名**（`@/...`），因此 Next.js / NestJS 多模块仓库可以获得真正的边。**PageRank** 对最重要的模块进行排名。每个文件都经过哈希处理，以便检测更改。
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)` | 文件调用的内部函数（传出调用边）。 |
## 快速开始
一个命令即可启用任何仓库 — 它会索引并打印确切的注册行：
```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` 将过时笔记的 frontmatter 补丁到 `estado: revisar`。这是自动刷新代码索引和人工策划的 wiki 之间的桥梁 — 文档不会悄悄失效。
`cerebro doc-refresh <note>` 闭环：它重新审计一个过时的笔记与**实时**代码，并打印简报 — 当前符号、摘要和每个引用的依赖项，以及任何移动文件的**新位置** — 代理人正需要这些信息来提出更新（自我修复文档，人类审查）。
如果没有全局安装，请在命令前加上 `uv run`（例如 `uv run cerebro setup`）。
通过设置 `CEREBRO_ROOT=/path/to/repo` 将 Cerebro 指向特定仓库。它遵循 `.gitignore` 和可选的 **`.cerebroignore`** （相同语法）以排除繁重的非源目录（`backup/`、`**/uploads/`、…），而无需修改您的 VCS 配置。`node_modules/`、`.next/`、`dist/`、`build/` 默认被忽略。
适用于多模块仓库：一次索引整个仓库（单个根目录下的大脑，具有跨包别名解析）或每个子应用程序（每个包的 `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`：model2vec 嵌入 — 每个符号一个向量 — 无 torch，无 API 密钥，机器上没有任何内容离开 — `cerebro_search` 成为混合语义 + 关键词，并落在确切的符号（`path:line`）上，而不是仅仅是文件），以及可视化（`cerebro-graph` → 自包含的交互式 HTML 依赖图；`cerebro-export-obsidian` → Obsidian 仓库，其中导入是 `[[links]]`），以及架构洞察（`cerebro_impact` 传递性爆炸半径，`cerebro_cycles` 循环导入，`cerebro_orphans` 死代码候选），以及符号级调用图（`cerebro_callers` / `cerebro_calls`，树状结构解析名称）。推迟到 v2：实时文件监视器，和基于 LSP 的调用图，用于类型精确解析（当前调用图按名称解析）。
