codebase-memory-mcp

codebase-memory-mcp

AI 编程智能体最快、最高效的代码智能引擎。 对一个普通仓库进行全索引只需毫秒级，Linux 内核（28M 代码行，75K 文件）只需 3 分钟。结构查询响应时间低于 1 毫秒。以单个静态二进制文件形式交付，支持 macOS、Linux 和 Windows — 下载，运行 install，完成。

通过 tree-sitter AST 分析支持 158 种语言的高质量解析，并针对 Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin 和 Rust 增加了 Hybrid LSP（混合语言服务协议）语义类型解析功能 — 生成包含函数、类、调用链、HTTP 路由和跨服务链接的持久性知识图谱。14 个 MCP 工具。零依赖。即插即用，兼容 11 个编码智能体。

研究 — 本项目背后的设计与基准测试在预印本 Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP (arXiv:2603.27277) 中进行了描述。在 31 个真实仓库上的评估结果：回答质量 83%，与逐文件探索相比，Token 数量减少 10 倍，工具调用次数减少 2.1 倍。

安全与信任 — 此工具会读取您的代码库并写入您的智能体配置文件。这就是它的设计用途。如果您希望在运行前进行审计，完整源代码在此 — 每个发行版二进制文件均经过签名、校验和验证，并由 70+ 反病毒引擎扫描。所有处理完全在本地进行；您的代码永远不会离开您的机器。发现安全问题？我们想知道 — 请参阅 SECURITY.md。安全是我们的首要任务。

内置 3D 图形可视化（UI 变体）— 在 localhost:9749 探索您的知识图谱

为什么选择 codebase-memory-mcp

• 极致的索引速度 — Linux 内核（28M 代码行，75K 文件）只需 3 分钟。基于内存的流水线：LZ4 压缩、内存 SQLite、融合 Aho-Corasick 模式匹配。索引完成后释放内存。
• 即插即用 — 单个静态二进制文件，支持 macOS（arm64/amd64）、Linux（arm64/amd64）和 Windows（amd64）。无需 Docker、无需运行时依赖、无需 API 密钥。下载 → install → 重启智能体 → 完成。
• 158 种语言 — 内置的 tree-sitter 语法已编译进二进制文件中。无需安装任何东西，不会出现兼容性问题。
• Token 数量减少 120 倍 — 5 个结构查询：约 3,400 个 Token，而逐文件搜索需要约 412,000 个 Token。一次图谱查询可替代数十次 grep/read 循环。
• 11 个智能体，一条命令 — install 自动检测 Claude Code、Codex CLI、Gemini CLI、Zed、OpenCode、Antigravity、Aider、KiloCode、VS Code、OpenClaw 和 Kiro — 为每个智能体配置 MCP 条目、指令文件和工具前钩子。
• 内置图形可视化 — 在 localhost:9749 上提供 3D 交互式 UI（可选 UI 二进制变体）。
• 基础设施即代码索引 — Dockerfile、Kubernetes 清单和 Kustomize 覆盖层作为图形节点进行索引，并带有交叉引用。K8s 类型使用 Resource 节点，Kustomize 覆盖层使用 Module 节点，并通过 IMPORTS 边连接到引用的资源。
• 14 个 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 -s -- --ui

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. 运行它
.\install.ps1

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

重启您的编码智能体。说 "Index this project" — 完成。

手动安装

1. 从最新发布为您的平台下载归档文件：

   • 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：

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

   Windows（PowerShell）：

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

3. 重启您的编码智能体。

install 命令会自动移除 macOS 隔离属性并临时签名二进制文件 — 无需手动执行 xattr/codesign。

install 命令会自动检测所有已安装的编码智能体，并为每个智能体配置 MCP 服务器条目、指令文件、技能和工具前钩子。

图形可视化 UI

如果您下载了 ui 变体：

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

在浏览器中打开 http://localhost:9749。UI 作为后台线程与 MCP 服务器一起运行 — 每当您的智能体连接时即可使用。

自动索引

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

codebase-memory-mcp config set auto_index true

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

保持更新

codebase-memory-mcp update

MCP 服务器也会在启动时检查更新，并在首次工具调用时通知是否有新版本可用。

卸载

codebase-memory-mcp uninstall

移除所有智能体配置、技能、钩子和指令。不会移除二进制文件或 SQLite 数据库。

功能特性

图谱与分析

• 架构概览：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 密钥、无需 Ollama、无需 Docker。采用 11 信号组合评分（TF-IDF、RRI、API/类型/装饰器签名、AST 轮廓、数据流、Halstead 轻量、MinHash、模块距离、图谱扩散）。
• BM25 全文搜索：通过 SQLite FTS5 实现，使用 cbm_camel_split 分词器（支持 camelCase / snake_case 感知）
• 结构搜索（search_graph）：正则名称模式、标签过滤器、最小/最大度数、文件范围限定
• 代码搜索（search_code）：仅在索引文件上进行的增强型 grep 搜索

跨服务链接

• HTTP 路由 ↔ 调用点匹配，带有置信度评分
• gRPC、GraphQL、tRPC 服务检测，支持 protobuf 路由提取
• 通道检测（EMITS / LISTENS_ON）：适用于 Socket.IO、EventEmitter 和通用的发布-订阅模式，覆盖 8 种语言并支持常量解析

跨仓库智能

• CROSS_* 边：链接同一存储区下多个仓库的节点
• 多星系 3D UI 布局：用于跨仓库架构可视化
• 跨仓库架构摘要：结合整个索引集群的服务、路由和依赖关系

边类型（部分）

• CALLS、IMPORTS、DEFINES、IMPLEMENTS、INHERITS
• HTTP_CALLS、ASYNC_CALLS（跨服务）
• EMITS、LISTENS_ON（通道）
• DATA_FLOWS（带有参数到参数映射和字段访问链）
• SIMILAR_TO（MinHash + LSH 近似克隆检测，Jaccard 评分）
• SEMANTICALLY_RELATED（词汇不匹配，同语言，分数 ≥ 0.80）

索引流水线

• 158 个内置的 tree-sitter 语法：已编译进二进制文件
• 通用包/模块解析：裸 specifier（如 @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 覆盖层作为图谱节点
• Hybrid LSP 语义类型解析：针对 Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin 和 Rust — 一个轻量级的 C 语言类型解析算法实现，在结构上受主要语言服务器（包括 tsserver / typescript-go、pyright、gopls、Roslyn、Eclipse JDT、rust-analyzer）启发并与之兼容（参数绑定、返回类型推断、泛型替换、JSX 组件分发、纯 JS 文件的 JSDoc 推断、PHP 的命名空间 + trait + 后期静态绑定解析、C# 的文件范围命名空间 + record + LINQ 方法语法、Java 的类层次结构 + 重载 + lambda 解析、Kotlin 的扩展函数 + 作用域函数解析、Rust 的 trait 方法 + UFCS 解析）
• 基于内存的流水线：LZ4 压缩、内存 SQLite、最后一次性转储到磁盘。索引完成后释放内存。

分发与操作

• 单一静态二进制文件，零基础设施：基于 SQLite 存储，持久化到 ~/.cache/codebase-memory-mcp/
• 自动同步：后台监视器检测文件变更并自动重新索引
• 路由节点：REST 端点作为一等图谱实体
• CLI 模式：codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*"}'
• 可用渠道：npm、PyPI、Homebrew、Scoop、Winget、Chocolatey、AUR、go install

团队共享图谱产物

将单个压缩文件提交到您的仓库，您的团队成员即可跳过重新索引。

.codebase-memory/graph.db.zst 是一个 zstd 压缩的知识图谱快照，位于源代码旁边。当您索引时，该产物会被写入或刷新；当团队成员克隆仓库并首次运行 codebase-memory-mcp 时，该产物会被解压缩，增量索引会填充他们的本地差异。

• 格式：SQLite 数据库，去除索引，VACUUM INTO 压缩，然后使用 zstd 1.5.7 压缩（典型比例为 8–13:1）
• 两个级别：
  • 最佳（zstd -9 + 索引去除 + VACUUM INTO）— 通过显式的 index_repository 写入
  • 快速（zstd -3）— 由监视器写入，用于低延迟的增量更新
• 引导：当本地数据库不存在但产物存在时，index_repository 首先导入产物，然后运行增量索引 — 避免了完整的重新索引成本
• 无合并冲突：在首次导出时自动创建 .gitattributes 行 merge=ours，因此并发编辑不会在二进制产物上产生冲突
• 可选：除非您想要，否则永远不会提交。如果您希望每个人都从头重新索引，请将 .codebase-memory/ 添加到 .gitignore。

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

工作原理

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

您: "哪些函数调用了 ProcessOrder?"

智能体调用: trace_path(function_name="ProcessOrder", direction="inbound")

codebase-memory-mcp: 执行图谱查询，返回结构化结果

智能体: 用通俗的英文呈现调用链

为什么不内置 LLM？ 其他代码图谱工具嵌入了 LLM 用于自然语言到图谱查询的翻译。这意味着额外的 API 密钥、额外的成本以及另一个需要配置的模型。通过 MCP，您已经在与之对话的智能体就是查询翻译器。

性能

在 Apple M3 Pro 上的基准测试：

操作	时间	备注
Linux 内核全索引	3 分钟	28M 代码行，75K 文件 → 4.81M 节点，7.72M 边
Linux 内核快速索引	1 分 12 秒	1.88M 节点
Django 全索引	~6 秒	49K 节点，196K 边
Cypher 查询	<1 毫秒	关系遍历
名称搜索（正则）	<10 毫秒	SQL LIKE 预过滤
死代码检测	~150 毫秒	全图扫描，带度数过滤
追踪调用路径（深度=5）	<10 毫秒	BFS 遍历

基于内存的流水线：所有索引在内存中运行（LZ4 HC 压缩读取、内存 SQLite、最后一次性转储）。索引完成后，内存会释放回操作系统。

Token 效率：通过 codebase-memory-mcp 完成的五个结构查询消耗约 3,400 个 Token，而通过逐文件 grep 探索则需要约 412,000 个 Token — 减少了 99.2%。

安装

预构建二进制文件

平台	标准版	带有图形 UI
macOS（Apple Silicon）	codebase-memory-mcp-darwin-arm64.tar.gz	codebase-memory-mcp-ui-darwin-arm64.tar.gz
macOS（Intel）	codebase-memory-mcp-darwin-amd64.tar.gz	codebase-memory-mcp-ui-darwin-amd64.tar.gz
Linux（x86_64）	codebase-memory-mcp-linux-amd64.tar.gz	codebase-memory-mcp-ui-linux-amd64.tar.gz
Linux（ARM64）	codebase-memory-mcp-linux-arm64.tar.gz	codebase-memory-mcp-ui-linux-arm64.tar.gz
Windows（x86_64）	codebase-memory-mcp-windows-amd64.zip	codebase-memory-mcp-ui-windows-amd64.zip

每个版本都包含带有 SHA-256 哈希的 checksums.txt。所有二进制文件都是静态链接的 — 没有共享库依赖。

Windows 说明：SmartScreen 可能会对未签名的软件显示警告。点击 "更多信息" → "仍然运行"。使用 checksums.txt 验证完整性。

设置脚本

自动下载 + 安装

macOS / Linux：

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

Windows（PowerShell）：

irm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 | iex

AUR（Arch Linux）

yay -S codebase-memory-mcp-bin

paru -S codebase-memory-mcp-bin

codebase-memory-mcp-bin 软件包可在以下位置获取：https://aur.archlinux.org/packages/codebase-memory-mcp-bin

通过 Claude Code 安装

您: "安装这个 MCP 服务器：https://github.com/DeusData/codebase-memory-mcp"

从源码构建

前置条件：C 编译器 + zlib

要求	检查	安装
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	大多数系统已预装

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh                    # 标准二进制文件
scripts/build.sh --with-ui          # 带有图形可视化
# 二进制文件位于：build/c/codebase-memory-mcp

手动 MCP 配置

如果您不想使用 install 命令

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

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

重启您的智能体。使用 /mcp 验证 — 您应该会看到 codebase-memory-mcp 带有 14 个工具。

多智能体支持

install 自动检测并配置所有已安装的智能体：

智能体	MCP 配置	指令	钩子
Claude Code	.claude/.mcp.json	4 个技能	PreToolUse（Grep/Glob 图谱增强，非阻塞）
Codex CLI	.codex/config.toml	.codex/AGENTS.md	SessionStart 提醒
Gemini CLI	.gemini/settings.json	.gemini/GEMINI.md	BeforeTool（grep 提醒）+ SessionStart 提醒
Zed	settings.json（JSONC）	—	—
OpenCode	opencode.json	AGENTS.md	—
Antigravity	.gemini/config/mcp_config.json（共享）	antigravity-cli/AGENTS.md	SessionStart 提醒
Aider	—	CONVENTIONS.md	—
KiloCode	mcp_settings.json	~/.kilocode/rules/	—
VS Code	Code/User/mcp.json	—	—
OpenClaw	openclaw.json	—	—
Kiro	.kiro/settings/mcp.json	—	—

钩子在结构上都是非阻塞的（退出码为 0，每个失败路径都会处理）。 对于 Claude Code，PreToolUse 钩子会拦截 Grep/Glob（从不拦截 Read — 拦截 Read 会破坏先读后编辑的不变性），当搜索 Token 匹配已索引的符号时，会通过 search_graph 将它们作为 additionalContext 注入，以便智能体在正常搜索结果旁边获得结构化上下文。对于 Codex、Gemini CLI 和 Antigravity，SessionStart 钩子会将一行代码发现提醒作为会话上下文注入（Gemini CLI 也保留其 BeforeTool 提醒）。 安装的 Claude shim 文件命名为 cbm-code-discovery-gate，以保持与现有安装的向后兼容性；尽管名称过时，但它从不拦截、从不阻塞。

CLI 模式

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

codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/repo"}'
codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'
codebase-memory-mcp cli trace_path '{"function_name": "Search", "direction": "both"}'
codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'
codebase-memory-mcp cli list_projects
codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.results[].name'

MCP 工具

索引

工具	描述
index_repository	将一个仓库索引到图谱中。之后自动同步会保持其最新。
list_projects	列出所有已索引的项目，包含节点/边计数。
delete_project	移除一个项目及其所有图谱数据。
index_status	检查项目的索引状态。

查询

工具	描述
search_graph	通过标签、名称模式、文件模式、度数过滤器进行结构化搜索。通过 limit/offset 支持分页。
trace_path	BFS 遍历 — 谁调用了某个函数，以及该函数又调用了什么（别名：trace_call_path）。深度 1-5。
detect_changes	将 git diff 映射到受影响的符号 + 影响范围，并带有风险分类。
query_graph	执行类 Cypher 的图谱查询（只读）。
get_graph_schema	节点/边计数、关系模式、每个标签的属性定义。首先运行此命令。
get_code_snippet	通过限定名读取某个函数的源代码。
get_architecture	代码库概览：语言、包、路由、热点、集群、ADR。
search_code	在已索引的项目文件中进行类似 grep 的文本搜索。
manage_adr	架构决策记录的 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。

此子集之外的任何内容（write/MERGE/CALL 子句、不支持的函数、列表/映射字面量、推导式、路径函数、参数）都将失败并返回清晰的 unsupported ... 错误，而不是返回空结果。

忽略文件

分层：硬编码模式（.git、node_modules 等） → .gitignore 层次结构 → .cbmignore（项目特定，gitignore 语法）。符号链接总是被跳过。

配置

codebase-memory-mcp config list                          # 显示所有设置
codebase-memory-mcp config set auto_index true           # 会话启动时自动索引
codebase-memory-mcp config set auto_index_limit 50000    # 自动索引的最大文件数
codebase-memory-mcp config reset auto_index              # 重置为默认值

环境变量

变量	默认值	描述
CBM_CACHE_DIR	~/.cache/codebase-memory-mcp	覆盖数据库存储目录。所有项目索引和配置都存储在此处。
CBM_DIAGNOSTICS	false	设置为 1 或 true 以启用定期诊断输出到 /tmp/cbm-diagnostics-<pid>.json。
CBM_DOWNLOAD_URL	（GitHub 发布版）	覆盖用于更新的下载 URL。用于测试或自托管部署。
CBM_LOG_LEVEL	info	设置最低日志级别。接受的值（不区分大小写）：debug、info、warn、error、none — 或者它们的数值等效项 0–4，与内部枚举匹配。日志输出到 stderr；stdout 保留给 MCP JSON-RPC。
CBM_WORKERS	（自动检测）	覆盖并行索引的工作线程数，由 cbm_default_worker_count 返回。在容器中很有用，因为 sysconf(_SC_NPROCESSORS_ONLN) 报告的是主机的 CPU 而不是 cgroup 的有效配额。范围 1–256；无效值会被忽略并发出警告。

# 将索引存储在自定义目录中
export CBM_CACHE_DIR=~/my-projects/cbm-data

自定义文件扩展名

通过 JSON 配置文件将额外的文件扩展名映射到支持的语言。对于框架