CodebaseMemoryMCP

1. 项目/产品概览

项目定位

Codebase Memory MCP 不是又一个代码搜索工具、也不是一个嵌入 LLM 的代码助手。它是一个纯结构化的代码智能后端——它只负责构建和查询代码知识图谱，将"理解代码"这件事交给 AI Agent（MCP Client）。这种分工在架构上非常清晰：

开发者: "ProcessOrder 函数被谁调用？"
  → AI Agent 调用 MCP 工具: trace_path(function_name="ProcessOrder", direction="inbound")
    → Codebase Memory MCP: 执行图查询，返回结构化结果
      → AI Agent: 用自然语言呈现调用链

这种设计避免了其他同类工具常见的"内置 LLM 做 NL→Query 翻译"带来的额外 API Key、额外成本和额外模型配置复杂度。

2. 它主要能做什么

Codebase Memory MCP 将整个代码库构建为一个多关系知识图谱，然后向 AI Agent 暴露 14 个 MCP 工具进行结构化和语义化查询：

2.1 图分析与结构化理解

2.2 搜索能力

2.3 跨服务链接

• HTTP 路由匹配：路由 ↔ 调用点匹配，带置信度评分
• gRPC / GraphQL / tRPC：服务检测 + protobuf Route 提取
• Channel 检测：EMITS / LISTENS_ON 边检测 Socket.IO、EventEmitter、通用 pub-sub 模式（覆盖 8 种语言）

2.4 跨仓库智能

• CROSS_* 边跨多个仓库链接节点（同一 SQLite 存储内）
• 多 galaxy 3D UI 布局用于跨仓库架构可视化
• 跨仓库架构摘要，整合所有已索引仓库的服务、路由和依赖

2.5 基础设施即代码 (IaC) 索引

• Dockerfiles → 图节点
• Kubernetes manifests → Resource 节点
• Kustomize overlays → Module 节点 + IMPORTS 边
• Helm charts → template/Chart.yaml 依赖边
• HCL (Terraform) → 块标签合并到节点名

2.6 14 种边（关系）类型

CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS, HTTP_CALLS, ASYNC_CALLS, EMITS, LISTENS_ON, DATA_FLOWS（含参数映射+字段访问链）, SIMILAR_TO（MinHash + LSH 近似代码克隆检测）, SEMANTICALLY_RELATED（词汇失配但语义相关，同语言，score ≥ 0.80）

2.7 可选 Graph UI

• 内置 3D 交互式可视化（Three.js + 自研 HTTP 服务器）
• localhost:9749 访问
• 作为后台线程与 MCP 服务器并行运行

2.8 团队共享图工件

• 单文件 .codebase-memory/graph.db.zst 提交到仓库
• 格式：SQLite → 去索引 → VACUUM INTO 压缩 → zstd 压缩（压缩比 8-13:1）
• 双档质量：Best（zstd -9，手动 index）和 Fast（zstd -3，watcher 增量更新）
• 团队成员 clone 后直接解压导入，跳过全量重索引，仅执行增量索引
• .gitattributes 自动添加 merge=ours，消除二进制工件合并冲突
• 可选：不提交则每人各自全量索引

3. 适用场景

3.1 核心场景：AI 辅助编程时的大代码库理解

问题：当 AI Agent（如 Claude Code）面对一个大型代码库时，每次查询都需要阅读大量文件、执行多次 grep，Token 消耗极大且没有全局结构感。 解决：先花 3-6 秒（或大型仓 3 分钟）构建知识图谱，之后所有结构查询通过图查询在 < 1ms 完成，Token 消耗降低 99.2%。

3.2 典型适用场景清单

3.3 语言覆盖面

158 种语言的 tree-sitter 解析层覆盖了几乎所有主流和小众编程语言。Hybrid LSP（9 种语言）则提供了更深的类型感知分析——对 Go、Python、TypeScript、Java、C/C++、C#、PHP、Kotlin、Rust 这类企业级主力语言，效果尤佳。

Benchmark 数据显示 Tier 1（≥90%）语言包括：Lua, Kotlin, C++, Perl, Objective-C, Groovy, C, Bash, Zig, Swift；Tier 2（75-89%）包括：Python, TypeScript, TSX, Go, Rust, Java, R, Dart, JavaScript, Erlang, Elixir, Scala, Ruby, PHP, C#。

4. 不太适合的场景

5. 核心能力清单

5.1 性能指标

5.2 论文评测结果

arXiv 论文中在 31 个真实仓库上的评估结果：

• 答案质量：83%（对比逐文件搜索的 92%）
• Token 消耗：减少 10 倍
• 工具调用次数：减少 2.1 倍
• 图原生查询（hub 检测、caller ranking）：在 31 种语言中的 19 种上持平或超越文件搜索

5.3 索引流水线

文件发现（gitignore 感知）
  → Tree-sitter AST 解析（158 种语言语法）
    → 多阶段提取流水线（定义、调用、导入、使用、HTTP 路由等）
      → 包/模块解析（package.json, go.mod, Cargo.toml 等 10+ 清单文件）
        → Hybrid LSP 语义解析（9 种语言，类型感知调用解析）
          → RAM-first 流水线（LZ4 压缩 → 内存 SQLite → 单次 dump → 释放内存）

5.4 运维特性

• 自动同步：后台文件监控（基于 git），变更自动重新索引
• 自动索引：config set auto_index true 后首次 MCP 连接自动触发索引
• 自更新：codebase-memory-mcp update 一键更新
• 卸载干净：codebase-memory-mcp uninstall 移除所有 Agent 配置、技能、钩子和指令
• CLI 模式：支持命令行直接调用，如 codebase-memory-mcp cli search_graph '{"name_pattern": ".Handler."}'
• cgroup 感知：CBM_WORKERS 环境变量控制并行度，适配容器化部署

5.5 安全与信任

• 100% 本地处理：代码从不离开本机
• 无网络调用：内嵌 embedding 模型，不需要 API Key、不需要 Ollama、不需要 Docker
• 每版 Release：SHA-256 签名 + 70+ 杀毒引擎扫描（全部 0 检出）
• SLSA Level 3 构建证明
• 自建 HTTP 服务器（v0.8.1 起）：仅绑定 127.0.0.1，严格 HTTP/1.1 解析，硬请求限制

6. 架构 / 部署 / 集成方式

6.1 项目源码结构

src/
├── foundation/      Arena 分配器、哈希表、字符串工具、平台兼容
├── store/           SQLite 图存储（WAL 模式、FTS5）
├── cypher/          Cypher 查询 → SQL 转换
├── mcp/             MCP 服务器（JSON-RPC 2.0 over stdio，14 个工具）
├── pipeline/        多阶段索引流水线
├── httplink.c       HTTP 路由提取（Go/Express/Laravel/Ktor/Python 等框架）
├── discover/        文件发现（gitignore 感知）
├── watcher/         Git 后台自动同步
├── cli/             CLI 子命令（install, update, uninstall, config）
├── ui/              图可视化 HTTP 服务器（自研 httpd.c）
internal/cbm/        Tree-sitter AST 提取（158 种语言，vendored C 语法）
vendored/            sqlite3, yyjson, mimalloc, xxhash, tree-sitter
graph-ui/            React/Three.js 可视化前端
tests/               所有 C 测试文件（5604 个）

6.2 部署架构

┌─────────────────────────────────────────┐
│            开发者机器                      │
│  ┌───────────┐    ┌────────────────────┐ │
│  │ AI Agent  │◄──►│ codebase-memory-mcp│ │
│  │(MCP Client)│    │  (MCP Server)      │ │
│  │           │    │  - stdio transport  │ │
│  │ Claude Code│   │  - 14 tools         │ │
│  │ Codex CLI  │   │  - SQLite 图存储    │ │
│  │ Gemini CLI │   │  - 文件监控         │ │
│  │ VS Code    │   │  - 3D Graph UI     │ │
│  │ ...        │    │    (:9749 可选)    │ │
│  └───────────┘    └────────┬───────────┘ │
│                            │              │
│                    ~/.cache/              │
│                    codebase-memory-mcp/   │
│                    (SQLite 数据库)         │
└─────────────────────────────────────────┘

6.3 安装与集成

一键安装（macOS / Linux）：

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

# 带 3D 可视化 UI
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

Windows（PowerShell）：

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

包管理器安装：

# Homebrew
brew install codebase-memory-mcp

# npm
npx codebase-memory-mcp install

# PyPI
uvx codebase-memory-mcp install

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

安装程序自动：检测所有已安装的编码 Agent（Claude Code、Codex CLI、Gemini CLI、Zed、OpenCode、Antigravity、Aider、KiloCode、VS Code、OpenClaw、Kiro），为其配置 MCP 服务器条目、指令文件、技能和 pre-tool hooks。

6.4 配置关键项

# 启用自动索引（首次连接时自动索引新项目）
codebase-memory-mcp config set auto_index true

# 自动索引文件上限（默认 50000）
codebase-memory-mcp config set auto_index_limit 100000

# 日志级别
export CBM_LOG_LEVEL=debug

# 并行 Workers 数量（容器化环境）
export CBM_WORKERS=4

6.5 从源码构建

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
git config core.hooksPath scripts/hooks  # 激活 pre-commit 安全检查
scripts/build.sh
# 输出: build/c/codebase-memory-mcp

前提条件：C 编译器 (gcc/clang)、make、zlib。

7. 怎么用

7.1 开发者日常工作流

步骤 1：安装并启动

安装后，重启你的 AI 编码 Agent（如 Claude Code）。Agent 自动连接到 MCP 服务器。

步骤 2：索引项目

直接对 Agent 说："Index this project"。

或者显式调用：

codebase-memory-mcp cli index_repository '{"path": "/path/to/project"}'

步骤 3：开始提问（例）

• "这个项目的整体架构是什么样的？" → Agent 调用 get_architecture
• "ProcessOrder 函数被谁调用？调用链是什么？" → Agent 调用 trace_path / trace_call_path
• "有没有从未被调用的函数？" → Agent 用 Cypher 做死代码检测
• "修改 auth.go 会影响哪些模块？" → Agent 调用 detect_changes
• "找一下和 sendNotification 功能类似的函数" → Agent 用 semantic_query
• "列出所有 HTTP REST 端点" → Agent 用 search_graph(label="Route")

7.2 CLI 独立使用

也可以在终端直接使用 CLI 模式进行查询：

# 搜索函数
codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*"}'

# Cypher 查询
codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = \"main\" RETURN g.name"}'

# 获取架构
codebase-memory-mcp cli get_architecture '{}'

7.3 团队共享工作流

# 开发者 A：索引后导出团队共享工件
# （索引时自动生成 .codebase-memory/graph.db.zst）

# 提交到仓库
git add .codebase-memory/graph.db.zst .gitattributes
git commit -m "更新代码知识图谱工件"

# 开发者 B：clone 后直接使用
# codebase-memory-mcp 检测到 graph.db.zst → 解压导入 → 仅跑增量索引

8. 售前可以怎么讲

8.1 核心价值主张（Elevator Pitch）

"您的开发团队在用 AI Agent 辅助编程时，是不是发现 Agent 面对大代码库经常'迷路'？频繁读文件、反复 grep，Token 消耗惊人，回答质量却不稳定？Codebase Memory MCP 用 3 分钟为您的代码库构建一张知识图谱，之后所有的代码结构查询都能在毫秒级完成，Token 消耗降低 99%。它是一个 35MB 的静态二进制文件，无需 Docker、不需要 API Key、代码从不离开您的机器——装完就能用。"

8.2 客户沟通话术（按角色）

对 CTO / 技术 VP：

• "这是一项基础设施投资，不是又一个工具。它让你们的 AI 编码 Agent 从'盲人摸象'变成'鸟瞰全局'，直接提升研发效能。"
• "MIT 开源，零供应商锁定。由德国团队维护，有学术论文和 SLSA Level 3 构建证明。"
• "已经在 Linux 内核（2800 万行代码）上验证通过，你们的代码库不会比它更大。"

对架构师：

• "Leiden 社区检测算法能自动发现代码库中的功能模块边界，帮助验证或纠偏你们现有的架构划分。"
• "支持跨服务 HTTP/gRPC 路由自动匹配和跨仓库依赖分析，微服务治理利器。"
• "支持 ADR（架构决策记录）管理，能在 AI 会话间持久化架构知识。"

对安全 / 合规负责人：

• "100% 本地处理，代码绝不离开你的机器。不需要任何外部 API。"
• "每个 Release 都经过 70+ 杀毒引擎扫描，SHA-256 签名校验。"
• "有专门的 SECURITY.md 和负责任披露流程。"

对开发者 Team Lead：

• "新人上手大项目的时间可以从几周缩短到几天——让 AI Agent 直接'理解'整个代码结构再回答问题。"
• "Git 变更→受影响符号自动映射，Pre-commit 或 CI 中就能做变更影响分析。"
• "支持 11 款主流 AI Agent，你的团队用哪个都行。"

8.3 横向对比优势

8.4 ROI 计算思路

假设一个 10 人开发团队：

• 每人每天问 AI Agent 20 个代码相关的问题
• 使用 grep/file-read 方式，每个问题平均消耗 4000 tokens → 每天 80 万 tokens
• 使用 Codebase Memory MCP，平均 170 tokens/问题 → 每天 3.4 万 tokens
• Token 节省 95.8%，按 Claude Sonnet 定价约 $3/M input tokens，每天节省约 $2.3，每年 ~$580/人
• 更重要的是回答质量提升和开发者时间节省——减少 Agent 因上下文不足而产生的错误回答和跟进成本

9. 常见客户问题

Q1：数据安全吗？代码会上传到外部吗？

A：绝对安全。所有处理 100% 在本地完成。代码从未离开你的机器。内置的语义搜索使用编译进二进制的 Nomic embedding 模型，不需要任何外部 API。每个 Release 都经过 70+ 杀毒引擎扫描和 SHA-256 签名。

Q2：索引需要多少时间？对开发体验有影响吗？

A：中小型项目（如 Django）约 6 秒；大型项目（Linux kernel 2800 万行）约 3 分钟。索引完成后内存释放回操作系统。后续文件变更通过后台监控自动增量索引，几乎无感。也可以启用自动索引，首次连接时自动触发。

Q3：和 VS Code / IntelliJ 的 "Go to Definition" 有什么不同？

A：IDE 的代码导航基于单文件/单语言的 LSP，主要服务于"人在编辑器里的跳转"。Codebase Memory MCP 构建的是跨文件、跨语言的全局知识图谱，专门为 AI Agent 的语义理解服务——Agent 可以一次性查询"这个函数的完整调用链"、"所有 HTTP 端点列表"、"与这个模块相似的代码"，而不需要几十次逐文件跳转。

Q4：支持的 158 种语言质量都一样吗？

A：高质量 Tier 1（≥90%，17 种语言）包括 C/C++、Kotlin、Lua、Groovy、Swift、Zig 等。Tier 2（75-89%，16 种）包括 Python、TypeScript、Go、Rust、Java、PHP、C# 等主流语言。其中 9 种语言有 Hybrid LSP 深度类型解析。Haskell 和 OCaml 目前为 Tier 3（<75%），但仍在持续改进。

Q5：能同时索引多个仓库吗？能跨仓库做分析吗？

A：可以。同一个 SQLite 存储可以容纳多个已索引仓库。通过 CROSS_* 边链接跨仓库节点。3D 可视化 UI 也支持多 galaxy 布局展示跨仓库架构。

Q6：费用如何？

A：MIT 开源，完全免费。没有企业版，没有 SaaS 订阅费用。唯一的"成本"是安装和索引时的计算资源（CPU + 内存）。

Q7：需要什么权限？

A：读取你的代码库（构建索引），写入 Agent 配置文件（安装时自动配置 MCP 条目）。不需要网络访问，不需要 sudo。

Q8：如何更新？

A：codebase-memory-mcp update 一键完成。服务器启动时也会自动检查更新。

10. PoC 建议

10.1 PoC 目标

验证 Codebase Memory MCP 在客户真实代码库上的（1）索引速度、（2）查询准确率、（3）与现有 AI Agent 的集成体验、（4）Token 节省效果。

10.2 PoC 方案（建议 1-2 周）

第 1 阶段：准备与环境搭建（1 天）

1. 选择一个有代表性的代码仓库（建议：多语言、> 1000 文件、有微服务或模块化结构，例如客户的核心业务仓库）
2. 在开发者机器上安装 Codebase Memory MCP（与客户已有的 AI Agent 集成）
3. 运行首次全量索引，记录索引时间、节点数、边数

第 2 阶段：功能验证（2-3 天）

准备一个问题集（10-15 个问题），涵盖：

• D1（定义/API 发现）："列出所有 REST API 端点" / "项目入口点在哪？"
• D2（关系/调用图）："下单流程的完整调用链？" / "auth 模块依赖哪些包？"
• D3（精准检索）："找到 PaymentService.process 的实现"
• D4（架构/结构）："这个项目的分层架构是怎样的？有哪些核心模块？"
• D5（交叉/语义）："有没有和 sendEmail 功能类似但名字不同的函数？"

分别用两种方式回答同一组问题：

• 对照组：纯 AI Agent（grep/read/Glob 方式）
• 实验组：AI Agent + Codebase Memory MCP

对比记录：

• Token 消耗量
• 回答准确率（人工评分 1-5）
• 回答时间
• 工具调用次数

第 3 阶段：深度场景验证（2-3 天）

根据客户实际痛点选择 2-3 个深度场景：

• 如果是微服务治理 → 验证 get_architecture + HTTP 路由匹配 + 跨服务调用链
• 如果是遗留系统维护 → 验证死代码检测 + 调用链追踪 + 影响分析（detect_changes）
• 如果是多仓库管理 → 验证跨仓库 CROSS_* 边 + 多仓库架构视图
• 如果是团队协作 → 验证 .codebase-memory/graph.db.zst 工件共享流程

第 4 阶段：总结报告（1 天）

输出 PoC 报告，包含：

• 索引性能指标
• 问题回答准确率对比
• Token 节省比例
• 开发者体验反馈
• 推荐的团队推广路径

10.3 PoC 成功标准

10.4 PoC 注意事项

1. 第一次索引需要一些时间：做好预期管理，强调"一次索引，长期受益"
2. 动态语言的效果略低于静态语言：Python/JS/PHP 的调用图精度取决于 Hybrid LSP 的类型推断，建议在 PoC 中也包含 Go/TypeScript/Java 等静态语言的仓库
3. 大仓索引内存：Linux kernel 级别索引约需数 GB 内存，确保 PoC 机器内存充裕（建议 16GB+）
4. 不替代代码审查：图分析是辅助，不应作为安全/质量的唯一依据
5. 文件监控开销：后台 git 监控在 Windows 上的性能需要额外关注

11. 风险和注意事项

11.1 技术风险

11.2 商业/生态风险

11.3 安全风险

• 代码数据安全：已确认 100% 本地处理，代码不离开机器 ✅
• 二进制供应链安全：SLSA Level 3 构建证明 + SHA-256 签名 + VirusTotal 扫描 ✅
• 图工件 graph.db.zst 提交到仓库：包含代码结构信息（函数名、调用关系），但不包含源码内容；敏感代码库可配置 .gitignore 不提交
• Graph UI：仅绑定 127.0.0.1，不对外暴露 ✅

12. 我的售前判断

12.1 整体评估：★★★★★ 强烈推荐

Codebase Memory MCP 是一个真正的差异化产品。它不是又一个"AI + 代码"的浅层包装，而是在 AI Agent 基础设施层解决了一个真实且普遍的痛点：AI Agent 面对大型代码库时的上下文爆炸和结构感知缺失。它在三个维度上做到了极致：

1. 性能极致：纯 C 编写 + RAM-first 流水线 + LZ4 压缩 → Linux 内核 3 分钟索引
2. 简单极致：单二进制文件、零依赖、一条 curl 命令安装
3. 开放极致：MIT 开源、MCP 标准协议、支持 11 款 Agent、158 种语言

12.2 谁应该立刻尝试？

• 所有正在使用 AI 编码 Agent 的团队：这是目前已知最有效的"Agent 代码理解加速器"
• 管理大型代码库（> 1000 文件）的团队：收益与代码库规模成正比
• 多语言/多服务架构团队：跨语言、跨服务的全局知识图谱是单语言 LSP 无法提供的
• 对安全性和数据隐私有严格要求的组织：全本地处理是核心卖点

12.3 谁需要再观望？

• 代码库极小（< 100 文件）的团队：直接让 Agent 读文件可能更简单
• 不使用 AI 编码 Agent 的团队：传统 IDE 导航已足够
• 主要使用 Haskell/OCaml 等 Tier 3 语言的团队：解析质量有待提升
• 需要商业 SLA 支持的客户：纯社区驱动的 MIT 项目，无官方商业支持

12.4 竞争格局

当前市场上类似项目（如 graphify、Sourcegraph Cody、GitNexus 等）在开源度、部署复杂度、语言覆盖广度上均不及 Codebase Memory MCP。该项目在 README 中已移除与 GitNexus 的对比表格，表明其对自身竞争力有足够信心。

12.5 售前行动建议

1. 优先级 1：向所有有 AI 编码 Agent 使用场景的客户推荐 PoC（成本极低，一条命令即可开始）
2. 优先级 2：制作中文化的使用指南和最佳实践文档，降低中国客户的使用门槛
3. 优先级 3：收集 PoC 数据，建立中国客户案例库（Token 节省、索引性能等真实数据）
4. 优先级 4：关注项目 Roadmap，特别是更多语言的 Hybrid LSP 支持和 CI/CD 集成能力

13. 参考资料

• GitHub 仓库
• 项目官网
• 学术论文 — arXiv:2603.27277
• Benchmark 详细报告
• 评测计划 (159 种语言)
• 安全披露流程
• 贡献指南
• Release 页面 (v0.8.1)
• MCP 官方 Registry 条目
• AUR 包
• MCP 协议规范: Model Context Protocol
• Tree-sitter: tree-sitter.github.io