codebase-memory-mcp：让AI编码代理拥有代码库持久记忆 | MCP服务器教程

2026年7月GitHub上最火的项目之一——codebase-memory-mcp（24,000+ Stars），一个用纯C编写的高性能代码智能MCP服务器。它能将整个代码库索引为持久知识图谱，让AI编码代理拥有"过目不忘"的记忆能力，Token消耗减少99%。

什么是 codebase-memory-mcp？

codebase-memory-mcp 是一个专为 AI 编码代理设计的代码智能引擎。它通过 tree-sitter 解析 + Hybrid LSP 类型解析，将代码库索引到 SQLite 持久化知识图谱中，提供 14 个 MCP 工具进行结构化代码查询。

项目地址：https://github.com/DeusData/codebase-memory-mcp

核心亮点

• 🚀 极速索引：Linux内核（28M行代码，75K文件）3分钟完成全索引
• ⚡ 亚毫秒查询：结构查询 <1ms，名称搜索 <10ms
• 💾 Token节省99%：5个结构化查询消耗 ~3,400 tokens vs 文件逐个搜索 ~412,000 tokens
• 📦 零依赖：单一静态二进制，所有库编译时嵌入
• 🔒 100%本地运行：代码、查询从不离开你的机器，零遥测
• 🌐 158种语言：tree-sitter 支持所有主流编程语言
• 🔌 11种AI代理：Claude Code / Codex / Gemini CLI / Cursor / Zed 等

技术架构

• 核心语言：C（32.4MB），C++（3.7MB）
• 存储引擎：SQLite（WAL模式，ACID安全）
• 解析引擎：tree-sitter（158种语言）+ 自研 Hybrid LSP
• 嵌入模型：Nomic nomic-embed-code（768维 int8，编译进二进制）
• 全文搜索：SQLite FTS5（支持 camelCase/snake_case 感知）
• 平台：macOS (arm64/amd64) / Linux (arm64/amd64) / Windows (amd64)

一键安装

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

# 仅安装二进制（跳过自动配置）
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --skip-config

# 自定义安装目录
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --dir=/opt/cbm

Windows (PowerShell)

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1" -OutFile install.ps1
.\install.ps1

Claude Code 直接安装

如果你使用 Claude Code，直接对它说：

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

包管理器安装

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

# Homebrew
brew install codebase-memory-mcp

# npm
npm install -g codebase-memory-mcp

# pip
pip install codebase-memory-mcp

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

# Winget
winget install codebase-memory-mcp

快速上手

安装完成后，重启你的AI编码代理，然后对它说：

Index this project

就这么简单！代理会自动调用 index_repository 工具完成索引。

14个MCP工具详解

索引类工具

• index_repository — 索引代码库
• list_projects — 列出已索引项目
• delete_project — 删除项目索引
• index_status — 查看索引状态

查询类工具

• search_graph — 结构化搜索（标签、名称模式、文件模式）
• trace_path — 追踪函数调用链（BFS遍历，深度1-5）
• detect_changes — Git diff 影响映射 + 风险分类
• query_graph — Cypher 风格图查询
• get_graph_schema — 节点/边计数、关系模式
• get_code_snippet — 按限定名读取源码
• get_architecture — 代码库架构概览
• search_code — 图增强 grep
• manage_adr — 架构决策记录管理
• ingest_traces — 运行时追踪验证

CLI 命令行使用

# 索引仓库
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 list_projects

# 原始输出 + jq 处理
codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.results[].name'

配置选项

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

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

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

# 重置配置
codebase-memory-mcp config reset auto_index

环境变量

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

图谱可视化 UI

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

浏览器打开 http://localhost:9749 即可看到 3D 代码图谱。

性能基准（Apple M3 Pro）

• Linux内核全索引：3分钟（28M行，75K文件 → 481万节点，772万边）
• Django全索引：~6秒（49K节点，196K边）
• Cypher查询：<1ms
• 名称搜索：<10ms
• 追踪调用路径（深度5）：<10ms
• 死代码检测：~150ms

安全保障

• 🔒 VirusTotal：所有二进制经70+杀毒引擎扫描
• 🔐 SLSA Level 3：GitHub Actions 加密构建来源
• ✍️ Sigstore cosign：所有工件无密钥签名
• 🔢 SHA-256校验：每个版本附带 checksums.txt
• 🛡️ CodeQL SAST：阻止有未解决警报的发布
• 🏠 100%本地运行：零遥测

总结

codebase-memory-mcp 是目前最高效的 AI 编码代理代码智能方案。核心优势：

• ⚡ 极速：毫秒级索引大型代码库
• 💾 省Token：结构化查询比文件搜索节省99% Token
• 📦 零依赖：单二进制部署，开箱即用
• 🔒 全本地：代码不离开你的机器
• 🔌 广泛兼容：支持11种主流AI编码代理

如果你正在使用 Claude Code、Cursor 等 AI 编码工具，codebase-memory-mcp 是提升编码效率的必备工具。