codebase-memory-mcp：毫秒级代码知识图谱MCP服务器，158语言支持

codebase-memory-mcp：毫秒级代码知识图谱MCP服务器，158语言支持 | 前端进阶之旅

Full translation

完整中文译文

面向 AI 编码智能体最快的代码智能引擎。平均代码仓库在毫秒级完成全量索引，Linux 内核（28M 行代码，75K 文件）仅需 3 分钟。结构化查询响应时间低于 1ms。以原生可执行文件形式发布，附带经核实的小型运行时资产集，支持 macOS、Linux 和 Windows——下载、运行 install、完成。

通过 tree-sitter AST 分析对全部 162 种语言进行高质量解析，并辅以 Hybrid LSP 语义类型解析增强，覆盖 Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin、Rust 和 Perl——从而构建出持久化的知识图谱，涵盖函数、类、调用链、HTTP 路由和跨服务链接。提供 17 个 MCP 工具。无需语言运行时、托管服务或 API 密钥。在 45 个支持的自动/条件客户端上即插即用。

研究——本项目的设计与基准测试详见预印本 Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP（arXiv:2603.27277）。在 31 个真实仓库中评估：答案质量 83%，令牌量减少 10 倍，工具调用次数比逐文件探索减少 2.1 倍。

安全与信任——此工具会读取你的代码库并写入智能体配置文件。这正是其设计用途。若你倾向于运行前先审计，完整源代码在此。每次发布产品时，三份行为完全相同的可执行文件候选（未剥离、调试剥离、剥离版）会提交至 VirusTotal 进行检测；选中候选后其 SHA-256 值保持不变。发布说明链接每份候选的检测结果。发布策略在 SECURITY.md 中仅允许微软 narrow 定义的单一 !ml 容差。所有处理 100% 在本地完成；你的代码绝不会离开你的机器。发现安全问题？请告知我们——见 SECURITY.md。安全是我们最优先的事项。

内置 3D 图可视化——在 localhost:9749 探索你的知识图谱

为什么选择 codebase-memory-mcp

极致索引速度——Linux 内核（28M 行代码，75K 文件）仅需 3 分钟。RAM 优先管道：LZ4 压缩、内存 SQLite、融合 Aho-Corasick 模式匹配。索引完成后释放内存。

即插即用——原生可执行文件 + 认证的 release 所有权资产，支持 macOS（arm64/amd64）、Linux（arm64/amd64）和 Windows（amd64）。原生安装无需 Docker、语言运行时或 API 密钥。下载 → 安装 → 重启智能体 → 完成。

162 种语言——tree-sitter 语法树直接编译进二进制文件。无需安装，不会出现兼容问题。

令牌量减少 120 倍——5 个结构化查询：约 3,400 个令牌 vs 逐文件搜索的约 412,000 个令牌。一次图查询替代数十次 grep/读取循环。

45 个支持的自动/条件客户端——安装脚本配置检测到的客户端，仅在存在文档化平台、标记或显式现有配置路径时安全激活条件客户端。详见多智能体支持章节获取完整矩阵及手动/仅 UI 边界说明。

内置图可视化——在 localhost:9749 提供 3D 交互式 UI，由二进制文件本身托管。

基础设施即代码索引——Dockerfile、Kubernetes 清单和 Kustomize overlay 作为图节点索引，并带交叉引用。K8s 类型的 Resource 节点、Kustomize overlay 的 Module 节点，以及指向被引用资源的 IMPORTS 边。

17 个 MCP 工具——搜索、追踪、架构、影响分析、针对性索引覆盖率检查、Cypher 查询、死代码检测、跨服务 HTTP 链接、ADR 管理等。

一键安装（macOS / Linux）：

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

带图可视化 UI：

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

Windows（PowerShell）：

# 1. 下载安装脚本
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# 2.（可选但建议）检查脚本内容
notepad install.ps1

# 3. 解除下载文件的阻止（移除浏览器/Invoke-WebRequest 添加的 Mark-of-the-Web 限制）
Unblock-File .\install.ps1

# 4. 运行安装脚本
.\install.ps1

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

选项：--skip-config（仅二进制文件，不设置智能体）、--dir=<path>（自定义位置）。

杀毒软件说明：Microsoft Defender 可能将发布二进制文件标记为 Trojan:Script/Wacatac.B!ml。这是已知的误报——通常 62 个引擎中有 61 个返回清洁，同一检测家族也会命中 gh、llama.cpp、Godot 和微软自己的 Go 工具链。详见误报说明查看证据、如何自行验证制品，以及如果你认为我们错了如何报告。

重启你的编码智能体。说"索引这个项目"——完成。

从最新 release 下载你平台的归档文件：codebase-memory-mcp-<os>-<arch>.tar.gz（macOS/Linux）或 .zip（Windows）

从最新 release 下载你平台的归档文件：

codebase-memory-mcp-<os>-<arch>.tar.gz（macOS/Linux）或 .zip（Windows）

解压并安装（每个归档包含 install.sh 或 install.ps1）：macOS / Linux：tar xzf codebase-memory-mcp-*.tar.gz ./install.sh Windows（PowerShell）：Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath . Unblock-File .\install.ps1 .\install.ps1

解压并安装（每个归档包含 install.sh 或 install.ps1）：

tar xzf codebase-memory-mcp-*.tar.gz ./install.sh

Windows (PowerShell):

Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
Unblock-File .\install.ps1
.\install.ps1

重启你的凭感觉编程智能体。

安装命令会自动移除 macOS 的隔离属性（quarantine），并对二进制文件进行 ad-hoc 签名——无需手动执行 xattr/codesign。

安装命令会自动检测已安装的编码智能体，并配置它们各自的 MCP 入口，以及在支持的平台上配置持久化指令、Skill 和生命周期钩子。

会话协调守护进程

CBM 会在 Claude Code、Codex、OpenCode 及所有其他已配置客户端之间自动共享一个按账户运行的协调守护进程。MCP 服务器或钩子客户端没有独立的开关设置：首个基于守护进程的 CBM 会话启动时，守护进程也随之启动，每个会话注册各自的工作，最后一个会话结束时关闭守护进程。守护进程负责管理长期运行的后台服务，如文件监听器、共享索引任务和可选的 UI 界面。关闭一个会话只会取消该会话独有的工作，仍被其他会话需要的任务会继续执行。

独立运行的守护进程不依赖 MCP 前端的 stderr。它在规范的 ${CBM_CACHE_DIR}/logs 目录下（默认 ~/.cache/codebase-memory-mcp/logs）维护仅所有者可访问的持久化记录。

轻量级前端仍会将即时的启动错误和会话特定的错误写入自己的 stderr；MCP JSON-RPC stdout 保持干净。

所有活动的 CBM 进程必须运行完全相同的版本、可执行文件构建版本、协调 ABI 和规范缓存根目录。等效的 CBM_CACHE_DIR 别名会解析到同一根目录；如果存在真正不同的根目录，在任何 CBM 进程处于活动状态时会被拒绝。MCP 服务器、钩子、单次 CLI 命令、临时索引工作器和守护进程共享一个 crash-safe 的 OS 准入屏障；启动一个普通冲突进程会在执行工作前失败，并在 ${CBM_CACHE_DIR}/logs/daemon-conflicts.ndjson 中记录明确的冲突。

原生安装、更新和卸载命令是这个冲突规则的刻意例外。下载、验证和私有同文件系统暂存先完成，这样一个坏的候选版本永远不会打扰正在运行的工作。然后激活过程发布账户范围的维护意图，请求守护进程和每个临时本地操作取消，并在有限期限内等待所有协调的 CBM 进程退出。它在更改活动二进制文件、配置、PATH 或索引期间独占持有准入和生命周期屏障。在此窗口期间，新 CBM 工作无法进入。激活进度和结果记录在 ${CBM_CACHE_DIR}/logs/activation-events.ndjson 中，成功的命令会告诉你重启打开的编码智能体会话，以便它们启动激活后的构建版本。

包管理器设置（npm、PyPI 或 Go）验证并发布一致的自有缓存运行时集。sidecar 文件在可执行文件之前被替换，使用每文件原子重命名；中断的多文件发布会被检测到并在下次启动时修复，而不是被描述为一次 crash-atomic 的文件系统事务。它不会替换活动的原生安装，因此不会停止正在运行的 CBM 会话。当该缓存的二进制文件被执行时，它仍然进入相同的精确构建准入屏障。Shell 和 PowerShell 安装器调用已验证候选版本的原生安装命令，因此它们会收到完整的账户范围激活保证。

普通的 cli 模式是有意分离的：它在本地运行一个命令，从不启动或连接到协调守护进程，不注册守护进程会话，也不启动监听器/UI。它的唯一共享状态是 OS 准入屏障加上用于图变更的按项目锁。命令运行时，一个临时监控器允许激活安全地取消该操作及其监督的工作线程；监控器与命令一起退出，永远不会成为常驻守护进程。详见 CLI Mode。

图可视化 UI

图 UI 内置在二进制文件中——每个平台、每个渠道的安装都包含它。运行方式：

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

在浏览器中打开 http://localhost:9749。UI 由共享协调守护进程拥有，因此并发的智能体会话不会启动重复的 HTTP 服务器。

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

codebase-memory-mcp config set auto_index true

启用后，新项目会在首次连接时自动索引。之前已索引的项目会在后台监听器中注册，用于持续的基于 git 的变更检测。可配置的文件限制：config set auto_index_limit 50000。

监听器注册由 auto_watch（默认 true）单独控制。设置 config set auto_watch false 可阻止会话将其项目注册到后台监听器——当跨多个项目工作时很有用，这样每个会话被限制在显式索引范围内。

要完全关闭监听器，请设置 config set watcher_enabled false（默认 true）：后台轮询线程永不启动，没有项目被注册，而 auto_index 和手动 index_repository 继续工作。与按会话检查的 auto_watch 不同——watcher_enabled 在后台守护进程启动时读取一次，因此修改后需要运行 codebase-memory-mcp daemon stop；仅重连 MCP 客户端不会重启守护进程。详见 docs/CONFIGURATION.md。

更新在每个平台上都通过安装脚本运行，而非在运行的二进制文件内部。codebase-memory-mcp update 验证你的标志后打印要运行的确切命令：

# macOS / Linux
bash "<install-dir>/install.sh"

# Windows
powershell -ExecutionPolicy Bypass -File "<install-dir>\install.ps1"

安装脚本在安装时放置在二进制文件旁边，因此打印的路径会在可执行文件旁边解析。它是幂等的，所以重复运行就是更新：它停止守护进程、停用运行的二进制文件、安装新的，并清理。

为什么这样设计。 在 Windows 上这是硬性要求——正在运行的执行文件无法替换自己的镜像，所以交换必须由一个不是被替换二进制文件的进程来完成。在 macOS 和 Linux 上这是深思熟虑的选择：进程内更新器本质是一个下载器（获取存档、验证、解压、标记文件为可执行、运行它），在每个二进制文件中携带这个组合来服务一个大多数人只运行几次的命令是一笔糟糕的交易。发布存档现在完全不携带下载 URL，cbm 本身不发出任何网络请求——它不在后台检查新版本，没有任何东西回连。你从安装脚本、包管理器或 GitHub 了解新版本发布。

如果 PowerShell 因为文件来自互联网而拒绝运行脚本，先用 Unblock-File 解除阻塞。

通过 npm 或 pip 安装？在每个平台上用你的包管理器更新（npm install -g codebase-memory-mcp@latest / pip install -U codebase-memory-mcp）。

codebase-memory-mcp uninstall

移除自有的智能体配置条目、Skill、钩子、指令和已安装的二进制文件。现有的图索引会列出并仅在确认后删除。

安装在二进制文件旁边的安装脚本会被报告而非删除——卸载会打印其路径和 rm 命令。这是刻意保留的：它可能是你自己的副本、指向 checkout 的符号链接，或由包管理器管理的，卸载程序不应该删除它无法证明所有权的文件。

架构概览：get_architecture 在一次调用中返回语言、包、入口点、路由、热点、边界、层和集群

架构决策记录：manage_adr 在会话之间持久化架构决策

Louvain 社区检测：通过聚类调用边发现功能模块

Git diff 影响映射：detect_changes 将未提交的变更映射到受影响的符号并带有风险分类

调用图：跨文件和包解析函数调用（导入感知、类型推断）

死代码检测：查找零调用者的函数，排除入口点

类 Cypher 查询：MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name

语义搜索（semantic_query）：跨整个图的向量搜索，由内置的 Nomic nomic-embed-code 嵌入驱动（40K tokens，768d int8）编译进二进制文件——无需 API key，无需 Ollama，无需 Docker。11 信号组合评分（TF-IDF、RRI、API/类型/装饰器签名、AST 配置、数据流、Halstead-lite、MinHash、模块邻近度、图扩散）。

BM25 全文搜索通过 SQLite FTS5 和 cbm_camel_split 分词器（感知 camelCase / snake_case）

结构化搜索（search_graph）：正则名称模式、标签过滤器、最小/最大度数、文件作用域

代码搜索（search_code）：仅对已索引文件进行图增强的 grep

跨服务链接

HTTP 路由 ↔ 调用点匹配，带置信度评分

gRPC、GraphQL、tRPC 服务检测，支持提取 protobuf 路由

跨 8 种语言的 Socket.IO、EventEmitter 及通用发布-订阅模式的通道检测（EMITS / LISTENS_ON），含常量解析

跨仓库智能

在同一个 store 下索引的多个仓库之间，通过 CROSS_* 边连接节点

跨仓库架构可视化的 Multi-galaxy 3D UI 布局

跨仓库架构摘要，整合索引 fleet 中所有仓库的服务、路由和依赖关系

边类型（部分）

CALLS — 一个可调用对象在源站点被调用

CALL_REFERENCE — 一个可调用对象在支持的引用站点被使用（例如直接值参数），并解析到唯一目标

USAGE — 一个标识符被使用，但无法证明唯一可调用目标（包括歧义或复杂表达式）

IMPORTS、DEFINES、IMPLEMENTS、INHERITS

HTTP_CALLS、ASYNC_CALLS（跨服务）

EMITS、LISTENS_ON（通道）

DATA_FLOWS，含参数到形参的映射 + 字段访问链

SIMILAR_TO（MinHash + LSH 近克隆检测，Jaccard 评分）

SEMANTICALLY_RELATED（词汇不匹配、同语言、评分 ≥ 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）

基础设施即代码索引 — Dockerfile、Kubernetes 清单、Kustomize overlay 作为图节点

混合 LSP 语义类型解析，支持 Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin、Rust 和 Perl — 轻量级 C 语言实现语言类型解析算法，在结构上借鉴并兼容主流语言服务器，包括 tsserver / typescript-go、pyright、gopls、Roslyn、Eclipse JDT 和 rust-analyzer（参数绑定、返回类型推断、泛型替换、JSX 组件分发、plain JS 文件的 JSDoc 推断、PHP 的命名空间 + trait + 延迟静态绑定解析、C# 的文件作用域命名空间 + records + LINQ 方法语法、Java 的类层次结构 + 重载 + lambda 解析、Kotlin 的扩展函数 + scope-function 解析、Rust 的 trait-method + UFCS 解析）

RAM 优先流水线：LZ4 压缩、内存 SQLite，结束时单次 dump，内存释放

分发与运行

原生运行时集，零基础设施服务：SQLite 后端，持久化到 ~/.cache/codebase-memory-mcp/

自动同步：后台文件监视器检测文件变更并自动重新索引

路由节点：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）— 由监视器写入，用于低延迟增量更新

Best（zstd -9 + 剥离索引 + VACUUM INTO）— 在显式 index_repository 时写入

Fast（zstd -3）— 由监视器写入，用于低延迟增量更新

Bootstrap：当本地 DB 不存在但产物存在时，index_repository 先导入产物，再运行增量索引 — 避免全量重新索引

无合并冲突：首次导出时自动创建 .codebase-memory/.gitattributes 行并设置 merge=ours，因此对二进制产物的并发编辑不会产生冲突

谨慎提交：产物在每次索引时都会被重写，包括监视器的 Fast 层级，git 将每次重写存储为一个全新的 blob。每次刷新都提交会让一个 20 MB 的文件变成数 GB 的历史 — 某个团队在这个单一路径上达到了约 6 GB（累计约 350 次提交）。选择一个节奏（发布版、里程碑、每日构建任务）而不是每次保存都提交。

Git LFS，如必须每次提交都迁移：从仓库根目录的 .gitattributes 追踪它，保留自动创建的 .codebase-memory/.gitattributes — 更近的文件负责提供 merge=ours，只有 filter 来自根目录：.codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text。只追踪 .zst；artifact.json 很小且携带 schema 版本。该属性仅对未来提交生效，因此已有 blob 历史记录的仓库需要先用 git-filter-repo 重写。引入 LFS 前需权衡两个成本：GitHub 按存储和带宽计量 LFS 费用，且其对象无法在联系支持前被裁剪；每位队友都需要运行 git lfs install — 未安装的话 checkout 会留下指针文件放在产物应有的位置，通过完整性检查的导入会拒绝它，然后回退到全量重新索引。

.codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text

可选：除非你想要，否则不提交。如希望所有人都从头重新索引，将 .codebase-memory/ 添加到 .gitignore。

结果在精神上类似于 graphify 的 graphify-out/ 目录，但作为单一压缩文件，具有明确的双层级导出、完整性检查的导入和零合并摩擦。

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

You: "what calls ProcessOrder?"

Agent 调用: trace_path(function_name="ProcessOrder")

Agent 追踪调用链: ProcessOrder → validateOrder → checkInventory → reserveStock

[可视化图谱展示调用路径]

You: "show me the data flow from user input to database"

Agent: get_data_flows(source="user input", target="database")

codebase-memory-mcp 将你的代码库转化为可查询的知识图谱，让 AI 智能体能够以超越传统语义搜索的方式进行推理。上下文工程的核心 — 将结构化代码知识与 AI 推理分离，专注做好每件事。

通过 CLI 或 MCP 协议集成到 AI 智能体工作流中，追踪复杂调用链、理解数据流、分析跨服务依赖 — 所有这些都基于你代码库的实际结构，而不是模糊的相似性匹配。