内容
# codebase-memory-mcp-pro
> **🔱 分叉通知** — `codebase-memory-mcp-pro` 是 [**DeusData/codebase-memory-mcp**](https://github.com/DeusData/codebase-memory-mcp) 的社区分叉版本（MIT 许可证，© 2025 DeusData），由 [@win4r](https://github.com/win4r) 维护。本项目跟踪上游并整合了以下修复，这些修复在上游合并之前：
>
> - **增量重新索引正确性** ([#528](https://github.com/DeusData/codebase-memory-mcp/pull/528)) — 在增量重新索引时保留入站跨文件 `CALLS` 边；编辑文件不再使调用其符号的记录失效。
> - **Cypher / `query_graph`** — 通过 `WITH` 聚合填充节点属性 ([#465](https://github.com/DeusData/codebase-memory-mcp/pull/465))；修复标签过滤遍历在 10 行时静默截断 ([#412](https://github.com/DeusData/codebase-memory-mcp/pull/412))。
> - **MCP 工具** — `detect_changes` 遵循 `since` ([#464](https://github.com/DeusData/codebase-memory-mcp/pull/464))；定义优先的名称解析，并报告歧义 ([#466](https://github.com/DeusData/codebase-memory-mcp/pull/466))；`get_code_snippet` 中的有效 UTF-8 ([#526](https://github.com/DeusData/codebase-memory-mcp/pull/526))。
> - **鲁棒性 / 构建** — `append_args_json` 中的堆缓冲区溢出修复 ([#475](https://github.com/DeusData/codebase-memory-mcp/pull/475))；JSON 控制字符转义 ([#527](https://github.com/DeusData/codebase-memory-mcp/pull/527))；在完整重新索引期间保留 ADR ([#539](https://github.com/DeusData/codebase-memory-mcp/pull/539))；libgit2 ≥ 1.8 构建修复 ([#512](https://github.com/DeusData/codebase-memory-mcp/pull/512))。
> - **代理原生增强（此分叉）** — 一个新的 **`explore`** MCP 工具：*一次*调用返回爆炸半径（属性调用者和内联扇入热点标志）、**附近邻居**（1 跳调用者和同文件兄弟姐妹，因此它涵盖周围区域），**以及**按文件分组的匹配符号的逐行源码，具有 `query_graph`/Cypher 出口 — 为 AI 代理构建，以便像 `Read` 一样读取。此外，**惯用 Swift 类型种类** — `struct`/`enum`/`actor` 是不同的图标签（`Struct`/`Enum`/`Actor`）而不是全部归类为 `Class`，而 Swift **枚举案例** 被提取为不同的 `EnumCase` 节点（包括多名称 `case a, b, c` 行）— 以及 Swift **枚举静态重复修复**（枚举的 `static func` 不再作为 Method 和 Function 节点重复发出）。
> - **Cypher 聚合修复（此分叉）** — 非聚合函数与聚合函数混合使用（例如 `RETURN type(r), count(*)`) 现在按函数值分组（每个边类型一行）而不是将所有行折叠到单个组中。
> - **`detect_changes` 爆炸半径（此分叉）** — `depth` 参数现在产生一个传递性**调用者** 爆炸半径：`impacted_symbols` 包括调用者直到 `depth` 跳，每个调用者都带有 `hop` + `transitive` 标签，同时具有重复的 `impacted_count`。
所有原始引擎的功劳归属于 DeusData。许可证保持不变 — 请参见 [LICENSE](LICENSE)。
### 🛠️ 从源代码构建此分叉版本
此分叉版本**不附带预构建的发布二进制文件** — 自己构建集成的二进制文件。纯 C，Apple clang / gcc，零外部运行时依赖：
```bash
git clone https://github.com/win4r/codebase-memory-mcp-pro.git
cd codebase-memory-mcp-pro
./scripts/build.sh # → build/c/codebase-memory-mcp (报告版本：dev)
```
第一次构建编译所有 158 个 vendored tree-sitter 语法（几分钟）；对于迭代重建，`make -j -f Makefile.cbm cbm` 更快。macOS **libgit2 ≥ 1.8 构建修复 (#512)** 已经集成，因此 Homebrew `libgit2` 编译干净。
将集成二进制文件安装到您的 PATH 中，并将其配置为 Claude Code 的 MCP 服务器：
```bash
cp build/c/codebase-memory-mcp ~/.local/bin/
# 标准输入/输出 MCP 服务器，在所有项目中可用：
claude mcp add codebase-memory -s user -- ~/.local/bin/codebase-memory-mcp
# 工具：explore, index_repository, query_graph, trace_path, get_code_snippet, detect_changes … （共 15 个）
```
确认集成的修复程序已启用（例如 **#465** — 节点属性在 `WITH` 聚合中存活，这在股票上游返回为空）：
```bash
codebase-memory-mcp cli index_repository '{"repo_path":"/path/to/repo"}'
codebase-memory-mcp cli query_graph '{"project":"<name>","query":"MATCH (a)-[:CALLS]->(b) WITH b, count(a) AS c RETURN b.file_path, c LIMIT 1"}'
# 非空 file_path 表示您正在运行挑选的构建
```
> ⚠️ **不要运行二进制文件的 `update` 子命令** — 它会拉取官方上游版本并覆盖此集成构建。相反，请重新运行 `./scripts/build.sh` 进行更新。
---
*上游 README 如下。*
[](https://github.com/DeusData/codebase-memory-mcp/releases/latest)
[](LICENSE)
[](https://github.com/DeusData/codebase-memory-mcp/actions/workflows/dry-run.yml)
[](https://github.com/DeusData/codebase-memory-mcp)
[](https://github.com/DeusData/codebase-memory-mcp)
[](#hybrid-lsp)
[](https://github.com/DeusData/codebase-memory-mcp)
[](https://github.com/DeusData/codebase-memory-mcp)
[](https://github.com/DeusData/codebase-memory-mcp/releases/latest)
[](https://scorecard.dev/viewer/?uri=github.com/DeusData/codebase-memory-mcp)
[](https://slsa.dev)
[](https://github.com/DeusData/codebase-memory-mcp/releases/latest)
[](https://arxiv.org/abs/2603.27277)
**适用于 AI 编码代理的最快、最有效的代码智能引擎。** 在毫秒级完成对平均仓库的完整索引，Linux 内核（2800 万 LOC，75K 文件）需 3 分钟。在 1 毫秒内回答结构化查询。作为单个静态二进制文件提供，适用于 macOS、Linux 和 Windows — 下载，运行 `install`，完成。
通过 [tree-sitter](https://tree-sitter.github.io/tree-sitter/) AST 分析，在所有 158 种语言上实现高质量解析，并通过 [**Hybrid LSP**](https://github.com/DeusData/codebase-memory-mcp/tree/main/docs/Hybrid-LSP.md) 语义类型解析增强 — 适用于 Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin 和 Rust — 生成函数、类、调用链、HTTP 路由和跨服务链接的持久化知识图谱。14 个 MCP 工具。零依赖。跨 11 个编码代理即插即用。
> **研究** — 本项目的设计和基准测试在预印本 [*Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP*](https://arxiv.org/abs/2603.27277) 中有描述（arXiv:2603.27277）。在 31 个现实世界仓库中评估：83% 的答案质量，10 倍更少的 token，2.1 倍更少的工具调用 vs. 文件逐文件探索。
> **安全与信任** — 此工具读取您的代码库并写入您的代理配置文件。这是它的设计目的。如果您喜欢在运行前进行审计，[这里提供完整的源代码](https://github.com/DeusData/codebase-memory-mcp) — 每个发布二进制文件都已签名、校验并由 70 多种反病毒引擎扫描。所有处理过程 100% 在本地进行；您的代码永远不会离开您的机器。发现安全问题？我们想知道 — 请参见 [SECURITY.md](SECURITY.md)。安全是我们第一优先级。
<p align="center">
<img src="docs/graph-ui-screenshot.png" alt="Graph visualization UI showing the codebase-memory-mcp knowledge graph" width="800">
<br>
<em>内置 3D 图形可视化（UI 变体） — 在 localhost:9749 上探索您的知识图谱</em>
</p>
## 为什么选择 codebase-memory-mcp
- **极快的索引速度** — Linux 内核（2800 万 LOC，75K 文件）需 3 分钟。RAM-first 管道：LZ4 压缩，内存 SQLite，融合 Aho-Corasick 模式匹配。索引后释放内存。
- **即插即用** — 单个静态二进制文件，适用于 macOS（arm64/amd64）、Linux（arm64/amd64）和 Windows（amd64）。无需 Docker，无需运行时依赖，无需 API 密钥。下载 → `install` → 重启代理 → 完成。
- **158 种语言** — 绑定的 tree-sitter 语法编译到二进制文件中。无需安装任何内容，无需担心破坏。
- **120 倍更少的 token** — 5 个结构化查询：~3,400 个 token vs ~412,000 个通过文件逐文件搜索。单个图查询替换数十个 grep/read 循环。
- **11 种代理，一个命令** — `install` 自动检测 Claude Code、Codex CLI、Gemini CLI、Zed、OpenCode、Antigravity、Aider、KiloCode、VS Code、OpenClaw 和 Kiro — 配置 MCP 条目、指令文件、技能和预工具钩子。
- **内置图形可视化** — 3D 交互式 UI 在 `localhost:9749`（可选 UI 二进制文件变体）。
- **基础设施即代码索引** — Dockerfiles、Kubernetes 清单和 Kustomize 叠加层作为图形节点索引，具有交叉引用。`Resource` 节点用于 K8s 类型，`Module` 节点用于 Kustomize 叠加层，具有 `IMPORTS` 边到引用的资源。
- **14 个 MCP 工具** — 搜索、跟踪、架构、影响分析、Cypher 查询、死代码检测、跨服务 HTTP 链接、ADR 管理等。
## 快速入门
**一键安装**（macOS / Linux）：
```bash
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
```
带图形可视化 UI：
```bash
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui
```
**Windows**（PowerShell）：
```powershell
# 1. 下载安装程序
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
# 2. （可选但推荐）检查脚本
notepad install.ps1
# 3. 运行
.\install.ps1
```
选项：`--ui`（图形可视化），`--skip-config`（仅二进制文件，无代理设置），`--dir=<path>`（自定义位置）。
重启您的编码代理。说 **"索引此项目"** — 完成。
<details>
<summary>手动安装</summary>
1. **下载**适用于您平台的存档，从 [最新版本](https://github.com/DeusData/codebase-memory-mcp/releases/latest)：
- `codebase-memory-mcp-<os>-<arch>.tar.gz`（macOS/Linux）或 `.zip`（Windows）— 标准
- `codebase-memory-mcp-ui-<os>-<arch>.tar.gz` / `.zip` — 带有图形可视化
2. **提取并安装**（每个存档都包含 `install.sh` 或 `install.ps1`）：
macOS / Linux：
```bash
tar xzf codebase-memory-mcp-*.tar.gz
./install.sh
```
Windows（PowerShell）：
```powershell
Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
.\install.ps1
```
3. **重启**您的编码代理。
`install` 命令会自动剥离 macOS 隔离属性并临时签署二进制文件 — 无需手动 `xattr`/`codesign`。
</details>
### 图形可视化 UI
如果您下载了 `ui` 变体：
```bash
codebase-memory-mcp --ui=true --port=9749
```
打开 `http://localhost:9749` 在您的浏览器中。UI 作为 MCP 服务器的后台线程运行 — 只要您的代理连接，它就可用。
### 自动索引
在 MCP 会话启动时启用自动索引：
```bash
codebase-memory-mcp config set auto_index true
```
启用后，新项目在首次连接时自动索引。以前索引的项目使用后台监视器注册以进行持续的 git 更改检测。可配置的文件限制：`config set auto_index_limit 50000`。
### 保持最新状态
```bash
codebase-memory-mcp update
```
MCP 服务器还会在启动时检查更新，并在第一个工具调用时通知如果有新版本可用。
### 卸载
```bash
codebase-memory-mcp uninstall
```
删除所有代理配置、技能、钩子和指令。不删除二进制文件或 SQLite 数据库。
## 功能
### 图形和分析
- **架构概述**：`get_architecture` 在单个调用中返回语言、包、入口点、路由、热点、边界、层和集群。
- **架构决策记录**：`manage_adr` 在会话之间持久化架构决策。
- **Louvain 社区检测**：通过聚类调用边发现功能模块。
- **Git 差异影响映射**：`detect_changes` 将未提交的更改映射到受影响的符号并进行风险分类。
- **调用图**：解析跨文件和包的函数调用（导入感知，类型推断）。
- **死代码检测**：查找零调用者函数，排除入口点。
- **Cypher 类似查询**：`MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name`
### 搜索
- **语义搜索**（`semantic_query`）：整个图上的向量搜索，由捆绑的 Nomic `nomic-embed-code` 嵌入（40K token，768d int8）编译到二进制文件 — 无需 API 密钥，无需 Ollama，无需 Docker。11 信号综合评分（TF-IDF，RRI，API/Type/Decorator 签名，AST 配置文件，数据流，Halstead-lite，MinHash，模块接近度，图扩散）。
- **BM25 全文搜索**：使用 `cbm_camel_split` 分词器（驼峰/下划线感知）通过 SQLite FTS5。
- **结构化搜索**（`search_graph`）：正则表达式名称模式，标签过滤器，最小/最大度，文件范围
- **代码搜索**（`search_code`）：基于图的 grep 仅限索引文件
### 跨服务链接
- **HTTP** 路由 ↔ 调用站点匹配并具有置信度评分
- **gRPC，GraphQL，tRPC** 服务检测，具有 protobuf 路由提取
- **通道检测**（`EMITS` / `LISTENS_ON`）用于 Socket.IO、EventEmitter 和通用发布-订阅模式，适用于 8 种语言，具有常量解析
### 跨仓库智能
- **`CROSS_*` 边** 在索引仓库下链接节点
- **多星系 3D 1.8 构建修复 (#512)** 已经集成，因此 Homebrew `libgit2` 编译干净。
### 索引流水线
- **158 种 vendored tree-sitter 语法** 编译到二进制文件中
- **通用包/模块解析** - 裸规格说明，例如 `@myorg/pkg`、`github.com/foo/bar`、`use my_crate::foo` 通过清单扫描解析 (`package.json`、`go.mod`、`Cargo.toml`、`pyproject.toml`、`composer.json`、`pubspec.yaml`、`pom.xml`、`build.gradle`、`mix.exs`、`*.gemspec`)
- **基础设施即代码索引** - Dockerfiles、Kubernetes 清单、Kustomize 叠加层作为图形节点
- **[Hybrid LSP 语义类型解析](https://github.com/DeusData/codebase-memory-mcp/tree/main/docs/Hybrid-LSP.md)** 用于 Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin 和 Rust - 轻量级 C 实现语言类型解析算法，结构灵感来自并兼容主要语言服务器，包括 tsserver / typescript-go，pyright，gopls，Roslyn，Eclipse JDT 和 rust-analyzer（参数绑定，返回类型推断，泛型替换，JSX 组件调度，JSDoc 推断用于纯 JS 文件，命名空间 + 特性 + 静态绑定解析用于 PHP，用于 C# 的文件范围命名空间 + 记录 + LINQ 方法语法，用于 Java 的类层次结构 + 重载 + lambda 解析，用于 Kotlin 的特征方法 + UFCS 解析，用于 Rust 的特征方法 + UFCS 解析）
- **RAM-first 管道**：LZ4 压缩，内存 SQLite，单个转储结束。内存释放后。
### 分发和操作
- **单个静态二进制文件，零基础设施**：SQLite 支持，持久化到 `~/.cache/codebase-memory-mcp/`
- **自动同步**：后台监视器检测文件更改并自动重新索引
- **路由节点**：REST 端点是一等公民图形实体
- **CLI 模式**：`codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*"'`
- **可用平台**：npm，PyPI，Homebrew，Scoop，Winget，Chocolatey，AUR，`go install`
### 边缘类型（选中）
- `CALLS`，`IMPORTS`，`DEFINES`，`IMPLEMENTS`，`INHERITS`
- `HTTP_CALLS`，`ASYNC_CALLS`（跨服务）
- `EMITS`，`LISTENS_ON`（通道）
- `DATA_FLOWS` 具有参数到参数映射 + 字段访问链
- `SIMILAR_TO`（MinHash + LSH 近克隆检测，Jaccard 评分）
- `SEMANTICALLY_RELATED`（词汇不匹配，同语言，分数 ≥ 0.80）
## 团队共享图工件
将单个压缩文件提交到您的存储库中，您的团队成员可以跳过重新索引。
`.codebase-memory/graph.db.zst` 是知识图的一个 zstd 压缩快照，它位于您的源代码旁边。当您索引时，工件被写入或刷新；当队友克隆存储库并第一次运行 `codebase-memory-mcp` 时，工件被解压缩，增量索引填充他们的本地差异。
- **格式**：SQLite 数据库，索引被剥离，`VACUUM INTO` 紧凑，然后使用 zstd 1.5.7 压缩（典型比例为 8-13:1）
- **两层**：
- **最佳**（`zstd -9` + 索引剥离 + `VACUUM INTO`）— 在显式 `index_repository` 上写入
- **快速**（`zstd -3`）— 由观察者写入，以实现低延迟增量更新
- **引导**：当没有本地数据库但存在工件时，`index_repository` 导入工件，然后运行增量索引 — 避免了完全重新索引的成本
- **无合并冲突**：在第一次导出时自动创建 `.gitattributes` 行，内容为 `merge=ours`，因此对二进制工件的并发编辑不会产生冲突
- **可选**：除非您需要，否则永远不会提交。 如果您希望每个人从头开始重新索引，请将 `.codebase-memory/` 添加到 `.gitignore` 中
其结果与 graphify 的 `graphify-out/` 目录类似，但作为单个压缩文件，具有明确的两层导出、完整性检查的导入和零合并冲突。
## 工作原理
codebase-memory-mcp 是一个**结构分析后端** — 它构建和查询知识图。 它不包括 LLM。 相反，它依赖于您的 MCP 客户端（Claude Code 或任何 MCP 兼容的代理）作为智能层。
```
您：“什么调用了 ProcessOrder？”
代理调用：trace_path(function_name="ProcessOrder", direction="inbound")
codebase-memory-mcp：执行图查询，返回结构化结果
代理：以纯英语呈现调用链
```
**为什么没有内置 LLM？** 其他代码图工具嵌入 LLM 以实现自然语言到图查询的翻译。 这意味着额外的 API 密钥、额外的成本以及另一个要配置的模型。 使用 MCP，您已经在使用的代理*是*查询翻译器。
## 性能
在 Apple M3 Pro 上基准测试：
| 操作 | 时间 | 备注 |
|-----------|------|-------|
| **Linux 内核完整索引** | **3 分钟** | 28M LOC，75K 文件 → 4.81M 节点，7.72M 边 |
| Linux 内核快速索引 | 1 分 12 秒 | 1.88M 节点 |
| Django 完整索引 | ~6 秒 | 49K 节点，196K 边 |
| Cypher 查询 | <1 毫秒 | 关系遍历 |
| 名称搜索（正则表达式） | <10 毫秒 | SQL LIKE 预过滤 |
| 死代码检测 | ~150 毫秒 | 全图扫描，带度过滤 |
| 跟踪调用路径（深度=5） | <10 毫秒 | 广度优先搜索遍历 |
**优先使用 RAM 的管道**：所有索引都在内存中运行（LZ4 HC 压缩读取，内存 SQLite，结束时单个转储）。索引完成后，内存会释放回操作系统。
**令牌效率**：通过 codebase-memory-mcp 消耗了约 3,400 个令牌，而通过文件逐一 grep 探索消耗了约 412,000 个令牌 — **减少了 99.2%**。
## 安装
### 预编译二进制文件
| 平台 | 标准 | 带图 UI |
|----------|----------|---------------|
| macOS (Apple Silicon) | `codebase-memory-mcp-darwin-arm64.tar.gz` | `codebase-memory-mcp-ui-darwin-arm64.tar.gz` |
| macOS (Intel) | `codebase-memory-mcp-darwin-amd64.tar.gz` | `codebase-memory-mcp-ui-darwin-amd64.tar.gz` |
| Linux (x86_64) | `codebase-memory-mcp-linux-amd64.tar.gz` | `codebase-memory-mcp-ui-linux-amd64.tar.gz` |
| Linux (ARM64) | `codebase-memory-mcp-linux-arm64.tar.gz` | `codebase-memory-mcp-ui-linux-arm64.tar.gz` |
| Windows (x86_64) | `codebase-memory-mcp-windows-amd64.zip` | `codebase-memory-mcp-ui-windows-amd64.zip` |
每个版本都包含带有 SHA-256 哈希值的 `checksums.txt`。所有二进制文件都是静态链接的 — 无共享库依赖项。
> **Windows 注意**：SmartScreen 可能会显示未签名软件的警告。单击 **“更多信息”** → **“无论如何都运行”**。使用 `checksums.txt` 验证完整性。
### 设置脚本
<details>
<summary>自动下载 + 安装</summary>
**macOS / Linux：**
```bash
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup.sh | bash
```
**Windows (PowerShell)：**
```powershell
irm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 | iex
```
</details>
### AUR (Arch Linux)
```bash
yay -S codebase-memory-mcp-bin
```
```bash
paru -S codebase-memory-mcp-bin
```
`codebase-memory-mcp-bin` 软件包可在：https://aur.archlinux.org/packages/codebase-memory-mcp-bin
### 通过 Claude Code 安装
```
您：“安装此 MCP 服务器：https://github.com/DeusData/codebase-memory-mcp”
```
### 从源代码构建
<details>
<summary>先决条件：C 编译器 + zlib</summary>
| 需求 | 检查 | 安装 |
|-------------|-------|---------|
| **C 编译器**（gcc 或 clang） | `gcc --version` 或 `clang --version` | macOS：`xcode-select --install`，Linux：`apt install build-essential` |
| **C++ 编译器** | `g++ --version` 或 `clang++ --version` | 与上述相同 |
| **zlib** | — | macOS：已包含，Linux：`apt install zlib1g-dev` |
| **Git** | `git --version` | ほとんどのシステムにプレインストール済み |
</details>
```bash
git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh # 标准二进制文件
scripts/build.sh --with-ui # 带图形可视化
# 二进制文件位于：build/c/codebase-memory-mcp
```
### 手动 MCP 配置
<details>
<summary>如果您不想使用安装命令</summary>
添加到 `~/.claude/.mcp.json`（全局）或项目 `.mcp.json`:
```json
{
"mcpServers": {
"codebase-memory-mcp": {
"command": "/path/to/codebase-memory-mcp",
"args": []
}
}
}
```
重启您的代理。验证 `/mcp` — 您应该看到带有 14 个工具的 `codebase-memory-mcp`。
</details>
## 多代理支持
`install` 自动检测并配置所有已安装的代理：
| 代理 | MCP 配置 | 说明 | 钩子 |
|-------|-----------|-------------|-------|
| Claude Code | `.claude/.mcp.json` | 4 个技能 | PreToolUse（Grep/Glob 图增强，非阻塞） |
| Codex CLI | `.codex/config.toml` | `.codex/AGENTS.md` | SessionStart 提醒 |
| Gemini CLI | `.gemini/settings.json` | `.gemini/GEMINI.md` | BeforeTool（grep 提醒）+ SessionStart 提醒 |
| Zed | `settings.json`（JSONC） | — | — |
| OpenCode | `opencode.json` | `AGENTS.md` | — |
| Antigravity | `.gemini/config/mcp_config.json`（共享） | `antigravity-cli/AGENTS.md` | SessionStart 提醒 |
| Aider | — | `CONVENTIONS.md` | — |
| KiloCode | `mcp_settings.json` | `~/.kilocode/rules/` | — |
| VS Code | `Code/User/mcp.json` | — | — |
| OpenClaw | `openclaw.json` | — | — |
| Kiro | `.kiro/settings/mcp.json` | — | — |
**钩子在结构上是非阻塞的**（退出代码 0，每个失败路径）。
对于 Claude Code，`PreToolUse` 钩子拦截 `Grep`/`Glob`（从不 `Read` —
门控 `Read` 会破坏先读后编辑的不变性），并在搜索令牌与索引符号匹配时，通过
`search_graph` 将它们注入为 `additionalContext`，以便代理在正常搜索结果之外获得结构化上下文。对于 Codex、Gemini CLI 和 Antigravity，`SessionStart` 钩子注入一行代码发现提醒作为会话上下文（Gemini CLI 还
保留其 `BeforeTool` 提醒）。
已安装的 Claude 桩文件名为 `cbm-code-discovery-gate`，用于
与现有安装的向后兼容性，尽管其名称已过时，但它
从不门控，从不阻塞。
## 命令行模式
每个 MCP 工具都可以通过命令行调用：
```bash
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/repo"}'
codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'
codebase-memory-mcp cli trace_path '{"function_name": "Search", "direction": "both"}'
codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'
codebase-memory-mcp cli list_projects
codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.results[].name'
```
## MCP 工具
### 索引
| 工具 | 描述 |
|------|-------------|
| `index_repository` | 将存储库索引到图中。自动同步在此之后保持最新。 |
| `list_projects` | 列出所有已索引的项目及其节点/边计数。 |
| `delete_project` | 删除项目及其所有图数据。 |
| `index_status` | 检查项目的索引状态。 |
### 查询
| 工具 | 描述 |
|------|-------------|
| `search_graph` | 按标签、名称模式、文件模式、度过滤器进行结构化搜索。分页通过 limit/offset 实现。 |
| `trace_path` | 广度优先搜索遍历 — 调用某个函数的是什么以及它调用的是什么（别名：`trace_call_path`）。深度 1-5。 |
| `detect_changes` | 将 git diff 映射到受影响的符号 + 辐射范围，并具有风险分类。 |
| `query_graph` | 执行类似 Cypher 的图查询（只读）。 |
| `get_graph_schema` | 节点/边计数、关系模式、每个标签的属性定义。首先运行此命令。 |
| `get_code_snippet` | 通过限定名称读取函数的源代码。 |
| `get_architecture` | 代码库概述：语言、包、路由、热点、集群、ADR。 |
| `search_code` | 索引项目文件内的 grep 类似文本搜索。 |
| `manage_adr` | ADR 的 CRUD 操作。 |
| `ingest_traces` | 提取运行时轨迹以验证 HTTP_CALLS 边。 |
## 图数据模型
### 节点标签
`Project`、`Package`、`Folder`、`File`、`Module`、`Class`、`Function`、`Method`、`Interface`、`Enum`、`Type`、`Route`、`Resource`
### 边类型
`CONTAINS_PACKAGE`、`CONTAINS_FOLDER`、`CONTAINS_FILE`、`DEFINES`、`DEFINES_METHOD`、`IMPORTS`、`CALLS`、`HTTP_CALLS`、`ASYNC_CALLS`、`IMPLEMENTS`、`HANDLES`、`USAGE`、`CONFIGURES`、`WRITES`、`MEMBER_OF`、`TESTS`、`USES_TYPE`、`FILE_CHANGES_WITH`
### 限定名称
`get_code_snippet` 使用限定名称：`<project>.<path_parts>.<name>`。首先使用 `search_graph` 来发现它们。
### 支持的 Cypher（openCypher 读取子集）
`query_graph` 是一个只读的 openCypher 子集：
- **子句**：`MATCH`、`OPTIONAL MATCH`、多个 `MATCH`、`WHERE`、`WITH`（+ `WITH … WHERE`）、`RETURN`、`ORDER BY`、`SKIP`、`LIMIT`、`DISTINCT`、`UNWIND`、`UNION` / `UNION ALL`、`CASE`。
- **模式**：标记节点、标签交替 `(n:A|B)`、关系类型/方向、变长路径 `[*1..3]`、内联属性映射。
- **WHERE**：`=` `<` `>` `>=`、`AND`/`OR`/`XOR`/`NOT`、`IN`、`CONTAINS`、`STARTS WITH`、`ENDS WITH`、`IS [NOT] NULL`、正则表达式 `=~`、标签测试 `n:Label` 和 `EXISTS { (n)-[:TYPE]->() }`（单跳存在 — 非常适合死代码，例如 `WHERE NOT EXISTS { (f)<-[:CALLS]-() }`）。
- **聚合**：`count`（+`DISTINCT`）、`sum`、`avg`、`min`、`max`、`collect`。
- **函数**：`labels`、`type`、`id`、`keys`、`properties`；`toLower/toUpper/toString/toInteger/toFloat/toBoolean`；`size`、`length`、`trim/ltrim/rtrim`、`reverse`；`coalesce`、`substring`、`replace`、`left`、`right`。
超出此子集的任何内容（写入/`MERGE`/`CALL` 子句、未支持的函数、列表/映射文字、理解、路径函数、参数）**都会以明确的 `unsupported …` 错误失败**，而不是返回空结果。
## 忽略文件
分层：硬编码模式（`.git`、`node_modules` 等）→ `.gitignore` 层次结构→ `.cbmignore`（特定于项目，gitignore 语法）。永远跳过符号链接。
## 配置
```bash
codebase-memory-mcp config list # 显示所有设置
codebase-memory-mcp config set auto_index true # 会话启动时自动索引
codebase-memory-mcp config set auto_index_limit 50000 # 自动索引的最大文件数
codebase-memory-mcp config reset auto_index # 重置为默认值
```
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `CBM_CACHE_DIR` | `~/.cache/codebase-memory-mcp` | 覆盖数据库存储目录。所有项目索引和配置都存储在此处。 |
| `CBM_DIAGNOSTICS` | `false` | 将其设置为 `1` 或 `true` 以启用每隔一段时间输出诊断信息到 `/tmp/cbm-diagnostics-<pid>.json`。 |
| `CBM_DOWNLOAD_URL` | *(GitHub 版本)* | 覆盖更新的下载 URL。用于测试或自托管部署。 |
| `CBM_LOG_LEVEL` | `info` | 设置最低日志级别。接受的值（不区分大小写）：`debug`、`info`、`warn`、`error`、`none` — 或其数字等价物 `0`–`4`，匹配内部枚举。日志输出到 stderr；stdout 保留用于 MCP JSON-RPC。 |
| `CBM_WORKERS` | *(检测)* | 覆盖 `cbm_default_worker_count` 返回的并行索引工作线程数。在 `sysconf(_SC_NPROCESSORS_ONLN)` 报告主机 CPU 而不是 cgroup 的有效配额的容器中很有用。范围 1–256；无效值被忽略并带有警告。 |
```bash
# 将索引存储在自定义目录中
export CBM_CACHE_DIR=~/my-projects/cbm-data
```
## 自定义文件扩展名
通过 JSON 配置文件将其他文件扩展名映射到支持的语言。对于特定框架扩展名（如 Laravel 的 `.blade.php` 或 ES 模块的 `.mjs`）非常有用。
**每个项目**（在您的存储库根目录中）：
```json
// .codebase-memory.json
{"extra_extensions": {".blade.php": "php", ".mjs": "javascript"}}
```
**全局**（适用于所有项目）：
```json
// ~/.config/codebase-memory-mcp/config.json （或 $XDG_CONFIG_HOME/...)
{"extra_extensions": {".twig": "html", ".phtml": "php"}}
```
项目配置覆盖全局配置以解决冲突的扩展名。 未知的语言值被静默跳过。 缺失的配置文件被忽略。
## 持久性
SQLite 数据库存储在 `~/.cache/codebase-memory-mcp/`。在重启后保持不变（WAL 模式，ACID 安全）。要重置：`rm -rf ~/.cache/codebase-memory-mcp/`.
## 故障排除
| 问题 | 修复 |
|---------|-----|
| `/mcp` 未显示服务器 | 检查 `.mcp.json` 路径是否为绝对路径。重启代理。测试：`echo '{}' \| /path/to/binary` 应该输出 JSON。 |
| `index_repository` 失败 | 传递绝对路径：`index_repository(repo_path="/absolute/path")` |
| `trace_path` 返回 0 结果 | 首先使用 `search_graph(name_pattern=".*PartialName.*")` 查找确切名称。 |
| 查询返回错误的项目结果 | 添加 `project="name"` 参数。使用 `list_projects` 查看名称。 |
| 安装后找不到二进制文件 | 添加到 PATH：`export PATH="$HOME/.local/bin:$PATH"` |
| UI 未加载 | 确保您下载了 `ui` 变体并运行 `--ui=true`。检查 `http://localhost:9749`。 |
## 混合语言服务器（Hybrid LSP）
**超越 tree-sitter 的语义类型解析。**
仅 tree-sitter 提供语法抽象语法树（AST）。它能很好地处理命名、结构和调用站点，但无法告诉你 `user.profile.display_name()` 解析为在三个模块外声明的 `Profile.display_name` —— tree-sitter 不跟踪导入、泛型、继承或标准库类型。
codebase-memory-mcp 配备了一个 **轻量级 C 实现的语言类型解析算法**，在结构上受到主要语言服务器的启发和兼容（tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, rust-analyzer），直接嵌入到静态二进制文件中。无需语言服务器进程，无需每个项目设置，无需 API 密钥。我们称这一层为 **混合语言服务器（Hybrid LSP）**：它在每次解析时与 tree-sitter 一起运行，并用类型信息完善 `CALLS`、`USAGE` 和 `RESOLVED_CALLS` 边，使生成的图谱反映出 IDE “跳转到定义”所解析的内容。
**支持完整混合语言服务器的语言：**
| 语言 | 处理内容 |
|----------|-----------------|
| **Python** *(v0.7.0 新增)* | 导入 + 点符号子模块遍历，数据类，`Self` 返回类型，泛型，`@property`，`match/case` 类模式，SQLAlchemy 2.0 `Mapped[T]`，Pydantic `BaseModel`，`typing.Annotated` / `ClassVar` / `Final` / `InitVar`，异步/等待，类方法/静态方法，收窄（`isinstance` / `is not None` / 瓦士运算符），`typing.cast` / `assert_type`，常见标准库（日志，路径，JSON，函数工具）。目标是对惯用代码实现约 95% 的解析。 |
| **TypeScript / JavaScript / JSX / TSX** | 泛型，JSX 组件调度，纯 JS 的 JSDoc 推断，`.d.ts` 声明，模块重新导出，通过返回类型传播的方法链接，每个文件叠加到共享的跨文件注册表 |
| **PHP** *(v0.7.0 新增)* | 命名空间，特质，延迟静态绑定，PHPDoc 推断，参数绑定，返回类型推断 |
| **C#** *(v0.7.0 新增)* | 全局 using，文件作用域命名空间，记录（包括 C# 12 主要构造函数），LINQ 方法语法，`async Task<T>` / `ValueTask<T>` 解包，泛型方法，`this` / `base` 调度，`var` 推断，公共 BCL 标准库 |
| **Go** *(v0.7.0 加强)* | 预建的每个包的跨文件注册表，泛型，嵌入结构体，接口满足，包感知导入解析 |
| **C / C++** *(v0.7.0 加强)* | 预建的每个语言的跨文件注册表，在 C 和 C++ 之间共享；C 端处理宏 + `typedef` 链 + 头文件与源文件链接；C++ 端处理模板，命名空间，`auto` 推断和通过类层次结构的方法解析 |
| **Java** *(v0.8.0 新增)* | 导入（单类型，按需，静态），具有 `this` / `super` 调度的类层次结构，泛型，注解，通过参数数量和参数类型匹配的重载，绑定到函数接口的 lambda / 方法引用，字段类型推断，公共 JDK 标准库 |
| **Kotlin** *(v0.8.0 新增)* | 导入 + 同包解析，类 / 对象 / 同伴对象，扩展函数，数据类，可空类型解包，作用域函数（`let` / `apply` / `run` / `also` / `with`），中缀调用，公共标准库 |
| **Rust** *(v0.8.0 新增)* | `use` 声明 + 模块路径，`impl` 块和特征方法，结构体字段，带有特征边界的泛型，运算符特征糖化，派生宏方法合成，UFCS 静态路径，公共标准预lude |
**两层架构：**
1. **Tree-sitter 传递** — 快速，语法分析，每种语言都运行。提取定义，调用，导入。
2. **混合语言服务器传递** — 类型感知，在 tree-sitter 传递之上按语言运行。使用导入图和每个文件或预建的跨文件定义注册表完善调用边。尚无混合语言服务器传递的语言会回落到文本解析，因此你始终会得到 *一些* 答案。
结果是一个知识图谱，准确性足以驱动 `trace_path` 跨包，继承层次和标准库调用 —— 无需为每个项目支付语言服务器进程的费用。
## 语言支持
158 种语言，均通过编译到二进制文件中的 tree-sitter 语法分析。针对 64 个真实开源仓库（78 到 49K 节点）进行基准测试：
| 层级 | 分数 | 语言 |
|------|-------|-----------|
| **优秀** (>= 90%) | | Lua, Kotlin, C++, Perl, Objective-C, Groovy, C, Bash, Zig, Swift, CSS, YAML, TOML, HTML, SCSS, HCL, Dockerfile |
| **良好** (75-89%) | | Python, TypeScript, TSX, Go, Rust, Java, R, Dart, JavaScript, Erlang, Elixir, Scala, Ruby, PHP, C#, SQL |
| **功能性** (< 75%) | | OCaml, Haskell |
也支持（尚未基准测试）：Ada, Agda, Apex, Assembly (NASM), Astro, AWK, Beancount, BibTeX, Bicep, Bitbake, Blade, Cairo, Cap'n Proto, Clojure, CMake, COBOL, Common Lisp, Crystal, CSV, CUDA, D, Devicetree, Diff, .env, Elm, Emacs Lisp, F#, Fennel, Fish, FORM, Fortran, FunC, GDScript, .gitattributes, .gitignore, Gleam, GLSL, GN, Go module, Go template, GraphQL, Hare, HLSL, Hyprlang, INI, ISPC, Janet, Jinja2, JSDoc, JSON, JSON5, Jsonnet, Julia, Just, Kconfig, KDL, Lean 4, Linker Script, Liquid, LLVM IR, Luau, Magma, Makefile, Markdown, MATLAB, Mermaid, Meson, Move, Nickel, Nim, Nix, Odin, Pascal, Pkl, PO (gettext), Pony, PowerShell, Prisma, .properties, Protobuf, Puppet, PureScript, Racket, Regex, requirements.txt, ReScript, RON, reStructuredText, Scheme, Slang, Smali, Smithy, Solidity, SOQL, SOSL, Squirrel, SSH config, Starlark, Svelte, Sway, SystemVerilog, TableGen, Tcl, Teal, Templ, Thrift, TLA+, Typst, Verilog, VHDL, Vim script, Vue, WGSL, WIT, Wolfram, XML, Zsh.
## 架构
```
src/
main.c 入口点（MCP 标准输入/输出服务器 + CLI + 安装/更新/配置）
mcp/ MCP 服务器（14 种工具，JSON-RPC 2.0，会话检测，自动索引）
cli/ 安装/卸载/更新/配置（10 种代理，钩子，指令）
store/ SQLite 图存储（节点，边，遍历，搜索，Louvain）
pipeline/ 多传递索引（结构 → 定义 → 调用 → HTTP 链接 → 配置 → 测试）
cypher/ Cypher 查询词法分析器，解析器，规划器，执行器
discover/ 文件发现（.gitignore，.cbmignore，符号链接处理）
watcher/ 后台自动同步（git 轮询，自适应间隔）
traces/ 运行时轨迹摄入
ui/ 嵌入式 HTTP 服务器 + 3D 图可视化
foundation/ 平台抽象（线程，文件系统，日志，内存）
internal/cbm/ 提供的 tree-sitter 语法分析器（158 种语言）+ AST 提取引擎
```
## 安全
每个发布版本在发布前都会通过多层流水线验证：
- **VirusTotal** — 所有二进制文件都由 70+ 个防病毒引擎扫描（发布前需要零检测）
- **SLSA Level 3** — 通过 GitHub Actions 生成的加密构建出处；使用 `gh attestation verify <file> --repo DeusData/codebase-memory-mcp` 进行验证
- **Sigstore cosign** — 所有制品的无密钥签名；每个版本中都包含捆绑包
- **SHA-256 校验和** — `checksums.txt` 与每个版本一起发布；由安装脚本在提取前验证
- **CodeQL SAST** — 如果存在任何开放警报，则阻止发布流水线
- **零运行时依赖** — 无传递性供应链；所有库都在编译时提供
### v0.7.0 VirusTotal 扫描
| 二进制文件 | SHA-256 | VirusTotal |
|--------|---------|-----------|
| `linux-amd64` | `8e12bb2d6ead7f20a6d3...` | [0/72 ✅](https://www.virustotal.com/gui/file/8e12bb2d6ead7f20a6d3bf2be1e51f978c38acce810f0734f510d134b039d152/detection) |
| `linux-arm64` | `10f7136bfbf3950c6b2a...` | [0/72 ✅](https://www.virustotal.com/gui/file/10f7136bfbf3950c6b2a1a950bbf85e88b97ee55ab00b4dfbc2a5e9c2ede8672/detection) |
| `darwin-arm64` | `7062a7408906344bf4f8...` | [0/72 ✅](https://www.virustotal.com/gui/file/7062a7408906344bf4f835e9580048af85d12dd2b7cec0edf869df93ad9a0592/detection) |
| `darwin-amd64` | `28c6d640e1a0ac7bfcab...` | [0/72 ✅](https://www.virustotal.com/gui/file/28c6d640e1a0ac7bfcab5094c2186eced5264a20dcdffcb4455a1b28c5df2171/detection) |
| `windows-amd64` | `9c3ddcf78368fd4fa891...` | [0/72 ✅](https://www.virustotal.com/gui/file/9c3ddcf78368fd4fa89156a553641bf1e03640b4fb6dd29a12c84aa5bc98cd86/detection) |
每版本扫描链接也会自动包含在 GitHub 版本说明中。
## 许可证
MIT
连接信息
猜你喜欢
暂无推荐服务器