什么是 codebase-memory-mcp？

codebase-memory-mcp 是一个高性能的代码智能 MCP 服务器，它能将你的代码库索引为一个持久化的知识图谱。通过 Tree-sitter AST 分析和 Hybrid LSP 语义类型解析，为 AI 编码助手提供精确的代码结构理解。

核心特点

特点	说明
⚡ 极速索引	Linux 内核（28M LOC, 75K 文件）仅需 3 分钟
🔍 毫秒级查询	结构查询响应时间 < 1ms
🌐 158 种语言	内置 Tree-sitter 语法解析器
📦 零依赖	单一静态二进制文件，开箱即用
🔒 100% 本地	代码永不离开你的机器

---

安装指南

macOS / Linux

# 一键安装
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

# 带图形化界面版本
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

# 解除下载限制
Unblock-File .\install.ps1

# 执行安装
.\install.ps1

其他安装方式

# npm
npm install -g codebase-memory-mcp

# PyPI
pip install codebase-memory-mcp

# Homebrew
brew install codebase-memory-mcp

# Scoop (Windows)
scoop install codebase-memory-mcp

Claude Code CLI 配置

安装脚本会自动检测并配置已安装的编码 Agent。如果你使用 Claude Code CLI，执行安装脚本后 MCP 会自动添加到 Claude Code 的配置中。

Windows 用户：

# 下载并执行安装脚本后，MCP 会自动配置
.\install.ps1

安装完成后重启 Claude Code CLI 即可生效。

---

快速开始

1. 安装后重启你的编码 Agent

安装脚本会自动检测并配置已安装的编码 Agent（Claude Code、Cursor、Codex 等）。

2. 索引项目

在 Agent 中输入：

Index this project

或者使用 CLI：

cd your-project
codebase-memory-mcp index

3. 开始查询

what calls ProcessOrder?
trace the call path to submitOrder
find all HTTP routes in this project

---

核心功能详解

1. 架构概览

一次调用获取完整架构信息：

# 通过 MCP Agent
"show me the architecture overview"

# CLI 模式
codebase-memory-mcp cli get_architecture '{"project": "my-project"}'

返回信息包括：

• 语言分布
• 包/模块结构
• 入口点
• HTTP 路由
• 热点分析
• 边界与分层

2. 调用链追踪

追踪函数的调用路径：

# 入站追踪（谁调用了这个函数）
trace_path(function_name="ProcessOrder", direction="inbound")

# 出站追踪（这个函数调用了谁）
trace_path(function_name="ProcessOrder", direction="outbound")

3. 影响分析

分析代码变更的影响范围：

# 检测未提交的变更影响
detect_changes

# 查找函数的所有调用者
find_callers(function_name="authenticate")

4. 死代码检测

找出没有被调用的函数：

# 查找零调用函数
find_dead_code

5. 语义搜索

基于向量嵌入的语义搜索：

# 自然语言搜索
semantic_query("user authentication logic")

# 正则模式搜索
search_graph(name_pattern=".*Handler.*")

6. Cypher 查询

类 Cypher 的图查询语言：

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

7. HTTP 路由分析

自动检测并关联 HTTP 路由：

# 列出所有路由
list_routes

# 查找路由的调用链
trace_route(path="/api/users")

8. 跨服务关联（Cross-Repo Intelligence）

codebase-memory-mcp 支持跨服务/跨仓库的智能关联，可以在多个已索引项目之间建立调用关系，帮助理解微服务架构中的服务依赖。

关联所有已索引项目

# Bash 写法
codebase-memory-mcp cli index_repository \
  --mode cross-repo-intelligence \
  --target-projects '["*"]'

或 JSON 写法：

codebase-memory-mcp cli index_repository \
  '{"mode":"cross-repo-intelligence","target_projects":["*"]}'

只关联指定项目

codebase-memory-mcp cli index_repository \
  '{"mode":"cross-repo-intelligence","target_projects":["user-service","order-service"]}'

注意事项

部分版本里 repo_path 仍是必填字段。如果报错缺 repo_path，随便填其中一个已索引项目的路径即可：

codebase-memory-mcp cli index_repository \
  '{"repo_path":"/path/to/user-service","mode":"cross-repo-intelligence","target_projects":["*"]}'

在 AI 客户端里怎么说

直接对 Claude Code / Cursor 说：

用 index_repository，mode 设为 cross-repo-intelligence，target_projects 用 ["*"]，把已索引的项目做跨服务关联。

或更精确：

请调用 index_repository，参数：
  mode = "cross-repo-intelligence"
  target_projects = ["user-service", "order-service"]

---

图形化界面

启用 UI 版本后，可以访问内置的 3D 图谱可视化：

# 启动带 UI 的版本
codebase-memory-mcp --ui=true --port=9749

浏览器访问 http://localhost:9749，可以：

• 3D 可视化代码结构
• 交互式探索调用关系
• 多仓库架构视图

---

自动索引与监控

启用自动索引

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

# 设置文件限制
codebase-memory-mcp config set auto_index_limit 50000

后台文件监控

默认启用，检测文件变化并自动重新索引：

# 禁用自动监控
codebase-memory-mcp config set auto_watch false

---

团队协作

共享索引

将索引文件提交到仓库，团队成员无需重新索引：

# 索引文件位置
.codebase-memory/graph.db.zst

这是 zstd 压缩的知识图谱快照（压缩比 8-13:1）， teammates clone 后直接可用。

---

与 CodeGraph 对比

codebase-memory-mcp 与 CodeGraph 都是基于 Model Context Protocol (MCP) 的代码知识图谱工具，共同目标都是为 AI 编程助手（如 Claude Code、Cursor 等）提供结构化代码记忆，避免 AI 每次通过机械地 grep 和读文件来「迷路」和浪费 Token。但在设计理念和功能侧重上有明显差异。

核心对比

对比维度	codebase-memory-mcp	CodeGraph
底层实现	纯 C / C++ 编写，单静态二进制，零运行时依赖，本地 SQLite 存储	轻量专注，利用 OS 级文件事件联动
语言支持	158 种（基于 Tree-sitter）	常见主流语言
核心定位	偏向重型、架构级与跨团队协作	偏向轻量、日常单仓库编码、实时跟随文件编辑
MCP 工具数	15 个核心工具，聚焦高层抽象	45 个工具，覆盖更细粒度操作
Hybrid LSP	✅ 支持（11 种语言语义类型解析）	❌
图形化界面	✅ 3D 可视化	❌
基础设施代码	✅ Dockerfile/K8s 分析	❌
语义搜索	✅ 内置向量嵌入	❌

性能与内存对比

在性能与内存优化的绝对指标上，codebase-memory-mcp 占据压倒性优势，底层工程进行了极致的性能榨干；而 CodeGraph 采用常规的轻量级缓存设计，更适合日常中小型项目。

性能维度	codebase-memory-mcp 🥇	CodeGraph
构建与索引性能	极快。2800万行的 Linux 内核全量索引仅需 3 分钟；中型项目秒级完成	较快。适合 500+ 文件规模项目，初次构建中规中矩
查询响应延迟	亚毫秒级（<1ms）。关系遍历、复杂逻辑搜索均在 1ms 内响应	微秒级（依赖缓存）。缓存命中时极快，未命中时依赖内存图解析
内存占用 (RAM)	RAM 优先 + 自动释放。采用多阶段并行流水线、mimalloc 分配器与 LZ4 压缩，索引完立即释放内存	持续常驻。依赖常驻内存的 LRU 缓存（最大分配约 500MB），文件频繁变动时内存较为固定
数据持久化体积	极小。图谱写入嵌入式 SQLite 并经过高倍率压缩（graph.db.zst，压缩比 8-13:1）	中等。同样基于 SQLite 存储，但缺乏重度的图结构空间压缩技术

核心差异与技术取舍

性能与工程架构：

codebase-memory-mcp 采用纯 C 编写并借助 Tree-sitter，在冷启动索引速度、多语言支持广度上表现极端强悍。它的快照压缩（graph.db.zst）允许团队直接将索引提交至 Git 仓库，新成员无需本地重跑全量构建。

轻量与实时响应：

CodeGraph 胜在轻量级与专注度，依靠操作系统级的文件事件（File Watcher）能够非常实时地跟随代码编辑进行索引更新，日常在单仓内对代码片段的变动反馈更敏捷。

适用场景推荐

场景	推荐选择	原因
项目体量庞大、语言杂	codebase-memory-mcp	极致索引速度，跨语言支持
需要梳理微服务/HTTP 路由/异步调用关系	codebase-memory-mcp	HTTP 路由/异步事件一等公民支持
团队协作，共享图谱快照	codebase-memory-mcp	graph.db.zst 可提交 Git
需要 LSP 级类型解析	codebase-memory-mcp	Hybrid LSP 支持 11 种语言
基础设施代码分析	codebase-memory-mcp	支持 Dockerfile/K8s
日常单仓编码，低心智负担	CodeGraph	轻量即时，实时跟随编辑
需要更细粒度工具控制	CodeGraph	45 个 MCP 工具
中小型项目，快速上手	CodeGraph	开箱即用响应快

---

性能基准

在 Apple M3 Pro 上的测试数据：

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

---

安全与隐私

• ✅ 100% 本地处理，代码永不离开机器
• ✅ 所有发布二进制文件签名、校验、扫描
• ✅ 支持 70+ 杀毒引擎扫描
• ✅ 开源代码可审计

---

更新与卸载

# 检查更新
codebase-memory-mcp update

# 卸载
codebase-memory-mcp uninstall

---

相关资源

• GitHub 仓库 (opens new window)
• 研究论文 (opens new window)
• CodeGraph 对比文章
• MCP 协议介绍

---

总结

codebase-memory-mcp 是一个极致性能的代码智能引擎，特别适合：

• 大型代码库的快速理解
• 需要精确类型解析的项目
• 多语言混合开发
• 基础设施即代码分析
• 团队协作共享索引

相比 CodeGraph，它在语言覆盖、类型解析深度、语义搜索等方面有明显优势，是 AI 辅助开发工具链中的重要组成部分。