codebase-memory-mcp 24K Star 的代码知识图谱引擎

它是什么

一句话：给 AI 编程 Agent 装上「代码大脑」的 MCP 服务器。

你用 Claude Code、Codex CLI、Cursor 这类 AI 编程工具的时候，有没有遇到过这种问题：Agent 每次都要重新读代码、重新理解项目结构，token 烧得飞快，稍微大点的项目就懵了。

codebase-memory-mcp 的思路是：先花极短时间把整个代码库索引成一张知识图谱，然后 Agent 每次查询只需要 sub-millisecond 级别的图查询，而不是重新读文件。

它是纯 C 写的单个静态二进制文件，零依赖，下载即用。支持 158 种编程语言，索引速度极快——Linux 内核（2800 万行、7.5 万个文件）3 分钟搞定。查询一次用的 token 只有传统方式的 1/120。

解决什么问题

AI 编程 Agent 目前最大的瓶颈之一就是上下文理解效率。传统方式是"逐文件阅读"：

方式	问题
逐文件 grep + read	5 次结构化查询要 ~412,000 tokens
每次都重新理解项目	重复工作，浪费时间和钱
跨文件调用链追踪	AI 很难自己理清函数间的调用关系
大型代码库	超过几千文件 Agent 就开始"迷路"

codebase-memory-mcp 的方案：索引一次，反复查询。同样的 5 次结构化查询只需要 ~3,400 tokens，省了 99%。而且查询速度从"秒级"变成"亚毫秒级"。

技术架构拆解

索引引擎：tree-sitter + Hybrid LSP

核心用 tree-sitter 做 AST（抽象语法树）解析，内置了 158 种语言的 grammar，全部编译进二进制文件，不需要额外安装任何东西。

在此基础上，对 Python、TypeScript/JavaScript/JSX/TSX、PHP、C#、Go、C、C++、Java、Kotlin、Rust 这 9 种语言做了 Hybrid LSP 语义类型解析——一个轻量 C 实现，兼容主流语言服务器（tsserver、pyright、gopls、Roslyn、rust-analyzer 等），能做参数绑定、返回类型推断、泛型替换、JSX 组件分发等。

索引管线是 RAM-first 的：LZ4 压缩 → 内存 SQLite → 最后一次性 dump 到磁盘。索引完成后立即释放内存。

知识图谱：SQLite + Cypher 查询

索引结果是一张持久化的知识图谱，节点包括函数、类、HTTP 路由、K8s 资源等，边包括：

CALLS — 函数调用关系（跨文件、跨包）
IMPORTS — 模块导入关系
HTTP_CALLS — 跨服务 HTTP 调用
EMITS / LISTENS_ON — 事件频道（Socket.IO、EventEmitter 等）
DATA_FLOWS — 数据流（参数到形参映射）
SIMILAR_TO — 近似代码检测（MinHash + LSH）

支持 Cypher 风格查询语言：

MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name

底层是 SQLite，持久化到 ~/.cache/codebase-memory-mcp/，跨会话不丢失。

语义搜索：内置 Embedding

这是最让人意外的部分——它内置了 Nomic nomic-embed-code 向量模型（768 维 int8，40K token 上下文），直接编译进二进制，不需要 API Key、不需要 Ollama、不需要 Docker。

语义搜索用了 11 种信号混合打分：TF-IDF、RRI、API/Type/Decorator 签名、AST 特征、数据流、Halstead-lite、MinHash、模块邻近度、图扩散等。不是简单的向量相似度，而是结构 + 语义的综合匹配。

跨服务链接

它不只是看单个文件，还能识别服务间的调用关系：

HTTP 路由 ↔ 调用方匹配（带置信度评分）
gRPC、GraphQL、tRPC 服务检测
Proto 文件中的 Route 提取
跨仓库索引：CROSS_* 边连接多个仓库的节点

14 个 MCP 工具

作为 MCP 服务器，它向 Agent 暴露了 14 个工具：

工具	功能
`get_architecture`	一键获取项目架构概览：语言、包、入口点、路由、热点、边界、分层
`search_graph`	结构化图搜索：正则名称、标签过滤、度数范围
`semantic_query`	语义向量搜索（内置 embedding，零配置）
`search_code`	图增强的代码搜索（只搜已索引文件）
`trace`	调用链追踪
`detect_changes`	Git diff 影响分析：未提交变更影响了哪些符号
`dead_code`	死代码检测：找到零调用者的函数
`cypher_query`	Cypher 风格图查询
`manage_adr`	架构决策记录管理
...以及更多搜索、分析、管理工具

Agent 兼容性

install 命令自动检测已安装的编程 Agent 并配置 MCP：

Claude Code
Codex CLI
Gemini CLI
Zed
VS Code
Aider
KiloCode
OpenCode
Antigravity
OpenClaw
Kiro

11 个 Agent，一条命令搞定。

团队协作：Graph Artifact

这是个很有意思的设计——你可以把索引好的知识图谱压缩后提交到 Git 仓库（.codebase-memory/graph.db.zst），队友 clone 下来直接用，跳过重新索引。

zstd 压缩，典型压缩比 8-13:1
两档：Best（zstd -9，显式导出）和 Fast（zstd -3，watcher 增量更新）
自动设置 merge=ours 避免二进制合并冲突
可选，不想提交就加 .gitignore

其他亮点

3D 图可视化 — 可选 UI 变体，localhost:9749 交互式浏览知识图谱
基础设施即代码索引 — Dockerfile、K8s Manifest、Kustomize Overlay 都是图节点
Louvain 社区检测 — 通过调用边聚类自动发现功能模块
自动同步 — 后台 watcher 检测文件变更，自动增量重建索引
CLI 模式 — 不接 MCP 也能直接命令行查询
全平台 — macOS (arm64/amd64)、Linux (arm64/amd64)、Windows (amd64)
多种安装方式 — npm、PyPI、Homebrew、Scoop、Winget、Chocolatey、AUR、go install

学术背景

这个项目有正式的研究论文：Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP（arXiv:2603.27277）。

在 31 个真实仓库上的评测结果：

回答质量 83%
token 消耗减少 10×
工具调用减少 2.1×

安全和供应链

这个项目在安全方面做得很扎实：

SLSA 3 级供应链安全认证
每个 release 都签名、校验和、70+ 杀毒引擎扫描
OpenSSF Scorecard 通过
100% 本地处理，代码不离开你的机器
MIT 开源协议

怎么用

一键安装（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）

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

使用

# 安装后重启你的编程 Agent，然后说：
"Index this project"

# 开启自动索引
codebase-memory-mcp config set auto_index true

# 更新
codebase-memory-mcp update

# 图可视化（UI 变体）
codebase-memory-mcp --ui=true --port=9749

实际体验和局限

首次索引大项目需要时间 — 虽然号称 Linux 内核 3 分钟，但普通开发机可能更久，取决于磁盘 IO
内存占用 — 索引期间 RAM-first 策略，大项目可能吃几个 G 内存（索引完释放）
C 语言写的 — 好处是快且零依赖，坏处是你没法自己改源码调试（大多数人不会 C）
Hybrid LSP 覆盖有限 — 高级语义解析只覆盖 9 种语言，其他 149 种靠 tree-sitter AST
Graph Artifact 是二进制文件 — 提交到 Git 会增大仓库体积，虽然压缩了但还是要注意

和同类工具对比

工具	定位	codebase-memory-mcp 的优势
graphify	代码图谱生成	更快、内置 embedding、MCP 原生集成
Sourcegraph	代码搜索平台	零基础设施、本地运行、Agent 直接调用
Aider / Claude Code 原生	逐文件理解	知识图谱持久化，token 省 99%
Greptile	代码理解 API	完全本地、无需云端 API、零成本

总结

24K Star 不是白来的。codebase-memory-mcp 解决的是 AI 编程 Agent 最核心的瓶颈：如何高效理解大型代码库。它的方案很暴力也很优雅——用纯 C 写一个极快的索引引擎，把代码变成知识图谱，让 Agent 的每次查询都从"翻书"变成"查数据库"。

如果你在用 AI 编程 Agent 做实际项目，特别是代码库超过几千行的项目，这个工具值得试试。一键安装、零配置、零成本，效果立竿见影。

项目地址：github.com/DeusData/codebase-memory-mcp

论文：arXiv:2603.27277

文档：deusdata.github.io/codebase-memory-mcp