Codebase Memory MCP

这是什么？

Codebase Memory MCP 是一个高性能代码智能 MCP 服务器，将代码库索引为持久化知识图谱。GitHub DeusData/codebase-memory-mcp，37.4k Stars，Apache 2.0 许可证。

核心价值：AI Agent 通过 MCP 协议查询代码库的语义结构和关系，像查询数据库一样理解代码。支持语义搜索（“找到所有处理用户认证的函数”）和关系查询（“这个函数被哪些模块调用”）。

适合谁：使用 Claude Code / Codex / Cursor 等 AI 编程工具的开发者，需要跨大型代码库进行上下文理解的团队。

前置条件：Node.js 20+，支持 MCP 的 AI 编程客户端（Claude Code / Codex / Cursor）。

准备工作

安装

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
npm install
npm run build

配置 MCP 客户端

在 Claude Code 的 MCP 配置中添加：

{
  "mcpServers": {
    "codebase-memory": {
      "command": "node",
      "args": ["path/to/codebase-memory-mcp/dist/index.js"],
      "env": {
        "CODEBASE_PATH": "/path/to/your/project"
      }
    }
  }
}

时间预算：安装 5 分钟，索引 10 万行代码约 3-5 分钟。

三步上手

第一步：索引代码库

npx codebase-memory index --path /path/to/project

首次索引会扫描所有源文件，构建 AST 并提取符号、依赖关系、调用图。

第二步：语义搜索

在 AI 编程客户端中直接提问：

“找到项目中所有包含 SQL 注入风险的数据库查询函数”

Agent 会自动调用 Codebase Memory MCP 进行语义搜索，返回相关代码片段和上下文。

第三步：关系查询

“show me the call graph for the authenticate() function”

查看函数的完整调用链，理解代码影响范围。

常见踩坑

踩坑 1：索引大型仓库 OOM

症状：索引超过 50 万行的仓库时内存溢出。

原因：默认配置将整个 AST 树加载到内存。

解决：使用 --incremental 增量索引模式，或 --max-file-size 100KB 跳过超大文件。

踩坑 2：MCP 连接超时

症状：Agent 调用时返回 “MCP server not responding”。

原因：代码库索引未完成或 MCP 服务未启动。

解决：确认 npx codebase-memory serve 进程在运行，检查 ~/.codebase-memory/ 下的索引文件。

踩坑 3：动态语言索引不完整

症状：Python/JavaScript 项目中的动态导入未被索引。

原因：静态分析无法处理 importlib.import_module() 或 require(variable) 模式。

解决：使用 --dynamic-analysis 启用运行时追踪（需先运行测试套件）。

踩坑 4：索引文件占用磁盘过大

症状：.codebase-memory/ 目录超过 2GB。

原因：默认存储完整 AST 和源码快照。

解决：使用 --storage-mode compact 仅存储符号和关系，不存储源码文本。

踩坑 5：多分支切换后索引过期

症状：切换 Git 分支后搜索结果不准确。

原因：索引基于旧分支构建。

解决：配置 Git hooks 自动重建索引，或手动运行 npx codebase-memory reindex。

FAQ

Q1: 是否支持私有代码库？

A: 完全本地运行，代码不离开你的机器。Apache 2.0 开源许可证。

Q2: 支持哪些编程语言？

A: 支持 TypeScript/JavaScript、Python、Go、Rust、Java、C/C++。更多语言通过 Tree-sitter 语法扩展。

Q3: 与传统代码搜索（grep/rg）有什么区别？

A: Codebase Memory MCP 理解代码语义——grep "auth" 返回所有包含 “auth” 的行，而 MCP 返回所有处理认证的函数和模块。

Q4: 索引速度如何？

A: 10 万行代码约 3-5 分钟（M1 Mac）。增量索引仅处理变更文件，秒级完成。

Q5: 与 Sourcegraph/Cody 有什么区别？

A: Sourcegraph 是 SaaS 平台，Codebase Memory MCP 是完全本地化的 MCP 工具，可嵌入任何 AI 编程工作流。

参考链接

• 官方 GitHub
• MCP 协议规范

本文基于公开资料整理，AI 辅助生成，数据截至 2026-08-05。具体功能请以官方文档为准。