wehub/deusdata--codebase-memory-mcp

Fork 0

Files

T

wehub-resource-sync 938d2268fb

CodeQL SAST / analyze (push) Waiting to run

Details

OpenSSF Scorecard / scorecard (push) Waiting to run

Details

DCO / dco (push) Waiting to run

Details

docs: make Chinese README the default

2026-07-13 10:09:10 +00:00

41 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

codebase-memory-mcp

面向 AI 编程智能体（AI coding agents）的最快、最高效的代码智能引擎。 普通仓库可在毫秒级完成全量索引，Linux 内核（2800 万行代码、7.5 万个文件）仅需 3 分钟。结构查询响应时间低于 1 毫秒。以单一静态二进制形式发布，支持 macOS、Linux 和 Windows —— 下载、运行 install，即可使用。

通过 tree-sitter 实现高质量解析，覆盖全部 158 种语言的 AST 分析，并结合 Hybrid LSP 语义类型解析增强 Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin、Rust 和 Perl —— 生成函数、类、调用链、HTTP 路由和跨服务链接的持久化知识图谱。14 个 MCP 工具。零依赖。可在 11 种编程智能体中即插即用。

研究 — 本项目的设计与基准测试详见预印本 Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP (arXiv:2603.27277)。在 31 个真实仓库上评估：答案质量 83%，相比逐文件探索，token 用量减少 10 倍，工具调用减少 2.1 倍。

安全与信任 — 本工具会读取你的代码库并写入智能体配置文件，这正是其设计用途。若你希望在运行前进行审计，完整源码在此 —— 每个发布二进制均经过签名、校验和扫描（70+ 款杀毒引擎）。所有处理 100% 在本地完成；你的代码绝不会离开你的机器。发现安全问题？我们希望知晓 —— 请参阅 SECURITY.md。安全是我们的首要优先级（Priority #1）。

内置 3D 图谱可视化（UI 变体）—— 在 localhost:9749 探索你的知识图谱

为什么选择 codebase-memory-mcp

极致索引速度 — Linux 内核（2800 万行代码、7.5 万个文件）3 分钟完成。RAM 优先流水线：LZ4 压缩、内存 SQLite、融合 Aho-Corasick 模式匹配。索引完成后释放内存。
即插即用 — macOS（arm64/amd64）、Linux（arm64/amd64）和 Windows（amd64）单一静态二进制。无需 Docker、无运行时依赖、无需 API 密钥。下载 → install → 重启智能体 → 完成。
158 种语言 — 内置（vendored）tree-sitter 语法编译进二进制。无需安装，不会损坏。
token 用量减少 120 倍 — 5 次结构查询：约 3,400 个 token，而逐文件搜索约 412,000 个。一次图谱查询可替代数十轮 grep/read 循环。
11 种智能体，一条命令 — install 自动检测 Claude Code、Codex CLI、Gemini CLI、Zed、OpenCode、Antigravity、Aider、KiloCode、VS Code、OpenClaw 和 Kiro —— 为每种智能体配置 MCP 条目、指令文件和 pre-tool 钩子。
内置图谱可视化 — 在 localhost:9749 提供 3D 交互式 UI（可选 UI 二进制变体）。
基础设施即代码（Infrastructure-as-code）索引 — 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. Download the installer
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# 2. (Optional but recommended) Inspect the script
notepad install.ps1

# 3. Unblock the downloaded file (removes Mark-of-the-Web restriction added by browsers/Invoke-WebRequest)
Unblock-File .\install.ps1

# 4. Run it
.\install.ps1

注意： 若出现脚本执行策略错误，请先运行 Set-ExecutionPolicy -Scope Process Bypass，或使用 PowerShell -ExecutionPolicy Bypass -File .\install.ps1 调用。

选项：--ui（图谱可视化）、--skip-config（仅二进制，不配置智能体）、--dir=<path>（自定义安装位置）。

重启你的编程智能体。说 "Index this project" —— 完成。

手动安装

从最新发布版: 下载适合你平台的压缩包
- codebase-memory-mcp-<os>-<arch>.tar.gz（macOS/Linux）或 .zip（Windows）—— 标准版
- codebase-memory-mcp-ui-<os>-<arch>.tar.gz / .zip —— 含图谱可视化

解压并安装（每个压缩包均包含 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 .
Unblock-File .\install.ps1
.\install.ps1

重启你的编程智能体。

install 命令会自动清除 macOS 隔离属性并对二进制进行临时签名 —— 无需手动执行 xattr/codesign。

install 命令会自动检测所有已安装的编程智能体，并为每种智能体配置 MCP 服务器条目、指令文件、技能和 pre-tool 钩子。

图谱可视化 UI

UI 以独立的 ui 构建版本发布（内嵌前端）。各渠道默认安装的是精简的无头（headless）服务器；可通过以下方式选择 UI 构建版本：

install.sh： 添加 --ui（见快速开始）
npm： CBM_VARIANT=ui npm install -g codebase-memory-mcp
PyPI： CBM_VARIANT=ui pip install codebase-memory-mcp
手动： 下载 codebase-memory-mcp-ui-<os>-<arch> 压缩包

然后运行：

codebase-memory-mcp --ui=true --port=9749

在浏览器中打开 http://localhost:9749。UI 作为后台线程与 MCP 服务器并行运行 —— 只要智能体已连接即可使用。

自动索引

在 MCP 会话启动时启用自动索引：

codebase-memory-mcp config set auto_index true

启用后，新项目会在首次连接时自动建立索引。此前已索引的项目会注册到后台 watcher，以便持续进行基于 git 的变更检测。可配置文件数量上限：config set auto_index_limit 50000。

Watcher 注册由 auto_watch 单独控制（默认 true）。将 config set auto_watch false 设为可阻止会话将其项目注册到后台 watcher——在同时处理多个项目、且希望每个会话仅进行显式索引时很有用。

保持最新

codebase-memory-mcp update

MCP 服务器还会在启动时检查更新，并在首次工具调用时若有新版本可用则发出通知。

卸载

codebase-memory-mcp uninstall

会移除所有 agent 配置、skills、hooks 和 instructions。不会移除二进制文件或 SQLite 数据库。

功能

图与分析

架构概览：get_architecture 单次调用即可返回语言、包、入口点、路由、热点（hotspots）、边界、层级与聚类
架构决策记录（Architecture Decision Records）：manage_adr 在多个会话间持久化架构决策
Louvain 社区发现：通过对调用边聚类来发现功能模块
Git diff 影响映射：detect_changes 将未提交变更映射到受影响的符号，并进行风险分类
调用图（Call graph）：跨文件与包解析函数调用（感知 import、类型推断）
死代码检测：找出零调用者的函数，排除入口点
类 Cypher 查询：MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name

搜索

语义搜索（semantic_query）：在整个图上进行向量搜索，由内置的 Nomic nomic-embed-code 嵌入（40K tokens，768 维 int8）编译进二进制——无需 API key、无需 Ollama、无需 Docker。11 信号组合评分（TF-IDF、RRI、API/Type/Decorator 签名、AST 概要、数据流、Halstead-lite、MinHash、模块邻近度、图扩散）。
BM25 全文搜索：通过 SQLite FTS5，使用 cbm_camel_split 分词器（支持 camelCase / snake_case）
结构化搜索（search_graph）：正则名称模式、标签过滤、最小/最大度数、文件范围限定
代码搜索（search_code）：仅对已索引文件进行图增强 grep

跨服务链接

HTTP 路由 ↔ 调用点匹配，带置信度评分
gRPC、GraphQL、tRPC 服务检测，并提取 protobuf Route
通道检测（EMITS / LISTENS_ON）：支持 Socket.IO、EventEmitter 及通用 pub-sub 模式，覆盖 8 种语言，并进行常量解析

跨仓库智能

CROSS_* 边 将同一 store 下已索引的多个仓库中的节点相互链接
多星系 3D UI 布局，用于跨仓库架构可视化
跨仓库架构摘要，汇总已索引集群中的服务、路由与依赖

边类型（节选）

CALLS、IMPORTS、DEFINES、IMPLEMENTS、INHERITS
HTTP_CALLS、ASYNC_CALLS（跨服务）
EMITS、LISTENS_ON（通道）
DATA_FLOWS，含参数到形参映射 + 字段访问链
SIMILAR_TO（MinHash + LSH 近克隆检测，Jaccard 评分）
SEMANTICALLY_RELATED（词汇不匹配、同语言，score ≥ 0.80）

索引流水线

158 个 vendored tree-sitter 语法 编译进二进制
通用包 / 模块解析 —— 裸说明符如 @myorg/pkg、github.com/foo/bar、use my_crate::foo 通过清单扫描解析（package.json、go.mod、Cargo.toml、pyproject.toml、composer.json、pubspec.yaml、pom.xml、build.gradle、mix.exs、*.gemspec）
基础设施即代码（Infrastructure-as-code）索引 —— Dockerfile、Kubernetes manifest、Kustomize overlay 作为图节点
混合 LSP 语义类型解析，支持 Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin、Rust 与 Perl —— 语言类型解析算法的轻量 C 实现，在结构上受主流 language server 启发并与之兼容，包括 tsserver / typescript-go、pyright、gopls、Roslyn、Eclipse JDT 与 rust-analyzer（参数绑定、返回类型推断、泛型替换、JSX 组件派发、纯 JS 文件的 JSDoc 推断、PHP 的 namespace + trait + late-static-binding 解析、C# 的文件作用域 namespace + records + LINQ 方法语法、Java 的类层次 + 重载 + lambda 解析、Kotlin 的扩展函数 + 作用域函数解析、Rust 的 trait 方法 + UFCS 解析）
RAM 优先流水线：LZ4 压缩、内存 SQLite、结束时单次 dump。之后释放内存。

分发与运行

单一静态二进制，零基础设施：基于 SQLite，持久化到 ~/.cache/codebase-memory-mcp/
自动同步：后台 watcher 检测文件变更并自动重新索引
路由节点：REST 端点为一等图实体
CLI 模式：codebase-memory-mcp cli search_graph '{"project": "my-project", "name_pattern": ".*Handler.*"}'
可通过以下渠道获取：npm、PyPI、Homebrew、Scoop、Winget、Chocolatey、AUR、go install

团队共享图制品

向仓库提交单个压缩文件，队友即可跳过重新索引。

.codebase-memory/graph.db.zst 是位于源码旁的知识图 zstd 压缩快照。索引时会写入或刷新该制品；队友克隆仓库并首次运行 codebase-memory-mcp 时，制品会被解压，增量索引再补齐其本地 diff。

格式：SQLite 数据库，剥离索引，VACUUM INTO 压缩后，再以 zstd 1.5.7 压缩（典型压缩比 8–13:1）
两层级：
- Best（zstd -9 + 索引剥离 + VACUUM INTO）—— 在显式执行 index_repository 时写入
- Fast（zstd -3）—— 由 watcher 写入，用于低延迟增量更新
引导：本地无 DB 但存在制品时，index_repository 先导入制品，再运行增量索引 —— 避免完整重新索引的开销
无合并烦恼：首次导出时会自动创建带 merge=ours 的 .gitattributes 行，并发编辑不会在二进制制品上产生冲突
可选：除非你主动提交，否则不会入库。若希望每个人都从零重新索引，可将 .codebase-memory/ 加入 .gitignore。

其结果在理念上类似 graphify 的 graphify-out/ 目录，但以单个压缩文件呈现，具备显式两层级导出、完整性校验导入，且零合并摩擦。

工作原理

codebase-memory-mcp 是一个结构化分析后端 —— 它构建并查询知识图。它不包含 LLM。相反，它依赖你的 MCP 客户端（Claude Code，或任何兼容 MCP 的 agent）作为智能层。

You: "what calls ProcessOrder?"

Agent calls: trace_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 key、额外成本，以及又要配置一个模型。借助 MCP，你已经在对话的 agent 就是查询翻译器。

性能

在 Apple M3 Pro 上基准测试：

Operation	Time	Notes
Linux kernel full index	3 min	28M LOC, 75K files → 4.81M nodes, 7.72M edges
Linux kernel fast index	1m 12s	1.88M nodes
Django full index	~6s	49K nodes, 196K edges
Cypher query	<1ms	Relationship traversal
Name search (regex)	<10ms	SQL LIKE pre-filtering
Dead code detection	~150ms	Full graph scan with degree filtering
Trace call path (depth=5)	<10ms	BFS traversal

RAM 优先流水线（RAM-first pipeline）：所有索引均在内存中完成（LZ4 HC 压缩读取、内存 SQLite、最后一次性转储）。索引完成后，内存会释放回操作系统。

Token 效率：五次结构化查询通过 codebase-memory-mcp 仅消耗约 3,400 个 token，而通过逐文件 grep 探索则消耗约 412,000 个 token——减少 99.2%。

故障排查与诊断

codebase-memory-mcp 100% 本地运行且不收集任何遥测数据——你的代码、查询、环境和使用情况永远不会离开你的机器。这一隐私保障也意味着，当你遇到我们无法在本地复现的问题（数小时内内存缓慢攀升、性能回退、或仅在多日实际使用后才会出现的泄漏）时，除非你主动发送，否则我们完全没有任何数据。 以下介绍如何自行采集。

采集诊断日志

在 MCP 服务器启动前设置 CBM_DIAGNOSTICS=1，然后复现问题（让它运行足够久——缓慢泄漏需要时间才能在趋势中显现）。服务器会将两个文件写入系统临时目录（macOS/Linux 为 $TMPDIR 或 /tmp，Windows 为 %TEMP%）：

文件	说明
`cbm-diagnostics-<pid>.ndjson`	内存轨迹——每 5 秒一行 JSON，包含 `rss`、`committed`（Windows commit charge）、`peak_`、`page_faults`、`fd` 和 `queries`。这是我们处理内存/泄漏报告所需的文件——随时间变化的趋势才能定位泄漏。服务器退出后该文件会保留在磁盘上*（便于事后获取），超过约 8 MB 时会轮转到 `.ndjson.1`。
`cbm-diagnostics-<pid>.json`	仅最新快照——便于快速实时检查。正常退出时会被删除。

启动日志会打印两个路径，例如：

level=info msg=diagnostics.start snapshot=/tmp/cbm-diagnostics-12345.json trajectory=/tmp/cbm-diagnostics-12345.ndjson interval=5s

在代理的 MCP 服务器配置中的 env 块内设置该变量，或在启动服务器前 export。

需要分享的内容

当你提交内存/性能相关 issue 时，请附上 .ndjson 轨迹文件——其中不含源代码或查询文本，仅有资源计数器。若不想附加文件，可将其（或代理对其的摘要）粘贴到 issue 中：你的助手可直接读取 NDJSON，并报告 rss/committed 是否单调增长、增速如何、以及与查询次数的相对关系——这正是我们定位原因所需的信息。

安装

预编译二进制

平台	标准版	含 Graph UI
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`

每次发布均包含带 SHA-256 哈希的 checksums.txt。所有二进制均为静态链接——无共享库依赖。

Windows 说明：SmartScreen 可能对未签名软件显示警告。点击 "More info" → "Run anyway"。使用 checksums.txt 验证完整性。

安装脚本

自动下载 + 安装

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

AUR (Arch Linux)

yay -S codebase-memory-mcp-bin

paru -S codebase-memory-mcp-bin

codebase-memory-mcp-bin 软件包可在以下地址获取：https://aur.archlinux.org/packages/codebase-memory-mcp-bin

通过 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 配置

若不想使用 install 命令

添加到 ~/.claude/.mcp.json（全局）或项目 .mcp.json：

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

重启你的代理。使用 /mcp 验证——你应能看到 codebase-memory-mcp 及 14 个工具。

多代理支持

install 会自动检测并配置所有已安装的代理：

代理	MCP 配置	说明/指令	Hooks
Claude Code	`.claude/.mcp.json`	4 Skills	PreToolUse（Grep/Glob 图增强，非阻塞）
Codex CLI	`.codex/config.toml`	`.codex/AGENTS.md`	SessionStart 提醒
Gemini CLI	`.gemini/settings.json`	`.gemini/GEMINI.md`	BeforeTool（grep 提醒）+ SessionStart 提醒
Zed	`settings.json` (JSONC)	—	—
OpenCode	`opencode.json`	`AGENTS.md`	—
Antigravity	`.gemini/config/mcp_config.json` (shared)	`antigravity-cli/AGENTS.md`	SessionStart 提醒
Aider	—	`CONVENTIONS.md`	—
KiloCode	`mcp_settings.json`	`~/.kilocode/rules/`	—
VS Code	`Code/User/mcp.json`	—	—
OpenClaw	`openclaw.json`	—	—
Kiro	`.kiro/settings/mcp.json`	—	—

Hooks 在结构上为非阻塞（退出码 0，所有失败路径亦然）。对于 Claude Code，PreToolUse hook 会拦截 Grep/Glob（从不拦截 Read—— 对 Read 进行门控会破坏先读后改不变量），当搜索 token 与已索引符号匹配时，通过 search_graph 将其作为 additionalContext 注入，使代理在常规搜索结果之外还能获得结构化上下文。对于 Codex、Gemini CLI 和 Antigravity，SessionStart hook 会以会话上下文形式注入一行代码发现提醒（Gemini CLI 还会保留其 BeforeTool 提醒）。已安装的 Claude shim 文件名为 cbm-code-discovery-gate，以兼容既有安装；尽管名称沿用旧版，它从不进行门控，也从不阻塞。

CLI 模式

每个 MCP 工具均可从命令行调用：

codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/repo"}'
codebase-memory-mcp cli list_projects

# Use the "name" returned by list_projects as the project value.
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"}'
codebase-memory-mcp cli --raw search_graph '{"project": "my-project", "label": "Function"}' | jq '.results[].name'

MCP 工具

索引

工具	说明
`index_repository`	将仓库索引到图中。之后自动同步保持最新。
`list_projects`	列出所有已索引项目及其节点/边数量。
`delete_project`	移除项目及其全部图数据。
`index_status`	检查项目的索引状态。

查询

工具	说明
`search_graph`	按标签、名称模式、文件模式、度过滤进行结构化搜索。通过 limit/offset 分页。
`trace_path`	BFS 遍历——谁调用了某函数，以及它调用了什么（别名：`trace_call_path`）。深度 1-5。
`detect_changes`	将 git diff 映射到受影响的符号 + 带风险分级的影响半径（blast radius）。
`query_graph`	执行类 Cypher 的图查询（只读）。
`get_graph_schema`	各标签的节点/边数量、关系模式、属性定义。请先运行此项。
`get_code_snippet`	按限定名读取函数的源代码。
`get_architecture`	代码库概览：语言、包、路由、热点、簇、ADR。
`search_code`	在已索引的项目文件中进行类 Grep 的文本搜索。
`manage_adr`	架构决策记录（Architecture Decision Records）的 CRUD。
`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 使用限定名：<project>.<path_parts>.<name>。请先用 search_graph 发现它们。

支持的 Cypher（openCypher 只读子集）

query_graph 是只读的 openCypher 子集：

子句：MATCH, OPTIONAL MATCH, 多个 MATCH, WHERE, WITH（+ WITH … WHERE）, RETURN, ORDER BY, SKIP, LIMIT, DISTINCT, UNWIND, UNION / UNION ALL, CASE。
模式：带标签的节点、标签交替 (n:A|B)、关系类型/方向、可变长度路径 [*1..3]、内联属性映射。
WHERE：= <> < <= > >=, AND/OR/XOR/NOT, IN, CONTAINS, STARTS WITH, ENDS WITH, IS [NOT] NULL, 正则 =~, 标签测试 n:Label, 以及 EXISTS { (n)-[:TYPE]->() }（单跳存在性——非常适合死代码，例如 WHERE NOT EXISTS { (f)<-[:CALLS]-() }）。
聚合：count（+DISTINCT）, sum, avg, min, max, collect。
函数：labels, type, id, keys, properties；toLower/toUpper/toString/toInteger/toFloat/toBoolean；size, length, trim/ltrim/rtrim, reverse；coalesce, substring, replace, left, right。

该子集之外的任何内容（写操作/MERGE/CALL 子句、不支持的函数、列表/映射字面量、推导式、路径函数、参数）会以明确的 unsupported … 错误失败，而不是返回空结果。

忽略文件

分层处理：硬编码模式（.git、node_modules 等）→ .gitignore 层级 → .cbmignore（项目专用，gitignore 语法）。符号链接始终跳过。

完整的 .cbmignore 用法说明（语法、各忽略层的优先级、取反语义）见 docs/cbmignore.md。

配置

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 set auto_watch false          # don't register background git watcher (default: true)
codebase-memory-mcp config reset auto_index              # reset to default

环境变量

变量	默认值	说明
`CBM_ALLOWED_ROOT`	(未设置)	将 `index_repository` 限制在此目录内的路径。设置后，若 `repo_path` 在解析（符号链接 / `..` 解析之后）落在该根目录之外，则会被拒绝；未设置时不加限制。适用于服务器可能由不可信调用方驱动的场景，例如智能体或跨租户部署。
`CBM_CACHE_DIR`	`~/.cache/codebase-memory-mcp`	覆盖数据库存储目录。所有项目索引与配置都保存在此。
`CBM_DIAGNOSTICS`	`false`	设为 `1` 或 `true`，以启用向 `/tmp/cbm-diagnostics-<pid>.json` 定期输出诊断信息。
`CBM_DOWNLOAD_URL`	(GitHub releases)	覆盖更新下载 URL。用于测试或自托管部署。
`CBM_LOG_LEVEL`	`info`	设置最低日志级别。可接受的值（不区分大小写）：`debug`、`info`、`warn`、`error`、`none` —— 或其与内部枚举对应的数字等价形式 `0`–`4`。日志输出到 stderr；stdout 保留给 MCP JSON-RPC。
`CBM_WORKERS`	(自动检测)	覆盖 `cbm_default_worker_count` 返回的并行索引进程数。在容器内很有用，因为 `sysconf(_SC_NPROCESSORS_ONLN)` 报告的是宿主机 CPU 数，而非 cgroup 的有效配额。范围 1–256；无效值会被忽略并给出警告。
`CBM_MEM_BUDGET_MB`	(自动检测)	用显式的 MiB 上限覆盖内存中图的预算，优先于 `ram_fraction × total_RAM` 默认值。适用于没有 cgroup 限制的裸机主机，或将预算固定在 cgroup 限制之下，以便为同机其他进程留出余量。必须为正整数；会被钳制到检测到的总 RAM（记录为 `mem.budget.clamped`），非数字或非正值会被忽略并给出警告（`mem.budget.env.invalid`）。
`CBM_DUMP_VERIFY_MIN_RATIO`	`0.5`	索引完成后，比较持久化的 SQLite 节点数与内存转储节点数。当持久化节点数低于已提交节点数的该比例（且已提交 > 50）时，`index_repository` 返回 `status:"degraded"`，而不是静默的 `indexed`。范围 0–1；设为 `0` 可禁用。无效值会被忽略并给出警告。

# Store indexes in a custom directory
export CBM_CACHE_DIR=~/my-projects/cbm-data

自定义文件扩展名

JSON 配置文件支持单个键 extra_extensions，用于将额外的文件扩展名映射到受支持的语言。适用于框架专用扩展名，例如 .blade.php（Laravel）或 .mjs（ES modules）。（其他可调项见环境变量以及上文的 config 子命令。）

需要完整的配置文件参考？见 docs/CONFIGURATION.md。

按项目（在仓库根目录）：

// .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"}}

每条将扩展名（必须以 . 开头）映射到语言名。语言名匹配不区分大小写。可接受的值（括号内为别名）为：

bash (sh), c, c++ (cpp), c# (csharp), clojure, cmake, cobol, common lisp (commonlisp, lisp), css, cuda, dart, dockerfile, elixir, elm, emacs lisp (emacslisp), erlang, f# (fsharp), form, fortran, glsl, go, graphql, groovy, haskell, hcl (terraform), html, ini, java, javascript, json, julia, kotlin, lean, lua, magma, makefile, markdown, matlab, meson, nix, objective-c (objc), ocaml, perl, php, protobuf, python, r, ruby, rust, scala, scss, sql, svelte, swift, toml, tsx, typescript, verilog, vimscript, vue, wolfram, xml, yaml, zig。

对冲突的扩展名，项目配置覆盖全局配置。语言名未知、或扩展名不以 . 开头的条目会被跳过，并在 stderr 记录警告（在默认的 info 日志级别下可见）。缺失的配置文件会被忽略。

持久化

SQLite 数据库存储在 ~/.cache/codebase-memory-mcp/。跨重启持久保存（WAL 模式，ACID 安全）。若要重置：rm -rf ~/.cache/codebase-memory-mcp/。

故障排除

问题	处理
`/mcp` 未显示服务器	检查 `.mcp.json` 路径是否为绝对路径。重启 agent。测试：`echo '{}' \| /path/to/binary` 应输出 JSON。
`index_repository` 失败	传入绝对路径：`index_repository(repo_path="/absolute/path")`
`trace_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`。

Hybrid LSP

超越 tree-sitter 的语义类型解析。

仅靠 tree-sitter 只能得到语法 AST。这对命名、结构和调用点处理得很好，但它无法告诉你 user.profile.display_name() 会解析到三个模块之外声明的 Profile.display_name —— tree-sitter 不跟踪 import、泛型、继承或标准库类型。

codebase-memory-mcp 内置了轻量级 C 语言实现的类型解析算法，在结构上受主流语言服务器（language server）启发并与之兼容（tsserver / typescript-go、pyright、gopls、Roslyn、Eclipse JDT、rust-analyzer），直接嵌入静态二进制文件中。无需语言服务器进程、无需按项目配置、无需 API 密钥。我们将这一层称为 Hybrid LSP：它在每次解析时与 tree-sitter 并行运行，并用类型信息细化 CALLS、USAGE 和 RESOLVED_CALLS 边，从而使生成的图谱与 IDE 中「转到定义」（Go to Definition）的解析结果一致。

已完整支持 Hybrid LSP 的语言：

Language	What it handles
Python (new in v0.7.0)	imports + 点号子模块遍历、dataclasses、`Self` 返回类型、泛型、`@property`、`match/case` 类模式、SQLAlchemy 2.0 `Mapped[T]`、Pydantic `BaseModel`、`typing.Annotated` / `ClassVar` / `Final` / `InitVar`、async/await、classmethod/staticmethod、收窄（`isinstance` / `is not None` / walrus）、`typing.cast` / `assert_type`、常用标准库（logging、pathlib、json、functools）。目标是在惯用代码上达到约 95% 的解析率。
TypeScript / JavaScript / JSX / TSX	泛型、JSX 组件分派、纯 JS 的 JSDoc 推断、`.d.ts` 声明、模块再导出、通过返回类型传播实现的方法链、按文件叠加并链接到共享跨文件注册表
PHP (new in v0.7.0)	命名空间、trait、late-static-binding、PHPDoc 推断、参数绑定、返回类型推断
C# (new in v0.7.0)	全局 using、文件作用域命名空间、record（含 C# 12 主构造函数）、LINQ 方法语法、`async Task<T>` / `ValueTask<T>` 解包、泛型方法、`this` / `base` 分派、`var` 推断、常用 BCL 标准库
Go (sharpened in v0.7.0)	预构建的按包跨文件注册表、泛型、嵌入结构体、接口满足、包感知的 import 解析
C / C++ (sharpened in v0.7.0)	预构建的按语言跨文件注册表，C 与 C++ 共享；C 侧处理宏 + `typedef` 链 + 头文件与源文件链接；C++ 侧处理模板、命名空间、`auto` 推断，以及通过类层次结构进行的方法解析
Java (new in v0.8.0)	import（单类型、按需、静态）、带 `this` / `super` 分派的类层次结构、泛型、注解、按参数个数与参数类型的重载匹配、绑定到函数式接口的 lambda / 方法引用、字段类型推断、常用 JDK 标准库
Kotlin (new in v0.8.0)	import + 同包解析、class / object / companion object、扩展函数、data class、可空类型解包、作用域函数（`let` / `apply` / `run` / `also` / `with`）、中缀调用、常用标准库
Rust (new in v0.8.0)	`use` 声明 + 模块路径、`impl` 块与 trait 方法、结构体字段、带 trait 约束的泛型、运算符 trait 脱糖、derive 宏方法合成、UFCS 静态路径、常用 std prelude
Perl	包 + `@ISA` / `use parent` / `use base` 继承及方法解析顺序（method-resolution-order）分派、`SUPER::` 调用、Exporter（`use Foo qw(...)`）import 映射、`bless` / `ref($class)\|\|$class` self 类型推断、限定 `Pkg::sub` 静态调用、精选 perlfunc + CPAN OOP 标准库；未解析的接收者不产生边（零边保证）

双层架构：

Tree-sitter pass —— 快速、语法级，对全部 158 种语言运行。提取定义、调用、import。
Hybrid LSP pass —— 类型感知，在 tree-sitter pass 之上按语言运行。利用 import 图以及按文件或预构建的跨文件定义注册表来细化调用边。尚未支持 Hybrid LSP pass 的语言会回退到文本解析，因此你总能得到某种答案。

最终得到的知识图谱足够准确，可驱动跨包、继承层次结构和标准库调用的 trace_path —— 且无需为每个项目支付语言服务器进程的开销。

Language Support

158 种语言，均通过编入二进制的 vendored tree-sitter 语法进行解析。已在 64 个真实开源仓库上完成基准测试（节点数从 78 到 49K）：

Tier	Score	Languages
Excellent (>= 90%)		Lua、Kotlin、C++、Perl、Objective-C、Groovy、C、Bash、Zig、Swift、CSS、YAML、TOML、HTML、SCSS、HCL、Dockerfile
Good (75-89%)		Python、TypeScript、TSX、Go、Rust、Java、R、Dart、JavaScript、Erlang、Elixir、Scala、Ruby、PHP、C#、SQL
Functional (< 75%)		OCaml、Haskell

另已支持（尚未基准测试）：Ada、Agda、Apex、Assembly (NASM)、Astro、AWK、Beancount、BibTeX、Bicep、Bitbake、Blade、Cairo、Cap'n Proto、Clojure、CMake、COBOL、Common Lisp、Crystal、CSV、CUDA、D、Devicetree、Diff、.env、Elm、Emacs Lisp、F#、Fennel、Fish、FORM、Fortran、FunC、GDScript、.gitattributes、.gitignore、Gleam、GLSL、GN、Go module、Go template、GraphQL、Hare、HLSL、Hyprlang、INI、ISPC、Janet、Jinja2、JSDoc、JSON、JSON5、Jsonnet、Julia、Just、Kconfig、KDL、Lean 4、Linker Script、Liquid、LLVM IR、Luau、Magma、Makefile、Markdown、MATLAB、Mermaid、Meson、Move、Nickel、Nim、Nix、Odin、Pascal、Pkl、PO (gettext)、Pony、PowerShell、Prisma、.properties、Protobuf、Puppet、PureScript、Racket、Regex、requirements.txt、ReScript、RON、reStructuredText、Scheme、Slang、Smali、Smithy、Solidity、SOQL、SOSL、Squirrel、SSH config、Starlark、Svelte、Sway、SystemVerilog、TableGen、Tcl、Teal、Templ、Thrift、TLA+、Typst、Verilog、VHDL、Vim script、Vue、WGSL、WIT、Wolfram、XML、Zsh。

Architecture

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 (158 languages) + AST extraction engine

Security

每次发布前，所有发行版二进制文件都会经过多层流水线验证：

VirusTotal —— 所有二进制文件由 70+ 款杀毒引擎扫描（发布前要求零检出）
SLSA Level 3 —— 由受信任的 GitHub Actions 构建工作流生成加密构建溯源（build provenance）；使用 gh attestation verify <file> --repo DeusData/codebase-memory-mcp --signer-workflow DeusData/codebase-memory-mcp/.github/workflows/_build.yml 进行验证
Sigstore cosign —— 对所有制品进行无密钥签名；每个发行版均包含 bundle
SHA-256 checksums —— 每次发行都会发布 checksums.txt；安装脚本在解压前都会进行校验
CodeQL SAST —— 若仍存在未关闭的告警，将阻断发布流水线
Zero runtime dependencies —— 无传递性供应链；所有库在编译时 vendored

v0.7.0 VirusTotal scans

Binary	SHA-256	VirusTotal
`linux-amd64`	`8e12bb2d6ead7f20a6d3...`	0/72 ✅
`linux-arm64`	`10f7136bfbf3950c6b2a...`	0/72 ✅
`darwin-arm64`	`7062a7408906344bf4f8...`	0/72 ✅
`darwin-amd64`	`28c6d640e1a0ac7bfcab...`	0/72 ✅
`windows-amd64`	`9c3ddcf78368fd4fa891...`	0/72 ✅

每个版本的扫描链接也会自动包含在 GitHub Release 说明中。

许可证

MIT

41 KiB Raw Permalink Blame History Unescape Escape

codebase-memory-mcp

为什么选择 codebase-memory-mcp

快速开始

图谱可视化 UI

自动索引

保持最新

卸载

功能

图与分析

搜索

跨服务链接

跨仓库智能

边类型（节选）

索引流水线

分发与运行

团队共享图制品

工作原理

性能

故障排查与诊断

采集诊断日志

需要分享的内容

安装

预编译二进制

安装脚本

AUR (Arch Linux)

通过 Claude Code 安装

从源码构建

手动 MCP 配置

多代理支持

CLI 模式

MCP 工具

索引

查询

图数据模型

节点标签

边类型

限定名

支持的 Cypher（openCypher 只读子集）

忽略文件

配置

环境变量

自定义文件扩展名

持久化

故障排除

Hybrid LSP

Language Support

Architecture

Security

v0.7.0 VirusTotal scans

许可证

41 KiB

Raw Permalink Blame History