GitHub Trending：DeusData/codebase-memory-mcp —— 把代码库变成知识图谱的 MCP 服务器

项目概览

仓库：DeusData/codebase-memory-mcp
语言：C 88.2% · C++ 10.5% · Shell 0.7% · TypeScript 0.3%
Stars：6,167（今日新增 +371）
Forks：516
许可证：MIT
最新版本：v0.8.1（2026-06-12）
论文：arXiv:2603.27277

过去一年，几乎每个 AI 编程代理（Claude Code、Codex CLI、Cursor、Gemini CLI、Aider……）都在反复做同一件事：逐文件搜索代码库来理解代码。这种线性 grep → read → grep → read 的探索模式不仅慢，而且极其消耗 Token —— 一次典型的代码理解任务可能消耗数十万 Token。codebase-memory-mcp 给出了一个根本性的答案：一次性将代码库索引为知识图谱，而后所有查询都在亚毫秒内完成，Token 用量下降 99%。更令人印象深刻的是，它是用 C 写成的单一静态二进制，零依赖，在 Apple M3 Pro 上索引 Linux 内核（28M LOC，75K 文件）仅需 3 分钟。

为什么需要它

传统的 AI 编码代理代码探索模式：

1
2
3
4
5


代理: "processOrder 函数被谁调用？"
  → grep "processOrder" 整个代码库（返回大量匹配）
  → 逐个读取匹配文件
  → 手动追踪调用链
  → 再 grep，再 read，再 grep……

这个循环反复发生，每次消耗数万 Token。codebase-memory-mcp 将它替换为：

1
2
3


代理: "谁调用了 processOrder？"
  → MCP 工具 trace_path(function_name="processOrder", direction="inbound")
  → 毫秒内返回结构化调用链

5 个结构化查询消耗约 3,400 Token，而逐文件 grep 探索需要约 412,000 Token —— 减少 99.2%。这不仅仅是成本的节省，更意味着代理可以在一次对话中理解更复杂的代码库。

核心架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


src/
  main.c              入口点（MCP stdio 服务器 + CLI + install/update/config）
  mcp/                 MCP 服务器（14 个工具，JSON-RPC 2.0）
  cli/                 安装/卸载/更新/配置（11 个代理，Hooks，指令）
  store/               SQLite 图谱存储（节点、边、遍历、搜索、Louvain 社区检测）
  pipeline/            多通道索引管道（结构 → 定义 → 调用 → HTTP 链接 → 配置 → 测试）
  cypher/              Cypher 查询词法分析、解析器、规划器、执行器
  discover/            文件发现（.gitignore、.cbmignore、符号链接处理）
  watcher/             后台自动同步（git 轮询，自适应间隔）
  traces/              运行时追踪摄入
  ui/                  嵌入式 HTTP 服务器 + 3D 图谱可视化
  foundation/          平台抽象（线程、文件系统、日志、内存）
internal/cbm/          内置 tree-sitter 语法（158 种语言）+ AST 提取引擎

索引管道采用 RAM-first 设计：LZ4 压缩、内存 SQLite，索引完成后单次 dump 到磁盘并释放内存。持久化使用 WAL 模式 SQLite，ACID 安全，存储在 ~/.cache/codebase-memory-mcp/。

性能基准

在 Apple M3 Pro 上的测试结果：

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

两大杀手锏

1. Hybrid LSP —— 超越 tree-sitter 的语义解析

tree-sitter 只提供语法级 AST，无法追踪导入、泛型、继承或标准库类型。codebase-memory-mcp 内嵌了轻量 C 语言实现的类型解析算法（结构上受 tsserver、pyright、gopls、Roslyn、Eclipse JDT、rust-analyzer 启发），作为 Hybrid LSP 层在 tree-sitter 之上运行，用类型信息精炼调用边。

语言	关键处理能力
Python	导入+点号子模块遍历、dataclass、`Self` 返回类型、泛型、SQLAlchemy 2.0、Pydantic、async/await、类型窄化
TypeScript/JS/JSX/TSX	泛型、JSX 组件分发、JSDoc 推断、`.d.ts` 声明、模块重导出、方法链式调用
Go	泛型、嵌入结构体、接口满足、包感知导入解析
C/C++	C 侧：宏+typedef 链+头文件链接；C++ 侧：模板、命名空间、`auto` 推断、类层次结构
Java	导入、泛型、注解、重载匹配、lambda/方法引用、JDK 标准库
Kotlin	扩展函数、data class、可空类型解包、scope functions、中缀调用
Rust	`use` 声明+模块路径、trait 方法、泛型+trait bounds、derive 宏方法合成、UFCS
C#	global usings、records、LINQ、`async Task<T>` 解包、`var` 推断
PHP	命名空间、traits、后期静态绑定、PHPDoc 推断

双层架构：Tree-sitter 通道覆盖全部 158 种语言（快速语法级）；Hybrid LSP 通道在上层做类型感知精炼。没有 Hybrid LSP 通道的语言回退到文本解析。

2. 11 个代理，一条命令

install 命令自动检测并配置已安装的所有 AI 编程代理：

代理	MCP 配置	额外集成
Claude Code	`.claude/.mcp.json`	4 Skills + PreToolUse Hook（Grep/Glob 图谱增强）
Codex CLI	`.codex/config.toml`	`.codex/AGENTS.md` + SessionStart 提醒
Gemini CLI	`.gemini/settings.json`	`.gemini/GEMINI.md` + BeforeTool/Start 提醒
Zed	`settings.json` (JSONC)	—
OpenCode	`opencode.json`	`AGENTS.md`
Antigravity	`mcp_config.json`	`AGENTS.md` + SessionStart
Aider	—	`CONVENTIONS.md`
KiloCode	`mcp_settings.json`	Rules 文件
VS Code	`Code/User/mcp.json`	—
OpenClaw	`openclaw.json`	—
Kiro	`.kiro/settings/mcp.json`	—

14 个 MCP 工具

索引工具

工具	功能
`index_repository`	索引仓库，之后自动同步保持更新
`list_projects`	列出所有已索引项目及节点/边计数
`delete_project`	移除项目及所有图谱数据
`index_status`	检查项目索引状态

查询工具

工具	功能
`search_graph`	按标签、名称模式、文件模式、度过滤的结构化搜索
`trace_path`	BFS 遍历——谁调用了某函数以及它调用了谁（深度 1-5）
`detect_changes`	将 git diff 映射到受影响符号 + 爆炸半径 + 风险分类
`query_graph`	执行类 Cypher 图谱查询（只读）
`get_graph_schema`	获取图谱 Schema——节点/边计数、关系模式、属性定义
`get_code_snippet`	按限定名读取函数源代码
`get_architecture`	代码库概览：语言、包、路由、热点、集群、ADR
`search_code`	在已索引项目文件中进行 grep 式文本搜索
`manage_adr`	架构决策记录（ADR）CRUD
`ingest_traces`	摄入运行时追踪以验证 HTTP_CALLS 边

图谱数据模型

节点标签：Project, Package, Folder, File, Module, Class, Function, Method, Interface, Enum, Type, Route, Resource

边类型（精选）：

CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS — 基础调用关系
HTTP_CALLS, ASYNC_CALLS — 跨服务 HTTP 链接
EMITS, LISTENS_ON — 事件通道（Socket.IO、EventEmitter 等）
DATA_FLOWS — 参数到参数的映射 + 字段访问链
SIMILAR_TO — MinHash + LSH 近似克隆检测
SEMANTICALLY_RELATED — 跨词汇的语义关联

支持 openCypher 只读子集查询，包括 MATCH、OPTIONAL MATCH、WHERE、WITH、聚合函数（count/sum/avg/min/max/collect）、变长路径 [*1..3] 等。

快速开始

一键安装（macOS/Linux）

1

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

带 3D 图谱可视化 UI：

1

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

Windows（PowerShell）

1
2


Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
.\install.ps1

安装后重启编程代理，说一句 “Index this project” 即可开始使用。

自动索引

1

codebase-memory-mcp config set auto_index true

启用后新项目首次连接时自动索引，可用 auto_index_limit 限制最大文件数。

图谱可视化

1

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

浏览器打开 http://localhost:9749，可 3D 交互式浏览代码图谱。

团队共享

.codebase-memory/graph.db.zst 是知识图谱的 zstd 压缩快照，可直接提交到仓库。团队其他成员 clone 后自动导入，跳过重新索引。提供 Best（zstd -9，显式索引时写入）和 Fast（zstd -3，监视器增量更新）两层压缩。首次导出自动创建 .gitattributes（merge=ours），避免合并冲突。

安全性

每个发布二进制经过 VirusTotal 70+ 引擎扫描（零检出才发布）、SLSA Level 3 构建溯源、Sigstore cosign 无密钥签名、SHA-256 校验和和 CodeQL SAST 验证。所有处理 100% 在本地完成，代码永不离开你的机器。零运行时依赖，无传递供应链风险。

与其他方案对比

维度	codebase-memory-mcp	传统 grep+read 探索	其他代码图谱工具
索引速度	毫秒-分钟级	无需索引	分钟-小时级
查询延迟	亚毫秒	秒-分钟	毫秒-秒
Token 效率	极高（3,400/任务）	极低（412K/任务）	中等
语言支持	158 种	不限	20-50 种
部署复杂度	单二进制，零依赖	无	Docker/Python 环境
LLM 依赖	无（通过 MCP 解耦）	无	通常内嵌 LLM
跨服务分析	支持（HTTP/gRPC/tRPC）	不支持	部分支持

综合评价

codebase-memory-mcp 是一个在工程执行上几近完美的项目：

亮点：

速度惊人：C 语言实现 + RAM-first 管道，Linux 内核 3 分钟索引完，查询亚毫秒
真正的零依赖：单静态二进制，无 Docker、无 Python 环境、无 API 密钥
Hybrid LSP 语义解析：直接在二进制里跑 9 种语言的类型推断，是个硬核工程 feat
代理生态全覆盖：install 一条命令搞定 11 个编程代理的 MCP 配置
安全第一：多层签名验证 + VirusTotal + 全本地处理
学术支撑：有 arXiv 论文，在 31 个仓库上做了系统评估

适用场景：

使用 AI 编程代理（Claude Code/Codex/Cursor 等）且频繁需要理解大型代码库
大型 monorepo 的跨服务依赖分析
代码审计、死代码检测、架构可视化
团队协作（共享图谱制品）

局限性：

完全依赖 MCP 生态，独立使用价值有限
C 语言实现意味着社区贡献门槛较高
Hybrid LSP 层对动态语言（Python/PHP）的解析率约 95%，仍有边界情况

总的来说，codebase-memory-mcp 代表了 AI 编程代理基础设施的一个明确趋势：从"搜索文件"到"查询知识图谱"的范式转变。当你的代码库足够大、足够复杂时，这种结构性理解的价值远超"又一个 grep 包装工具"。

项目仓库：github.com/DeusData/codebase-memory-mcp
论文：Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP