## 项目概述

codebase-memory-mcp 是一个高性能的代码智能 MCP（Model Context Protocol）服务器，由 DeusData 开发，采用纯 C 语言编写，遵循 MIT 许可证。它通过 tree-sitter 语法分析将代码库索引为持久化的知识图谱，平均仓库可在毫秒级完成索引，支持 158 种编程语言，查询响应时间低于 1 毫秒，并显著减少 AI 编码代理的 token 消耗（最高减少 99%）。该项目以单一静态二进制文件分发，无运行时依赖，支持 macOS、Linux 和 Windows 平台。

## 核心功能

- **极速索引**：Linux 内核（2800 万行代码，7.5 万文件）完整索引仅需 3 分钟，采用 RAM 优先流水线（LZ4 压缩、内存 SQLite、Aho-Corasick 模式匹配）。
- **知识图谱构建**：生成包含函数、类、调用链、HTTP 路由、跨服务链接的持久化知识图谱，支持 15 种 MCP 工具。
- **多语言支持**：内置 158 种 tree-sitter 语法，并通过 Hybrid LSP 语义类型解析增强 Python、TypeScript、Go、Rust 等 12 种语言的调用解析精度。
- **语义搜索**：内置 Nomic 嵌入模型（nomic-embed-code），无需 API 密钥，支持 11 信号组合评分。
- **跨服务链接**：支持 HTTP、gRPC、GraphQL、tRPC 路由检测，以及 Socket.IO、EventEmitter 等通道检测。
- **团队共享图谱**：支持将压缩的知识图谱快照（`.codebase-memory/graph.db.zst`）提交到仓库，队友克隆后无需重新索引。
- **内置 3D 图可视化 UI**：通过 `localhost:9749` 访问，由共享协调守护进程管理。
- **多代理支持**：自动配置 43 种客户端表面（如 Claude Code、Codex、Gemini CLI 等），并安装技能、钩子和指令。
- **CLI 模式**：所有 MCP 工具均可作为本地一次性命令调用，不启动守护进程。

## 适用与不适用场景

**适用场景：**
- AI 编码代理（如 Claude Code、Codex、Cursor 等）需要快速理解大型代码库结构。
- 开发者需要跨文件、跨包追踪函数调用链、查找死代码、分析架构。
- 团队希望共享代码知识图谱，减少重复索引成本。
- 需要本地化、隐私安全的代码分析，代码不离开机器。

**不适用场景：**
- 需要自然语言到图查询的自动翻译（项目本身不包含 LLM，依赖 MCP 客户端）。
- 对非结构化文本或二进制文件的深度语义理解。
- 需要实时、动态的代码行为分析（如运行时性能剖析）。
- 不支持的语言（如某些小众语言）可能解析不完整。

## 技术架构与依赖

- **语言**：纯 C（从 Go 重写，v0.5.0 起）。
- **核心组件**：tree-sitter（语法解析）、SQLite（图存储，WAL 模式）、LZ4（压缩）、Nomic 嵌入模型（语义搜索）、Cypher 查询子集解析器。
- **架构分层**：`src/` 包含主入口、守护进程、MCP 服务器、CLI、存储、流水线、Cypher、发现、监视器、UI 等模块；`internal/cbm/` 包含语言注册表和 AST 提取引擎。
- **依赖**：无运行时依赖，所有库（sqlite3、yyjson、mimalloc 等）在编译时 vendored。
- **平台**：macOS（arm64/amd64）、Linux（arm64/amd64）、Windows（amd64）。

## 安装与快速开始

**一键安装（macOS/Linux）：**
```bash
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
```

**Windows（PowerShell）：**
```powershell
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
Unblock-File .\install.ps1
.\install.ps1
```

安装后重启编码代理，然后说“Index this project”即可。也可通过包管理器安装（npm、PyPI、Homebrew、Scoop、Winget、Chocolatey、AUR、`go install`）。

## 典型使用方法

**索引仓库：**
```bash
codebase-memory-mcp cli index_repository --repo-path /path/to/repo
```

**查询图：**
```bash
codebase-memory-mcp cli search_graph --project my-project --name-pattern '.*Handler.*' --label Function
codebase-memory-mcp cli trace_path --project my-project --function-name Search --direction both
codebase-memory-mcp cli query_graph --project my-project --query 'MATCH (f:Function) RETURN f.name LIMIT 5'
```

**启用自动索引：**
```bash
codebase-memory-mcp config set auto_index true
```

**启动图可视化 UI：**
```bash
codebase-memory-mcp --ui=true --port=9749
```

## 配置与部署要点

- **环境变量**：`CBM_CACHE_DIR`（缓存目录）、`CBM_ALLOWED_ROOT`（限制索引根目录）、`CBM_LOG_LEVEL`（日志级别）、`CBM_WORKERS`（并行索引线程数）等。
- **配置文件**：全局配置位于 `~/.config/codebase-memory-mcp/config.json`，项目配置位于 `.codebase-memory.json`，支持自定义文件扩展名映射。
- **忽略文件**：支持 `.cbmignore`（gitignore 语法）和 `.gitignore` 分层过滤。
- **安全**：所有处理在本地进行，无遥测；发布版本经过 VirusTotal 扫描、SLSA 3 级签名、SHA-256 校验。
- **部署**：单二进制，无需 Docker 或语言运行时；支持离线环境。

## 限制、风险与许可证

- **限制**：不包含 LLM，依赖外部 MCP 客户端进行自然语言理解；部分语言（如 Haskell、OCaml）的调用追踪精度有限；Cypher 查询仅支持只读子集。
- **风险**：工具会读取代码库并写入代理配置文件，需审计后使用；Windows 上可能触发 Defender 误报（已知问题）；索引大型仓库可能消耗较多内存（但索引后释放）。
- **许可证**：MIT 许可证。

## 官方链接

- GitHub 仓库：https://github.com/DeusData/codebase-memory-mcp
- 最新发布：https://github.com/DeusData/codebase-memory-mcp/releases/latest
- 研究论文：https://arxiv.org/abs/2603.27277
- AUR 包：https://aur.archlinux.org/packages/codebase-memory-mcp-bin

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CONTRIBUTING.md、docs/BENCHMARK.md、docs/CONFIGURATION.md、docs/SECURITY-DISCLOSURE.md、docs/cbmignore.md。
- 分析时间：2026-08-10（基于最新发布 v0.10.0 日期）。