MCP Codebase-Memory 本地代码智能为开发者和AI智能体建知识图谱

AI 编码助手最常见的短板，是“记不住”你的代码库：每次对话都从零读文件，重复消耗大量 token，也容易被长上下文淹没，甚至读漏关键文件。更隐蔽的问题是，它往往不清楚“改 A 会影响哪些测试”，于是一边改一边引入新的回归。Codebase-Memory-MCP 用一个本地知识图谱把代码、文档与基础设施连起来，让 AI 智能体像拥有长期记忆一样精准定位改动点，而不是盲目扫描全仓。它把“代码理解”从每次临时读取，升级为一次建图、长久复用。

项目基本信息

一、项目介绍

codebase-memory-mcp（简称 CBM）是一个本地运行的代码智能服务，以 MCP 协议暴露 17 个工具，供 Claude Code、Codex、Cursor 等编码智能体调用。它用原生 C 后端解析多种语言与文件格式，并叠加 Hybrid LSP 类型解析，把仓库索引成一张可查询的知识图谱。最新版本 v0.12.1，索引与查询均无需托管服务或 API Key，适合对数据外流零容忍的团队。它还提供 CBM Lens 做代码可视化与源码导航，并支持变更感知的测试选择（Smart CI）。

这个项目解决的是一个越来越普遍的问题：智能体每次会话都是“失忆”的。它读过的文件、分析过的调用关系，关掉窗口就没了，下一次从零开始，既慢又容易得出矛盾结论。Codebase Memory MCP 的思路是给代码库建一份持久化记忆：通过 MCP 协议把代码结构、依赖关系、历史结论存成可检索的知识图谱，任何支持 MCP 的客户端都能直接查询。它运行在本地，索引数据不出机器，对代码安全敏感的项目比较友好。索引过程是增量的，代码变更后只需更新受影响部分，不用每次全量重建。

二、核心优势

第一，本地优先、零外发。源码分析与图谱存储都在本机完成，数据不出内网，私有仓库也可放心使用。第二，原生高性能。C 后端无需 Docker 或语言运行时，解析语法树效率高，大仓也能快速建索引。第三，智能体集成广。安装器自动适配 45 种客户端配置，包括 skills、agent profiles 与 hooks。第四，聚焦查询显著降低 token 消耗，减少重复读文件，长期用下来更省成本。第五，类型感知，借助 Hybrid LSP 获得比纯文本检索更准的依赖关系。

第六，查询接口是结构化的。你可以问“谁调用了这个函数”“这个配置项被哪些模块读取”，返回的是经过验证的事实，而不是模型根据片段猜的答案。第七，它天然多客户端复用：同一份索引，Claude Code、Cursor、自研智能体都能连，避免每个工具各建一套。第八，数据格式开放，可以导出、备份或接入现有检索系统。第九，部署极简，一个本地进程加一份配置文件即可，不需要额外的数据库服务。第十，对 monorepo 支持良好，能按包划分索引边界。

三、适用场景

适合代码库庞大、AI 助手反复“失忆”的团队；希望给编码智能体加上长期记忆、提升跨文件改动能量的开发者；以及需要在 CI 中做变更感知测试选择（Smart CI）的工程组织。当你发现智能体每次都要重读整个模块、token 账单居高不下时，CBM 能明显改善体验，让改动更有针对性。

典型用法包括：大型重构前先查影响面，确认所有调用点都被覆盖；新人入职时查询模块职责，快速建立全局观；智能体开发时把历史结论作为上下文注入，减少重复探索。对维护多个仓库的团队，它还可以作为统一的代码知识入口，让不同项目的结构对比变得容易。

四、安装教程

macOS 与 Linux 一行安装：

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

Windows 用 PowerShell：

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

安装后启动可视化服务：

codebase-memory-mcp daemon start --open --port=9749

若遇到脚本执行策略限制，可先 Set-ExecutionPolicy -Scope Process Bypass 再运行，安装完成后建议恢复默认策略。

五、使用示例

在支持的客户端里，你可以让智能体直接问图谱：

哪些模块依赖了 auth 模块？改动 login 函数会影响哪些测试？

CBM 返回聚焦的子图与受影响文件列表，智能体据此精准编辑，而不是盲目扫描全仓。这种“先问依赖、再动手”的方式，显著降低了引入回归的概率，也让测试更聚焦，跑得更少、更快。

在支持 MCP 的客户端里加入配置即可启用：

{
  "mcpServers": {
    "codebase-memory": {
      "command": "npx",
      "args": ["-y", "codebase-memory-mcp", "--repo", "./"]
    }
  }
}

启动后让它索引仓库，随后就能用自然语言查询结构关系，例如“找出所有直接读写数据库表的模块”。首次索引耗时取决于代码规模，之后增量更新通常在秒级完成。

六、常见问题

问：支持哪些语言？内置多语言语法与 Hybrid LSP，常见语言均覆盖，详见仓库语言支持表。问：会泄露代码吗？全部本地处理，可放心用于私有仓库。问：和向量检索有何不同？它保留结构化依赖关系，查询更精确，而非模糊语义匹配，更适合“影响面分析”这类任务。问：占用资源多吗？索引期会吃 CPU，完成后主要是磁盘存储。

问：索引文件有多大？与代码规模和保留粒度有关，通常远小于代码本身。问：支持哪些语言？主流静态语言与脚本语言均可解析。问：能和 Git 历史结合吗？可以按提交关联索引快照，回看某个版本的结构。

七、总结

codebase-memory-mcp 用 MIT 协议把“代码长期记忆”这件刚需做成可自托管的 MCP 服务。它直击 AI 编码助手失忆、费 token 的痛点，是构建高效本地 AI 开发工作流的优质拼图，尤其适合大型私有代码库。

在智能体逐渐成为日常工具的阶段，“记忆”是会持续产生复利的基础设施。这个项目把代码库认知沉淀下来，让每次会话都站在前一次的肩膀上，方向上很值得关注。