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

本文介绍 codebase-memory-mcp —— 一个高性能代码智能 MCP 服务器能将代码库索引为知识图谱让 AI 编程助手真正理解代码结构而非逐文件搜索。一、什么是 codebase-memory-mcpcodebase-memory-mcp 是一个基于MCPModel 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 / Linuxcurl-fsSLhttps://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh|bash带图形化知识图谱 UIcurl-fsSLhttps://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh|bash-s----uiWindowsPowerShell# 下载安装脚本Invoke-WebRequest-Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1-OutFile install.ps1# 可选检查脚本内容notepad install.ps1# 执行安装.\install.ps1方法二包管理器安装# Arch Linux (AUR)yay-Scodebase-memory-mcp-bin# macOS (Homebrew)brewinstalldeusdata/tap/codebase-memory-mcp# Windows (Scoop)scoopinstallcodebase-memory-mcp# Windows (Winget)wingetinstallDeusData.CodebaseMemoryMCP# Windows (Chocolatey)chocoinstallcodebase-memory-mcp# npmnpminstall-gcodebase-memory-mcp# pippipinstallcodebase-memory-mcp方法三手动安装从 GitHub Releases 下载对应平台的压缩包解压后运行安装脚本# macOS / Linuxtarxzf 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 说Install this MCP server: https://github.com/DeusData/codebase-memory-mcp三、新手接到项目后的使用流程第 1 步确认安装成功安装完成后重启 Claude Code输入/mcp查看是否显示codebase-memory-mcp及其 14 个工具。第 2 步索引你的项目进入项目目录对 AI 说Index this project或者使用 CLI 命令codebase-memory-mcp cli index_repository{repo_path: /path/to/your/project}索引完成后会显示类似{project:your-project,total_nodes:4156,total_edges:10093,languages:[{language:TypeScript,file_count:306}],duration_ms:1250}第 3 步查看项目架构索引完成后让 AI 帮你了解项目全貌帮我分析这个项目的整体架构AI 会调用get_architecture工具返回使用的编程语言及文件数包/模块结构入口点HTTP 路由热点文件变更频繁功能聚类第 4 步开始提问现在你可以像和资深开发者对话一样提问调用链追踪ProcessOrder 函数被谁调用它又调用了哪些函数AI 调用trace_path工具返回完整的调用链。代码搜索找出所有包含 Handler 的函数AI 调用search_graph按名称模式搜索。死代码检测有哪些函数没有被任何人调用AI 用 Cypher 查询MATCH (f:Function) WHERE NOT EXISTS { (f)-[:CALLS]-() } AND f.is_entry_point false RETURN f.name, f.file_path变更影响分析我改了这个文件会影响哪些其他模块AI 调用detect_changes映射 git diff 到受影响的符号并评估风险。四、14 个 MCP 工具详解索引管理类工具功能使用场景index_repository索引代码库到知识图谱首次使用或代码有大变更时list_projects列出所有已索引项目查看已有索引delete_project删除项目索引清理旧索引index_status检查索引状态确认索引是否最新查询分析类工具功能使用场景search_graph按标签、名称模式、文件模式搜索查找函数、类、接口等trace_pathBFS 遍历调用链深度 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新人入职快速了解项目你帮我看看这个项目的整体架构有哪些主要模块 AI 调用get_architecture(projectmy-app,aspects[all])返回语言分布、包结构、入口点、路由、热点文件、功能聚类等示例 2理解一个函数的作用你UserService.createUser 这个函数做了什么谁调用它 AI 调用1. search_graph(name_patterncreateUser,labelFunction)→ 找到限定名2. get_code_snippet(qualified_name...)→ 获取源码3. trace_path(function_namecreateUser,directioninbound)→ 找到调用者示例 3重构前的影响分析你我打算修改数据库连接配置帮我分析影响范围 AI 调用1. search_graph(name_pattern.*connection.*|.*database.*)→ 找到相关节点2. trace_path(function_namegetConnection,directionboth)→ 追踪上下游3. detect_changes()→ 分析未提交变更的影响示例 4查找死代码你帮我找出项目中没有被调用的函数 AI 执行 Cypher 查询 MATCH(f:Function)WHERE NOT EXISTS{(f)-[:CALLS]-()}AND f.is_entry_pointfalseAND f.is_testfalseRETURN f.name, f.file_path, f.lines ORDER BY f.lines DESC示例 5理解 HTTP 路由你这个项目有哪些 API 路由 AI 调用search_graph(labelRoute)→ 返回所有 HTTP 端点六、CLI 命令行用法除了通过 MCP 协议使用你也可以直接在命令行调用# 列出所有已索引项目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]}七、配置与调优基本配置# 查看所有配置codebase-memory-mcp config list# 开启自动索引MCP 会话启动时自动索引新项目codebase-memory-mcp configsetauto_indextrue# 设置自动索引的最大文件数codebase-memory-mcp configsetauto_index_limit50000# 重置为默认值codebase-memory-mcp config reset auto_index图形化 UI如果你安装了带 UI 的版本可以启动可视化界面codebase-memory-mcp--uitrue--port9749然后在浏览器打开http://localhost:9749可以看到 3D 交互式知识图谱。环境变量变量默认值说明CBM_CACHE_DIR~/.cache/codebase-memory-mcp数据库存储目录CBM_DIAGNOSTICSfalse设为1启用诊断日志CBM_LOG_LEVELinfo日志级别debug/info/warn/error/noneCBM_WORKERS自动检测并行索引线程数1-256手动配置 MCP不使用 install 命令在~/.claude/.mcp.json全局或项目.mcp.json中添加{mcpServers:{codebase-memory-mcp:{command:/path/to/codebase-memory-mcp,args:[]}}}八、更新与卸载# 更新到最新版本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提交到仓库队友无需重新索引# 导出压缩的图谱文件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」提问→ 像和同事对话一样问关于代码的问题项目地址https://github.com/DeusData/codebase-memory-mcp