codebase-memory-mcp 使用指南
# 什么是 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
1
2
3
4
5
2
3
4
5
# 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
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
# 其他安装方式
# 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
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
# 快速开始
# 1. 安装后重启你的编码 Agent
安装脚本会自动检测并配置已安装的编码 Agent（Claude Code、Cursor、Codex 等）。
# 2. 索引项目
在 Agent 中输入：
Index this project
1
或者使用 CLI：
cd your-project
codebase-memory-mcp index
1
2
2
# 3. 开始查询
what calls ProcessOrder?
trace the call path to submitOrder
find all HTTP routes in this project
1
2
3
2
3
# 核心功能详解
# 1. 架构概览
一次调用获取完整架构信息：
# 通过 MCP Agent
"show me the architecture overview"
# CLI 模式
codebase-memory-mcp cli get_architecture '{"project": "my-project"}'
1
2
3
4
5
2
3
4
5
返回信息包括：
- 语言分布
- 包/模块结构
- 入口点
- HTTP 路由
- 热点分析
- 边界与分层
# 2. 调用链追踪
追踪函数的调用路径：
# 入站追踪（谁调用了这个函数）
trace_path(function_name="ProcessOrder", direction="inbound")
# 出站追踪（这个函数调用了谁）
trace_path(function_name="ProcessOrder", direction="outbound")
1
2
3
4
5
2
3
4
5
# 3. 影响分析
分析代码变更的影响范围：
# 检测未提交的变更影响
detect_changes
# 查找函数的所有调用者
find_callers(function_name="authenticate")
1
2
3
4
5
2
3
4
5
# 4. 死代码检测
找出没有被调用的函数：
# 查找零调用函数
find_dead_code
1
2
2
# 5. 语义搜索
基于向量嵌入的语义搜索：
# 自然语言搜索
semantic_query("user authentication logic")
# 正则模式搜索
search_graph(name_pattern=".*Handler.*")
1
2
3
4
5
2
3
4
5
# 6. Cypher 查询
类 Cypher 的图查询语言：
MATCH (f:Function)-[:CALLS]->(g)
WHERE f.name = 'main'
RETURN g.name
1
2
3
2
3
# 7. HTTP 路由分析
自动检测并关联 HTTP 路由：
# 列出所有路由
list_routes
# 查找路由的调用链
trace_route(path="/api/users")
1
2
3
4
5
2
3
4
5
# 图形化界面
启用 UI 版本后，可以访问内置的 3D 图谱可视化：
# 启动带 UI 的版本
codebase-memory-mcp --ui=true --port=9749
1
2
2
浏览器访问 http://localhost:9749，可以：
- 3D 可视化代码结构
- 交互式探索调用关系
- 多仓库架构视图
# 自动索引与监控
# 启用自动索引
# 开启自动索引
codebase-memory-mcp config set auto_index true
# 设置文件限制
codebase-memory-mcp config set auto_index_limit 50000
1
2
3
4
5
2
3
4
5
# 后台文件监控
默认启用，检测文件变化并自动重新索引：
# 禁用自动监控
codebase-memory-mcp config set auto_watch false
1
2
2
# 团队协作
# 共享索引
将索引文件提交到仓库，团队成员无需重新索引：
# 索引文件位置
.codebase-memory/graph.db.zst
1
2
2
这是 zstd 压缩的知识图谱快照（压缩比 8-13:1）， teammates clone 后直接可用。
# 与 CodeGraph 对比
codebase-memory-mcp 和 CodeGraph 都是代码知识图谱工具，但在设计理念和功能侧重上有明显差异：
# 核心对比
| 对比项 | codebase-memory-mcp | CodeGraph |
|---|---|---|
| 语言支持 | 158 种 | 37 种 |
| 索引速度 | Linux 内核 3 分钟 | 未公开具体数据 |
| 查询延迟 | <1ms | 未公开 |
| MCP 工具数 | 15 个 | 45 个 |
| Hybrid LSP | ✅ 支持（11 种语言） | ❌ |
| 内置 LLM | ❌ 无（依赖 Agent） | ❌ 无 |
| 图形化界面 | ✅ 3D 可视化 | ❌ |
| 安装方式 | 静态二进制 / npm / PyPI | npm / 静态包 |
| 跨仓库分析 | ✅ CROSS_* 边 | ✅ |
| 基础设施代码 | ✅ Dockerfile/K8s | ❌ |
| 架构决策记录 | ✅ ADR 管理 | ❌ |
| 语义搜索 | ✅ 内置向量嵌入 | ❌ |
# 功能差异详解
# 1. 语言支持
- codebase-memory-mcp: 支持 158 种语言，内置 Tree-sitter 语法解析器
- CodeGraph: 支持 37 种主流语言
# 2. Hybrid LSP 类型解析
codebase-memory-mcp 的独有特性，为 11 种语言提供语义类型解析：
| 语言 | 类型解析特性 |
|---|---|
| Python | 参数绑定、返回类型推断 |
| TypeScript/JSX | 泛型替换、JSX 组件分发 |
| Go | 接口实现解析 |
| Java | 类继承、重载、Lambda |
| Rust | trait 方法、UFCS |
| PHP | namespace、trait、延迟静态绑定 |
| C# | 文件作用域 namespace、LINQ |
# 3. 语义搜索
codebase-memory-mcp 内置 Nomic 嵌入模型（无需 API Key）：
- 40K tokens 容量
- 768 维 int8 量化
- 11 信号组合评分（TF-IDF、API 签名、数据流等）
# 4. 基础设施即代码
codebase-memory-mcp 支持：
- Dockerfile 索引
- Kubernetes 清单
- Kustomize overlays
CodeGraph 目前不支持基础设施代码分析。
# 5. MCP 工具数量
- CodeGraph: 45 个工具，覆盖更细粒度的操作
- codebase-memory-mcp: 15 个核心工具，更聚焦高层抽象
# 选择建议
| 场景 | 推荐选择 |
|---|---|
| 多语言项目 | codebase-memory-mcp |
| 需要 LSP 级类型解析 | codebase-memory-mcp |
| 基础设施代码分析 | codebase-memory-mcp |
| 团队协作共享索引 | 两者都支持 |
| 需要更细粒度工具控制 | CodeGraph |
| 需要 3D 可视化 | codebase-memory-mcp |
# 性能基准
在 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
1
2
3
4
5
2
3
4
5
# 相关资源
# 总结
codebase-memory-mcp 是一个极致性能的代码智能引擎，特别适合：
- 大型代码库的快速理解
- 需要精确类型解析的项目
- 多语言混合开发
- 基础设施即代码分析
- 团队协作共享索引
相比 CodeGraph，它在语言覆盖、类型解析深度、语义搜索等方面有明显优势，是 AI 辅助开发工具链中的重要组成部分。