用 codebase-memory-mcp 给 AI 编程加一层“代码记忆”

最近我在用 Codex 做开发时，遇到一个很现实的问题：AI 每次理解项目，都要反复读文件、搜索代码、追调用链。项目一大，token 消耗很快，而且上下文一长，回答也更容易偏。

我的目标很简单：省 token，让 AI coding 更准确。

后来我开始尝试 DeusData/codebase-memory-mcp。它的思路不是让 AI 每次都从零读代码，而是先把项目索引成一个本地知识图谱。之后 AI 要找类、函数、调用关系、架构边界，就可以直接查图谱，而不是一遍遍 grep、读文件、猜上下文。

它解决什么问题

传统 AI 编码流程通常是：

搜索关键词
读取多个文件
猜测调用关系
再搜索更多文件
最后才开始改代码

这会消耗大量 token，而且很依赖模型是否刚好读到了关键文件。

codebase-memory-mcp 会把项目里的函数、类、调用关系、路由、配置、文件结构等信息抽取成图谱。AI 之后可以直接问：

这个类在哪里定义？
谁调用了这个函数？
这个模块的架构是什么？
改这个方法会影响哪些地方？
项目有哪些入口点和热点函数？

这类结构化问题，用图谱查会比反复读文件更稳定。

官方介绍里提到，它支持多语言代码索引、结构化搜索、调用链追踪、架构概览和本地 3D 图谱可视化，并且所有处理都在本地完成，下边是我自己部署后对项目生成的知识图谱，看起来特别炫酷，同时支持筛选目录、文件、类、方法之间的关系图展示。

安装

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

安装后确认命令是否可用：

codebase-memory-mcp --help

我本机的路径是：

/Users/webjing/.local/bin/codebase-memory-mcp

为指定项目生成知识图谱

核心命令是 index_repository。

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

以我的 Halo 插件项目为例：

/Users/webjing/.local/bin/codebase-memory-mcp cli index_repository '{
  "repo_path": "/Users/webjing/code/halo-project/plugin-simple-reveal",
  "mode": "fast",
  "name": "plugin-simple-reveal"
}'

常用模式：

# 快速索引，适合日常使用
codebase-memory-mcp cli index_repository '{
  "repo_path": "/path/to/project",
  "mode": "fast",
  "name": "project-name"
}'

# 完整索引，适合需要更深入分析时使用
codebase-memory-mcp cli index_repository '{
  "repo_path": "/path/to/project",
  "mode": "full",
  "name": "project-name"
}'

验证索引结果

查看已索引项目：

codebase-memory-mcp cli list_projects '{}'

搜索图谱：

codebase-memory-mcp cli search_graph '{
  "project": "Users-webjing-code-halo-project-plugin-simple-reveal",
  "query": "SlideDeck",
  "limit": 10
}'

查看架构概览：

codebase-memory-mcp cli get_architecture '{
  "project": "Users-webjing-code-halo-project-plugin-simple-reveal",
  "aspects": ["all"]
}'

追踪调用链：

codebase-memory-mcp cli trace_path '{
  "project": "Users-webjing-code-halo-project-plugin-simple-reveal",
  "function_name": "update",
  "direction": "both",
  "depth": 3
}'

读取具体代码片段：

codebase-memory-mcp cli get_code_snippet '{
  "project": "Users-webjing-code-halo-project-plugin-simple-reveal",
  "qualified_name": "完整 qualified_name"
}'

在受限环境里写到项目内

有些环境不允许 MCP 写全局缓存目录。可以把缓存放到项目内：

mkdir -p .codebase-memory-local/home .codebase-memory-local/cache

HOME="$PWD/.codebase-memory-local/home" \
XDG_CACHE_HOME="$PWD/.codebase-memory-local/cache" \
codebase-memory-mcp cli index_repository '{
  "repo_path": "'$PWD'",
  "mode": "fast",
  "name": "project-name"
}'

之后查询也要带上相同环境变量：

HOME="$PWD/.codebase-memory-local/home" \
XDG_CACHE_HOME="$PWD/.codebase-memory-local/cache" \
codebase-memory-mcp cli list_projects '{}'

开启图谱 UI

如果安装的是 UI 版本，可以启动本地图谱界面：

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

然后打开：

http://127.0.0.1:9749

配置自动索引

可以开启 MCP 会话启动时自动索引：

codebase-memory-mcp config set auto_index true

查看配置：

codebase-memory-mcp config list

我的使用感受

对 AI 编程来说，最贵的不是“写代码”，而是“理解项目”。

没有知识图谱时，AI 往往要不断搜索和读取文件。用了 codebase-memory-mcp 后，AI 可以先查结构，再决定读哪些文件。这样做有几个好处：

token 消耗明显更可控
不容易漏掉关键调用关系
修改前能更快判断影响范围
对多模块项目、插件项目、前后端混合项目更友好
后续对同一个项目继续开发时，AI 不必每次从零开始理解

我的建议是：只要项目不是一个很小的 demo，都可以先跑一次索引。尤其是 Spring 项目、python项目、Vue 管理端这类前后端混合工程，图谱带来的收益很明显。

常用命令速查

# 生成图谱
codebase-memory-mcp cli index_repository '{
  "repo_path": "/path/to/project",
  "mode": "fast",
  "name": "project-name"
}'

# 查看项目
codebase-memory-mcp cli list_projects '{}'

# 搜索符号
codebase-memory-mcp cli search_graph '{
  "project": "project-name",
  "query": "keyword",
  "limit": 10
}'

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

# 调用链
codebase-memory-mcp cli trace_path '{
  "project": "project-name",
  "function_name": "functionName",
  "direction": "both",
  "depth": 3
}'

# 代码片段
codebase-memory-mcp cli get_code_snippet '{
  "project": "project-name",
  "qualified_name": "qualified.name"
}'

# 启动 UI
codebase-memory-mcp --ui=true --port=9749