deusdata--codebase-memory-mcp/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/DeusData/codebase-memory-mcp) · [上游 README](https://github.com/DeusData/codebase-memory-mcp/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# codebase-memory-mcp

[![GitHub Release](https://img.shields.io/github/v/release/DeusData/codebase-memory-mcp?style=flat&color=blue)](https://github.com/DeusData/codebase-memory-mcp/releases/latest)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/DeusData/codebase-memory-mcp/dry-run.yml?label=CI)](https://github.com/DeusData/codebase-memory-mcp/actions/workflows/dry-run.yml)
[![Tests](https://img.shields.io/badge/tests-5604_passing-brightgreen)](https://github.com/DeusData/codebase-memory-mcp)
[![Languages](https://img.shields.io/badge/languages-158-orange)](https://github.com/DeusData/codebase-memory-mcp)
[![Hybrid LSP](https://img.shields.io/badge/Hybrid_LSP-10_languages-blue)](#hybrid-lsp)
[![Agents](https://img.shields.io/badge/agents-11-purple)](https://github.com/DeusData/codebase-memory-mcp)
[![Pure C](https://img.shields.io/badge/pure_C-zero_dependencies-blue)](https://github.com/DeusData/codebase-memory-mcp)
[![Platform](https://img.shields.io/badge/macOS_%7C_Linux_%7C_Windows-supported-lightgrey)](https://github.com/DeusData/codebase-memory-mcp/releases/latest)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/DeusData/codebase-memory-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/DeusData/codebase-memory-mcp)
[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev)
[![VirusTotal](https://img.shields.io/badge/VirusTotal-scanned_every_release-brightgreen?logo=virustotal)](https://github.com/DeusData/codebase-memory-mcp/releases/latest)
[![arXiv](https://img.shields.io/badge/arXiv-2603.27277-b31b1b?logo=arxiv)](https://arxiv.org/abs/2603.27277)

**面向 AI 编程智能体（AI coding agents）的最快、最高效的代码智能引擎。** 普通仓库可在毫秒级完成全量索引，Linux 内核（2800 万行代码、7.5 万个文件）仅需 3 分钟。结构查询响应时间低于 1 毫秒。以单一静态二进制形式发布，支持 macOS、Linux 和 Windows —— 下载、运行 `install`，即可使用。

通过 [tree-sitter](https://tree-sitter.github.io/tree-sitter/) 实现高质量解析，覆盖全部 158 种语言的 AST 分析，并结合 [**Hybrid LSP** 语义类型解析](#hybrid-lsp) 增强 Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin、Rust 和 Perl —— 生成函数、类、调用链、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%，相比逐文件探索，token 用量减少 10 倍，工具调用减少 2.1 倍。

> **安全与信任** — 本工具会读取你的代码库并写入智能体配置文件，这正是其设计用途。若你希望在运行前进行审计，[完整源码在此](https://github.com/DeusData/codebase-memory-mcp) —— 每个发布二进制均经过签名、校验和扫描（70+ 款杀毒引擎）。所有处理 100% 在本地完成；你的代码绝不会离开你的机器。发现安全问题？我们希望知晓 —— 请参阅 [SECURITY.md](SECURITY.md)。安全是我们的首要优先级（Priority #1）。

<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 万行代码、7.5 万个文件）3 分钟完成。RAM 优先流水线：LZ4 压缩、内存 SQLite、融合 Aho-Corasick 模式匹配。索引完成后释放内存。
- **即插即用** — macOS（arm64/amd64）、Linux（arm64/amd64）和 Windows（amd64）单一静态二进制。无需 Docker、无运行时依赖、无需 API 密钥。下载 → `install` → 重启智能体 → 完成。
- **158 种语言** — 内置（vendored）tree-sitter 语法编译进二进制。无需安装，不会损坏。
- **token 用量减少 120 倍** — 5 次结构查询：约 3,400 个 token，而逐文件搜索约 412,000 个。一次图谱查询可替代数十轮 grep/read 循环。
- **11 种智能体，一条命令** — `install` 自动检测 Claude Code、Codex CLI、Gemini CLI、Zed、OpenCode、Antigravity、Aider、KiloCode、VS Code、OpenClaw 和 Kiro —— 为每种智能体配置 MCP 条目、指令文件和 pre-tool 钩子。
- **内置图谱可视化** — 在 `localhost:9749` 提供 3D 交互式 UI（可选 UI 二进制变体）。
- **基础设施即代码（Infrastructure-as-code）索引** — Dockerfile、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. Download the installer
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# 2. (Optional but recommended) Inspect the script
notepad install.ps1

# 3. Unblock the downloaded file (removes Mark-of-the-Web restriction added by browsers/Invoke-WebRequest)
Unblock-File .\install.ps1

# 4. Run it
.\install.ps1

```

> **注意：** 若出现脚本执行策略错误，请先运行 `Set-ExecutionPolicy -Scope Process Bypass`，或使用 `PowerShell -ExecutionPolicy Bypass -File .\install.ps1` 调用。

选项：`--ui`（图谱可视化）、`--skip-config`（仅二进制，不配置智能体）、`--dir=<path>`（自定义安装位置）。

重启你的编程智能体。说 **"Index this project"** —— 完成。

<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 .
   Unblock-File .\install.ps1
   .\install.ps1
   ```

3. **重启** 你的编程智能体。

`install` 命令会自动清除 macOS 隔离属性并对二进制进行临时签名 —— 无需手动执行 `xattr`/`codesign`。
</details>

`install` 命令会自动检测所有已安装的编程智能体，并为每种智能体配置 MCP 服务器条目、指令文件、技能和 pre-tool 钩子。

### 图谱可视化 UI

UI 以独立的 `ui` 构建版本发布（内嵌前端）。各渠道默认安装的是精简的无头（headless）服务器；可通过以下方式选择 UI 构建版本：

- **install.sh：** 添加 `--ui`（见[快速开始](#quick-start)）
- **npm：** `CBM_VARIANT=ui npm install -g codebase-memory-mcp`
- **PyPI：** `CBM_VARIANT=ui pip install codebase-memory-mcp`
- **手动：** 下载 `codebase-memory-mcp-ui-<os>-<arch>` 压缩包

然后运行：

```bash
codebase-memory-mcp --ui=true --port=9749
```

在浏览器中打开 `http://localhost:9749`。UI 作为后台线程与 MCP 服务器并行运行 —— 只要智能体已连接即可使用。

### 自动索引

在 MCP 会话启动时启用自动索引：

```bash
codebase-memory-mcp config set auto_index true
```

启用后，新项目会在首次连接时自动建立索引。此前已索引的项目会注册到后台 watcher，以便持续进行基于 git 的变更检测。可配置文件数量上限：`config set auto_index_limit 50000`。

Watcher 注册由 `auto_watch` 单独控制（默认 `true`）。将 `config set auto_watch false` 设为可阻止会话将其项目注册到后台 watcher——在同时处理多个项目、且希望每个会话仅进行显式索引时很有用。

### 保持最新

```bash
codebase-memory-mcp update
```

MCP 服务器还会在启动时检查更新，并在首次工具调用时若有新版本可用则发出通知。

### 卸载

```bash
codebase-memory-mcp uninstall
```

会移除所有 agent 配置、skills、hooks 和 instructions。不会移除二进制文件或 SQLite 数据库。

## 功能

### 图与分析
- **架构概览**：`get_architecture` 单次调用即可返回语言、包、入口点、路由、热点（hotspots）、边界、层级与聚类
- **架构决策记录（Architecture Decision Records）**：`manage_adr` 在多个会话间持久化架构决策
- **Louvain 社区发现**：通过对调用边聚类来发现功能模块
- **Git diff 影响映射**：`detect_changes` 将未提交变更映射到受影响的符号，并进行风险分类
- **调用图（Call graph）**：跨文件与包解析函数调用（感知 import、类型推断）
- **死代码检测**：找出零调用者的函数，排除入口点
- **类 Cypher 查询**：`MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name`

### 搜索
- **语义搜索**（`semantic_query`）：在整个图上进行向量搜索，由内置的 Nomic `nomic-embed-code` 嵌入（40K tokens，768 维 int8）编译进二进制——无需 API key、无需 Ollama、无需 Docker。11 信号组合评分（TF-IDF、RRI、API/Type/Decorator 签名、AST 概要、数据流、Halstead-lite、MinHash、模块邻近度、图扩散）。
- **BM25 全文搜索**：通过 SQLite FTS5，使用 `cbm_camel_split` 分词器（支持 camelCase / snake_case）
- **结构化搜索**（`search_graph`）：正则名称模式、标签过滤、最小/最大度数、文件范围限定
- **代码搜索**（`search_code`）：仅对已索引文件进行图增强 grep

### 跨服务链接
- **HTTP** 路由 ↔ 调用点匹配，带置信度评分
- **gRPC、GraphQL、tRPC** 服务检测，并提取 protobuf Route
- **通道检测**（`EMITS` / `LISTENS_ON`）：支持 Socket.IO、EventEmitter 及通用 pub-sub 模式，覆盖 8 种语言，并进行常量解析

### 跨仓库智能
- **`CROSS_*` 边** 将同一 store 下已索引的多个仓库中的节点相互链接
- **多星系 3D UI 布局**，用于跨仓库架构可视化
- **跨仓库架构摘要**，汇总已索引集群中的服务、路由与依赖

### 边类型（节选）
- `CALLS`、`IMPORTS`、`DEFINES`、`IMPLEMENTS`、`INHERITS`
- `HTTP_CALLS`、`ASYNC_CALLS`（跨服务）
- `EMITS`、`LISTENS_ON`（通道）
- `DATA_FLOWS`，含参数到形参映射 + 字段访问链
- `SIMILAR_TO`（MinHash + LSH 近克隆检测，Jaccard 评分）
- `SEMANTICALLY_RELATED`（词汇不匹配、同语言，score ≥ 0.80）

### 索引流水线
- **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`）
- **基础设施即代码（Infrastructure-as-code）索引** —— Dockerfile、Kubernetes manifest、Kustomize overlay 作为图节点
- **[混合 LSP 语义类型解析](#hybrid-lsp)**，支持 Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin、Rust 与 Perl —— 语言类型解析算法的轻量 C 实现，在结构上受主流 language server 启发并与之兼容，包括 tsserver / typescript-go、pyright、gopls、Roslyn、Eclipse JDT 与 rust-analyzer（参数绑定、返回类型推断、泛型替换、JSX 组件派发、纯 JS 文件的 JSDoc 推断、PHP 的 namespace + trait + late-static-binding 解析、C# 的文件作用域 namespace + records + LINQ 方法语法、Java 的类层次 + 重载 + lambda 解析、Kotlin 的扩展函数 + 作用域函数解析、Rust 的 trait 方法 + UFCS 解析）
- **RAM 优先流水线**：LZ4 压缩、内存 SQLite、结束时单次 dump。之后释放内存。

### 分发与运行
- **单一静态二进制，零基础设施**：基于 SQLite，持久化到 `~/.cache/codebase-memory-mcp/`
- **自动同步**：后台 watcher 检测文件变更并自动重新索引
- **路由节点**：REST 端点为一等图实体
- **CLI 模式**：`codebase-memory-mcp cli search_graph '{"project": "my-project", "name_pattern": ".*Handler.*"}'`
- **可通过以下渠道获取**：npm、PyPI、Homebrew、Scoop、Winget、Chocolatey、AUR、`go install`

## 团队共享图制品

向仓库提交单个压缩文件，队友即可跳过重新索引。

`.codebase-memory/graph.db.zst` 是位于源码旁的知识图 zstd 压缩快照。索引时会写入或刷新该制品；队友克隆仓库并首次运行 `codebase-memory-mcp` 时，制品会被解压，增量索引再补齐其本地 diff。

- **格式**：SQLite 数据库，剥离索引，`VACUUM INTO` 压缩后，再以 zstd 1.5.7 压缩（典型压缩比 8–13:1）
- **两层级**：
  - **Best**（`zstd -9` + 索引剥离 + `VACUUM INTO`）—— 在显式执行 `index_repository` 时写入
  - **Fast**（`zstd -3`）—— 由 watcher 写入，用于低延迟增量更新
- **引导**：本地无 DB 但存在制品时，`index_repository` 先导入制品，再运行增量索引 —— 避免完整重新索引的开销
- **无合并烦恼**：首次导出时会自动创建带 `merge=ours` 的 `.gitattributes` 行，并发编辑不会在二进制制品上产生冲突
- **可选**：除非你主动提交，否则不会入库。若希望每个人都从零重新索引，可将 `.codebase-memory/` 加入 `.gitignore`。

其结果在理念上类似 graphify 的 `graphify-out/` 目录，但以单个压缩文件呈现，具备显式两层级导出、完整性校验导入，且零合并摩擦。

## 工作原理

codebase-memory-mcp 是一个**结构化分析后端** —— 它构建并查询知识图。它**不包含** LLM。相反，它依赖你的 MCP 客户端（Claude Code，或任何兼容 MCP 的 agent）作为智能层。

```
You: "what calls ProcessOrder?"

Agent calls: trace_path(function_name="ProcessOrder", direction="inbound")

codebase-memory-mcp: executes graph query, returns structured results

Agent: presents the call chain in plain English
```

**为何没有内置 LLM？** 其他代码图工具会嵌入 LLM，用于自然语言 → 图查询的翻译。这意味着额外的 API key、额外成本，以及又要配置一个模型。借助 MCP，你已经在对话的 agent *就是*查询翻译器。

## 性能

在 Apple M3 Pro 上基准测试：

| Operation | Time | Notes |
|-----------|------|-------|
| **Linux kernel full index** | **3 min** | 28M LOC, 75K files → 4.81M nodes, 7.72M edges |
| Linux kernel fast index | 1m 12s | 1.88M nodes |
| Django full index | ~6s | 49K nodes, 196K edges |
| Cypher query | <1ms | Relationship traversal |
| Name search (regex) | <10ms | SQL LIKE pre-filtering |
| Dead code detection | ~150ms | Full graph scan with degree filtering |
| Trace call path (depth=5) | <10ms | BFS traversal |

**RAM 优先流水线（RAM-first pipeline）**：所有索引均在内存中完成（LZ4 HC 压缩读取、内存 SQLite、最后一次性转储）。索引完成后，内存会释放回操作系统。

**Token 效率**：五次结构化查询通过 codebase-memory-mcp 仅消耗约 3,400 个 token，而通过逐文件 grep 探索则消耗约 412,000 个 token——**减少 99.2%**。

## 故障排查与诊断

codebase-memory-mcp **100% 本地运行且不收集任何遥测数据**——你的代码、查询、环境和使用情况永远不会离开你的机器。这一隐私保障也意味着，当你遇到我们无法在本地复现的问题（数小时内内存缓慢攀升、性能回退、或仅在多日实际使用后才会出现的泄漏）时，**除非你主动发送，否则我们完全没有任何数据。** 以下介绍如何自行采集。

### 采集诊断日志

在 MCP 服务器启动前设置 `CBM_DIAGNOSTICS=1`，然后复现问题（让它运行足够久——缓慢泄漏需要时间才能在趋势中显现）。服务器会将两个文件写入系统临时目录（macOS/Linux 为 `$TMPDIR` 或 `/tmp`，Windows 为 `%TEMP%`）：

| 文件 | 说明 |
|------|------|
| `cbm-diagnostics-<pid>.ndjson` | **内存轨迹**——每 5 秒一行 JSON，包含 `rss`、`committed`（Windows commit charge）、`peak_*`、`page_faults`、`fd` 和 `queries`。**这是我们处理内存/泄漏报告所需的文件**——*随时间变化的趋势*才能定位泄漏。服务器退出后**该文件会保留在磁盘上**（便于事后获取），超过约 8 MB 时会轮转到 `.ndjson.1`。 |
| `cbm-diagnostics-<pid>.json` | 仅最新快照——便于快速实时检查。正常退出时会被删除。 |

启动日志会打印两个路径，例如：

```
level=info msg=diagnostics.start snapshot=/tmp/cbm-diagnostics-12345.json trajectory=/tmp/cbm-diagnostics-12345.ndjson interval=5s
```

在代理的 MCP 服务器配置中的 `env` 块内设置该变量，或在启动服务器前 export。

### 需要分享的内容

当你提交内存/性能相关 issue 时，**请附上 `.ndjson` 轨迹文件**——其中不含源代码或查询文本，仅有资源计数器。若不想附加文件，可将其（或代理对其的摘要）粘贴到 issue 中：你的助手可直接读取 NDJSON，并报告 `rss`/`committed` 是否单调增长、增速如何、以及与查询次数的相对关系——这正是我们定位原因所需的信息。

## 安装

### 预编译二进制

| 平台 | 标准版 | 含 Graph 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 可能对未签名软件显示警告。点击 **"More info"** → **"Run anyway"**。使用 `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 安装

```
You: "Install this MCP server: 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                    # standard binary
scripts/build.sh --with-ui          # with graph visualization
# Binary at: build/c/codebase-memory-mcp
```

### 手动 MCP 配置

<details>
<summary>若不想使用 install 命令</summary>

添加到 `~/.claude/.mcp.json`（全局）或项目 `.mcp.json`：

```json
{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}
```

重启你的代理。使用 `/mcp` 验证——你应能看到 `codebase-memory-mcp` 及 14 个工具。

</details>

## 多代理支持

`install` 会自动检测并配置所有已安装的代理：

| 代理 | MCP 配置 | 说明/指令 | Hooks |
|-------|-----------|-------------|-------|
| Claude Code | `.claude/.mcp.json` | 4 Skills | 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` (shared) | `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` | — | — |

**Hooks 在结构上为非阻塞**（退出码 0，所有失败路径亦然）。
对于 Claude Code，`PreToolUse` hook 会拦截 `Grep`/`Glob`（从不拦截 `Read`——
对 `Read` 进行门控会破坏先读后改不变量），当搜索
token 与已索引符号匹配时，通过
`search_graph` 将其作为 `additionalContext` 注入，
使代理在常规搜索结果之外还能获得结构化上下文。对于 Codex、Gemini CLI 和 Antigravity，`SessionStart` hook
会以会话上下文形式注入一行代码发现提醒（Gemini CLI 还会
保留其 `BeforeTool` 提醒）。
已安装的 Claude shim 文件名为 `cbm-code-discovery-gate`，以
兼容既有安装；尽管名称沿用旧版，它
从不进行门控，也从不阻塞。

## CLI 模式

每个 MCP 工具均可从命令行调用：

```bash
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/repo"}'
codebase-memory-mcp cli list_projects

# Use the "name" returned by list_projects as the project value.
codebase-memory-mcp cli search_graph '{"project": "my-project", "name_pattern": ".*Handler.*", "label": "Function"}'
codebase-memory-mcp cli trace_path '{"project": "my-project", "function_name": "Search", "direction": "both"}'
codebase-memory-mcp cli query_graph '{"project": "my-project", "query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'
codebase-memory-mcp cli --raw search_graph '{"project": "my-project", "label": "Function"}' | jq '.results[].name'
```

## MCP 工具

### 索引

| 工具 | 说明 |
|------|------|
| `index_repository` | 将仓库索引到图中。之后自动同步保持最新。 |
| `list_projects` | 列出所有已索引项目及其节点/边数量。 |
| `delete_project` | 移除项目及其全部图数据。 |
| `index_status` | 检查项目的索引状态。 |

### 查询

| 工具 | 说明 |
|------|-------------|
| `search_graph` | 按标签、名称模式、文件模式、度过滤进行结构化搜索。通过 limit/offset 分页。 |
| `trace_path` | BFS 遍历——谁调用了某函数，以及它调用了什么（别名：`trace_call_path`）。深度 1-5。 |
| `detect_changes` | 将 git diff 映射到受影响的符号 + 带风险分级的影响半径（blast radius）。 |
| `query_graph` | 执行类 Cypher 的图查询（只读）。 |
| `get_graph_schema` | 各标签的节点/边数量、关系模式、属性定义。请先运行此项。 |
| `get_code_snippet` | 按限定名读取函数的源代码。 |
| `get_architecture` | 代码库概览：语言、包、路由、热点、簇、ADR。 |
| `search_code` | 在已索引的项目文件中进行类 Grep 的文本搜索。 |
| `manage_adr` | 架构决策记录（Architecture Decision Records）的 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 语法）。符号链接始终跳过。

完整的 `.cbmignore` 用法说明（语法、各忽略层的优先级、取反语义）见 [docs/cbmignore.md](docs/cbmignore.md)。

## 配置

```bash
codebase-memory-mcp config list                          # show all settings
codebase-memory-mcp config set auto_index true           # auto-index on session start
codebase-memory-mcp config set auto_index_limit 50000    # max files for auto-index
codebase-memory-mcp config set auto_watch false          # don't register background git watcher (default: true)
codebase-memory-mcp config reset auto_index              # reset to default
```

### 环境变量

| 变量 | 默认值 | 说明 |
|----------|---------|-------------|
| `CBM_ALLOWED_ROOT` | *(未设置)* | 将 `index_repository` 限制在此目录内的路径。设置后，若 `repo_path` 在解析（符号链接 / `..` 解析之后）落在该根目录之外，则会被拒绝；未设置时不加限制。适用于服务器可能由不可信调用方驱动的场景，例如智能体或跨租户部署。 |
| `CBM_CACHE_DIR` | `~/.cache/codebase-memory-mcp` | 覆盖数据库存储目录。所有项目索引与配置都保存在此。 |
| `CBM_DIAGNOSTICS` | `false` | 设为 `1` 或 `true`，以启用向 `/tmp/cbm-diagnostics-<pid>.json` 定期输出诊断信息。 |
| `CBM_DOWNLOAD_URL` | *(GitHub releases)* | 覆盖更新下载 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；无效值会被忽略并给出警告。 |
| `CBM_MEM_BUDGET_MB` | *(自动检测)* | 用显式的 MiB 上限覆盖内存中图的预算，优先于 `ram_fraction × total_RAM` 默认值。适用于没有 cgroup 限制的裸机主机，或将预算固定在 cgroup 限制*之下*，以便为同机其他进程留出余量。必须为正整数；会被钳制到检测到的总 RAM（记录为 `mem.budget.clamped`），非数字或非正值会被忽略并给出警告（`mem.budget.env.invalid`）。 |
| `CBM_DUMP_VERIFY_MIN_RATIO` | `0.5` | 索引完成后，比较持久化的 SQLite 节点数与内存转储节点数。当持久化节点数低于已提交节点数的该比例（且已提交 > 50）时，`index_repository` 返回 `status:"degraded"`，而不是静默的 `indexed`。范围 0–1；设为 `0` 可禁用。无效值会被忽略并给出警告。 |

```bash
# Store indexes in a custom directory
export CBM_CACHE_DIR=~/my-projects/cbm-data
```

## 自定义文件扩展名

JSON 配置文件支持单个键 `extra_extensions`，用于将额外的文件扩展名映射到受支持的语言。适用于框架专用扩展名，例如 `.blade.php`（Laravel）或 `.mjs`（ES modules）。（其他可调项见 [环境变量](#environment-variables) 以及上文的 `config` 子命令。）

需要完整的配置文件参考？见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。

**按项目**（在仓库根目录）：
```json
// .codebase-memory.json
{"extra_extensions": {".blade.php": "php", ".mjs": "javascript"}}
```

**全局**（应用于所有项目）：
```json
// ~/.config/codebase-memory-mcp/config.json  (or $XDG_CONFIG_HOME/...)
{"extra_extensions": {".twig": "html", ".phtml": "php"}}
```

每条将扩展名（**必须**以 `.` 开头）映射到语言名。语言名匹配**不区分大小写**。可接受的值（括号内为别名）为：

`bash` (`sh`), `c`, `c++` (`cpp`), `c#` (`csharp`), `clojure`, `cmake`, `cobol`, `common lisp` (`commonlisp`, `lisp`), `css`, `cuda`, `dart`, `dockerfile`, `elixir`, `elm`, `emacs lisp` (`emacslisp`), `erlang`, `f#` (`fsharp`), `form`, `fortran`, `glsl`, `go`, `graphql`, `groovy`, `haskell`, `hcl` (`terraform`), `html`, `ini`, `java`, `javascript`, `json`, `julia`, `kotlin`, `lean`, `lua`, `magma`, `makefile`, `markdown`, `matlab`, `meson`, `nix`, `objective-c` (`objc`), `ocaml`, `perl`, `php`, `protobuf`, `python`, `r`, `ruby`, `rust`, `scala`, `scss`, `sql`, `svelte`, `swift`, `toml`, `tsx`, `typescript`, `verilog`, `vimscript`, `vue`, `wolfram`, `xml`, `yaml`, `zig`。

对冲突的扩展名，项目配置覆盖全局配置。语言名未知、或扩展名不以 `.` 开头的条目会被跳过，并在 stderr 记录警告（在默认的 `info` 日志级别下可见）。缺失的配置文件会被忽略。

## 持久化

SQLite 数据库存储在 `~/.cache/codebase-memory-mcp/`。跨重启持久保存（WAL 模式，ACID 安全）。若要重置：`rm -rf ~/.cache/codebase-memory-mcp/`。

## 故障排除

| 问题 | 处理 |
|---------|-----|
| `/mcp` 未显示服务器 | 检查 `.mcp.json` 路径是否为绝对路径。重启 agent。测试：`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 不跟踪 import、泛型、继承或标准库类型。

codebase-memory-mcp 内置了**轻量级 C 语言实现的类型解析算法**，在结构上受主流语言服务器（language server）启发并与之兼容（tsserver / typescript-go、pyright、gopls、Roslyn、Eclipse JDT、rust-analyzer），直接嵌入静态二进制文件中。无需语言服务器进程、无需按项目配置、无需 API 密钥。我们将这一层称为 **Hybrid LSP**：它在每次解析时与 tree-sitter 并行运行，并用类型信息细化 `CALLS`、`USAGE` 和 `RESOLVED_CALLS` 边，从而使生成的图谱与 IDE 中「转到定义」（Go to Definition）的解析结果一致。

**已完整支持 Hybrid LSP 的语言：**

| Language | What it handles |
|----------|-----------------|
| **Python** *(new in v0.7.0)* | imports + 点号子模块遍历、dataclasses、`Self` 返回类型、泛型、`@property`、`match/case` 类模式、SQLAlchemy 2.0 `Mapped[T]`、Pydantic `BaseModel`、`typing.Annotated` / `ClassVar` / `Final` / `InitVar`、async/await、classmethod/staticmethod、收窄（`isinstance` / `is not None` / walrus）、`typing.cast` / `assert_type`、常用标准库（logging、pathlib、json、functools）。目标是在惯用代码上达到约 95% 的解析率。 |
| **TypeScript / JavaScript / JSX / TSX** | 泛型、JSX 组件分派、纯 JS 的 JSDoc 推断、`.d.ts` 声明、模块再导出、通过返回类型传播实现的方法链、按文件叠加并链接到共享跨文件注册表 |
| **PHP** *(new in v0.7.0)* | 命名空间、trait、late-static-binding、PHPDoc 推断、参数绑定、返回类型推断 |
| **C#** *(new in v0.7.0)* | 全局 using、文件作用域命名空间、record（含 C# 12 主构造函数）、LINQ 方法语法、`async Task<T>` / `ValueTask<T>` 解包、泛型方法、`this` / `base` 分派、`var` 推断、常用 BCL 标准库 |
| **Go** *(sharpened in v0.7.0)* | 预构建的按包跨文件注册表、泛型、嵌入结构体、接口满足、包感知的 import 解析 |
| **C / C++** *(sharpened in v0.7.0)* | 预构建的按语言跨文件注册表，C 与 C++ 共享；C 侧处理宏 + `typedef` 链 + 头文件与源文件链接；C++ 侧处理模板、命名空间、`auto` 推断，以及通过类层次结构进行的方法解析 |
| **Java** *(new in v0.8.0)* | import（单类型、按需、静态）、带 `this` / `super` 分派的类层次结构、泛型、注解、按参数个数与参数类型的重载匹配、绑定到函数式接口的 lambda / 方法引用、字段类型推断、常用 JDK 标准库 |
| **Kotlin** *(new in v0.8.0)* | import + 同包解析、class / object / companion object、扩展函数、data class、可空类型解包、作用域函数（`let` / `apply` / `run` / `also` / `with`）、中缀调用、常用标准库 |
| **Rust** *(new in v0.8.0)* | `use` 声明 + 模块路径、`impl` 块与 trait 方法、结构体字段、带 trait 约束的泛型、运算符 trait 脱糖、derive 宏方法合成、UFCS 静态路径、常用 std prelude |
| **Perl** | 包 + `@ISA` / `use parent` / `use base` 继承及方法解析顺序（method-resolution-order）分派、`SUPER::` 调用、Exporter（`use Foo qw(...)`）import 映射、`bless` / `ref($class)\|\|$class` self 类型推断、限定 `Pkg::sub` 静态调用、精选 perlfunc + CPAN OOP 标准库；未解析的接收者不产生边（零边保证） |

**双层架构：**

1. **Tree-sitter pass** —— 快速、语法级，对全部 158 种语言运行。提取定义、调用、import。
2. **Hybrid LSP pass** —— 类型感知，在 tree-sitter pass 之上按语言运行。利用 import 图以及按文件或预构建的跨文件定义注册表来细化调用边。尚未支持 Hybrid LSP pass 的语言会回退到文本解析，因此你总能得到*某种*答案。

最终得到的知识图谱足够准确，可驱动跨包、继承层次结构和标准库调用的 `trace_path` —— 且无需为每个项目支付语言服务器进程的开销。

## Language Support

158 种语言，均通过编入二进制的 vendored tree-sitter 语法进行解析。已在 64 个真实开源仓库上完成基准测试（节点数从 78 到 49K）：

| Tier | Score | Languages |
|------|-------|-----------|
| **Excellent** (>= 90%) | | Lua、Kotlin、C++、Perl、Objective-C、Groovy、C、Bash、Zig、Swift、CSS、YAML、TOML、HTML、SCSS、HCL、Dockerfile |
| **Good** (75-89%) | | Python、TypeScript、TSX、Go、Rust、Java、R、Dart、JavaScript、Erlang、Elixir、Scala、Ruby、PHP、C#、SQL |
| **Functional** (< 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。

## Architecture

```
src/
  main.c              Entry point (MCP stdio server + CLI + install/update/config)
  mcp/                MCP server (14 tools, JSON-RPC 2.0, session detection, auto-index)
  cli/                Install/uninstall/update/config (10 agents, hooks, instructions)
  store/              SQLite graph storage (nodes, edges, traversal, search, Louvain)
  pipeline/           Multi-pass indexing (structure → definitions → calls → HTTP links → config → tests)
  cypher/             Cypher query lexer, parser, planner, executor
  discover/           File discovery (.gitignore, .cbmignore, symlink handling)
  watcher/            Background auto-sync (git polling, adaptive intervals)
  traces/             Runtime trace ingestion
  ui/                 Embedded HTTP server + 3D graph visualization
  foundation/         Platform abstractions (threads, filesystem, logging, memory)
internal/cbm/         Vendored tree-sitter grammars (158 languages) + AST extraction engine
```

## Security

每次发布前，所有发行版二进制文件都会经过多层流水线验证：

- **VirusTotal** —— 所有二进制文件由 70+ 款杀毒引擎扫描（发布前要求零检出）
- **SLSA Level 3** —— 由受信任的 GitHub Actions 构建工作流生成加密构建溯源（build provenance）；使用 `gh attestation verify <file> --repo DeusData/codebase-memory-mcp --signer-workflow DeusData/codebase-memory-mcp/.github/workflows/_build.yml` 进行验证
- **Sigstore cosign** —— 对所有制品进行无密钥签名；每个发行版均包含 bundle
- **SHA-256 checksums** —— 每次发行都会发布 `checksums.txt`；安装脚本在解压前都会进行校验
- **CodeQL SAST** —— 若仍存在未关闭的告警，将阻断发布流水线
- **Zero runtime dependencies** —— 无传递性供应链；所有库在编译时 vendored

### v0.7.0 VirusTotal scans

| Binary | 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 Release 说明中。

## 许可证

MIT