每日一个开源项目（第135篇）：codebase-memory-mcp - 为 AI Agent 构建代码库知识图谱

引言

今天介绍的 codebase-memory-mcp，是用纯 C 编写的代码库知识图谱 MCP 服务器；本文为"每日一个开源项目"系列第135篇。

当你让 Claude Code 处理一个中型项目时，Agent 通常怎样认识代码结构？它会逐个读取文件：先检查目录结构，接着阅读几个关键文件，再追踪引用并打开更多文件……这些步骤都会消耗 token，而且每次新会话都得从头再来，在大型代码库中很快便会达到上下文限制。

codebase-memory-mcp 选择先提取代码库的结构信息，将其构建为持久化知识图谱并存入 SQLite；当 Agent 需要理解代码结构时，直接查询图谱，无需读取文件。正是从“每次重新探索”转为“查询已有的结构记忆”这一设计变化，带来了 120 倍的 token 差距。

你会了解哪些内容

• 代码知识图谱的数据模型：节点与边分别有哪些类型
• Tree-sitter 负责语法层，Hybrid LSP 负责语义层：由此组成两层解析架构
• 从 Cypher 查询到索引：14 个 MCP 工具的功能分布
• 性能指标：完成 Linux 内核级代码库的图谱构建需要多久
• 团队协作场景：如何共享压缩后的图谱文件
• 安全设计：SLSA Level 3、Sigstore 签名、VirusTotal 扫描

需要具备的前置知识

• 具备其他支持 MCP 的 AI 编程工具或 Claude Code 使用经验
• 掌握代码库结构的基本概念，包括函数、类和调用关系
• 掌握 MCP 协议的基础概念

项目背景

项目概述

AI Agent 不再依靠文件读取，而是用结构化查询理解代码；codebase-memory-mcp 这款代码智能 MCP 服务器，会把代码库结构信息转成持久化知识图谱。

此处的“知识图谱”含义十分明确：节点对应代码结构元素，包括文件、类、函数、路由和资源；边则表示调用、继承、导入、HTTP 调用及数据流等结构关系。完整图谱存储于 SQLite 数据库，并支持 Cypher 风格的图查询语言。

学术论文（arXiv:2603.27277）为项目提供支撑；它也属于 Anthropic 开源后首批出现的高质量 MCP Server。

作者与团队简介

• 组织: 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，结果来自持久化图谱，秒级响应

使用场景

1. 大型代码库理解：接手陌生代码库时，通过图查询快速定位关键结构，不需要逐文件阅读
2. 重构辅助：查找所有调用某函数的路径（trace_path），确认改动影响范围
3. 死代码检测：找到没有被任何调用链触及的孤立函数
4. 架构分析：用 Leiden 社区检测算法自动识别代码的模块边界
5. 跨仓库分析：CROSS_* 边类型链接多个已索引的仓库，分析服务间依赖

快速开始

安装：

# 一键安装脚本curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash# npmnpm install -g codebase-memory-mcp# PyPIpip install codebase-memory-mcp# Homebrew (macOS)brew install deusdata/tap/codebase-memory-mcp

配置到 Claude Code（自动配置，支持 11 个 Agent）：

codebase-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 工具

项目详细剖析

知识图谱数据模型

图谱里的节点和边涵盖代码库的完整结构语义：

部分节点类型：

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 LSP（9 种语言）├── 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_countWHERE caller_count > 5RETURN g.name, caller_countORDER 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 上测试：

性能的基础来自纯 C 实现：既不会发生 GC 暂停，也没有 JVM 预热和 Python 解释器开销，整个索引过程均在 C 层完成。

团队协作：共享图谱文件

这项设计值得专门展开说明：

# 把压缩后的图谱文件提交到 gitgit add .codebase-memory/graph.db.zstgit commit -m "update codebase knowledge graph"git push# 队友克隆后直接用，不需要重新索引git clone ...codebase-memory-mcp serve# 图谱已经在 .codebase-memory/ 里

graph.db.zst 是 Zstandard 压缩的 SQLite 数据库。对大型代码库，团队里每人重新索引一遍浪费时间；由 CI 生成并提交图谱文件，其他人直接用。

安全设计

以单个可执行二进制进行分发存在供应链风险，因此该项目配备了比多数同类项目更完整的安全措施：

• 每个 Release 的构建过程都有可验证的来源证明，达到 SLSA Level 3 构建来源要求
• 签名由 Sigstore 链完成验证，因此采用 Sigstore cosign 无密钥签名时，不必管理 GPG 密钥
• 在 72 个引擎的 VirusTotal 扫描中，v0.8.1 二进制检出结果为 0/72
• 发布门禁包含 CodeQL SAST 所做的代码安全静态分析
• 代码不会发送至外部服务，所有处理均留在本地，这是项目的本地处理承诺
• 由于 HTTP 绑定 127.0.0.1，内置可视化界面只接收本地连接；任何非 localhost 访问路径均已在 v0.8.1 中明确排除。

项目地址及相关资源

官方资源

• ? GitHub: DeusData/codebase-memory-mcp
• ? arXiv:2603.27277：论文

分发渠道

MCP Registry 官方目录，以及 Chocolatey、AUR、Winget、Scoop、Homebrew、PyPI、npm

总结

每次会话都重新读文件，使 AI Agent 探索代码库时的 token 消耗达到结构查询的 120 倍，效率极低；codebase-memory-mcp 的核心贡献，正是为这个系统性问题给出工程解答。

专门围绕代码库 + MCP 接口设计并实现的工具仍不多，尽管知识图谱在数据库领域已是成熟思路。它凭纯 C + 零依赖成为性能最稳定、最易分发的选项之一；面对多语言代码库，158 语言覆盖与 Hybrid LSP 语义层解析让它具备实际可用性；Agent 则可借助14 个 MCP 工具的接口，精确描述所需的结构信息。

这个 MCP 服务器值得装上尝试，尤其适合使用 Claude Code 处理超过 5 万行代码的场景，或长期围绕同一个代码库工作的开发者。

每一个都由真实企业工作流验证，只保留真正有用的内容、去除浮夸；到 PrimeSkills 探索精选 AI Agent 与技能的市场。

欢迎前往我的个人主页，查看更多有价值的洞见与有趣产品。