【开源】codebase-memory-mcp 安装与实战教程（2026最新版）

让 AI 编程助手拥有"代码库记忆"：codebase-memory-mcp 安装与实战教程

前言

现在很多人已经在用 Claude Code、Cursor、Codex CLI、Gemini CLI 等 AI 编程工具。但在大型项目里，一个很明显的问题是：AI 每次理解代码都要重新 grep、读文件、猜调用关系，既慢，又消耗大量 Token。

codebase-memory-mcp 的思路很直接：先把代码库索引成一个本地知识图谱，再通过 MCP 协议提供给 AI 编程助手查询。这样 AI 不再盲目翻文件，而是可以直接问：

• 这个函数被谁调用？
• 某个接口最终走到哪些业务逻辑？
• 这次改动会影响哪些模块？
• 项目里有哪些入口、路由、热点文件和架构边界？

项目地址：DeusData/codebase-memory-mcp

截至 2026-06-30，官方 GitHub 页面显示最新版本为 v0.8.1，发布日期为 2026-06-12。

1. codebase-memory-mcp 是什么？

codebase-memory-mcp 是一个高性能代码智能 MCP Server。它会在本地扫描你的项目源码，提取函数、类、模块、调用链、HTTP 路由、跨服务调用等信息，并存入 SQLite 知识图谱。

它本身不是大模型，而是 AI 编程助手的"代码结构数据库"。

简单理解：

用户提问
  ↓
AI 编程助手理解问题
  ↓
调用 codebase-memory-mcp 查询代码图谱
  ↓
返回调用链、结构、影响范围等结果
  ↓
AI 用自然语言解释给用户

官方 README 中提到，它支持 158 种语言，使用 tree-sitter 做 AST 解析，并对 Python、TypeScript、JavaScript、Go、Java、Rust、C/C++ 等语言提供 Hybrid LSP 语义增强。

2. 为什么值得用？

传统 AI 读代码通常是这样的：

搜索关键字 → 读取文件 → 再搜索 → 再读取 → 猜调用关系

缺点很明显：

• Token 消耗大；
• 容易遗漏跨文件调用；
• 对大型项目很慢；
• 每个新会话都要重新理解项目。

codebase-memory-mcp 的优势是：

• 本地索引，代码不出机器；
• 单个静态二进制，无需 Docker、数据库、API Key；
• 使用 SQLite 持久化保存图谱；
• 支持函数调用链、架构概览、死代码检测、影响分析；
• 可通过 MCP 接入 Claude Code、Codex CLI、Gemini CLI、VS Code 等工具；
• 可选 3D 图谱可视化界面。

官方基准中提到，Linux kernel 约 2800 万行代码、7.5 万文件的完整索引约 3 分钟完成；结构查询可达到毫秒级。

3. 安装方式

macOS / Linux 一键安装

普通版本：

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

带图谱可视化 UI 的版本：

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

notepad install.ps1

.\install.ps1

如果只想安装二进制文件，不自动修改 AI 工具配置，可以使用：

--skip-config

如果想指定安装目录，可以使用：

--dir=<path>

4. 验证是否安装成功

安装完成后，重启你的 AI 编程工具。

如果使用 Claude Code，可以输入：

/mcp

正常情况下应该能看到 codebase-memory-mcp，并显示可用的 MCP tools。

也可以直接在终端测试 CLI：

codebase-memory-mcp cli list_projects

如果命令不存在，通常是 PATH 没配置好。macOS/Linux 可以检查：

export PATH="$HOME/.local/bin:$PATH"

5. 给项目建立索引

进入你的代码项目后，可以直接让 AI 助手执行：

Index this project

也可以用 CLI 手动索引：

codebase-memory-mcp cli index_repository '{"repo_path": "/absolute/path/to/your/repo"}'

注意：这里建议使用绝对路径，避免 MCP Server 找不到项目目录。

索引完成后查看项目列表：

codebase-memory-mcp cli list_projects

6. 常用查询示例

6.1 搜索函数或类

codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'

适合查找类似 UserHandler、OrderHandler 这种入口函数。

6.2 查看函数调用链

codebase-memory-mcp cli trace_path '{"function_name": "Search", "direction": "both"}'

direction 可以理解为：

• inbound：谁调用了它；
• outbound：它调用了谁；
• both：双向查看。

6.3 查询项目架构概览

codebase-memory-mcp cli get_architecture '{"repo_path": "/absolute/path/to/your/repo"}'

它会返回语言分布、包结构、入口点、路由、热点模块等信息，适合让 AI 快速理解项目。

6.4 执行图查询

codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'

它支持一个只读的 openCypher 子集，可以用来做更精细的结构查询。

7. 开启自动索引

如果希望 MCP 会话启动时自动索引新项目，可以开启：

codebase-memory-mcp config set auto_index true

限制自动索引文件数：

codebase-memory-mcp config set auto_index_limit 50000

查看当前配置：

codebase-memory-mcp config list

8. 使用图谱可视化 UI

如果你安装的是 UI 版本，可以启动：

codebase-memory-mcp --ui=true --port=9749

然后浏览器打开：

http://localhost:9749

这个页面可以查看项目知识图谱，适合分析大型项目模块关系、跨服务调用和核心节点。

9. 手动配置 MCP

如果你不想使用自动安装脚本，也可以手动配置 MCP。

例如 Claude Code 的 .mcp.json：

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

配置完成后重启 AI 编程工具。

对于 Cursor、Continue、VS Code 等支持 MCP 的客户端，思路类似：把 codebase-memory-mcp 作为一个本地 MCP Server 加进去即可。

10. 推荐提问方式

索引完成后，可以这样问 AI：

请分析这个项目的整体架构，重点说明入口、核心模块和数据流。

请查一下 UserService.createUser 被哪些地方调用，调用链是什么？

我准备修改 OrderController.submitOrder，请分析可能影响到哪些模块。

请找出项目中可能没有调用者的函数，并按风险排序。

请结合代码图谱解释这个接口从路由到数据库写入的完整链路。

这类问题非常适合 codebase-memory-mcp，因为它们依赖结构信息，而不是简单全文搜索。

11. 常见问题

/mcp 看不到服务

检查 MCP 配置里的 command 是否是绝对路径，然后重启 AI 工具。

索引失败

优先确认 repo_path 是绝对路径：

codebase-memory-mcp cli index_repository '{"repo_path": "/absolute/path"}'

查询结果为空

先用模糊搜索找到准确名称：

codebase-memory-mcp cli search_graph '{"name_pattern": ".*PartialName.*"}'

再用完整函数名查询调用链。

不想索引某些文件

可以使用 .gitignore 或项目级 .cbmignore 排除目录，例如：

node_modules/
dist/
build/
coverage/

12. 卸载与更新

更新：

codebase-memory-mcp update

卸载 MCP 配置：

codebase-memory-mcp uninstall

注意：卸载命令会移除 agent 配置、hooks、instructions，但不会删除二进制文件和 SQLite 数据库。

总结

codebase-memory-mcp 的价值，不是让 AI "更会聊天"，而是让 AI 拥有可查询的代码结构记忆。

对于小项目，它能减少重复读文件；对于大型项目，它能显著提升 AI 理解调用链、架构边界和影响范围的能力。尤其是多人维护的老项目、微服务项目、跨语言项目，接入之后体验会非常明显。

如果你正在用 Claude Code、Codex CLI、Cursor、Gemini CLI 或其他支持 MCP 的 AI 编程工具，非常建议把它作为代码智能基础设施装上。