DeusData/codebase-memory-mcp

# codebase-memory-mcp [](https://github.com/DeusData/codebase-memory-mcp/releases/latest) [](LICENSE) [](https://github.com/DeusData/codebase-memory-mcp/actions/workflows/dry-run.yml) [](https://github.com/DeusData/codebase-memory-mcp) [](https://github.com/DeusData/codebase-memory-mcp) [](https://github.com/DeusData/codebase-memory-mcp) [](https://github.com/DeusData/codebase-memory-mcp) [](https://github.com/DeusData/codebase-memory-mcp/releases/latest) [](https://scorecard.dev/viewer/?uri=github.com/DeusData/codebase-memory-mcp) [](https://slsa.dev) [](https://www.virustotal.com/gui/file/dcbe9a951a2b1f7ec6d003edce2f38b586f74bf8cf98faeedec36f1dd3444b06/detection) [](https://arxiv.org/abs/2603.27277) **速度最快、效率最高的 AI 编码智能体代码理解引擎**。平均对仓库建立完整索引仅需毫秒级，Linux 内核（28M 行代码，75K 个文件）在 3 分钟内完成。结构化查询响应时间低于 1ms。提供适用于 macOS、Linux 和 Windows 的单一静态二进制文件——下载，运行 `install`，完成。 通过 [tree-sitter](https://tree-sitter.github.io/tree-sitter/) AST 分析对所有 66 种语言进行高质量解析，附带 LSP 风格的混合类型解析能力（支持 Go、C、C++，更多语言即将支持）——生成包含函数、类、调用链、HTTP 路由和跨服务引用的持久化知识图谱。内置 14 个 MCP 工具，零依赖。可即插即用于 10 种编码智能体。

Built-in 3D graph visualization (UI variant) — explore your knowledge graph at localhost:9749

## 为何选择 codebase-memory-mcp - **极速索引**——Linux 内核（28M 行代码，75K 个文件）仅需 3 分钟。内存优先流水线：LZ4 压缩、内存内 SQLite、融合的 Aho-Corasick 模式匹配。索引完成后释放内存。 - **即插即用**——适用于 macOS（arm64/amd64）、Linux（arm64/amd64）和 Windows（amd64）的单一静态二进制文件。无需 Docker、无运行时依赖、无 API 密钥。下载 → `install` → 重启智能体 → 完成。 - **66 种语言**——内置于二进制文件中的 tree-sitter 语法分析器。无需安装，开箱即用。 - **令牌量减少 120 倍**——5 个结构化查询：约 3,400 个令牌，相比逐文件搜索的约 412,000 个令牌，减少约 99.2%。一个图查询可替代数十次 grep/读取循环。 - **11 个智能体，一条命令**——`install` 自动检测 Claude Code、Codex CLI、Gemini CLI、Zed、OpenCode、Antigravity、Aider、KiloCode、VS Code、OpenClaw 和 Kiro，并为每个配置 MCP 条目、指令文件和预工具钩子。 - **内置图可视化**——`localhost:9749` 上的 3D 交互式 UI（可选 UI 二进制变体）。 - **基础设施即代码索引**——Dockerfile、Kubernetes 清单和 Kustomize 覆盖层被作为图节点进行索引，并带有交叉引用。`Resource` 节点表示 K8s 类型，`Module` 节点表示 Kustomize 覆盖层，并通过 `IMPORTS` 边引用相关资源。 - **14 个 MCP 工具**——搜索、追踪、架构、影响分析、Cypher 查询、死代码检测、跨服务 HTTP 链接、ADR 管理等。 ## 快速开始 **一键安装**（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 ``` **Windows**（PowerShell）： ``` # 1. 下载安装程序 Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1 # 2. （可选但推荐）检查脚本 notepad install.ps1 # 3. 运行它 .\install.ps1 ``` 选项：`--ui`（图可视化）、`--skip-config`（仅二进制，不配置智能体）、`--dir=`（自定义路径）。 重启你的智能体。说 **“索引此项目”** —— 完成。

手动安装

1. **下载**适用于你平台架构的最新发布包：[最新版本](https://github.com/DeusData/codebase-memory-mcp/releases/latest)： - `codebase-memory-mcp--.tar.gz`（macOS/Linux）或 `.zip`（Windows）——标准版 - `codebase-memory-mcp-ui--.tar.gz` / `.zip` —— 包含图可视化 2. **解压并安装**（每个归档包均包含 `install.sh` 或 `install.ps1`）： macOS / Linux： tar xzf codebase-memory-mcp-*.tar.gz ./install.sh Windows（PowerShell）： Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath . .\install.ps1 3. **重启**你的智能体。 `install` 命令会自动移除 macOS 的 quarantine 属性并为二进制文件附加 ad-hoc 签名——无需手动执行 `xattr` 或 `codesign`。

`install` 命令会自动检测所有已安装智能体，并为每个智能体配置 MCP 服务器条目、指令文件、技能以及预工具钩子。 ### 图可视化 UI 如果你下载了 `ui` 变体： ``` codebase-memory-mcp --ui=true --port=9749 ``` 在浏览器中打开 `http://localhost:9749`。UI 会在 MCP 服务器旁以后台线程运行——只要智能体保持连接即可使用。 ### 自动索引 启用 MCP 会话启动时的自动索引： ``` codebase-memory-mcp config set auto_index true ``` 启用后，新项目将在首次连接时自动索引。已索引项目会通过后台监听器注册以进行持续的 git 变更检测。可配置文件限制：`config set auto_index_limit 50000`。 ### 保持更新 ``` codebase-memory-mcp update ``` MCP 服务器在启动时也会检查更新，并在首次调用工具时通知是否有新版本可用。 ### 卸载 ``` codebase-memory-mcp uninstall ``` 移除所有智能体配置、技能、钩子和指令。不会移除二进制文件或 SQLite 数据库。 ## 功能特性 - **架构概览**：`get_architecture` 在一次调用中返回语言、包、入口点、路由、热点、边界、层级和集群。 - **架构决策记录**：`manage_adr` 持久化架构决策以便跨会话使用。 - **Louvain 社区发现**：通过聚类调用边识别功能模块。 - **Git 差异影响映射**：`detect_changes` 将未提交的变更映射到受影响的符号并进行风险分类。 - **调用图**：解析跨文件和跨包的函数调用（支持导入感知和类型推断）。 - **跨服务 HTTP 链接**：发现 REST 路由并与 HTTP 调用站点匹配，附带置信度评分。 - **自动同步**：后台监听器检测文件变更并自动重新索引。 - **类似 Cypher 的查询**：`MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name` - **死代码检测**：查找无调用者的函数，排除入口点。 - **路由节点**：REST 端点是图中的第一类实体。 - **CLI 模式**：`codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*"}'` - **单一二进制，零基础设施**——基于 SQLite，持久化存储于 `~/.cache/codebase-memory-mcp/`。 ## 工作原理 codebase-memory-mcp 是一个 **结构化分析后端**它构建并查询知识图谱。它 **不** 包含大语言模型（LLM）。相反，它依赖你的 MCP 智能体（Claude Code 或任何 MCP 兼容智能体）作为查询翻译的智能层。 ``` You: "what calls ProcessOrder?" Agent calls: trace_call_path(function_name="ProcessOrder", direction="inbound") codebase-memory-mcp: executes graph query, returns structured results Agent: presents the call chain in plain English ``` **为何不内置 LLM？** 其他代码图谱工具通过嵌入 LLM 来实现自然语言到图谱查询的翻译。这意味着需要额外的 API 密钥、额外成本以及另一个需要配置的模型。通过 MCP，你正在使用的智能体本身就是查询翻译器。 ## 性能 在 Apple M3 Pro 上进行基准测试： | 操作 | 耗时 | 说明 | |------|------|------| | **Linux 内核完整索引** | **3 分钟** | 28M 行代码，75K 个文件 → 210 万节点，490 万边 | | Linux 内核快速索引 | 1 分 12 秒 | 188 万节点 | | Django 完整索引 | ~6 秒 | 4.9 万节点，19.6 万边 | | Cypher 查询 | <1 毫秒 | 关系遍历 | | 名称搜索（正则） | <10 毫秒 | SQL LIKE 预过滤 | | 死代码检测 | ~150 毫秒 | 全图扫描与度过滤 | | 调用路径跟踪（深度=5） | <10 毫秒 | BFS 遍历 | **内存优先流水线**：所有索引在内存中运行（读取时 LZ4 高压缩、内存内 SQLite、最后一次性转储）。索引完成后将内存释放回操作系统。 **令牌效率**：五个结构化查询通过 codebase-memory-mcp 消耗约 3,400 个令牌，而通过逐文件 grep 探索消耗约 412,000 个令牌——**减少 99.2%**。 ## 安装 ### 预编译二进制文件 | 平台 | 标准版 | 含图可视化版 | |------|--------|--------------| | macOS（Apple Silicon） | `codebase-memory-mcp-darwin-arm64.tar.gz` | `codebase-memory-mcp-ui-darwin-arm64.tar.gz` | | macOS（Intel） | `codebase-memory-mcp-darwin-amd64.tar.gz` | `codebase-memory-mcp-ui-darwin-amd64.tar.gz` | | Linux（x86_64） | `codebase-memory-mcp-linux-amd64.tar.gz` | `codebase-memory-mcp-ui-linux-amd64.tar.gz` | | Linux（ARM64） | `codebase-memory-mcp-linux-arm64.tar.gz` | `codebase-memory-mcp-ui-linux-arm64.tar.gz` | | Windows（x86_64） | `codebase-memory-mcp-windows-amd64.zip` | `codebase-memory-mcp-ui-windows-amd64.zip` | 每个版本均包含 `checksums.txt`，提供 SHA-256 哈希值。所有二进制文件均为静态链接，无共享库依赖。 ### 安装脚本

自动下载并安装

**macOS / Linux：** ``` curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup.sh | bash ``` **Windows（PowerShell）：** ``` irm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 | iex ```

### 通过 Claude Code 安装 ``` You: "Install this MCP server: https://github.com/DeusData/codebase-memory-mcp" ``` ### 从源码构建

前提条件：C 编译器 + zlib

| 要求 | 检查 | 安装 | |------|------|------| | **C 编译器**（gcc 或 clang） | `gcc --version` 或 `clang --version` | macOS：`xcode-select --install`，Linux：`apt install build-essential` | | **C++ 编译器** | `g++ --version` 或 `clang++ --version` | 同上 | | **zlib** | — | macOS：已包含，Linux：`apt install zlib1g-dev` | | **Git** | `git --version` | 大多数系统已预装 |

``` git clone https://github.com/DeusData/codebase-memory-mcp.git cd codebase-memory-mcp scripts/build.sh # standard binary scripts/build.sh --with-ui # with graph visualization # Binary at: build/c/codebase-memory-mcp ``` ### 手动 MCP 配置

如果你不想使用安装命令

添加到 `~/.claude/.mcp.json`（全局）或项目 `.mcp.json`： ``` { "mcpServers": { "codebase-memory-mcp": { "command": "/path/to/codebase-memory-mcp", "args": [] } } } ``` 重启你的智能体。通过 `/mcp` 验证——应看到 `codebase-memory-mcp` 及其 14 个工具。

## 多智能体支持 `install` 会自动检测并配置所有已安装的智能体： | 智能体 | MCP 配置 | 指令 | 钩子 | |--------|----------|------|------| | Claude Code | `.claude/.mcp.json` | 4 个技能 | PreToolUse（Grep/Glob/Read 提醒） | | Codex CLI | `.codex/config.toml` | `.codex/AGENTS.md` | — | | Gemini CLI | `.gemini/settings.json` | `.gemini/GEMINI.md` | BeforeTool（grep/read 提醒） | | Zed | `settings.json`（JSONC） | — | — | | OpenCode | `opencode.json` | `AGENTS.md` | — | | Antigravity | `mcp_config.json` | `AGENTS.md` | — | | Aider | — | `CONVENTIONS.md` | — | | KiloCode | `mcp_settings.json` | `~/.kilocode/rules/` | — | | VS Code | `Code/User/mcp.json` | — | — | | OpenClaw | `openclaw.json` | — | — | | Kiro | `.kiro/settings/mcp.json` | — | — | **钩子** 是建议性质（退出码 0）——它们提醒智能体在调用 grep/glob/read 时优先使用 MCP 图工具，但不会阻塞工具调用。 ## CLI 模式 每个 MCP 工具均可通过命令行调用： ``` 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_call_path '{"function_name": "Search", "direction": "both"}' codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}' codebase-memory-mcp cli list_projects codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.results[].name' ``` ## MCP 工具 ### 索引 | 工具 | 描述 | |------|------| | `index_repository` | 将仓库索引到图谱中。自动同步会持续更新。 | | `list_projects` | 列出所有已索引的项目及其节点/边数量。 | | `delete_project` | 删除项目及其所有图谱数据。 | | `index_status` | 检查项目的索引状态。 | ### 查询 | 工具 | 描述 | |------|------| | `search_graph` | 按标签、名称模式、文件模式、度过滤进行结构化搜索。支持分页（limit/offset）。 | | `trace_call_path` | 广度优先遍历——谁调用某函数及其调用链。深度 1-5。 | | `detect_changes` | 将 Git 差异映射到受影响的符号及影响范围，并附带风险分类。 | | `query_graph` | 执行类似 Cypher 的只读图查询。 | | `get_graph_schema` | 获取节点/边数量、关系模式及属性定义。首次运行建议执行此命令。 | | `get_code_snippet` | 通过限定名读取函数源代码。 | | `get_architecture` | 代码库概览：语言、包、路由、热点、集群、ADR。 | | `search_code` | 在已索引项目文件中执行类似 grep 的文本搜索。 | | `manage_adr` | 架构决策记录的增删改查。 | | `ingest_traces` | 摄入运行时追踪以验证 HTTP_CALLS 边。 | ## 图数据模型 ### 节点标签 `Project`、`Package`、`Folder`、`File`、`Module`、`Class`、`Function`、`Method`、`Interface`、`Enum`、`Type`、`Route`、`Resource` ### 边类型 `CONTAINS_PACKAGE`、`CONTAINS_FOLDER`、`CONTAINS_FILE`、`DEFINES`、`DEFINES_METHOD`、`IMPORTS`、`CALLS`、`HTTP_CALLS`、`ASYNC_CALLS`、`IMPLEMENTS`、`HANDLES`、`USAGE`、`CONFIGURES`、`WRITES`、`MEMBER_OF`、`TESTS`、`USES_TYPE`、`FILE_CHANGES_WITH` ### 限定名 `get_code_snippet` 使用名：`..`。请先使用 `search_graph` 查找。 ### 支持的 Cypher 子集 `query_graph` 支持：`MATCH`（带标签和关系类型）、可变长度路径、`WHERE`（比较/正则/CONTAINS）、`RETURN`（属性访问及 `COUNT`/`DISTINCT`）、`ORDER BY`、`LIMIT`。不支持：`WITH`、`COLLECT`、`OPTIONAL MATCH`、变更操作。 ## 忽略文件 分层机制：硬编码模式（`.git`、`node_modules` 等）→ `.gitignore` 层级 → `.cbmignore`（项目级，gitignore 语法）。始终跳过符号链接。 ## 配置 ``` codebase-memory-mcp config list # show all settings codebase-memory-mcp config set auto_index true # auto-index on session start codebase-memory-mcp config set auto_index_limit 50000 # max files for auto-index codebase-memory-mcp config reset auto_index # reset to default ``` ### 环境变量 | 变量 | 默认值 | 描述 | |------|--------|------| | `CBM_CACHE_DIR` | `~/.cache/codebase-memory-mcp` | 覆盖数据库存储目录。所有项目索引和配置均存储于此。 | | `CBM_DIAGNOSTICS` | `false` | 设为 `1` 或 `true` 以启用周期性诊断输出到 `/tmp/cbm-diagnostics-.json`。 | | `CBM_DOWNLOAD_URL` | *(GitHub 发布版)* | 覆盖更新下载 URL。用于测试或自托管部署。 | ``` # Store indexes in a custom directory export CBM_CACHE_DIR=~/my-projects/cbm-data ``` ### 自定义文件扩展名 通过 JSON 配置文件将额外文件扩展名映射到支持的语言。对框架特定扩展（如 `.blade.php`（Laravel）或 `.mjs`（ES 模块））非常有用。 **项目级**（在仓库根目录）： ``` // .codebase-memory.json {"extra_extensions": {".blade.php": "php", ".mjs": "javascript"}} ``` **全局级**（适用于所有项目）： ``` // ~/.config/codebase-memory-mcp/config.json (or $XDG_CONFIG_HOME/...) {"extra_extensions": {".twig": "html", ".phtml": "php"}} ``` 项目配置会覆盖全局配置中的冲突扩展。未知语言值将被静默跳过。缺失的配置文件会被忽略。 ## 持久化 SQLite 数据库存储在 `~/.cache/codebase-memory-mcp/` 中。跨重启持久化（WAL 模式，ACID 安全）。重置方法：`rm -rf ~/.cache/codebase-memory-mcp/`。 ## 故障排查 | 问题 | 解决方案 | |------|----------| | `/mcp` 未显示服务端 | 检查 `.mcp.json` 路径是否为绝对路径。重启智能体。测试：`echo '{}' \| /path/to/binary` 应输出 JSON。 | | `index_repository` 失败 | 传入绝对路径：`index_repository(repo_path="/absolute/path")` | | `trace_call_path` 返回 0 结果 | 先使用 `search_graph(name_pattern=".*PartialName.*")` 查找确切名称。 | | 查询返回错误的项目结果 | 添加 `project="name"` 参数。使用 `list_projects` 查看项目名称。 | | 安装后找不到二进制文件 | 添加到 PATH：`export PATH="$HOME/.local/bin:$PATH"` | | UI 无法加载 | 确保下载了 `ui` 变体并运行了 `--ui=true`。检查 `http://localhost:9749`。 | ## 语言支持 66 种语言。在 64 个真实开源仓库（78 到 49K 个节点）上进行基准测试： | 等级 | 评分 | 语言 | |------|------|------| | **优秀**（≥ 90%） | | Lua、Kotlin、C++、Perl、Objective-C、Groovy、C、Bash、Zig、Swift、CSS、YAML、TOML、HTML、SCSS、HCL、Dockerfile | | **良好**（75-89%） | | Python、TypeScript、TSX、Go、Rust、Java、R、Dart、JavaScript、Erlang、Elixir、Scala、Ruby、PHP、C#、SQL | | **功能性**（< 75%） | | OCaml、Haskell | 此外支持：Clojure、F#、Julia、Vim Script、Nix、Common Lisp、Elm、Fortran、CUDA、COBOL、Verilog、Emacs Lisp、MATLAB、Lean 4、FORM、Magma、Wolfram、JSON、XML、Markdown、Makefile、CMake、Protobuf、GraphQL、Vue、Svelte、Meson、GLSL、INI。 ## 架构 ``` src/ main.c Entry point (MCP stdio server + CLI + install/update/config) mcp/ MCP server (14 tools, JSON-RPC 2.0, session detection, auto-index) cli/ Install/uninstall/update/config (10 agents, hooks, instructions) store/ SQLite graph storage (nodes, edges, traversal, search, Louvain) pipeline/ Multi-pass indexing (structure → definitions → calls → HTTP links → config → tests) cypher/ Cypher query lexer, parser, planner, executor discover/ File discovery (.gitignore, .cbmignore, symlink handling) watcher/ Background auto-sync (git polling, adaptive intervals) traces/ Runtime trace ingestion ui/ Embedded HTTP server + 3D graph visualization foundation/ Platform abstractions (threads, filesystem, logging, memory) internal/cbm/ Vendored tree-sitter grammars (66 languages) + AST extraction engine ``` ## 安全 每个发布二进制文件均通过多阶段流水线验证后才发布： - **VirusTotal**——所有二进制文件经 70+ 款杀毒引擎扫描（要求零检测才能发布） - **SLSA Level 3**——通过 GitHub Actions 生成加密构建证明；可使用 `gh attestation verify --repo DeusData/codebase-memory-mcp` 验证 - **Sigstore cosign**——所有工件均有关键签名；每个发布包都包含签名 - **SHA-256 校验和**——每个版本附带 `checksums.txt`，安装脚本在解压前验证 - **CodeQL SAST**——若存在开放警报则阻断发布流水线 - **零运行时依赖**——无传递依赖；所有库在编译时静态包含 ### v0.6.0 VirusTotal 扫描结果 | 二进制文件 | SHA-256 | VirusTotal | |------------|---------|-----------| | `linux-amd64` | `dcbe9a951a2b1f7ec6d0...` | [0/72 ✅](https://www.virustotal.com/gui/file/dcbe9a951a2b1f7ec6d003edce2f38b586f74bf8cf98faeedec36f1dd3444b06/detection) | | `linux-arm64` | `3dc702d2ff2b5a7e9094...` | [0/72 ✅](https://www.virustotal.com/gui/file/3dc702d2ff2b5a7e909409337a8a24ba3f724e7e47d6b159b3c9dedf70117fe2/detection) | | `darwin-arm64` | `61d543c9c795471702...` | [0/72 ✅](https://www.virustotal.com/gui/file/61d543c9c79547170296badddcdfe117b145471361d86606c7094d41aea2644f/detection) | | `darwin-amd64` | `eea862d705ac9b44a7bd...` | [0/72 ✅](https://www.virustotal.com/gui/file/eea862d705ac9b44a7bd595bfcd1c5c36aa3409ae6e7f0a2454308024c205e40/detection) | | `windows-amd64` | `dd828ee0d790f9d81c9b...` | [0/72 ✅](https://www.virustotal.com/gui/file/dd828ee0d790f9d81c9bde348db8d5681d624f786bba0e1b5e6c9409534c7a28/detection) | 每个发布的扫描链接也会自动包含在 GitHub 发布说明中。 ## 许可证 MIT

标签：AI编码助手, LLM工具, MCP服务器, SLSA, 代码分析, 代码导航, 代码搜索, 代码智能, 代码理解, 代码索引, 代码记忆, 代码语义, 令牌压缩, 凭证管理, 大模型工具链, 子毫秒查询, 客户端加密, 开源, 毫秒级索引, 零依赖, 静态二进制, 高性能查询