codebase-memory-mcp 新手完全教程：让 AI 真正「理解」你的代码库

本文介绍 codebase-memory-mcp ------ 一个高性能代码智能 MCP 服务器，能将代码库索引为知识图谱，让 AI 编程助手真正理解代码结构，而非逐文件搜索。

一、什么是 codebase-memory-mcp？

codebase-memory-mcp 是一个基于 MCP（Model Context Protocol） 的代码智能引擎。它通过 tree-sitter AST 分析，将你的代码库解析成一个持久化知识图谱，包含函数、类、调用链、HTTP 路由等结构化信息。

核心优势

特性	说明
极速索引	普通项目毫秒级完成，Linux 内核（2800 万行）仅需 3 分钟
158 种语言	通过 tree-sitter 支持几乎所有主流编程语言
99% Token 节省	结构化查询 vs 逐文件搜索，Token 消耗从 41.2 万降至 3400
零依赖	单个静态二进制文件，下载即用
100% 本地	所有处理在本地完成，代码永远不会离开你的机器
14 个 MCP 工具	搜索、追踪、架构分析、死代码检测、Cypher 查询等

支持的 AI 编程助手

自动检测并配置：Claude Code、Codex CLI、Gemini CLI、Zed、OpenCode、Aider、KiloCode、VS Code、Kiro 等 11 种。

二、安装方法

方法一：一键安装（推荐）

macOS / Linux：

bash 复制代码

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

带图形化知识图谱 UI：

bash 复制代码

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

Windows（PowerShell）：

powershell 复制代码

# 下载安装脚本
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# （可选）检查脚本内容
notepad install.ps1

# 执行安装
.\install.ps1

方法二：包管理器安装

bash 复制代码

# Arch Linux (AUR)
yay -S codebase-memory-mcp-bin

# macOS (Homebrew)
brew install deusdata/tap/codebase-memory-mcp

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

# Windows (Winget)
winget install DeusData.CodebaseMemoryMCP

# Windows (Chocolatey)
choco install codebase-memory-mcp

# npm
npm install -g codebase-memory-mcp

# pip
pip install codebase-memory-mcp

方法三：手动安装

从 GitHub Releases 下载对应平台的压缩包
解压后运行安装脚本：

bash 复制代码

# macOS / Linux
tar xzf codebase-memory-mcp-*.tar.gz
./install.sh

# Windows (PowerShell)
Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
.\install.ps1

重启你的 AI 编程助手

方法四：通过 Claude Code 安装

直接对 Claude Code 说：

bash 复制代码

Install this MCP server: https://github.com/DeusData/codebase-memory-mcp

三、新手接到项目后的使用流程

第 1 步：确认安装成功

安装完成后，重启 Claude Code，输入 /mcp 查看是否显示 codebase-memory-mcp 及其 14 个工具。

第 2 步：索引你的项目

进入项目目录，对 AI 说：

bash 复制代码

Index this project

或者使用 CLI 命令：

bash 复制代码

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

索引完成后会显示类似：

json 复制代码

{
  "project": "your-project",
  "total_nodes": 4156,
  "total_edges": 10093,
  "languages": [{"language": "TypeScript", "file_count": 306}],
  "duration_ms": 1250
}

第 3 步：查看项目架构

索引完成后，让 AI 帮你了解项目全貌：

bash 复制代码

帮我分析这个项目的整体架构

AI 会调用 get_architecture 工具，返回：

使用的编程语言及文件数
包/模块结构
入口点
HTTP 路由
热点文件（变更频繁）
功能聚类

第 4 步：开始提问

现在你可以像和资深开发者对话一样提问：

调用链追踪：

bash 复制代码

ProcessOrder 函数被谁调用？它又调用了哪些函数？

AI 调用 trace_path 工具，返回完整的调用链。

代码搜索：

bash 复制代码

找出所有包含 Handler 的函数

AI 调用 search_graph，按名称模式搜索。

死代码检测：

bash 复制代码

有哪些函数没有被任何人调用？

AI 用 Cypher 查询：

cypher 复制代码

MATCH (f:Function)
WHERE NOT EXISTS { (f)<-[:CALLS]-() }
AND f.is_entry_point = false
RETURN f.name, f.file_path

变更影响分析：

bash 复制代码

我改了这个文件，会影响哪些其他模块？

AI 调用 detect_changes，映射 git diff 到受影响的符号并评估风险。

四、14 个 MCP 工具详解

索引管理类

工具	功能	使用场景
`index_repository`	索引代码库到知识图谱	首次使用或代码有大变更时
`list_projects`	列出所有已索引项目	查看已有索引
`delete_project`	删除项目索引	清理旧索引
`index_status`	检查索引状态	确认索引是否最新

查询分析类

工具	功能	使用场景
`search_graph`	按标签、名称模式、文件模式搜索	查找函数、类、接口等
`trace_path`	BFS 遍历调用链（深度 1-5）	追踪函数调用关系
`query_graph`	执行 Cypher-like 图查询	复杂的结构化查询
`get_graph_schema`	获取图谱结构定义	了解可用的节点和边类型
`get_code_snippet`	按限定名获取源代码	查看具体函数实现
`get_architecture`	获取代码库架构概览	快速了解项目全貌
`search_code`	图增强的 grep 搜索	文本搜索 + 结构化上下文
`detect_changes`	映射 git diff 到受影响符号	评估代码变更的影响范围
`manage_adr`	架构决策记录 CRUD	记录和查询架构决策
`ingest_traces`	导入运行时 trace	验证 HTTP 调用关系

五、实际使用示例

示例 1：新人入职快速了解项目

bash 复制代码

你：帮我看看这个项目的整体架构，有哪些主要模块？

AI 调用：get_architecture(project="my-app", aspects=["all"])

返回：语言分布、包结构、入口点、路由、热点文件、功能聚类等

示例 2：理解一个函数的作用

bash 复制代码

你：UserService.createUser 这个函数做了什么？谁调用它？

AI 调用：
1. search_graph(name_pattern="createUser", label="Function") → 找到限定名
2. get_code_snippet(qualified_name="...") → 获取源码
3. trace_path(function_name="createUser", direction="inbound") → 找到调用者

示例 3：重构前的影响分析

bash 复制代码

你：我打算修改数据库连接配置，帮我分析影响范围

AI 调用：
1. search_graph(name_pattern=".*connection.*|.*database.*") → 找到相关节点
2. trace_path(function_name="getConnection", direction="both") → 追踪上下游
3. detect_changes() → 分析未提交变更的影响

示例 4：查找死代码

bash 复制代码

你：帮我找出项目中没有被调用的函数

AI 执行 Cypher 查询：
MATCH (f:Function)
WHERE NOT EXISTS { (f)<-[:CALLS]-() }
AND f.is_entry_point = false
AND f.is_test = false
RETURN f.name, f.file_path, f.lines
ORDER BY f.lines DESC

示例 5：理解 HTTP 路由

bash 复制代码

你：这个项目有哪些 API 路由？

AI 调用：search_graph(label="Route") → 返回所有 HTTP 端点

六、CLI 命令行用法

除了通过 MCP 协议使用，你也可以直接在命令行调用：

bash 复制代码

# 列出所有已索引项目
codebase-memory-mcp cli list_projects

# 索引一个项目
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/repo"}'

# 搜索函数
codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'

# 追踪调用链
codebase-memory-mcp cli trace_path '{"function_name": "Search", "direction": "both"}'

# 执行 Cypher 查询
codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'

# 获取架构概览
codebase-memory-mcp cli get_architecture '{"project": "my-app", "aspects": ["all"]}'

七、配置与调优

基本配置

bash 复制代码

# 查看所有配置
codebase-memory-mcp config list

# 开启自动索引（MCP 会话启动时自动索引新项目）
codebase-memory-mcp config set auto_index true

# 设置自动索引的最大文件数
codebase-memory-mcp config set auto_index_limit 50000

# 重置为默认值
codebase-memory-mcp config reset auto_index

图形化 UI

如果你安装了带 UI 的版本，可以启动可视化界面：

bash 复制代码

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

然后在浏览器打开 http://localhost:9749，可以看到 3D 交互式知识图谱。

环境变量

变量	默认值	说明
`CBM_CACHE_DIR`	`~/.cache/codebase-memory-mcp`	数据库存储目录
`CBM_DIAGNOSTICS`	`false`	设为 `1` 启用诊断日志
`CBM_LOG_LEVEL`	`info`	日志级别：debug/info/warn/error/none
`CBM_WORKERS`	自动检测	并行索引线程数（1-256）

手动配置 MCP（不使用 install 命令）

在 ~/.claude/.mcp.json（全局）或项目 .mcp.json 中添加：

json 复制代码

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

八、更新与卸载

bash 复制代码

# 更新到最新版本
codebase-memory-mcp update

# 卸载（移除所有 agent 配置，但保留数据库）
codebase-memory-mcp uninstall

九、常见问题

Q：索引需要多长时间？

取决于项目大小。普通项目（几千文件）通常在几秒内完成。Linux 内核（7.5 万文件）全量索引约 3 分钟。

Q：索引数据存在哪里？

默认在 ~/.cache/codebase-memory-mcp/ 目录下，以 SQLite 数据库存储。

Q：支持哪些编程语言？

通过 tree-sitter 支持 158 种语言。其中 Python、TypeScript/JavaScript、PHP、C#、Go、C/C++、Java、Kotlin、Rust 还支持 Hybrid LSP 语义类型解析。

Q：代码会被上传到云端吗？

不会。所有处理 100% 在本地完成，代码永远不会离开你的机器。

Q：如何忽略某些文件？

支持三层过滤：

内置模式（.git、node_modules 等）
.gitignore 规则
.cbmignore 文件（项目专用，gitignore 语法）

Q：团队如何共享索引？

可以将 .codebase-memory/graph.db.zst 提交到仓库，队友无需重新索引：

bash 复制代码

# 导出压缩的图谱文件
codebase-memory-mcp cli export_graph '{"project": "my-app"}'

十、总结

codebase-memory-mcp 解决了 AI 编程助手的一个核心痛点：无法高效理解代码库的结构。传统方式下，AI 需要逐文件搜索（grep/read），消耗大量 Token 且容易遗漏关键信息。而通过知识图谱，AI 可以用一个结构化查询替代数十次文件搜索，Token 消耗降低 99%。

新手快速上手三步走：

安装 → 一行命令搞定
索引 → index_repository 或直接说「Index this project」
提问 → 像和同事对话一样问关于代码的问题

项目地址：github.com/DeusData/co...