引言“AI Agent 探索代码库时读取每一个文件消耗 412,000 个 token。换成知识图谱查询只需要 3,400 个 token。”这是每日一个开源项目系列的第135篇文章。今天的主角是codebase-memory-mcp——一个用纯 C 编写的代码库知识图谱 MCP 服务器。你用 Claude Code 处理一个中型项目时Agent 会怎么理解代码结构通常是逐文件读取先看目录结构再读几个关键文件再追踪引用再读更多文件……每一步都在消耗 token每次新会话都要重新来一遍大型代码库里很快就触到上下文限制。codebase-memory-mcp 的思路是先把代码库的结构信息提取成持久化的知识图谱存进 SQLiteAgent 需要了解代码结构时不读文件查图谱。从每次重新探索变成查询已有的结构记忆。120 倍的 token 差距来自这个设计改变。你将学到什么代码知识图谱的数据模型节点类型和边类型是什么两层解析架构Tree-sitter 语法层 Hybrid LSP 语义层14 个 MCP 工具的功能分布从索引到 Cypher 查询性能数据Linux 内核级别的代码库需要多久建完图谱团队协作场景共享压缩图谱文件的工作流安全设计SLSA Level 3、Sigstore 签名、VirusTotal 扫描前置知识使用过 Claude Code 或其他支持 MCP 的 AI 编程工具了解代码库结构函数、类、调用关系的基本概念了解 MCP 协议的基本概念项目背景项目简介codebase-memory-mcp 是一个代码智能 MCP 服务器把代码库的结构信息构建成持久化的知识图谱让 AI Agent 通过结构化查询而非文件读取来理解代码。知识图谱在这里是精确的词节点是代码结构元素文件、类、函数、路由、资源边是结构关系调用、继承、导入、HTTP 调用、数据流整个图存在 SQLite 数据库里支持 Cypher 风格的图查询语言。项目是 Anthropic 开源后最早出现的高质量 MCP Server 之一背后有学术论文支撑arXiv:2603.27277。作者/团队介绍组织: DeusData语言: 纯 C零运行时依赖License: MIT最新版本: v0.8.1测试用例: 5,604 个项目数据⭐ GitHub Stars:5,400 Forks: 491 License: MIT 论文: arXiv:2603.27277主要功能核心作用传统方式逐文件读取 AI Agent → 读 file1.py → 读 file2.py → 读 file3.py → ... ↓ ~412,000 tokens每次会话重复遇到上下文限制 知识图谱方式 AI Agent → query_graph(MATCH (f:Function)-[:CALLS]-(g)...) ↓ ~3,400 tokens结果来自持久化图谱秒级响应使用场景大型代码库理解接手陌生代码库时通过图查询快速定位关键结构不需要逐文件阅读重构辅助查找所有调用某函数的路径trace_path确认改动影响范围死代码检测找到没有被任何调用链触及的孤立函数架构分析用 Leiden 社区检测算法自动识别代码的模块边界跨仓库分析CROSS_*边类型链接多个已索引的仓库分析服务间依赖快速开始安装# 一键安装脚本curl-fsSLhttps://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh|bash# npmnpminstall-gcodebase-memory-mcp# PyPIpipinstallcodebase-memory-mcp# Homebrew (macOS)brewinstalldeusdata/tap/codebase-memory-mcp配置到 Claude Code自动配置支持 11 个 Agentcodebase-memory-mcp setup claude-code手动配置~/.claude/mcp.json{mcpServers:{codebase-memory:{command:codebase-memory-mcp,args:[serve]}}}在 Claude Code 中使用# 告诉 Agent 索引当前项目 Index this project # Agent 调用 index_repository几秒到几分钟后图谱建完 # 之后所有代码探索走图谱不走文件读取 Find all functions that call the authentication handler What does the payment flow look like from API to database? Are there any functions that are never called?CLI 直接查询# 搜索包含 Handler 的函数codebase-memory-mcp cli search_graph\{name_pattern: .*Handler.*, label: Function}# 追踪某函数的调用路径codebase-memory-mcp cli trace_path\{function_name: processPayment, direction: both}# Cypher 图查询codebase-memory-mcp cli query_graph\{query: MATCH (f:Function)-[:CALLS]-(g:Function) WHERE f.name \main\ RETURN g.name}14 个 MCP 工具工具功能index_repository索引代码库构建或更新知识图谱search_graph按名称模式/标签搜索节点search_code四阶段混合代码搜索grep 图智能semantic_query向量嵌入语义搜索Nomic nomic-embed-codetrace_path追踪函数调用链可指定方向和深度query_graph原生 Cypher 图查询find_dead_code检测未被调用的孤立代码analyze_architecture用 Leiden 算法检测模块边界get_node获取单个节点的详细信息list_routes列出所有 HTTP 路由REST API 分析get_dependencies获取包/模块的依赖关系get_graph_stats图谱统计节点数、边数、覆盖率watch_repository启动后台 Git 感知自动同步get_index_status查看索引状态和进度项目详细剖析知识图谱数据模型图谱里的节点和边涵盖代码库的完整结构语义节点类型部分Project ← 仓库根节点 Package ← 包/模块 File ← 源文件 Class ← 类定义 Function ← 独立函数 Method ← 类方法 Route ← HTTP 路由端点 Resource ← 基础设施资源K8s、Docker边类型部分CALLS ← 函数/方法调用关系 IMPORTS ← 模块导入关系 INHERITS ← 类继承关系 HTTP_CALLS ← 跨服务 HTTP 调用 EMITS ← 事件发送消息队列 LISTENS_ON ← 事件监听 DATA_FLOWS ← 数据流向关系 SIMILAR_TO ← MinHash 近似重复代码 CROSS_* ← 跨仓库依赖边这个数据模型的精度超过大多数 IDE 的符号索引。DATA_FLOWS和HTTP_CALLS边需要理解运行时行为不只是语法结构。两层解析架构解析流水线 ↓ Layer 1: Tree-sitter ├── 158 种语言的语法分析 ├── 提取函数/类/方法定义、调用关系、导入 └── 速度极快但只有语法层面的信息 不知道泛型实例化的具体类型、跨模块的类型解析 ↓ Layer 2: Hybrid LSP9 种语言 ├── Python、TypeScript/JS、PHP、C# ├── Go、C/C、Java、Kotlin、Rust └── 类型感知分析 ├── 跨模块调用解析知道 foo() 调用的是哪个 foo ├── 泛型实例化 ├── 继承链解析 └── 类型推断 关键Hybrid LSP 不启动语言服务器进程在进程内完成类型解析v0.7.0 引入 Hybrid LSP 后TypeScript 编译器索引时间从 ~5,100 秒降到 ~50 秒100 倍提升。代价是仅对 9 种主流语言有效其余 149 种语言只有 Tree-sitter 语法层。Cypher 查询语言图谱支持类似 Neo4j Cypher 的查询语法-- 找出所有被超过 5 个函数调用的函数高耦合节点 MATCH (g:Function)-[:CALLS]-(f:Function) WITH g, count(f) AS caller_count WHERE caller_count 5 RETURN g.name, caller_count ORDER BY caller_count DESC -- 找出完整的认证调用链 MATCH path (api:Route)-[:CALLS*..5]-(auth:Function) WHERE auth.name CONTAINS authenticate RETURN path -- 检测循环依赖 MATCH (a:Package)-[:IMPORTS]-(b:Package)-[:IMPORTS]-(a) RETURN a.name, b.name查询延迟 小于1ms因为 SQLite 在 WAL 模式下运行图遍历和过滤在 C 层执行。性能基准在 Apple M3 Pro 上测试操作时间Linux 内核完整索引28M LOC75K 文件~3 分钟Django 完整索引约 10 万行~6 秒平均规模仓库毫秒级Cypher 查询小于1ms追踪调用路径深度 5小于10ms死代码检测~150ms纯 C 实现是性能的基础没有 GC 暂停没有 JVM 预热没有 Python 解释器开销索引过程全程在 C 层进行。团队协作共享图谱文件这是一个值得单独说的设计# 把压缩后的图谱文件提交到 gitgitadd.codebase-memory/graph.db.zstgitcommit-mupdate codebase knowledge graphgitpush# 队友克隆后直接用不需要重新索引gitclone... codebase-memory-mcp serve# 图谱已经在 .codebase-memory/ 里graph.db.zst是 Zstandard 压缩的 SQLite 数据库。对大型代码库团队里每人重新索引一遍浪费时间由 CI 生成并提交图谱文件其他人直接用。安全设计单一可执行二进制的分发方式有供应链风险这个项目的安全措施比多数同类项目完善SLSA Level 3 构建来源每个 Release 的构建过程有可验证的来源证明Sigstore cosign 无密钥签名不需要管理 GPG 密钥签名可以通过 Sigstore 链验证VirusTotal 扫描v0.8.1 的二进制在 72 个引擎上 0/72 检出CodeQL SAST代码安全静态分析作为发布门禁本地处理承诺所有代码处理发生在本地不发送到外部服务HTTP 绑定 127.0.0.1内置可视化界面只接受本地连接v0.8.1 明确排除了任何非 localhost 访问路径项目地址与资源官方资源GitHub: DeusData/codebase-memory-mcp论文: arXiv:2603.27277分发渠道npm、PyPI、Homebrew、Scoop、Winget、AUR、Chocolatey、MCP Registry 官方目录总结codebase-memory-mcp 的核心贡献是把一个系统性问题做出了工程解答AI Agent 探索代码库的方式效率极低每次会话重新读文件token 消耗是结构查询的 120 倍。知识图谱的思路在数据库领域是成熟的但专门为代码库 MCP 接口设计并实现的工具并不多。纯 C 零依赖的实现使它成为分发最容易、性能最稳定的选项之一158 语言覆盖和 Hybrid LSP 语义层解析使它对多语言代码库实际可用14 个 MCP 工具的接口设计使 Agent 可以精确描述想要的结构信息。对于长期在同一个代码库上工作的开发者或者使用 Claude Code 处理超过 5 万行代码的场景这个 MCP 服务器值得装上试试。探索 PrimeSkills —— 精选 AI Agent 与技能的市场每一个都经过真实企业工作流验证去掉浮夸留下真正有用的。欢迎访问我的个人主页发现更多有价值的见解和有趣的产品。