codebase-memory-mcp 安装教程

codebase-memory-mcp 是一个 MCP (Model Context Protocol) Server，它会分析代码仓库构建知识图谱，

让 Claude Code 能够快速查询函数调用链、模块依赖、架构概览等结构化信息。

当前版本: 0.8.1

---

1. 下载

方式一：GitHub Release（推荐）

前往 GitHub Releases 页面下载对应平台的可执行文件：

https://github.com/ArcticXWolf/codebase-memory-mcp/releases

平台	文件名
Windows	codebase-memory-mcp.exe
macOS (Intel)	codebase-memory-mcp-darwin-amd64
macOS (Apple Silicon)	codebase-memory-mcp-darwin-arm64
Linux	codebase-memory-mcp-linux-amd64

方式二：从源码编译

# 需要 Rust 环境 (https://rustup.rs)
git clone https://github.com/ArcticXWolf/codebase-memory-mcp.git
cd codebase-memory-mcp
cargo build --release
# 编译产物在 target/release/codebase-memory-mcp

---

2. 安装

Windows

1. 创建安装目录：

mkdir D:\Programs\codebase-memory-mcp

2. 将下载的 codebase-memory-mcp.exe 放入该目录

3. 验证安装：

D:\Programs\codebase-memory-mcp\codebase-memory-mcp.exe --version
# 输出: codebase-memory-mcp 0.8.1

macOS / Linux

# 创建目录
mkdir -p ~/.local/bin/codebase-memory-mcp

# 移动文件
mv ~/Downloads/codebase-memory-mcp-* ~/.local/bin/codebase-memory-mcp/codebase-memory-mcp

# 添加执行权限
chmod +x ~/.local/bin/codebase-memory-mcp/codebase-memory-mcp

# 验证
~/.local/bin/codebase-memory-mcp/codebase-memory-mcp --version

---

3. 配置 Claude Code

方法一：全局配置（推荐）

编辑 ~/.claude/.mcp.json，添加 codebase-memory-mcp：

{
    "mcpServers": {
        "codebase-memory-mcp": {
            "command": "D:/Programs/codebase-memory-mcp/codebase-memory-mcp.exe"
        }
    }
}

macOS / Linux 版本：

{
    "mcpServers": {
        "codebase-memory-mcp": {
            "command": "/Users/你的用户名/.local/bin/codebase-memory-mcp/codebase-memory-mcp"
        }
    }
}

方法二：项目级配置

在项目根目录创建 .mcp.json：

{
    "mcpServers": {
        "codebase-memory-mcp": {
            "command": "D:/Programs/codebase-memory-mcp/codebase-memory-mcp.exe"
        }
    }
}

配置文件位置说明

文件	作用域	路径
全局配置	所有项目	~/.claude/.mcp.json
项目配置	单个项目	<项目根目录>/.mcp.json

---

4. 安装 Skill（可选，增强体验）

Skill 文件让 Claude Code 知道何时以及如何使用这个 MCP 工具。

创建文件 ~/.claude/skills/codebase-memory/SKILL.md：

---
name: codebase-memory
description: Use the codebase knowledge graph for structural code queries. Triggers on: explore the codebase, understand the architecture, what functions exist, show me the structure, who calls this function, what does X call, trace the call chain, find callers of, show dependencies, impact analysis, dead code, unused functions, high fan-out, refactor candidates, code quality audit.
---

# Codebase Memory --- Knowledge Graph Tools

Graph tools return precise structural results in ~500 tokens vs ~80K for grep.

## Quick Decision Matrix

| Question | Tool call |
|----------|----------|
| Who calls X? | `trace_path(direction="inbound")` |
| What does X call? | `trace_path(direction="outbound")` |
| Full call context | `trace_path(direction="both")` |
| Find by name pattern | `search_graph(name_pattern="...")` |
| Dead code | `search_graph(max_degree=0, exclude_entry_points=true)` |
| Cross-service edges | `query_graph` with Cypher |
| Impact of local changes | `detect_changes()` |

## Exploration Workflow
1. `list_projects` --- check if project is indexed
2. `get_graph_schema` --- understand node/edge types
3. `search_graph(label="Function", name_pattern=".*Pattern.*")` --- find code
4. `get_code_snippet(qualified_name="project.path.FuncName")` --- read source

## 14 MCP Tools
`index_repository`, `index_status`, `list_projects`, `delete_project`,
`search_graph`, `search_code`, `trace_path`, `detect_changes`,
`query_graph`, `get_graph_schema`, `get_code_snippet`, `get_architecture`,
`manage_adr`, `ingest_traces`

---

5. 验证安装

1. 重启 Claude Code（必须，MCP 配置变更需要重启生效）

2. 在 Claude Code 中运行 /mcp 命令，确认 codebase-memory-mcp 已连接

3. 测试基本功能：

# 索引一个项目
index_repository(repo_path="你的项目路径", mode="fast")

# 查看已索引项目
list_projects()

---

6. 常见问题

Q: MCP Server 连接失败？

# 检查 exe 是否存在且可执行
ls -la D:/Programs/codebase-memory-mcp/codebase-memory-mcp.exe

# 手动运行看看有没有报错
D:/Programs/codebase-memory-mcp/codebase-memory-mcp.exe --version

Q: 索引很慢？

• 使用 mode="fast" 快速索引
• 排除不需要的目录（node_modules, .git 等会自动排除）
• 大仓库建议用 mode="moderate" 平衡速度和精度

Q: 代码修改后需要重新索引吗？

是的。修改代码后需要重新调用 index_repository() 更新图谱。

Q: 索引数据存在哪里？

默认存在 MCP server 的内存/临时存储中。如果需要持久化或团队共享：

index_repository(repo_path="...", persistence=true)
# 会在项目下生成 .codebase-memory/graph.db.zst

Q: 支持哪些编程语言？

支持所有主流语言，包括但不限于：

• TypeScript / JavaScript
• Python
• Rust
• Go
• Java
• C / C++

---

7. 完整配置示例

~/.claude/.mcp.json（Windows）

{
    "mcpServers": {
        "codebase-memory-mcp": {
            "command": "D:/Programs/codebase-memory-mcp/codebase-memory-mcp.exe"
        },
        "headroom": {
            "command": "D:/tools/headroom-venv/Scripts/headroom.exe",
            "args": ["mcp", "serve", "--proxy-url", "http://127.0.0.1:9999"],
            "cwd": "D:/tools",
            "env": {
                "HEADROOM_DATA_DIR": "D:/tools/headroom-data"
            }
        }
    }
}

注意 : 如果已有其他 MCP Server 配置（如 headroom），只需在 mcpServers 对象中添加 codebase-memory-mcp 字段即可，不要覆盖整个文件。

---

8. 使用速查

安装完成后，参考 codebase-memory-mcp-tutorial.md 学习具体使用方法。

第一步	命令
索引项目	index_repository(repo_path="项目路径")
看架构	get_architecture(project="项目名")
搜函数	search_graph(project="项目名", query="函数名")
看源码	get_code_snippet(project="项目名", qualified_name="...")