wehub/deusdata--codebase-memory-mcp
1
0
Fork 0
Code Issues Pull Requests Actions 7 Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: make Chinese README the default
CodeQL SAST / analyze (push) Waiting to run
Details
OpenSSF Scorecard / scorecard (push) Waiting to run
Details
DCO / dco (push) Waiting to run
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 10:09:10 +00:00
parent 7625e32ed8
commit 938d2268fb
1 changed files with 263 additions and 257 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+263 -257
View File
@@ -1,3 +1,9 @@
<!-- 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 # 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) [![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)
@@ -14,44 +20,44 @@
[![VirusTotal](https://img.shields.io/badge/VirusTotal-scanned_every_release-brightgreen?logo=virustotal)](https://github.com/DeusData/codebase-memory-mcp/releases/latest) [![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) [![arXiv](https://img.shields.io/badge/arXiv-2603.27277-b31b1b?logo=arxiv)](https://arxiv.org/abs/2603.27277)
**The fastest and most efficient code intelligence engine for AI coding agents.** Full-indexes an average repository in milliseconds, the Linux kernel (28M LOC, 75K files) in 3 minutes. Answers structural queries in under 1ms. Ships as a single static binary for macOS, Linux, and Windows — download, run `install`, done. **面向 AI 编程智能体（AI coding agents）的最快、最高效的代码智能引擎。** 普通仓库可在毫秒级完成全量索引，Linux 内核（2800 万行代码、7.5 万个文件）仅需 3 分钟。结构查询响应时间低于 1 毫秒。以单一静态二进制形式发布，支持 macOS、Linux 和 Windows —— 下载、运行 `install`，即可使用。
High-quality parsing through [tree-sitter](https://tree-sitter.github.io/tree-sitter/) AST analysis across all 158 languages, enhanced with [**Hybrid LSP** semantic type resolution](#hybrid-lsp) for Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl — producing a persistent knowledge graph of functions, classes, call chains, HTTP routes, and cross-service links. 14 MCP tools. Zero dependencies. Plug and play across 11 coding agents. 通过 [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 种编程智能体中即插即用。
> **Research** — The design and benchmarks behind this project are described in the preprint [*Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP*](https://arxiv.org/abs/2603.27277) (arXiv:2603.27277). Evaluated across 31 real-world repositories: 83% answer quality, 10× fewer tokens, 2.1× fewer tool calls vs. file-by-file exploration. > **研究** — 本项目的设计与基准测试详见预印本 [*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 倍。
> **Security & Trust** — This tool reads your codebase and writes to your agent configuration files. That is what it is designed to do. If you prefer to audit before running, the [full source is here](https://github.com/DeusData/codebase-memory-mcp) — every release binary is signed, checksummed, and scanned by 70+ antivirus engines. All processing happens 100% locally; your code never leaves your machine. Found a security issue? We want to know — see [SECURITY.md](SECURITY.md). Security is Priority #1 for us. > **安全与信任** — 本工具会读取你的代码库并写入智能体配置文件，这正是其设计用途。若你希望在运行前进行审计，[完整源码在此](https://github.com/DeusData/codebase-memory-mcp) —— 每个发布二进制均经过签名、校验和扫描（70+ 款杀毒引擎）。所有处理 100% 在本地完成；你的代码绝不会离开你的机器。发现安全问题？我们希望知晓 —— 请参阅 [SECURITY.md](SECURITY.md)。安全是我们的首要优先级（Priority #1）。
<p align="center"> <p align="center">
<img src="docs/graph-ui-screenshot.png" alt="Graph visualization UI showing the codebase-memory-mcp knowledge graph" width="800"> <img src="docs/graph-ui-screenshot.png" alt="Graph visualization UI showing the codebase-memory-mcp knowledge graph" width="800">
<br> <br>
<em>Built-in 3D graph visualization (UI variant) — explore your knowledge graph at localhost:9749</em> <em>内置 3D 图谱可视化（UI 变体）—— 在 localhost:9749 探索你的知识图谱</em>
</p> </p>
## Why codebase-memory-mcp ## 为什么选择 codebase-memory-mcp
- **Extreme indexing speed** — Linux kernel (28M LOC, 75K files) in 3 minutes. RAM-first pipeline: LZ4 compression, in-memory SQLite, fused Aho-Corasick pattern matching. Memory released after indexing. - **极致索引速度** — Linux 内核（2800 万行代码、7.5 万个文件）3 分钟完成。RAM 优先流水线：LZ4 压缩、内存 SQLite、融合 Aho-Corasick 模式匹配。索引完成后释放内存。
- **Plug and play** — single static binary for macOS (arm64/amd64), Linux (arm64/amd64), and Windows (amd64). No Docker, no runtime dependencies, no API keys. Download → `install` → restart agent → done. - **即插即用** — macOS（arm64/amd64）、Linux（arm64/amd64）和 Windows（amd64）单一静态二进制。无需 Docker、无运行时依赖、无需 API 密钥。下载 → `install` → 重启智能体 → 完成。
- **158 languages** — vendored tree-sitter grammars compiled into the binary. Nothing to install, nothing that breaks. - **158 种语言** — 内置（vendored）tree-sitter 语法编译进二进制。无需安装，不会损坏。
- **120x fewer tokens** — 5 structural queries: ~3,400 tokens vs ~412,000 via file-by-file search. One graph query replaces dozens of grep/read cycles. - **token 用量减少 120 倍** — 5 次结构查询：约 3,400 个 token，而逐文件搜索约 412,000 个。一次图谱查询可替代数十轮 grep/read 循环。
- **11 agents, one command** — `install` auto-detects Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro — configures MCP entries, instruction files, and pre-tool hooks for each. - **11 种智能体，一条命令** — `install` 自动检测 Claude Code、Codex CLI、Gemini CLI、Zed、OpenCode、Antigravity、Aider、KiloCode、VS Code、OpenClaw 和 Kiro —— 为每种智能体配置 MCP 条目、指令文件和 pre-tool 钩子。
- **Built-in graph visualization** — 3D interactive UI at `localhost:9749` (optional UI binary variant). - **内置图谱可视化** — 在 `localhost:9749` 提供 3D 交互式 UI（可选 UI 二进制变体）。
- **Infrastructure-as-code indexing** — Dockerfiles, Kubernetes manifests, and Kustomize overlays indexed as graph nodes with cross-references. `Resource` nodes for K8s kinds, `Module` nodes for Kustomize overlays with `IMPORTS` edges to referenced resources. - **基础设施即代码（Infrastructure-as-code）索引** — Dockerfile、Kubernetes 清单和 Kustomize 叠加层作为图谱节点索引并建立交叉引用。`Resource` 节点对应 K8s 资源类型，`Module` 节点对应 Kustomize 叠加层，并通过 `IMPORTS` 边连接被引用的资源。
- **14 MCP tools** — search, trace, architecture, impact analysis, Cypher queries, dead code detection, cross-service HTTP linking, ADR management, and more. - **14 个 MCP 工具** — 搜索、追踪、架构分析、影响分析、Cypher 查询、死代码检测、跨服务 HTTP 链接、ADR 管理等。
## Quick Start ## 快速开始
**One-line install** (macOS / Linux): **一行安装**（macOS / Linux）：
```bash ```bash
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
``` ```
With graph visualization UI: 含图谱可视化 UI：
```bash ```bash
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui
``` ```
**Windows** (PowerShell): **Windows**（PowerShell）：
```powershell ```powershell
# 1. Download the installer # 1. Download the installer
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1 Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
@@ -67,154 +73,154 @@ Unblock-File .\install.ps1
``` ```
> **Note:** If you see a script execution policy error, run `Set-ExecutionPolicy -Scope Process Bypass` first, or invoke with `PowerShell -ExecutionPolicy Bypass -File .\install.ps1`. > **注意：** 若出现脚本执行策略错误，请先运行 `Set-ExecutionPolicy -Scope Process Bypass`，或使用 `PowerShell -ExecutionPolicy Bypass -File .\install.ps1` 调用。
Options: `--ui` (graph visualization), `--skip-config` (binary only, no agent setup), `--dir=<path>` (custom location). 选项：`--ui`（图谱可视化）、`--skip-config`（仅二进制，不配置智能体）、`--dir=<path>`（自定义安装位置）。
Restart your coding agent. Say **"Index this project"** — done. 重启你的编程智能体。说 **"Index this project"** —— 完成。
<details> <details>
<summary>Manual install</summary> <summary>手动安装</summary>
1. **Download** the archive for your platform from the [latest release](https://github.com/DeusData/codebase-memory-mcp/releases/latest): 1. 从 [最新发布版](https://github.com/DeusData/codebase-memory-mcp/releases/latest): 下载适合你平台的压缩包
- `codebase-memory-mcp-<os>-<arch>.tar.gz` (macOS/Linux) or `.zip` (Windows) — standard - `codebase-memory-mcp-<os>-<arch>.tar.gz`（macOS/Linux）或 `.zip`（Windows）—— 标准版
- `codebase-memory-mcp-ui-<os>-<arch>.tar.gz` / `.zip` — with graph visualization - `codebase-memory-mcp-ui-<os>-<arch>.tar.gz` / `.zip` —— 含图谱可视化
2. **Extract and install** (each archive includes `install.sh` or `install.ps1`): 2. **解压并安装**（每个压缩包均包含 `install.sh` 或 `install.ps1`）：
macOS / Linux: macOS / Linux：
```bash ```bash
tar xzf codebase-memory-mcp-*.tar.gz tar xzf codebase-memory-mcp-*.tar.gz
./install.sh ./install.sh
``` ```
Windows (PowerShell): Windows (PowerShell)：
```powershell ```powershell
Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath . Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
Unblock-File .\install.ps1 Unblock-File .\install.ps1
.\install.ps1 .\install.ps1
``` ```
3. **Restart** your coding agent. 3. **重启** 你的编程智能体。
The `install` command automatically strips macOS quarantine attributes and ad-hoc signs the binary — no manual `xattr`/`codesign` needed. `install` 命令会自动清除 macOS 隔离属性并对二进制进行临时签名 —— 无需手动执行 `xattr`/`codesign`。
</details> </details>
The `install` command auto-detects all installed coding agents and configures MCP server entries, instruction files, skills, and pre-tool hooks for each. `install` 命令会自动检测所有已安装的编程智能体，并为每种智能体配置 MCP 服务器条目、指令文件、技能和 pre-tool 钩子。
### Graph Visualization UI ### 图谱可视化 UI
The UI ships as a separate `ui` build (it embeds the frontend). The default install on every channel is the lean, headless server; opt into the UI build with: UI 以独立的 `ui` 构建版本发布（内嵌前端）。各渠道默认安装的是精简的无头（headless）服务器；可通过以下方式选择 UI 构建版本：
- **install.sh:** add `--ui` (see [Quick Start](#quick-start)) - **install.sh：** 添加 `--ui`（见[快速开始](#quick-start)）
- **npm:** `CBM_VARIANT=ui npm install -g codebase-memory-mcp` - **npm：** `CBM_VARIANT=ui npm install -g codebase-memory-mcp`
- **PyPI:** `CBM_VARIANT=ui pip install codebase-memory-mcp` - **PyPI：** `CBM_VARIANT=ui pip install codebase-memory-mcp`
- **Manual:** download the `codebase-memory-mcp-ui-<os>-<arch>` archive - **手动：** 下载 `codebase-memory-mcp-ui-<os>-<arch>` 压缩包
Then run it: 然后运行：
```bash ```bash
codebase-memory-mcp --ui=true --port=9749 codebase-memory-mcp --ui=true --port=9749
``` ```
Open `http://localhost:9749` in your browser. The UI runs as a background thread alongside the MCP server — it's available whenever your agent is connected. 在浏览器中打开 `http://localhost:9749`。UI 作为后台线程与 MCP 服务器并行运行 —— 只要智能体已连接即可使用。
### Auto-Index ### 自动索引
Enable automatic indexing on MCP session start: 在 MCP 会话启动时启用自动索引：
```bash ```bash
codebase-memory-mcp config set auto_index true codebase-memory-mcp config set auto_index true
``` ```
When enabled, new projects are indexed automatically on first connection. Previously-indexed projects are registered with the background watcher for ongoing git-based change detection. Configurable file limit: `config set auto_index_limit 50000`. 启用后，新项目会在首次连接时自动建立索引。此前已索引的项目会注册到后台 watcher，以便持续进行基于 git 的变更检测。可配置文件数量上限：`config set auto_index_limit 50000`。
Watcher registration is controlled separately by `auto_watch` (default `true`). Set `config set auto_watch false` to keep a session from registering its project with the background watcher — useful when working across many projects and you want each session contained to explicit indexing. Watcher 注册由 `auto_watch` 单独控制（默认 `true`）。将 `config set auto_watch false` 设为可阻止会话将其项目注册到后台 watcher——在同时处理多个项目、且希望每个会话仅进行显式索引时很有用。
### Keeping Up to Date ### 保持最新
```bash ```bash
codebase-memory-mcp update codebase-memory-mcp update
``` ```
The MCP server also checks for updates on startup and notifies on the first tool call if a newer release is available. MCP 服务器还会在启动时检查更新，并在首次工具调用时若有新版本可用则发出通知。
### Uninstall ### 卸载
```bash ```bash
codebase-memory-mcp uninstall codebase-memory-mcp uninstall
``` ```
Removes all agent configs, skills, hooks, and instructions. Does not remove the binary or SQLite databases. 会移除所有 agent 配置、skills、hooks 和 instructions。不会移除二进制文件或 SQLite 数据库。
## Features ## 功能
### Graph & analysis ### 图与分析
- **Architecture overview**: `get_architecture` returns languages, packages, entry points, routes, hotspots, boundaries, layers, and clusters in a single call - **架构概览**：`get_architecture` 单次调用即可返回语言、包、入口点、路由、热点（hotspots）、边界、层级与聚类
- **Architecture Decision Records**: `manage_adr` persists architectural decisions across sessions - **架构决策记录（Architecture Decision Records）**：`manage_adr` 在多个会话间持久化架构决策
- **Louvain community detection**: Discovers functional modules by clustering call edges - **Louvain 社区发现**：通过对调用边聚类来发现功能模块
- **Git diff impact mapping**: `detect_changes` maps uncommitted changes to affected symbols with risk classification - **Git diff 影响映射**：`detect_changes` 将未提交变更映射到受影响的符号，并进行风险分类
- **Call graph**: Resolves function calls across files and packages (import-aware, type-inferred) - **调用图（Call graph）**：跨文件与包解析函数调用（感知 import、类型推断）
- **Dead code detection**: Finds functions with zero callers, excluding entry points - **死代码检测**：找出零调用者的函数，排除入口点
- **Cypher-like queries**: `MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name` - **类 Cypher 查询**：`MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name`
### Search ### 搜索
- **Semantic search** (`semantic_query`): vector search across the entire graph, powered by bundled Nomic `nomic-embed-code` embeddings (40K tokens, 768d int8) compiled into the binary — no API key, no Ollama, no Docker. 11-signal combined scoring (TF-IDF, RRI, API/Type/Decorator signatures, AST profiles, data flow, Halstead-lite, MinHash, module proximity, graph diffusion). - **语义搜索**（`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 full-text search** via SQLite FTS5 with `cbm_camel_split` tokenizer (camelCase / snake_case aware) - **BM25 全文搜索**：通过 SQLite FTS5，使用 `cbm_camel_split` 分词器（支持 camelCase / snake_case）
- **Structural search** (`search_graph`): regex name patterns, label filters, min/max degree, file scoping - **结构化搜索**（`search_graph`）：正则名称模式、标签过滤、最小/最大度数、文件范围限定
- **Code search** (`search_code`): graph-augmented grep over indexed files only - **代码搜索**（`search_code`）：仅对已索引文件进行图增强 grep
### Cross-service linking ### 跨服务链接
- **HTTP** route ↔ call-site matching with confidence scoring - **HTTP** 路由 ↔ 调用点匹配，带置信度评分
- **gRPC, GraphQL, tRPC** service detection with protobuf Route extraction - **gRPC、GraphQL、tRPC** 服务检测，并提取 protobuf Route
- **Channel detection** (`EMITS` / `LISTENS_ON`) for Socket.IO, EventEmitter, and generic pub-sub patterns across 8 languages with constant resolution - **通道检测**（`EMITS` / `LISTENS_ON`）：支持 Socket.IO、EventEmitter 及通用 pub-sub 模式，覆盖 8 种语言，并进行常量解析
### Cross-repo intelligence ### 跨仓库智能
- **`CROSS_*` edges** link nodes across multiple repos indexed under the same store - **`CROSS_*` 边** 将同一 store 下已索引的多个仓库中的节点相互链接
- **Multi-galaxy 3D UI layout** for cross-repo architecture visualization - **多星系 3D UI 布局**，用于跨仓库架构可视化
- **Cross-repo architecture summary** combining services, routes, and dependencies across the indexed fleet - **跨仓库架构摘要**，汇总已索引集群中的服务、路由与依赖
### Edge types (selected) ### 边类型（节选）
- `CALLS`, `IMPORTS`, `DEFINES`, `IMPLEMENTS`, `INHERITS` - `CALLS`、`IMPORTS`、`DEFINES`、`IMPLEMENTS`、`INHERITS`
- `HTTP_CALLS`, `ASYNC_CALLS` (cross-service) - `HTTP_CALLS`、`ASYNC_CALLS`（跨服务）
- `EMITS`, `LISTENS_ON` (channels) - `EMITS`、`LISTENS_ON`（通道）
- `DATA_FLOWS` with arg-to-param mapping + field access chains - `DATA_FLOWS`，含参数到形参映射 + 字段访问链
- `SIMILAR_TO` (MinHash + LSH near-clone detection, Jaccard scored) - `SIMILAR_TO`（MinHash + LSH 近克隆检测，Jaccard 评分）
- `SEMANTICALLY_RELATED` (vocabulary-mismatch, same-language, score ≥ 0.80) - `SEMANTICALLY_RELATED`（词汇不匹配、同语言，score ≥ 0.80）
### Indexing pipeline ### 索引流水线
- **158 vendored tree-sitter grammars** compiled into the binary - **158 个 vendored tree-sitter 语法** 编译进二进制
- **Generic package / module resolution** — bare specifiers like `@myorg/pkg`, `github.com/foo/bar`, `use my_crate::foo` resolved via manifest scanning (`package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `composer.json`, `pubspec.yaml`, `pom.xml`, `build.gradle`, `mix.exs`, `*.gemspec`) - **通用包 / 模块解析** —— 裸说明符如 `@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 indexing** — Dockerfiles, Kubernetes manifests, Kustomize overlays as graph nodes - **基础设施即代码（Infrastructure-as-code）索引** —— Dockerfile、Kubernetes manifest、Kustomize overlay 作为图节点
- **[Hybrid LSP semantic type resolution](#hybrid-lsp)** for Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl — a lightweight C implementation of language type-resolution algorithms, structurally inspired by and compatible with major language servers including tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, and rust-analyzer (parameter binding, return-type inference, generic substitution, JSX component dispatch, JSDoc inference for plain JS files, namespace + trait + late-static-binding resolution for PHP, file-scoped namespaces + records + LINQ method syntax for C#, class-hierarchy + overload + lambda resolution for Java, extension-function + scope-function resolution for Kotlin, trait-method + UFCS resolution for Rust) - **[混合 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-first pipeline**: LZ4 compression, in-memory SQLite, single dump at end. Memory released after. - **RAM 优先流水线**：LZ4 压缩、内存 SQLite、结束时单次 dump。之后释放内存。
### Distribution & operation ### 分发与运行
- **Single static binary, zero infrastructure**: SQLite-backed, persists to `~/.cache/codebase-memory-mcp/` - **单一静态二进制，零基础设施**：基于 SQLite，持久化到 `~/.cache/codebase-memory-mcp/`
- **Auto-sync**: Background watcher detects file changes and re-indexes automatically - **自动同步**：后台 watcher 检测文件变更并自动重新索引
- **Route nodes**: REST endpoints are first-class graph entities - **路由节点**：REST 端点为一等图实体
- **CLI mode**: `codebase-memory-mcp cli search_graph '{"project": "my-project", "name_pattern": ".*Handler.*"}'` - **CLI 模式**：`codebase-memory-mcp cli search_graph '{"project": "my-project", "name_pattern": ".*Handler.*"}'`
- **Available on**: npm, PyPI, Homebrew, Scoop, Winget, Chocolatey, AUR, `go install` - **可通过以下渠道获取**：npm、PyPI、Homebrew、Scoop、Winget、Chocolatey、AUR、`go install`
## Team-Shared Graph Artifact ## 团队共享图制品
Commit a single compressed file to your repo and your teammates skip the reindex. 向仓库提交单个压缩文件，队友即可跳过重新索引。
`.codebase-memory/graph.db.zst` is a zstd-compressed snapshot of the knowledge graph that lives next to your source. When you index, the artifact is written or refreshed; when a teammate clones the repo and runs `codebase-memory-mcp` for the first time, the artifact is decompressed and incremental indexing fills in their local diff. `.codebase-memory/graph.db.zst` 是位于源码旁的知识图 zstd 压缩快照。索引时会写入或刷新该制品；队友克隆仓库并首次运行 `codebase-memory-mcp` 时，制品会被解压，增量索引再补齐其本地 diff。
- **Format**: SQLite database, indexes stripped, `VACUUM INTO` compacted, then zstd 1.5.7 compressed (8–13:1 ratio typical) - **格式**：SQLite 数据库，剥离索引，`VACUUM INTO` 压缩后，再以 zstd 1.5.7 压缩（典型压缩比 8–13:1）
- **Two tiers**: - **两层级**：
- **Best** (`zstd -9` + index strip + `VACUUM INTO`) — written on explicit `index_repository` - **Best**（`zstd -9` + 索引剥离 + `VACUUM INTO`）—— 在显式执行 `index_repository` 时写入
- **Fast** (`zstd -3`) — written by the watcher for low-latency incremental updates - **Fast**（`zstd -3`）—— 由 watcher 写入，用于低延迟增量更新
- **Bootstrap**: when no local DB exists but the artifact is present, `index_repository` imports the artifact first, then runs incremental indexing — avoiding the full reindex cost - **引导**：本地无 DB 但存在制品时，`index_repository` 先导入制品，再运行增量索引 —— 避免完整重新索引的开销
- **No merge pain**: a `.gitattributes` line with `merge=ours` is auto-created on first export, so concurrent edits don't produce conflicts on the binary artifact - **无合并烦恼**：首次导出时会自动创建带 `merge=ours` 的 `.gitattributes` 行，并发编辑不会在二进制制品上产生冲突
- **Optional**: never committed unless you want it. Add `.codebase-memory/` to `.gitignore` if you prefer everyone to reindex from scratch. - **可选**：除非你主动提交，否则不会入库。若希望每个人都从零重新索引，可将 `.codebase-memory/` 加入 `.gitignore`。
The result is similar in spirit to graphify's `graphify-out/` directory, but as a single compressed file with explicit two-tier export, integrity-checked import, and zero merge friction. 其结果在理念上类似 graphify 的 `graphify-out/` 目录，但以单个压缩文件呈现，具备显式两层级导出、完整性校验导入，且零合并摩擦。
## How It Works ## 工作原理
codebase-memory-mcp is a **structural analysis backend** — it builds and queries the knowledge graph. It does **not** include an LLM. Instead, it relies on your MCP client (Claude Code, or any MCP-compatible agent) to be the intelligence layer. codebase-memory-mcp 是一个**结构化分析后端** —— 它构建并查询知识图。它**不包含** LLM。相反，它依赖你的 MCP 客户端（Claude Code，或任何兼容 MCP 的 agent）作为智能层。
``` ```
You: "what calls ProcessOrder?" You: "what calls ProcessOrder?"
@@ -226,11 +232,11 @@ codebase-memory-mcp: executes graph query, returns structured results
Agent: presents the call chain in plain English Agent: presents the call chain in plain English
``` ```
**Why no built-in LLM?** Other code graph tools embed an LLM for natural language → graph query translation. This means extra API keys, extra cost, and another model to configure. With MCP, the agent you're already talking to *is* the query translator. **为何没有内置 LLM？** 其他代码图工具会嵌入 LLM，用于自然语言 → 图查询的翻译。这意味着额外的 API key、额外成本，以及又要配置一个模型。借助 MCP，你已经在对话的 agent *就是*查询翻译器。
## Performance ## 性能
Benchmarked on Apple M3 Pro: 在 Apple M3 Pro 上基准测试：
| Operation | Time | Notes | | Operation | Time | Notes |
|-----------|------|-------| |-----------|------|-------|
@@ -242,40 +248,40 @@ Benchmarked on Apple M3 Pro:
| Dead code detection | ~150ms | Full graph scan with degree filtering | | Dead code detection | ~150ms | Full graph scan with degree filtering |
| Trace call path (depth=5) | <10ms | BFS traversal | | Trace call path (depth=5) | <10ms | BFS traversal |
**RAM-first pipeline**: All indexing runs in memory (LZ4 HC compressed read, in-memory SQLite, single dump at end). Memory is released back to the OS after indexing completes. **RAM 优先流水线（RAM-first pipeline）**：所有索引均在内存中完成（LZ4 HC 压缩读取、内存 SQLite、最后一次性转储）。索引完成后，内存会释放回操作系统。
**Token efficiency**: Five structural queries consumed ~3,400 tokens via codebase-memory-mcp versus ~412,000 tokens via file-by-file grep exploration — a **99.2% reduction**. **Token 效率**：五次结构化查询通过 codebase-memory-mcp 仅消耗约 3,400 个 token，而通过逐文件 grep 探索则消耗约 412,000 个 token——**减少 99.2%**。
## Troubleshooting & Diagnostics ## 故障排查与诊断
codebase-memory-mcp runs **100% locally and collects no telemetry** — your code, queries, environment, and usage never leave your machine. That privacy guarantee also means that when you hit something we can't reproduce on our side (a slow memory climb over hours, a performance regression, a leak that only appears after days of real use), **we have no data at all unless you choose to send it.** Here is how to capture it yourself. codebase-memory-mcp **100% 本地运行且不收集任何遥测数据**——你的代码、查询、环境和使用情况永远不会离开你的机器。这一隐私保障也意味着，当你遇到我们无法在本地复现的问题（数小时内内存缓慢攀升、性能回退、或仅在多日实际使用后才会出现的泄漏）时，**除非你主动发送，否则我们完全没有任何数据。** 以下介绍如何自行采集。
### Capture a diagnostics log ### 采集诊断日志
Set `CBM_DIAGNOSTICS=1` before the MCP server starts, then reproduce the problem (let it run as long as it takes — a slow leak needs time to show in the trend). The server writes two files to your system temp directory (`$TMPDIR` or `/tmp` on macOS/Linux, `%TEMP%` on Windows): 在 MCP 服务器启动前设置 `CBM_DIAGNOSTICS=1`，然后复现问题（让它运行足够久——缓慢泄漏需要时间才能在趋势中显现）。服务器会将两个文件写入系统临时目录（macOS/Linux 为 `$TMPDIR` 或 `/tmp`，Windows 为 `%TEMP%`）：
| File | What it is | | 文件 | 说明 |
|------|------------| |------|------|
| `cbm-diagnostics-<pid>.ndjson` | **The memory trajectory** — one JSON line every 5 s with `rss`, `committed` (Windows commit charge), `peak_*`, `page_faults`, `fd`, and `queries`. **This is the file we need for memory/leak reports** — the *trend over time* is what pinpoints a leak. It is **kept on disk after the server exits** (so you can grab it post-mortem) and rotates to `.ndjson.1` past ~8 MB. | | `cbm-diagnostics-<pid>.ndjson` | **内存轨迹**——每 5 秒一行 JSON，包含 `rss`、`committed`（Windows commit charge）、`peak_*`、`page_faults`、`fd` 和 `queries`。**这是我们处理内存/泄漏报告所需的文件**——*随时间变化的趋势*才能定位泄漏。服务器退出后**该文件会保留在磁盘上**（便于事后获取），超过约 8 MB 时会轮转到 `.ndjson.1`。 |
| `cbm-diagnostics-<pid>.json` | The latest snapshot only — handy for a quick live check. Removed on clean exit. | | `cbm-diagnostics-<pid>.json` | 仅最新快照——便于快速实时检查。正常退出时会被删除。 |
The startup log prints both paths, e.g.: 启动日志会打印两个路径，例如：
``` ```
level=info msg=diagnostics.start snapshot=/tmp/cbm-diagnostics-12345.json trajectory=/tmp/cbm-diagnostics-12345.ndjson interval=5s level=info msg=diagnostics.start snapshot=/tmp/cbm-diagnostics-12345.json trajectory=/tmp/cbm-diagnostics-12345.ndjson interval=5s
``` ```
Set the variable in the `env` block of your agent's MCP server config, or export it before launching the server. 在代理的 MCP 服务器配置中的 `env` 块内设置该变量，或在启动服务器前 export。
### What to share ### 需要分享的内容
When you open a memory/performance issue, **attach the `.ndjson` trajectory** — it contains no source code or query text, only resource counters. If you'd rather not attach a file, paste it (or an agent's summary of it) into the issue: your assistant can read the NDJSON directly and report whether `rss`/`committed` grow monotonically, how fast, and relative to query count — which is exactly what we need to find the cause. 当你提交内存/性能相关 issue 时，**请附上 `.ndjson` 轨迹文件**——其中不含源代码或查询文本，仅有资源计数器。若不想附加文件，可将其（或代理对其的摘要）粘贴到 issue 中：你的助手可直接读取 NDJSON，并报告 `rss`/`committed` 是否单调增长、增速如何、以及与查询次数的相对关系——这正是我们定位原因所需的信息。
## Installation ## 安装
### Pre-built Binaries ### 预编译二进制
| Platform | Standard | With Graph UI | | 平台 | 标准版 | 含 Graph UI |
|----------|----------|---------------| |----------|----------|---------------|
| macOS (Apple Silicon) | `codebase-memory-mcp-darwin-arm64.tar.gz` | `codebase-memory-mcp-ui-darwin-arm64.tar.gz` | | 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` | | macOS (Intel) | `codebase-memory-mcp-darwin-amd64.tar.gz` | `codebase-memory-mcp-ui-darwin-amd64.tar.gz` |
@@ -283,14 +289,14 @@ When you open a memory/performance issue, **attach the `.ndjson` trajectory**
| Linux (ARM64) | `codebase-memory-mcp-linux-arm64.tar.gz` | `codebase-memory-mcp-ui-linux-arm64.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` | | Windows (x86_64) | `codebase-memory-mcp-windows-amd64.zip` | `codebase-memory-mcp-ui-windows-amd64.zip` |
Every release includes `checksums.txt` with SHA-256 hashes. All binaries are statically linked — no shared library dependencies. 每次发布均包含带 SHA-256 哈希的 `checksums.txt`。所有二进制均为静态链接——无共享库依赖。
> **Windows note**: SmartScreen may show a warning for unsigned software. Click **"More info"** → **"Run anyway"**. Verify integrity with `checksums.txt`. > **Windows 说明**：SmartScreen 可能对未签名软件显示警告。点击 **"More info"** → **"Run anyway"**。使用 `checksums.txt` 验证完整性。
### Setup Scripts ### 安装脚本
<details> <details>
<summary>Automated download + install</summary> <summary>自动下载 + 安装</summary>
**macOS / Linux:** **macOS / Linux:**
@@ -316,25 +322,25 @@ yay -S codebase-memory-mcp-bin
paru -S codebase-memory-mcp-bin paru -S codebase-memory-mcp-bin
``` ```
The `codebase-memory-mcp-bin` package is available at: https://aur.archlinux.org/packages/codebase-memory-mcp-bin `codebase-memory-mcp-bin` 软件包可在以下地址获取：https://aur.archlinux.org/packages/codebase-memory-mcp-bin
### Install via Claude Code ### 通过 Claude Code 安装
``` ```
You: "Install this MCP server: https://github.com/DeusData/codebase-memory-mcp" You: "Install this MCP server: https://github.com/DeusData/codebase-memory-mcp"
``` ```
### Build from Source ### 从源码构建
<details> <details>
<summary>Prerequisites: C compiler + zlib</summary> <summary>前置条件：C 编译器 + zlib</summary>
| Requirement | Check | Install | | 要求 | 检查 | 安装 |
|-------------|-------|---------| |-------------|-------|---------|
| **C compiler** (gcc or clang) | `gcc --version` or `clang --version` | macOS: `xcode-select --install`, Linux: `apt install build-essential` | | **C 编译器**（gcc 或 clang） | `gcc --version` 或 `clang --version` | macOS：`xcode-select --install`，Linux：`apt install build-essential` |
| **C++ compiler** | `g++ --version` or `clang++ --version` | Same as above | | **C++ 编译器** | `g++ --version` 或 `clang++ --version` | 同上 |
| **zlib** | — | macOS: included, Linux: `apt install zlib1g-dev` | | **zlib** | — | macOS：已内置，Linux：`apt install zlib1g-dev` |
| **Git** | `git --version` | Pre-installed on most systems | | **Git** | `git --version` | 大多数系统已预装 |
</details> </details>
@@ -346,12 +352,12 @@ scripts/build.sh --with-ui # with graph visualization
# Binary at: build/c/codebase-memory-mcp # Binary at: build/c/codebase-memory-mcp
``` ```
### Manual MCP Configuration ### 手动 MCP 配置
<details> <details>
<summary>If you prefer not to use the install command</summary> <summary>若不想使用 install 命令</summary>
Add to `~/.claude/.mcp.json` (global) or project `.mcp.json`: 添加到 `~/.claude/.mcp.json`（全局）或项目 `.mcp.json`：
```json ```json
{ {
@@ -364,43 +370,43 @@ Add to `~/.claude/.mcp.json` (global) or project `.mcp.json`:
} }
``` ```
Restart your agent. Verify with `/mcp` — you should see `codebase-memory-mcp` with 14 tools. 重启你的代理。使用 `/mcp` 验证——你应能看到 `codebase-memory-mcp` 及 14 个工具。
</details> </details>
## Multi-Agent Support ## 多代理支持
`install` auto-detects and configures all installed agents: `install` 会自动检测并配置所有已安装的代理：
| Agent | MCP Config | Instructions | Hooks | | 代理 | MCP 配置 | 说明/指令 | Hooks |
|-------|-----------|-------------|-------| |-------|-----------|-------------|-------|
| Claude Code | `.claude/.mcp.json` | 4 Skills | PreToolUse (Grep/Glob graph augment, non-blocking) | | Claude Code | `.claude/.mcp.json` | 4 Skills | PreToolUse（Grep/Glob 图增强，非阻塞） |
| Codex CLI | `.codex/config.toml` | `.codex/AGENTS.md` | SessionStart reminder | | Codex CLI | `.codex/config.toml` | `.codex/AGENTS.md` | SessionStart 提醒 |
| Gemini CLI | `.gemini/settings.json` | `.gemini/GEMINI.md` | BeforeTool (grep reminder) + SessionStart reminder | | Gemini CLI | `.gemini/settings.json` | `.gemini/GEMINI.md` | BeforeTool（grep 提醒）+ SessionStart 提醒 |
| Zed | `settings.json` (JSONC) | — | — | | Zed | `settings.json` (JSONC) | — | — |
| OpenCode | `opencode.json` | `AGENTS.md` | — | | OpenCode | `opencode.json` | `AGENTS.md` | — |
| Antigravity | `.gemini/config/mcp_config.json` (shared) | `antigravity-cli/AGENTS.md` | SessionStart reminder | | Antigravity | `.gemini/config/mcp_config.json` (shared) | `antigravity-cli/AGENTS.md` | SessionStart 提醒 |
| Aider | — | `CONVENTIONS.md` | — | | Aider | — | `CONVENTIONS.md` | — |
| KiloCode | `mcp_settings.json` | `~/.kilocode/rules/` | — | | KiloCode | `mcp_settings.json` | `~/.kilocode/rules/` | — |
| VS Code | `Code/User/mcp.json` | — | — | | VS Code | `Code/User/mcp.json` | — | — |
| OpenClaw | `openclaw.json` | — | — | | OpenClaw | `openclaw.json` | — | — |
| Kiro | `.kiro/settings/mcp.json` | — | — | | Kiro | `.kiro/settings/mcp.json` | — | — |
**Hooks are structurally non-blocking** (exit code 0, every failure path). **Hooks 在结构上为非阻塞**（退出码 0，所有失败路径亦然）。
For Claude Code, the `PreToolUse` hook intercepts `Grep`/`Glob` (never `Read` — 对于 Claude Code，`PreToolUse` hook 会拦截 `Grep`/`Glob`（从不拦截 `Read`——
gating `Read` breaks the read-before-edit invariant) and, when the search 对 `Read` 进行门控会破坏先读后改不变量），当搜索
token matches indexed symbols, injects them as `additionalContext` via token 与已索引符号匹配时，通过
`search_graph` so the agent gets structured context alongside its normal `search_graph` 将其作为 `additionalContext` 注入，
search results. For Codex, Gemini CLI, and Antigravity, a `SessionStart` hook 使代理在常规搜索结果之外还能获得结构化上下文。对于 Codex、Gemini CLI 和 Antigravity，`SessionStart` hook
injects a one-line code-discovery reminder as session context (Gemini CLI also 会以会话上下文形式注入一行代码发现提醒（Gemini CLI 还会
keeps its `BeforeTool` reminder). 保留其 `BeforeTool` 提醒）。
The installed Claude shim file is named `cbm-code-discovery-gate` for 已安装的 Claude shim 文件名为 `cbm-code-discovery-gate`，以
backward compatibility with existing installs; despite the legacy name it 兼容既有安装；尽管名称沿用旧版，它
never gates and never blocks. 从不进行门控，也从不阻塞。
## CLI Mode ## CLI 模式
Every MCP tool can be invoked from the command line: 每个 MCP 工具均可从命令行调用：
```bash ```bash
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/repo"}' codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/repo"}'
@@ -413,65 +419,65 @@ codebase-memory-mcp cli query_graph '{"project": "my-project", "query": "MATCH (
codebase-memory-mcp cli --raw search_graph '{"project": "my-project", "label": "Function"}' | jq '.results[].name' codebase-memory-mcp cli --raw search_graph '{"project": "my-project", "label": "Function"}' | jq '.results[].name'
``` ```
## MCP Tools ## MCP 工具
### Indexing ### 索引
| Tool | Description | | 工具 | 说明 |
|------|------|
| `index_repository` | 将仓库索引到图中。之后自动同步保持最新。 |
| `list_projects` | 列出所有已索引项目及其节点/边数量。 |
| `delete_project` | 移除项目及其全部图数据。 |
| `index_status` | 检查项目的索引状态。 |
### 查询
| 工具 | 说明 |
|------|-------------| |------|-------------|
| `index_repository` | Index a repository into the graph. Auto-sync keeps it fresh after that. | | `search_graph` | 按标签、名称模式、文件模式、度过滤进行结构化搜索。通过 limit/offset 分页。 |
| `list_projects` | List all indexed projects with node/edge counts. | | `trace_path` | BFS 遍历——谁调用了某函数，以及它调用了什么（别名：`trace_call_path`）。深度 1-5。 |
| `delete_project` | Remove a project and all its graph data. | | `detect_changes` | 将 git diff 映射到受影响的符号 + 带风险分级的影响半径（blast radius）。 |
| `index_status` | Check indexing status of a project. | | `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 边。 |
### Querying ## 图数据模型
| Tool | Description | ### 节点标签
|------|-------------|
| `search_graph` | Structured search by label, name pattern, file pattern, degree filters. Pagination via limit/offset. |
| `trace_path` | BFS traversal — who calls a function and what it calls (alias: `trace_call_path`). Depth 1-5. |
| `detect_changes` | Map git diff to affected symbols + blast radius with risk classification. |
| `query_graph` | Execute Cypher-like graph queries (read-only). |
| `get_graph_schema` | Node/edge counts, relationship patterns, property definitions per label. Run this first. |
| `get_code_snippet` | Read source code for a function by qualified name. |
| `get_architecture` | Codebase overview: languages, packages, routes, hotspots, clusters, ADR. |
| `search_code` | Grep-like text search within indexed project files. |
| `manage_adr` | CRUD for Architecture Decision Records. |
| `ingest_traces` | Ingest runtime traces to validate HTTP_CALLS edges. |
## Graph Data Model
### Node Labels
`Project`, `Package`, `Folder`, `File`, `Module`, `Class`, `Function`, `Method`, `Interface`, `Enum`, `Type`, `Route`, `Resource` `Project`, `Package`, `Folder`, `File`, `Module`, `Class`, `Function`, `Method`, `Interface`, `Enum`, `Type`, `Route`, `Resource`
### Edge Types ### 边类型
`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` `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`
### Qualified Names ### 限定名
`get_code_snippet` uses qualified names: `<project>.<path_parts>.<name>`. Use `search_graph` to discover them first. `get_code_snippet` 使用限定名：`<project>.<path_parts>.<name>`。请先用 `search_graph` 发现它们。
### Supported Cypher (openCypher read subset) ### 支持的 Cypher（openCypher 只读子集）
`query_graph` is a read-only openCypher subset: `query_graph` 是只读的 openCypher 子集：
- **Clauses**: `MATCH`, `OPTIONAL MATCH`, multiple `MATCH`, `WHERE`, `WITH` (+ `WITH … WHERE`), `RETURN`, `ORDER BY`, `SKIP`, `LIMIT`, `DISTINCT`, `UNWIND`, `UNION` / `UNION ALL`, `CASE`. - **子句**：`MATCH`, `OPTIONAL MATCH`, 多个 `MATCH`, `WHERE`, `WITH`（+ `WITH … WHERE`）, `RETURN`, `ORDER BY`, `SKIP`, `LIMIT`, `DISTINCT`, `UNWIND`, `UNION` / `UNION ALL`, `CASE`。
- **Patterns**: labelled nodes, label alternation `(n:A|B)`, relationship types/direction, variable-length paths `[*1..3]`, inline property maps. - **模式**：带标签的节点、标签交替 `(n:A|B)`、关系类型/方向、可变长度路径 `[*1..3]`、内联属性映射。
- **WHERE**: `= <> < <= > >=`, `AND/OR/XOR/NOT`, `IN`, `CONTAINS`, `STARTS WITH`, `ENDS WITH`, `IS [NOT] NULL`, regex `=~`, label test `n:Label`, and `EXISTS { (n)-[:TYPE]->() }` (single-hop existence — great for dead-code, e.g. `WHERE NOT EXISTS { (f)<-[:CALLS]-() }`). - **WHERE**：`= <> < <= > >=`, `AND/OR/XOR/NOT`, `IN`, `CONTAINS`, `STARTS WITH`, `ENDS WITH`, `IS [NOT] NULL`, 正则 `=~`, 标签测试 `n:Label`, 以及 `EXISTS { (n)-[:TYPE]->() }`（单跳存在性——非常适合死代码，例如 `WHERE NOT EXISTS { (f)<-[:CALLS]-() }`）。
- **Aggregates**: `count` (+`DISTINCT`), `sum`, `avg`, `min`, `max`, `collect`. - **聚合**：`count`（+`DISTINCT`）, `sum`, `avg`, `min`, `max`, `collect`。
- **Functions**: `labels`, `type`, `id`, `keys`, `properties`; `toLower/toUpper/toString/toInteger/toFloat/toBoolean`; `size`, `length`, `trim/ltrim/rtrim`, `reverse`; `coalesce`, `substring`, `replace`, `left`, `right`. - **函数**：`labels`, `type`, `id`, `keys`, `properties`；`toLower/toUpper/toString/toInteger/toFloat/toBoolean`；`size`, `length`, `trim/ltrim/rtrim`, `reverse`；`coalesce`, `substring`, `replace`, `left`, `right`。
Anything outside this subset (write/`MERGE`/`CALL` clauses, unsupported functions, list/map literals, comprehensions, path functions, parameters) **fails with a clear `unsupported …` error** rather than returning empty results. 该子集之外的任何内容（写操作/`MERGE`/`CALL` 子句、不支持的函数、列表/映射字面量、推导式、路径函数、参数）会**以明确的 `unsupported …` 错误失败**，而不是返回空结果。
## Ignoring Files ## 忽略文件
Layered: hardcoded patterns (`.git`, `node_modules`, etc.) → `.gitignore` hierarchy → `.cbmignore` (project-specific, gitignore syntax). Symlinks are always skipped. 分层处理：硬编码模式（`.git`、`node_modules` 等）→ `.gitignore` 层级 → `.cbmignore`（项目专用，gitignore 语法）。符号链接始终跳过。
See [docs/cbmignore.md](docs/cbmignore.md) for the full `.cbmignore` how-to: syntax, precedence across the ignore layers, and negation semantics. 完整的 `.cbmignore` 用法说明（语法、各忽略层的优先级、取反语义）见 [docs/cbmignore.md](docs/cbmignore.md)。
## Configuration ## 配置
```bash ```bash
codebase-memory-mcp config list # show all settings codebase-memory-mcp config list # show all settings
@@ -481,104 +487,104 @@ codebase-memory-mcp config set auto_watch false # don't register backgr
codebase-memory-mcp config reset auto_index # reset to default codebase-memory-mcp config reset auto_index # reset to default
``` ```
### Environment Variables ### 环境变量
| Variable | Default | Description | | 变量 | 默认值 | 说明 |
|----------|---------|-------------| |----------|---------|-------------|
| `CBM_ALLOWED_ROOT` | *(unset)* | Restrict `index_repository` to paths within this directory. When set, a `repo_path` that resolves (after symlink / `..` resolution) outside this root is refused; unset imposes no restriction. Useful when the server may be driven by an untrusted caller, e.g. agentic or multi-tenant deployments. | | `CBM_ALLOWED_ROOT` | *(未设置)* | 将 `index_repository` 限制在此目录内的路径。设置后，若 `repo_path` 在解析（符号链接 / `..` 解析之后）落在该根目录之外，则会被拒绝；未设置时不加限制。适用于服务器可能由不可信调用方驱动的场景，例如智能体或跨租户部署。 |
| `CBM_CACHE_DIR` | `~/.cache/codebase-memory-mcp` | Override the database storage directory. All project indexes and config are stored here. | | `CBM_CACHE_DIR` | `~/.cache/codebase-memory-mcp` | 覆盖数据库存储目录。所有项目索引与配置都保存在此。 |
| `CBM_DIAGNOSTICS` | `false` | Set to `1` or `true` to enable periodic diagnostics output to `/tmp/cbm-diagnostics-<pid>.json`. | | `CBM_DIAGNOSTICS` | `false` | 设为 `1` 或 `true`，以启用向 `/tmp/cbm-diagnostics-<pid>.json` 定期输出诊断信息。 |
| `CBM_DOWNLOAD_URL` | *(GitHub releases)* | Override the download URL for updates. Used for testing or self-hosted deployments. | | `CBM_DOWNLOAD_URL` | *(GitHub releases)* | 覆盖更新下载 URL。用于测试或自托管部署。 |
| `CBM_LOG_LEVEL` | `info` | Set the minimum log level. Accepted values (case-insensitive): `debug`, `info`, `warn`, `error`, `none` — or their numeric equivalents `0`–`4` matching the internal enum. Logs go to stderr; stdout is reserved for MCP JSON-RPC. | | `CBM_LOG_LEVEL` | `info` | 设置最低日志级别。可接受的值（不区分大小写）：`debug`、`info`、`warn`、`error`、`none` —— 或其与内部枚举对应的数字等价形式 `0`–`4`。日志输出到 stderr；stdout 保留给 MCP JSON-RPC。 |
| `CBM_WORKERS` | *(detected)* | Override the parallel-indexing worker count returned by `cbm_default_worker_count`. Useful inside containers where `sysconf(_SC_NPROCESSORS_ONLN)` reports host CPUs rather than the cgroup's effective quota. Range 1–256; invalid values are ignored with a warning. | | `CBM_WORKERS` | *(自动检测)* | 覆盖 `cbm_default_worker_count` 返回的并行索引进程数。在容器内很有用，因为 `sysconf(_SC_NPROCESSORS_ONLN)` 报告的是宿主机 CPU 数，而非 cgroup 的有效配额。范围 1–256；无效值会被忽略并给出警告。 |
| `CBM_MEM_BUDGET_MB` | *(detected)* | Override the in-memory graph budget with an explicit cap in MiB, taking precedence over the `ram_fraction × total_RAM` default. Useful on bare-metal hosts without a cgroup limit, or to pin a budget *below* the cgroup limit so headroom is left for sibling processes. Must be a positive integer; it is clamped to detected total RAM (logged as `mem.budget.clamped`), and non-numeric or non-positive values are ignored with a warning (`mem.budget.env.invalid`). | | `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` | After indexing, compare persisted SQLite node count to the in-memory dump count. When persisted nodes fall below this fraction of committed nodes (and committed > 50), `index_repository` returns `status:"degraded"` instead of silent `indexed`. Range 0–1; set `0` to disable. Invalid values are ignored with a warning. | | `CBM_DUMP_VERIFY_MIN_RATIO` | `0.5` | 索引完成后，比较持久化的 SQLite 节点数与内存转储节点数。当持久化节点数低于已提交节点数的该比例（且已提交 > 50）时，`index_repository` 返回 `status:"degraded"`，而不是静默的 `indexed`。范围 0–1；设为 `0` 可禁用。无效值会被忽略并给出警告。 |
```bash ```bash
# Store indexes in a custom directory # Store indexes in a custom directory
export CBM_CACHE_DIR=~/my-projects/cbm-data export CBM_CACHE_DIR=~/my-projects/cbm-data
``` ```
## Custom File Extensions ## 自定义文件扩展名
The JSON config files support a single key, `extra_extensions`, which maps additional file extensions to supported languages. Useful for framework-specific extensions like `.blade.php` (Laravel) or `.mjs` (ES modules). (For other tunables, see [Environment Variables](#environment-variables) and the `config` subcommand above.) JSON 配置文件支持单个键 `extra_extensions`，用于将额外的文件扩展名映射到受支持的语言。适用于框架专用扩展名，例如 `.blade.php`（Laravel）或 `.mjs`（ES modules）。（其他可调项见 [环境变量](#environment-variables) 以及上文的 `config` 子命令。）
Need the full config-file reference? See [docs/CONFIGURATION.md](docs/CONFIGURATION.md). 需要完整的配置文件参考？见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。
**Per-project** (in your repo root): **按项目**（在仓库根目录）：
```json ```json
// .codebase-memory.json // .codebase-memory.json
{"extra_extensions": {".blade.php": "php", ".mjs": "javascript"}} {"extra_extensions": {".blade.php": "php", ".mjs": "javascript"}}
``` ```
**Global** (applies to all projects): **全局**（应用于所有项目）：
```json ```json
// ~/.config/codebase-memory-mcp/config.json (or $XDG_CONFIG_HOME/...) // ~/.config/codebase-memory-mcp/config.json (or $XDG_CONFIG_HOME/...)
{"extra_extensions": {".twig": "html", ".phtml": "php"}} {"extra_extensions": {".twig": "html", ".phtml": "php"}}
``` ```
Each entry maps an extension (which **must** start with `.`) to a language name. Language names are matched **case-insensitively**. Accepted values (aliases in parentheses) are: 每条将扩展名（**必须**以 `.` 开头）映射到语言名。语言名匹配**不区分大小写**。可接受的值（括号内为别名）为：
`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`. `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`。
Project config overrides global for conflicting extensions. An entry whose language name is unknown, or whose extension does not start with `.`, is skipped and a warning is logged to stderr (shown at the default `info` log level). Missing config files are ignored. 对冲突的扩展名，项目配置覆盖全局配置。语言名未知、或扩展名不以 `.` 开头的条目会被跳过，并在 stderr 记录警告（在默认的 `info` 日志级别下可见）。缺失的配置文件会被忽略。
## Persistence ## 持久化
SQLite databases stored at `~/.cache/codebase-memory-mcp/`. Persists across restarts (WAL mode, ACID-safe). To reset: `rm -rf ~/.cache/codebase-memory-mcp/`. SQLite 数据库存储在 `~/.cache/codebase-memory-mcp/`。跨重启持久保存（WAL 模式，ACID 安全）。若要重置：`rm -rf ~/.cache/codebase-memory-mcp/`。
## Troubleshooting ## 故障排除
| Problem | Fix | | 问题 | 处理 |
|---------|-----| |---------|-----|
| `/mcp` doesn't show the server | Check `.mcp.json` path is absolute. Restart agent. Test: `echo '{}' \| /path/to/binary` should output JSON. | | `/mcp` 未显示服务器 | 检查 `.mcp.json` 路径是否为绝对路径。重启 agent。测试：`echo '{}' \| /path/to/binary` 应输出 JSON。 |
| `index_repository` fails | Pass absolute path: `index_repository(repo_path="/absolute/path")` | | `index_repository` 失败 | 传入绝对路径：`index_repository(repo_path="/absolute/path")` |
| `trace_path` returns 0 results | Use `search_graph(name_pattern=".*PartialName.*")` first to find the exact name. | | `trace_path` 返回 0 条结果 | 先用 `search_graph(name_pattern=".*PartialName.*")` 查找确切名称。 |
| Queries return wrong project results | Add `project="name"` parameter. Use `list_projects` to see names. | | 查询返回了错误项目的结果 | 添加 `project="name"` 参数。用 `list_projects` 查看名称。 |
| Binary not found after install | Add to PATH: `export PATH="$HOME/.local/bin:$PATH"` | | 安装后找不到二进制文件 | 加入 PATH：`export PATH="$HOME/.local/bin:$PATH"` |
| UI not loading | Ensure you downloaded the `ui` variant and ran `--ui=true`. Check `http://localhost:9749`. | | UI 无法加载 | 确保下载的是 `ui` 变体，并已运行 `--ui=true`。检查 `http://localhost:9749`。 |
## Hybrid LSP ## Hybrid LSP
**Semantic type resolution beyond tree-sitter.** **超越 tree-sitter 的语义类型解析。**
Tree-sitter alone gives a syntactic AST. That handles naming, structure, and call sites well, but it can't tell you that `user.profile.display_name()` resolves to `Profile.display_name` declared three modules away — tree-sitter doesn't track imports, generics, inheritance, or stdlib types. 仅靠 tree-sitter 只能得到语法 AST。这对命名、结构和调用点处理得很好，但它无法告诉你 `user.profile.display_name()` 会解析到三个模块之外声明的 `Profile.display_name` —— tree-sitter 不跟踪 import、泛型、继承或标准库类型。
codebase-memory-mcp ships a **lightweight C implementation of language type-resolution algorithms, structurally inspired by and compatible with major language servers** (tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, rust-analyzer), embedded directly into the static binary. No language server process, no per-project setup, no API key. We call this layer **Hybrid LSP**: it runs alongside tree-sitter on every parse and refines `CALLS`, `USAGE`, and `RESOLVED_CALLS` edges with type information, so the resulting graph mirrors what an IDE "Go to Definition" would resolve. 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）的解析结果一致。
**Languages with full Hybrid LSP:** **已完整支持 Hybrid LSP 的语言：**
| Language | What it handles | | Language | What it handles |
|----------|-----------------| |----------|-----------------|
| **Python** *(new in v0.7.0)* | imports + dotted submodule walks, dataclasses, `Self` return types, generics, `@property`, `match/case` class patterns, SQLAlchemy 2.0 `Mapped[T]`, Pydantic `BaseModel`, `typing.Annotated` / `ClassVar` / `Final` / `InitVar`, async/await, classmethod/staticmethod, narrowing (`isinstance` / `is not None` / walrus), `typing.cast` / `assert_type`, common stdlib (logging, pathlib, json, functools). Target ~95% resolution on idiomatic code. | | **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** | generics, JSX component dispatch, JSDoc inference for plain JS, `.d.ts` declarations, module re-exports, method chaining via return-type propagation, per-file overlay chained to a shared cross-file registry | | **TypeScript / JavaScript / JSX / TSX** | 泛型、JSX 组件分派、纯 JS 的 JSDoc 推断、`.d.ts` 声明、模块再导出、通过返回类型传播实现的方法链、按文件叠加并链接到共享跨文件注册表 |
| **PHP** *(new in v0.7.0)* | namespaces, traits, late-static-binding, PHPDoc inference, parameter binding, return-type inference | | **PHP** *(new in v0.7.0)* | 命名空间、trait、late-static-binding、PHPDoc 推断、参数绑定、返回类型推断 |
| **C#** *(new in v0.7.0)* | global usings, file-scoped namespaces, records (incl. C# 12 primary constructors), LINQ method syntax, `async Task<T>` / `ValueTask<T>` unwrap, generic methods, `this` / `base` dispatch, `var` inference, common BCL stdlib | | **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)* | pre-built per-package cross-file registry, generics, embedded structs, interface satisfaction, package-aware import resolution | | **Go** *(sharpened in v0.7.0)* | 预构建的按包跨文件注册表、泛型、嵌入结构体、接口满足、包感知的 import 解析 |
| **C / C++** *(sharpened in v0.7.0)* | pre-built per-language cross-file registry shared across C and C++; C side handles macros + `typedef` chains + header-vs-source linking; C++ side handles templates, namespaces, `auto` inference, and method resolution via class hierarchy | | **C / C++** *(sharpened in v0.7.0)* | 预构建的按语言跨文件注册表，C 与 C++ 共享；C 侧处理宏 + `typedef` 链 + 头文件与源文件链接；C++ 侧处理模板、命名空间、`auto` 推断，以及通过类层次结构进行的方法解析 |
| **Java** *(new in v0.8.0)* | imports (single-type, on-demand, static), class hierarchies with `this` / `super` dispatch, generics, annotations, overload matching by arity and parameter types, lambdas / method references bound to functional interfaces, field-type inference, common JDK stdlib | | **Java** *(new in v0.8.0)* | import（单类型、按需、静态）、带 `this` / `super` 分派的类层次结构、泛型、注解、按参数个数与参数类型的重载匹配、绑定到函数式接口的 lambda / 方法引用、字段类型推断、常用 JDK 标准库 |
| **Kotlin** *(new in v0.8.0)* | imports + same-package resolution, classes / objects / companion objects, extension functions, data classes, nullable-type unwrapping, scope functions (`let` / `apply` / `run` / `also` / `with`), infix calls, common stdlib | | **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` declarations + module paths, `impl` blocks and trait methods, struct fields, generics with trait bounds, operator-trait desugaring, derive-macro method synthesis, UFCS static paths, common std prelude | | **Rust** *(new in v0.8.0)* | `use` 声明 + 模块路径、`impl` 块与 trait 方法、结构体字段、带 trait 约束的泛型、运算符 trait 脱糖、derive 宏方法合成、UFCS 静态路径、常用 std prelude |
| **Perl** | packages + `@ISA` / `use parent` / `use base` inheritance with method-resolution-order dispatch, `SUPER::` calls, Exporter (`use Foo qw(...)`) import maps, `bless` / `ref($class)\|\|$class` self-type inference, qualified `Pkg::sub` static calls, curated perlfunc + CPAN OOP stdlib; unresolved receivers emit no edge (zero-edge guarantee) | | **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 标准库；未解析的接收者不产生边（零边保证） |
**Two-layer architecture:** **双层架构：**
1. **Tree-sitter pass** — fast, syntactic, runs for every one of the 158 languages. Extracts definitions, calls, imports. 1. **Tree-sitter pass** —— 快速、语法级，对全部 158 种语言运行。提取定义、调用、import。
2. **Hybrid LSP pass** — type-aware, runs above the tree-sitter pass per-language. Refines call edges using the import graph plus a per-file or pre-built cross-file definition registry. Languages without a Hybrid LSP pass yet fall back to textual resolution, so you always get *some* answer. 2. **Hybrid LSP pass** —— 类型感知，在 tree-sitter pass 之上按语言运行。利用 import 图以及按文件或预构建的跨文件定义注册表来细化调用边。尚未支持 Hybrid LSP pass 的语言会回退到文本解析，因此你总能得到*某种*答案。
The result is a knowledge graph accurate enough to drive `trace_path` across packages, inheritance hierarchies, and stdlib calls — without paying for a language server process per project. 最终得到的知识图谱足够准确，可驱动跨包、继承层次结构和标准库调用的 `trace_path` —— 且无需为每个项目支付语言服务器进程的开销。
## Language Support ## Language Support
158 languages, all parsed via vendored tree-sitter grammars compiled into the binary. Benchmarked against 64 real open-source repositories (78 to 49K nodes): 158 种语言，均通过编入二进制的 vendored tree-sitter 语法进行解析。已在 64 个真实开源仓库上完成基准测试（节点数从 78 到 49K）：
| Tier | Score | Languages | | Tier | Score | Languages |
|------|-------|-----------| |------|-------|-----------|
| **Excellent** (>= 90%) | | Lua, Kotlin, C++, Perl, Objective-C, Groovy, C, Bash, Zig, Swift, CSS, YAML, TOML, HTML, SCSS, HCL, Dockerfile | | **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 | | **Good** (75-89%) | | Python、TypeScript、TSX、Go、Rust、Java、R、Dart、JavaScript、Erlang、Elixir、Scala、Ruby、PHP、C#、SQL |
| **Functional** (< 75%) | | OCaml, Haskell | | **Functional** (< 75%) | | OCaml、Haskell |
Also supported (not yet benchmarked): 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. 另已支持（尚未基准测试）：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 ## Architecture
@@ -600,14 +606,14 @@ internal/cbm/ Vendored tree-sitter grammars (158 languages) + AST extrac
## Security ## Security
Every release binary is verified through a multi-layer pipeline before publication: 每次发布前，所有发行版二进制文件都会经过多层流水线验证：
- **VirusTotal** — all binaries scanned by 70+ antivirus engines (zero detections required to publish) - **VirusTotal** —— 所有二进制文件由 70+ 款杀毒引擎扫描（发布前要求零检出）
- **SLSA Level 3** — cryptographic build provenance generated by the trusted GitHub Actions build workflow; verify with `gh attestation verify <file> --repo DeusData/codebase-memory-mcp --signer-workflow DeusData/codebase-memory-mcp/.github/workflows/_build.yml` - **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** — keyless signatures on all artifacts; bundles included in every release - **Sigstore cosign** —— 对所有制品进行无密钥签名；每个发行版均包含 bundle
- **SHA-256 checksums** — `checksums.txt` published with every release; verified by both install scripts before extraction - **SHA-256 checksums** —— 每次发行都会发布 `checksums.txt`；安装脚本在解压前都会进行校验
- **CodeQL SAST** — blocks release pipeline if any open alerts remain - **CodeQL SAST** —— 若仍存在未关闭的告警，将阻断发布流水线
- **Zero runtime dependencies** — no transitive supply chain; all libraries vendored at compile time - **Zero runtime dependencies** —— 无传递性供应链；所有库在编译时 vendored
### v0.7.0 VirusTotal scans ### v0.7.0 VirusTotal scans
@@ -619,8 +625,8 @@ Every release binary is verified through a multi-layer pipeline before publicati
| `darwin-amd64` | `28c6d640e1a0ac7bfcab...` | [0/72 ✅](https://www.virustotal.com/gui/file/28c6d640e1a0ac7bfcab5094c2186eced5264a20dcdffcb4455a1b28c5df2171/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) | | `windows-amd64` | `9c3ddcf78368fd4fa891...` | [0/72 ✅](https://www.virustotal.com/gui/file/9c3ddcf78368fd4fa89156a553641bf1e03640b4fb6dd29a12c84aa5bc98cd86/detection) |
Scan links for every release are also included in the GitHub Release notes automatically. 每个版本的扫描链接也会自动包含在 GitHub Release 说明中。
## License ## 许可证
MIT MIT