Codebase Memory

codebase-memory-mcp：通过 MCP 为 AI Agent 提供本地代码智能

从源代码到周边系统，全面了解你的代码仓库。 codebase-memory-mcp 是一款 MCP 服务，可将代码、文档、配置和基础设施连接到持久化的本地知识图谱中。你可以用它查找不熟悉的功能、追踪跨服务调用、从部署追溯到源代码，或评估代码变更可能影响项目的哪些部分。

通过 Model Context Protocol（MCP）为编码 Agent 提供结构化上下文，也可以直接通过 CLI 查询图谱。**MCP 服务是本项目的核心。**可选的可视化配套工具 CBM Lens 目前处于公开测试阶段（v0.0.1），提供源代码阅读器、架构图、Galaxy 图谱、覆盖情况诊断、架构决策和本地代码聊天功能。

原生 C 后端提供 17 个 MCP 工具，使用内置语法解析器解析语言和文件格式，并为支持的语言提供 Hybrid LSP 类型解析。安装程序支持 45 种自动或有条件的客户端集成，包括客户端配置、技能、Agent 配置文件和适用的钩子。索引和图谱查询无需托管服务或 API 密钥。聚焦的图谱查询可以减少重复读取文件和令牌用量；请参阅实测结果。

快速开始 · 功能 · 文档 · 基础设施 · 智能 CI · 探索 CBM Lens · Agent 设置 · MCP 工具

**本地处理：**源码分析和图谱存储均在你的设备上运行。启用浏览器 AI 后，CBM Lens 可选择下载模型；推理仍在设备上进行。安装程序会为你选择的客户端写入 Agent 配置。有关发行版验证，请参阅安全性；如需报告问题，请参阅 SECURITY.md。

**通过 CBM Lens 查看图谱（开放测试版 v0.0.1）。**文件夹会变成嵌套平台，文件和符号会变成可选择的方块，箭头则显示已索引的关系。录屏在此仓库的地图中打开 src/foundation，选中 arena.c 并打开其源码。高度可以表示源码大小；热点引力反映静态扇入。静态图片。

**星系。**以 3D 方式探索代码知识图谱。录屏沿着 cbm_arena_alloc 的外向关系再深入一层，切换到层级视图，并展示通往 cbm_alloc 的两跳调用路径。边上的脉冲表示关系方向；它们不代表实时执行。静态图片：cbm_max_file_bytes 周围的两层依赖关系。

**探索。**在类似 IDE 的工作区中浏览文件，在 Monaco 中查看语法高亮的源码，并在旁边查看代码图谱。文件影响显示哪些内容依赖于当前打开的文件；代码详情显示插入符所在符号的调用方和调用。选择代码即可向本地聊天询问相关内容。

高分辨率 GIF 展示的是 2026 年 10 月 20 日的 CBM Lens Beta；静态图片拍摄于 10 月 12 日至 13 日。所有内容均展示此仓库中的公开源码。每次录制所用的构建版本、索引范围和录制设置，请参阅录制详情。

为什么选择 codebase-memory-mcp

• 结合上下文查找正确的代码：将符号、文本和语义搜索与调用方、依赖项、源码片段及文件大纲结合起来。定向查询和紧凑的分页结果可减少 Token 用量和重复读取文件的次数；参见性能中的范围测量数据。
• 将文档与实现关联起来：将文档章节、PDF 文本页、架构决策和受支持的引用索引到代码中。查找符号时即可查看相关说明。
• 沿着源码文件之外的脉络理解系统：通过 Docker、Kubernetes、Helm、Kustomize、Terraform/OpenTofu、Terragrunt、Ansible、脚本、Make 和 CI 配置，追踪受支持的关系。
• 运行更改之前先了解影响：检查受影响的符号、比较已索引的快照，并查找相关测试。实验性 Smart CI 将静态关系与受支持的 C/C++ 测试框架中每项测试的覆盖率结合起来；证据不足时则改为运行更广泛的测试。
• 通过 CBM Lens Beta 进行可视化探索：阅读源码、沿调用路径追踪、检查架构和覆盖率缺口、管理架构决策，并向本地模型询问所选代码。
• 为编码 Agent 配备工具：install 会设置受支持的客户端配置、持久化指导、技能、Scout/Verify/Auditor 配置，以及适用的上下文钩子。各客户端的支持情况不同；参见多 Agent 支持。
• 让上下文保持本地且可复用：索引会在会话之间保留，符合条件的活动 MCP 会话可使索引保持同步，可选的图谱产物还可供团队共享基线。
• 在你的机器上运行原生工具：标准版本包含适用于 macOS、Linux 和 Windows 的 CBM Lens。原生运行时无需 Docker 或语言运行时；解析器语法已包含在内。

快速入门

安装最新版本（macOS / Linux）：

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

标准原生版本包含 CBM Lens。安装后运行 codebase-memory-mcp daemon start --open --port=9749 即可启动。 Nix 软件包和源码构建也提供不含 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 调用。

选项：--skip-config（仅安装二进制文件，不设置 Agent），--dir=<path>（自定义位置）。

**防病毒软件提示：**Microsoft Defender 可能会将发布版二进制文件标记为 Trojan:Script/Wacatac.B!ml。这是已知的误报；通常约 62 款引擎中有 61 款 会判定为安全，同一检测类别也会命中 gh、llama.cpp、 Godot 和 Microsoft 自己的 Go 工具链。有关相关证据、如何自行验证制品以及 如果你认为我们的判断有误该如何报告，请参见 防病毒软件误报。

重启你的编码 Agent。说 “索引此项目”：完成。

安装还会配置受支持的编码 Agent，让它们在日常工作中使用图谱。原生 install 命令会检测客户端，并安装其文档格式支持的集成组件：

钩子增强仅提供上下文，并采用故障开放方式：不会替代或阻止请求的工具调用。各客户端和平台支持的功能有所不同；有些客户端会使用持久指令或交由父 Agent，而不是使用钩子或直接访问子 Agent 的 MCP。Codex 用户可通过 /hooks 检查并信任已安装的钩子。有关具体支持情况和启用要求，请参阅多 Agent 支持和会话、压缩与子 Agent。

会话协调守护进程

CBM 会自动为 Claude Code、Codex、OpenCode 以及所有其他已配置的客户端共享一个按账户运行的协调守护进程。MCP 服务或钩子客户端无需选择加入：第一个由守护进程支持的 CBM 会话会启动它，每个会话都会注册自己的工作，而由会话管理的守护进程会在最后一个会话结束后停止。通过 daemon start 启动的守护进程会持续运行，直到被停止。守护进程负责监控器、共享索引任务和可选 UI 等长期后台服务。关闭一个会话会取消仅由该会话负责的工作，而其他会话仍需要的工作会继续运行。

已脱离终端运行的守护进程不依赖 MCP 前端的 stderr。它会在规范的 ${CBM_CACHE_DIR}/logs 目录（默认为 ~/.cache/codebase-memory-mcp/logs）下保存仅所有者可访问的持久记录：

精简前端仍会将启动错误和会话专属错误立即写入各自的 stderr；MCP JSON-RPC stdout 则保持干净。

所有正在运行的 CBM 进程必须使用完全相同的版本、可执行文件构建版本、协调 ABI 和规范缓存根目录。等效的 CBM_CACHE_DIR 别名会解析到同一根目录；只要有任何 CBM 进程正在运行，真正不同的根目录就会被拒绝。MCP 服务、钩子、一次性 CLI 命令、临时索引工作进程和守护进程共用一个崩溃安全的操作系统准入屏障；启动普通的冲突进程会在其开始工作前失败，并在 ${CBM_CACHE_DIR}/logs/daemon-conflicts.ndjson 中记录明确的冲突。 原生 install 和 uninstall 命令是该冲突规则的有意例外。安装时，会先完成下载、验证和在同一文件系统上的私有暂存，然后再激活，因此有问题的候选版本不会干扰正在进行的工作。原生 update 命令会打印执行更新的安装程序命令。随后，激活过程会发布账户范围的维护意图，要求守护进程和所有临时本地操作取消，并在有限的截止时间内等待所有受协调的 CBM 进程退出。更改活动二进制文件、配置、PATH 或索引时，会独占持有准入屏障和生命周期屏障。在此期间，新的 CBM 工作无法进入。激活进度和结果会记录在 ${CBM_CACHE_DIR}/logs/activation-events.ndjson 中，命令成功后会提示你重启已打开的编码 Agent 会话，以便它们启动已激活的版本。

通过包管理器安装（npm、PyPI 或 Go）会验证并缓存该包对应的原生可执行文件。它不会替换活动的原生安装，因此不会停止正在运行的 CBM 会话。执行该缓存二进制文件时，它仍会进入同一个精确版本准入屏障。Shell 和 PowerShell 安装程序会调用已验证候选版本的原生 install 命令，因此同样享有完整的账户范围激活保障。

普通的 cli 模式会在本地运行一条命令，但它并非与上文的守护进程断开连接：它会连接到共享协调守护进程（如果尚未运行，则启动一个），以使用同一个准入屏障，以及图变更的项目级锁。其连接属于 cli_session：它不会注册项目监视器，也不会打开浏览器，并且只在命令运行期间持有准入租约。共享守护进程可根据其 UI 配置和可用资源提供 Lens 服务。如果启动守护进程的是命令自身的连接，那么命令结束且没有其他会话连接后，守护进程也会退出；如果守护进程原本已在运行，命令只会加入并在离开时保持其原样。命令运行期间，临时监视器会单独允许激活过程安全地取消该操作及其受监管的工作进程；监视器会随命令退出，绝不会成为常驻守护进程。详情请参阅 CLI 模式。

CBM Lens Beta：代码可视化与源代码导航

CBM Lens 是 MCP 服务的可选可视化伴侣，目前处于公开 Beta 阶段（v0.0.1）。 标准原生版本包含其浏览器界面，因此安装后即可直接启动 Lens；启用了 UI 的源码构建版本也包含该界面。它基于 CodeAtlasWeb，由 Bernhard Jackiewicz 开发（设计与跟踪见 #1964）。Lens 在回环地址上提供服务。只有在启用浏览器 AI 后，它才会下载可选模型；推理过程始终在设备本地进行。每个面板都会标明其事实来源，并将索引未记录的内容显示为缺口。启动本地服务：

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

浏览器会在 http://127.0.0.1:9749 打开。常驻守护进程会在命令退出后继续提供 UI。使用 daemon status 查看其状态，完成后使用 daemon stop 停止它。对于 MCP 会话，使用 --ui=true --port=9749 即可启用同一个共享 UI。活动客户端必须使用相同的可执行文件版本和缓存目录。

打开你的第一个代码仓库

1. 打开项目菜单并选择 添加项目索引。也可以使用 Alt+P。
2. 选择本地代码仓库文件夹并为索引命名。文件会保留在原处。
3. 开始索引并查看报告的状态。索引运行期间，你可以关闭对话框，之后从项目菜单重新打开其活动状态。
4. 打开已索引的项目。可先查看 Architecture 了解整体概况，或打开 Explore 阅读文件。

如需为视图添加书签，请使用 ?project=<name>&workspace=architecture。其他工作区值包括 explore、galaxy、adr、coverage 和 system。

架构视图

• **Overview：**在 3D 地图上浏览源代码文件夹和文件。可选择按源代码大小或统一高度显示、按语言或类型着色，以及筛选关系。切换到入口点视图，可从起始符号沿静态调用图浏览。
• **Routes：**在服务地图和端点连接之间切换。部署元数据与已索引的路由依据会分别显示；无法解析的注册项仍会显示。
• **Hotspots：**根据扇入和复杂度等测量指标检查符号。引力井有助于定位被频繁引用的区域。它们并非代码质量评分。
• **System structure：**检查组件依赖关系、展开分组、隔离循环，并沿连接追溯到源代码依据。
• **Behavior：**选择源和可达目标，以检查静态调用路径及其源代码语句。这些路径显示的是可能的关系，并非记录的执行顺序。运行时观察结果需要单独导入跟踪数据。

拖动 3D 视图可旋转，滚动可缩放，选择节点或边可检查详情。边的颜色用于区分关系，脉冲则表示其方向。启用减少动态效果偏好后，脉冲会暂停。大型视图会显示其限制和省略的数量。缺少某条边可能是由索引或显示限制造成的，因此在下结论前，请检查 Coverage 和源代码。

在本地与你的代码库聊天

点击右上角面板按钮打开 Chat，即可询问当前查看的代码。在 Explore 中，它会使用当前打开的文件或你选中的确切文本；在 Galaxy 中，它会使用选中的节点及其已加载的邻居。你也可以通过 Add context 附加图谱证据。

1. 点击右上角的机器人图标，打开 Agent 配置。
2. 选择本地模型。默认的 Qwen2.5 Coder 0.5B 下载大小约为 567 MB；Qwen3 0.6B、LFM2.5 1.2B 和 Qwen3.5 2B 是更大的选项。所有模型都需要支持 shader-f16 的 WebGPU。
3. 点击 Download & load。模型文件来自 Hugging Face；推理在浏览器中运行，无需托管聊天 API 或 API 密钥。已在浏览器缓存中的模型可通过 Load model (cached, no download) 加载。
4. 提出问题。编辑框会显示随问题一并发送的文件或选中内容。想让回答更聚焦时，请选取较小的范围。

关于调用者和被调用者的问题，例如“谁调用了 cbm_pipeline_run？”，无需模型即可根据已加载的图谱回答，并且回答会说明这一点。选中一个符号后，聊天会列出它的索引事实和代码行，模型再补充一句话；如果这句话声称了源代码中未显示的内容，则会省略。模型生成的文本会标明来源。

录屏询问谁调用了 arena_grow 以及它调用了什么，两个答案都直接列在所选符号旁边，来自已索引的图谱。模型说明和图谱回答的静态图片。

聊天历史会按项目保存在此浏览器中 24 小时。每条新消息都会使用阅读器中当前打开的源代码；之前的源代码快照不会被悄悄累积，关于其他文件或选中内容的消息也不会一并发送。如果提示词对模型来说太长，会先省略较早的消息；如果仍然无法容纳，CBM Lens 会请你减少选中的代码，而不是截断代码。这种聊天功能会根据你提供的上下文进行说明；它无法编辑文件或运行工具。请对照源代码检查回答。默认的小型模型措辞不够严谨，尤其是在英语以外的语言中。

搜索

Cmd+K 或 Ctrl+K 可打开 Galaxy 搜索。它会在整个索引中按名称或路径查找符号、文件和文件夹，也会查找尚未加载的节点。关于调用者和被调用者，请在聊天中提问；答案会根据图谱列出。

架构决策

ADR 工作区会在此浏览器标签页中为每个项目保留未保存的草稿。保存前，它会检查存储的文档是否已更改，但 API 不提供原子文档锁。编辑器最多接受 8,000 个 UTF-8 字节。保存会更改已索引的决策文档，而不是你代码库中的文件。

VITE_EXPERIMENTAL_AGENTS=true scripts/build.sh --with-ui

如需排查问题，请打开 System logs。前端错误和失败的请求会在本地记录。GET /api/ui-log 会从守护进程的 SQLite 日志中读取前端条目；${CBM_CACHE_DIR}/logs/ui.log 也会以循环 JSONL 导出的形式保留。日志范围、模型设置和开发详情请参阅前端 README。

自动索引

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

codebase-memory-mcp config set auto_index true

默认情况下，auto_index 处于关闭状态。启用后，新项目会在首次连接时自动建立索引。可通过 config set auto_index_limit 50000 配置文件数量上限。此前已建立索引的项目可以通过 auto_watch 进行监视（默认开启），但需遵循其全局设置和会话所有权规则。

每个已初始化且长期运行的 MCP 会话都可以在连接时注册其根项目，也可以注册成功调用 index_repository 后的任何目标，包括自定义项目名称以及位于其他工作树中的根目录。启用 auto_watch 后，这些监视项归注册会话所有；只要至少有一个所有者会话处于连接状态，监视项就会保留；最后一个所有者关闭后，监视项便会移除。异步索引仅会在成功完成且发起请求的会话仍处于连接状态时注册其目标。CLI 索引和失败的 MCP 索引不会注册监视项。全局设置 auto_watch 控制注册；将其设为 false 时，会在下一次刷新或注册请求时移除所有监视项。index_status 会在其 watch 对象中报告此状态：watched，以及轮询间隔和上次扫描时间，或未受监视的 reason。

监视器注册由全局设置 auto_watch 控制（默认值为 true）。在下一次刷新或注册请求时，设为 true 会允许 MCP 会话在连接时注册其根项目，并注册成功调用 index_repository 后的目标；设为 false 则会移除所有监视项。CLI 索引和失败的 MCP 索引不会添加监视项。

若要完全关闭监视器，请设置 config set watcher_enabled false（默认值为 true）：后台轮询线程将永不启动，也不会注册任何项目，但 auto_index 和手动调用 index_repository 仍可使用。与在下一次刷新或注册请求时生效的 auto_watch 不同，watcher_enabled 只会在后台守护进程启动时读取一次，因此更改后请运行 codebase-memory-mcp daemon stop；仅重新连接 MCP 客户端不会重启守护进程。参见 docs/CONFIGURATION.md。

默认情况下，监视器仅跟踪 git 项目：从非 git 仓库目录建立索引的项目不会受到监视，索引也会保持不变，直到你再次运行 index_repository。若要同时轮询此类根目录，请设置 config set watch_non_git true（默认值为 false，在守护进程启动时读取）：随后会按照相同的间隔检查这些目录，并使用索引器自身的忽略规则扫描文件树。

保持最新

所有平台的更新都通过安装脚本运行，而不是在运行中的二进制文件内进行。 codebase-memory-mcp update 会验证你的标志，然后打印要运行的确切命令：

# macOS / Linux
bash "<install-dir>/install.sh"

# Windows
powershell -File "<install-dir>\install.ps1"

安装时，安装脚本会放在二进制文件旁边，因此打印出的路径会指向可执行文件所在目录。该脚本是幂等的，因此重新运行它就是更新：它会停止守护进程、移走正在运行的二进制文件、安装新版本并清理。

这样设计的原因：在 Windows 上，这是硬性要求；正在运行的可执行文件无法替换自身映像，因此必须由一个不是待替换二进制文件的进程来完成替换。在 macOS 和 Linux 上，这是有意为之：进程内更新器本质上就是一个下载器（获取压缩包、验证、解压、将文件标记为可执行并运行），为了满足大多数人一年只运行几次的命令，而在每个二进制文件中附带这一整套功能并不划算。现在，发布压缩包中不再包含下载 URL，cbm 不会自行发起网络请求：它不会在后台检查新版本，也不会回传任何信息。你可以通过安装脚本、包管理器或 GitHub 了解发布情况。

如果 PowerShell 因为脚本文件来自互联网而拒绝运行，请先对该文件运行 Unblock-File。

通过 npm 或 pip 安装？所有平台都使用相应的包管理器进行更新（npm install -g codebase-memory-mcp@latest / pip install -U codebase-memory-mcp）。

卸载

codebase-memory-mcp uninstall

移除由本工具管理的 Agent 配置项、技能、钩子、说明文件和已安装的二进制文件。现有图索引会列出，但默认保留。使用 -y/--yes、-n/--no 或非交互式输入时，除非明确指定 --delete-indexes，否则都会保留索引。未指定该标志时，交互式终端会单独询问；默认回答为保留。

codebase-memory-mcp uninstall -y --delete-indexes   # also delete every project index
codebase-memory-mcp uninstall --dry-run --delete-indexes   # preview; change nothing

--delete-indexes 表示明确同意删除，优先级高于 --no；--dry-run 始终会保留文件。保留索引时，卸载程序会打印其缓存目录（${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}）以及删除方法。

卸载程序会报告安装脚本的位置，但不会删除脚本：它会打印脚本路径和用于删除它的 rm 命令。之所以有意保留，是因为它可能是你自己的副本、指向某个检出目录的符号链接，或由包管理器管理；卸载程序不应删除无法确认归其所有的文件。

功能

图谱与分析

• 架构概览：默认情况下，get_architecture 会返回简洁的摘要。可请求特定的 aspects，以获取路由、热点、依赖关系、集群或循环。system_structure 提供 CBM Lens 使用的投影，必须单独请求。
• 架构决策记录：manage_adr 会跨会话保存项目的决策记录；索引时也会从文档文件中提取受支持的 ADR 元数据和取代关系
• Louvain 社区检测：通过对调用边进行聚类，发现功能模块
• 变更影响：detect_changes 会将未提交的变更映射到受影响的符号并进行风险分类，还可通过 scope: "tests" 报告测试影响；compare_graphs 会比较已索引的快照
• 运行时观测：ingest_traces 会将从单独采集的跟踪记录中观测到的调用关系添加到静态分析结果中；仅靠静态调用路径无法显示实际运行过的内容
• 调用图：解析跨文件和包的函数调用（感知导入并推断类型）
• 死代码候选项：查找没有已索引调用方的函数，但排除入口点。删除代码前，请检查动态分派、覆盖率缺口和框架惯例。
• 类似 Cypher 的查询：MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name

搜索

• 语义搜索（search_graph 的 semantic_query 参数，并非单独的工具）：在整个图中进行向量搜索，由编译进二进制文件的 Nomic nomic-embed-code 嵌入模型提供支持（40K tokens，768d int8）；无需 API 密钥、Ollama 或 Docker。采用 11 种信号的综合评分（TF-IDF、RRI、API/Type/Decorator 签名、AST 配置文件、数据流、Halstead-lite、MinHash、模块邻近度、图扩散）。
• 通过 SQLite FTS5 和 cbm_camel_split 分词器进行 BM25 全文搜索（识别 camelCase / snake_case）
• 结构搜索（search_graph）：正则表达式名称模式、标签筛选、最小/最大度数、文件范围限定
• 代码搜索（search_code）：仅对已编入索引的文件进行图增强 grep

将文档关联到代码

查找符号背后的说明，并沿受支持的引用追溯到其实现。文档与源文件一同纳入图中：

• Markdown、reStructuredText 和 AsciiDoc 会转换为可浏览的文档章节；带文本层的 PDF 会转换为可搜索的文本页面。PDF 提取不会执行 OCR。
• 文档到代码的引用以及受支持语言中的文档注释引用，在目标可解析时会创建 MENTIONS 关系。
• 架构决策记录会提供状态、决策者和后续取代关系等元数据，因此可以结合其描述的代码探索决策。
• 受支持的图表和 OpenAPI 描述会生成结构化实体。不同格式的提取和引用解析方式各异；并非每次文本提及都会成为图边。

使用图搜索和文本搜索定位相关章节，沿记录的关系追踪，并打开源证据。在将缺少的结果视为仓库中不存在相关文档或引用的证明之前，请先检查 check_index_coverage。

基础设施和部署

询问 “是什么部署了此服务？”、“运行它的是哪个镜像？” 或 “此配置会影响哪些代码？” CBM 会将受支持的基础设施形式关联到它们所构建、配置和运行的源代码：

• 容器和集群：Dockerfile、Compose 服务、Kubernetes 资源、Helm 图表和发布版本，以及 Kustomize 覆盖配置和补丁。
• 资源配置和配置管理：Terraform/OpenTofu 资源和模块、tfvars 覆盖项、Terragrunt 依赖、Ansible 任务和处理程序，以及受支持的配置键和环境变量访问。
• 构建和交付：用于构建镜像、调用仓库脚本或部署资源的 shell 命令、Make 目标和受支持的 CI 步骤。

对于可解析的输入，追踪可以沿 Service → workload → image → Dockerfile → program 展开，也可以沿部署和配置关系追踪。使用 trace_path 的 topology、deployment 和 run 模式。这些是根据受支持的源形式生成的静态关系；动态值和无法解析的模板可能导致追踪中断。有关准确的关系规则和限制，请参阅边类型。

跨服务关联

• HTTP 路由 ↔ 调用点匹配，并附带置信度评分
• gRPC、GraphQL、tRPC 服务检测，并提取 protobuf Route
• 跨 8 种语言进行 Channel 检测（EMITS / LISTENS_ON），支持 Socket.IO、EventEmitter 和通用发布-订阅模式，并解析常量

跨仓库智能分析

• CROSS_* 边用于关联同一存储库中已索引的多个仓库里的节点
• 跨仓库架构摘要：汇总已索引代码库中的服务、路由和依赖项
• 运行状态：index_status（以及 linked_projects 旁的 UI 布局）包含一个 cross_repo 对象。运行 index_repository(mode="cross-repo-intelligence") 并将该项目设为源项目之前，其值为 {"status":"never_run"}；运行后则变为 "ran"，并包含 last_run_at、outcome、targets、projects_scanned、total_cross_edges 和 skipped_projects。这样就能区分“从未关联”和“已关联，但没有匹配项”。状态与项目自身索引中的 CROSS_* 边一同存储，因此重建索引的重新索引操作会同时清除二者，状态也会恢复为 never_run。
• 已跳过的存储库：target_projects: ["*"] 会跳过在 #768 架构变更之前构建的索引，而不是导致整个运行失败。响应会将每个跳过的项目列出为 skipped_projects: [{"name", "reason": "pre_768_schema", "hint": "reindex this project"}]。

智能 CI 和测试影响分析

使用图来说明变更会影响哪些测试，并依据这些证据聚焦运行受支持的 CI。智能 CI 目前仍处于实验阶段，包含两个层次：

codebase-memory-mcp test-impact select 会生成包含原因的选择结果；test-impact publish 会生成用作基线的图与覆盖率数据包。对于 Agent 辅助调查，detect_changes 配合 scope: "tests" 可通过 MCP 提供测试影响分析。

目前，缩小测试范围仅支持符合本仓库测试惯例或声明等效惯例的 C/C++ 系列代码。 它并非适用于 CBM 所索引所有语言的通用测试选择机制。证据缺失、过时、不兼容或不完整时，会扩大选择范围或返回 run_all；未经采纳覆盖率验证的静态可达性绝不会省略测试套件。请先使用仅报告的影子模式，并在启用门控前验证测试框架。

在本仓库中，当 TEST_IMPACT_MODE=gate 时，测试范围缩小功能会接入 Linux x86_64 测试阶段；发布和试运行工作流仍会执行完整测试。有关受支持的惯例、覆盖率采纳、设置、版本要求和回退行为，请参阅 智能 CI 指南。

边类型（选定）

• CALLS：在源位置调用可调用对象
• CALL_REFERENCE：在受支持的引用位置（例如，直接值参数）使用可调用对象，并解析为一个确切目标
• USAGE：使用了标识符，但无法证明其对应唯一的可调用目标（包括有歧义或复杂表达式）
• IMPORTS、DEFINES、IMPLEMENTS、INHERITS
• HTTP_CALLS、ASYNC_CALLS（跨服务）；运行 curl / wget 的 shell 脚本、Make 配方或 CI 步骤，会将其声明的 URL（解析常量部分，未知部分记为 {}）调用到对应 Route，并使用其标志指定的方法：若路径对应仓库的 Kubernetes Service，则像代码客户端那样处理；若为其他主机（下载、localhost），则保留主机名；边会保留 via、method、url_path、host，绝不保留用户信息或查询部分
• SPAWNS：调用方启动另一个程序（subprocess.run、exec.Command、posix_spawn、Process.Start、shell 命令或按路径运行程序的 Make 配方等）；目标是以程序名命名的 Process 节点；若程序不是字面值，则为 <dynamic>。当 shell 脚本、Make 配方、GitHub Actions 步骤或 Prow 任务运行仓库中的脚本（./hack/x.sh、bash hack/x.sh）时，目标是该脚本的 Module（否则为其 File）；make TARGET（包括 $(MAKE)、-C、-f）指向该目标的规则，并沿包含的 makefile 继续解析；来自 CI 的边会携带 ci 和 job。Dockerfile 最后一个阶段的 ENTRYPOINT（否则为 CMD）会生成容器所运行的对象（api: dockerfile）：仓库脚本或复制到镜像中的源代码、该阶段通过 go build -o 构建的二进制文件的 Go main，否则为 Process
• INFRA_MAPS：Kubernetes Service 指向其选择器中每个 key: value 均与其匹配、且位于同一命名空间的工作负载
• CONNECTS_TO：Kubernetes 工作负载或 compose 服务指向其容器环境变量所寻址的 Service（PRODUCT_CATALOG_SERVICE_ADDR: productcatalogservice:3550、URL 的主机名、<svc>.<ns>.svc...、*_ADDR / *_HOST / *_URL / ... 键上的裸名称；compose：插值项目的 .env）：指向同一 bundle 和命名空间中的 Kubernetes Service，或同一文件中的 compose 服务。边会保留 via: env、key 和 container，绝不保留值
• USAGE（ref: image）：Kubernetes 工作负载（任何 Pod 模板：containers、initContainers、CronJobs、自定义资源）或 docker compose 服务指向其运行的 Image
• Helm 模板会针对其镜像进行渲染：使用 chart 的 values（Chart 通过 DEPLOYS 指向它们，default_of：读取的 values 键）以及每个 release 的 values（Flux HelmRelease、kustomize helmCharts 条目、Terraform helm_release：override_of）。无法通过渲染确定的镜像会省略，绝不猜测：例如，改动 values 后无法精确运行的模板、无法查看其内容的 tpl 或 include、无法读取的 release value，或超出工作预算的情况。已知限制：每个模板文件单独渲染，而 Helm 会使用一份共享的 .Values 渲染 chart 的所有文件（子 chart 使用其父级的 .Values.<alias>），因此，在一个文件中修改 .Values、在另一个文件中读取它的 chart 仍可能显示错误的镜像
• DEPLOYS：将清单、kustomization 或 chart 部署到集群的对象，指向其部署内容：Flux Kustomization 或 Argo Application 指向其路径中的 kustomization / 清单 / chart；Flux HelmRelease 指向其 chart（spec.chart 或 chartRef → OCIRepository）；shell 命令或 Make 配方（kubectl apply -f/-k、kustomize build | kubectl apply、helm install/upgrade/template）；使用 Helm SDK 加载 chart 的 Go 安装程序；Terraform helm_release；Terraform kubernetes_* 资源指向其声明的对象（若名称为字面值，则作为清单中的 Resource，ecosystem: terraform）；展开 chart 的 kustomization（helmCharts；其 values 文件为 IMPORTS）。仓库外的 chart 是外部 Chart；若声明了其仓库 URL，则以发布者为键（__chart__<repository>/<name>，每个项目中均为同一节点，URL 位于 repository），否则每个项目和名称各自建立一个节点；边会记录 via（flux、argo、helmrelease、kubectl、kustomize、helm、helm-sdk、terraform、helmcharts 等）
• DEPENDS_ON：Helm chart 指向其声明的 chart（可解析的 file:// 仓库对应本地 chart，否则对应外部 Chart；边会保留 repository）；go.mod / requirements.txt 文件指向外部 Package；Dockerfile 指向其构建所基于的 Image（via: from、copy-from）；Image 指向构建它所用的 Dockerfile（via: build；对于脚本、Make 和 CI 中的 docker / podman / nerdctl / buildah 构建命令，tool 为 skaffold、compose、docker-build）；compose 服务指向其 depends_on / links 指定的服务
• CONFIGURES：读取环境变量的代码指向该名称对应的共享 EnvVar（strategy: env_access）；设置环境变量的 Kubernetes 容器、compose 服务或 Dockerfile（镜像的 ENV）指向该容器自己的 EnvVar（strategy: env_set，source 为 value、configMapKeyRef、secretKeyRef、fieldRef、...、compose、dockerfile；绝不存储值）；该容器的 EnvVar 指向在其镜像构建来源文件中读取该名称的代码（strategy: env_read，带有 dockerfile）：镜像文件是 Dockerfile 的 COPY / ADD 放入镜像的源文件，扣除上下文的 .dockerignore
• CONFIGURES（strategy: key_symbol）：代码符号指向其命名的配置键（config_key）。YAML、JSON、HCL（Terraform、OpenTofu、tfvars）、TOML 或 INI 键按精确名称链接（maxRetryCount = max_retry_count），且只链接到配置文件所属组件内的代码：即其目录，或 config/、configs/、conf/、settings/ 或 etc/ 目录外围的目录。.env 或 .properties 键也按子串链接（置信度 0.75）
• OVERRIDE（via: patch）：Kustomize patch 指向其 kustomization 构建中被其修改的每个对象（子项 → 基项）：patch 文件中的文档指向相同种类和名称的对象；内联 patch（来自 kustomization）或 JSON6902 操作文件指向其 target 所选对象（group、version、kind、name、namespace、label selector）；组件指向包含它的每个 kustomization 构建中的对象。边会保留 kustomization、patch 和 line；patch 文件是其 kustomization 的 IMPORTS（local_name: patches），绝不是构建内容的成员
• OVERRIDE（via: namePrefix / nameSuffix）：kustomization 重命名的对象，来自其变体：Resource 使用部署后的名称（capi- + controller-manager；嵌套 kustomization 的前缀从最外层到最内层排列，后缀从最内层到最外层排列），位于构建指定的命名空间，ecosystem: kustomize，由 kustomization 的文件 DEFINES。CRD、Namespace 和 API 服务保留其名称，与 kustomize 的行为一致。边会保留 kustomization 和 line
• USAGE（via: terraform）：Terraform / OpenTofu 引用（var.X、local.X、module.X、data.T.N、T.N）从包含它的顶层块指向其所属模块（其目录中的 .tf / .tofu 文件）中声明它的块（locals 条目指向其 locals 块）；块的 depends_on 列表中的条目则为 DEPENDS_ON。边会保留 ref（var、local、module、data、resource）和 line；仅在字符串文本中提及的名称不算引用。带本地 source 的模块调用（module "net" { source = "./modules/net" }）会对该目录的 Folder 执行 IMPORTS（local_name 为模块名称；根目录对应 Project），而 module.net.id（也包括 module.net[0].id、module.net[*].id）会对其中的 output "id" 执行 USAGE（ref: output），该输出位于 module.net 旁边
• OVERRIDE（via: tfvars）：.tfvars 赋值指向其所在目录的模块所声明的变量，从该文件的 Variable 指向该 variable 块（边会保留 line）；若 .tfvars 文件所在目录没有声明其任何名称，则会设置最近祖先模块中声明的变量，并在边上标记 inferred（此类文件由仓库未声明的 -var-file 应用）
• Terragrunt（via: terragrunt）：单元（terragrunt.hcl）在其自身上下文中求值：include 对其 path 指定的文件执行 IMPORTS（local_name）；read_terragrunt_config 对其指定的文件执行 IMPORTS（read：包含调用的文件），来源为包含该调用的块，若调用位于被包含文件中，则来源为引入该文件的单元 include 块；dependency 对另一个单元执行 DEPENDS_ON；本地 terraform source 对其 Folder 执行 IMPORTS。路径可以使用 find_in_parent_folders、dirname 和 get_terragrunt_dir；其他情况均视为未知，不建立链接
• Ansible（via: ansible）：剧本或任务文件（顶层为序列的 YAML 文件）对其指令所指定的对象执行 IMPORTS（local_name 为指令）：import_playbook 指向剧本；include_tasks / import_tasks / include 指向任务文件（从其目录查找，否则从其角色的 tasks/ 查找）；roles: 项目和 include_role / import_role 指向角色的 Folder（其目录及以上层级的 roles/<name>）。模板化目标不建立链接。每个任务和处理程序都是一个 Function（使用其 name: 命名，否则使用其模块名；source: ansible、kind、module），由其文件 DEFINES：包括剧本中的 plays、角色的 tasks/ 和 handlers/ 文件，以及这些文件所包含的文件；block 定义其中的任务，而非 block 本身。notify 对其名称或 listen 主题对应的每个处理程序执行 CALLS（via: notify），范围是任务所属角色（否则为其文件）。kube（kubespray 的模块）或 kubernetes.core.k8s 任务对其剧本渲染并应用清单所用的仓库文件执行 DEPLOYS（via: ansible、module）：即目标为该任务 filename 的 template（位于角色的 templates/）或 copy（位于其 files/）任务，逐项解析剧本声明的 register / with_items / loop 列表（字面列表、set_fact、角色的 defaults / vars），或解析 k8s 的 template: 参数
• EMITS、LISTENS_ON（通道）
• DATA_FLOWS，含参数到形参的映射及字段访问链
• SIMILAR_TO（MinHash + LSH 近克隆检测，按 Jaccard 评分）
• SEMANTICALLY_RELATED（词汇不匹配、同语言，评分 ≥ 0.80）

索引流水线

• 162 种随附的 tree-sitter 语法已编译到二进制文件中
• 通用包 / 模块解析：通过扫描清单文件（package.json、go.mod、Cargo.toml、pyproject.toml、composer.json、pubspec.yaml、pom.xml、build.gradle、mix.exs、*.gemspec）解析 @myorg/pkg、github.com/foo/bar、use my_crate::foo 这类裸说明符
• 基础设施即代码索引：Dockerfile（Dockerfile.*、*.Dockerfile、Containerfile：基础镜像、容器运行的内容、ENV），容器镜像（Image：边上记录规范化后的仓库、标签和摘要；由多个 Dockerfile 构建的仓库每个组件对应一个标签，每个组件都会获得一个 Image），docker compose 服务（Resource），Kubernetes 清单（Resource，包含 group、version、kind、namespace、labels，格式为 k=v,k2=v2），Kustomize 覆盖层（IMPORTS 指向其条目和补丁文件，OVERRIDE 从其补丁指向目标），Helm chart（Chart、DEPENDS_ON），Terraform / OpenTofu（.tf、.tofu、.tfvars）作为图节点。Service 会一路追踪到其运行的代码：Service → 工作负载 → Image → Dockerfile → main
• 面向 Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin、Rust 和 Perl 的**混合式 LSP 语义类型解析**；采用轻量级 C 实现的语言类型解析算法，在结构上受 tsserver / typescript-go、pyright、gopls、Roslyn、Eclipse JDT 和 rust-analyzer 等主流语言服务器启发并与之兼容（参数绑定、返回类型推断、泛型替换、JSX 组件分派、普通 JS 文件的 JSDoc 推断、PHP 的命名空间 + trait + 延迟静态绑定解析、C# 的文件范围命名空间 + record + LINQ 方法语法、Java 的类层次结构 + 重载 + lambda 解析、Kotlin 的扩展函数 + 作用域函数解析、Rust 的 trait 方法 + UFCS 解析）
• 以内存为先的流水线：LZ4 压缩、内存中的 SQLite，最后统一转储。之后释放内存。

分发与运行

• 原生运行时套件，无需基础设施服务：基于 SQLite，持久化到 ~/.cache/codebase-memory-mcp/
• 自动同步：后台监视器会检测活跃 MCP 会话注册的项目中的文件变更，包括成功的显式 index_repository 目标，并自动重新索引。
• 路由节点：REST 端点是图中的一等实体
• CLI 模式：codebase-memory-mcp cli search_graph --project my-project --name-pattern ".*Handler.*"
• 可通过以下渠道获取：npm、PyPI、Homebrew、Scoop、AUR、go install

索引模式

团队共享图谱工件

共享压缩后的图谱快照，让队友可以复用已建立索引的基线。

.codebase-memory/graph.db.zst 是与源代码放在一起的知识图谱 zstd 压缩快照。该工件为可选项：只有在设置 persistence: true 时（默认值为 false），index_repository 才会写入它；创建后，后续索引也会刷新它。本地索引始终会持久化。队友在已有该工件的克隆仓库中建立索引时，CBM 会导入该基线，并增量应用本地更改。

• 格式：SQLite 数据库，剥离索引后通过 VACUUM INTO 压缩，再使用 zstd 1.5.7 压缩（通常压缩比为 8 至 13:1）
• 两个级别：
  • 最佳（zstd -9 + 剥离索引 + VACUUM INTO）；由设置了 persistence: true 的 index_repository 写入
  • 快速（zstd -3）；每隔一次索引就会刷新现有工件，包括监视器的低延迟增量更新
• 引导：如果本地数据库不存在但工件存在，index_repository 会先导入工件，然后执行增量索引，并尽可能复用共享基线
• 合并策略：首次导出会创建 .codebase-memory/.gitattributes，其中设置了 merge=ours。依赖此设置处理并发工件更新前，请检查仓库的 Git 合并驱动配置。
• 谨慎提交：每次索引都会重写工件，包括监视器的快速级别更新；Git 会将每次重写存储为一个完整的新 Blob。每次刷新都提交，会让一个 20 MB 的文件积累出数 GB 的历史记录；有一个团队仅此路径的约 350 次提交就累计了约 6 GB。请选择合适的提交频率（例如发布、里程碑或每晚任务），不要每次保存都提交。
• 如果必须在每次提交时移动文件，可使用 Git LFS：在仓库根目录的 .gitattributes 中跟踪该文件，并保留自动创建的 .codebase-memory/.gitattributes；更近的文件会继续提供 merge=ours，只有 filter 来自根目录：

  .codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text
  

  仅跟踪 .zst 文件；artifact.json 很小，且包含架构版本。该属性仅适用于后续提交。删除现有 Blob 需要单独迁移历史记录。采用 Git LFS 前需权衡两项成本：GitHub 会对 LFS 存储和带宽计量，且无法在不联系支持团队的情况下清理其对象；此外，每位队友都需要执行 git lfs install。否则，他们检出的会是指针文件，而非工件；完整性检查会拒绝导入该文件，他们只能退回到完整重建索引。
• 可选：共享导出是可选的，是否提交 Git 也由你决定。如果希望所有人都从头重新建立索引，可将 .codebase-memory/ 添加到 .gitignore。

该工件提供共享基线，同时每位开发者都保留自己的本地查询数据库。

工作原理

codebase-memory-mcp 是一个结构分析后端：它构建并查询知识图谱。该后端不需要生成式模型，而是依靠你的 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

使用 MCP 时，编码 Agent 会将问题转换为工具调用。CBM Lens 也可以使用可选的浏览器模型提供解释；这不会改变后端索引或查询代码的方式。

性能

Apple M3 Pro 上发布的后端基准测试。这些测试与 CBM Lens 检查相互独立：

内存感知型流水线：索引过程中，热点数据保留在内存中；必要时，可将提取结果写入磁盘。索引完成后，内存会释放回操作系统。

上下文更聚焦，令牌更少：该项目的 31 个仓库预印本 报告称，与逐文件探索相比，令牌用量降低 10×，工具调用次数减少 2.1×。这些 2026 年 3 月的后端测量涵盖了研究中的工作负载和 Agent 配置；论文记录了完整的评估过程。较早的一项五条查询的对比报告称，结构化查询的令牌用量约为 3,400 对 412,000。研究中的系统性能测量包含上述 Linux 索引和 Cypher 耗时。

参阅测量指南，评估自有工作负载的质量、延迟和令牌用量。

故障排查与诊断

codebase-memory-mcp 在本地建立索引并执行查询，不收集任何遥测数据。如果遇到我们无法在本地复现的问题（例如，数小时内内存缓慢增长、性能回退，或仅在实际使用数天后才出现的泄漏），**除非你选择发送诊断数据，否则我们无法获取任何诊断信息。**下面介绍如何自行捕获诊断数据。

捕获诊断日志

在第一个由守护进程支持的 MCP 会话启动前设置 CBM_DIAGNOSTICS=1，然后复现问题（让程序按需运行足够长的时间；缓慢泄漏需要时间才能从趋势中显现）。共享守护进程会采用启动它的会话中的此设置。如果守护进程已经在运行，请关闭所有由守护进程支持的会话，使其退出后再更改此设置。守护进程会在系统临时目录下创建一个全新的、仅所有者可访问的 cbm-diagnostics-<pid>-<random> 目录（macOS/Linux 上为 $TMPDIR 或 /tmp，Windows 上为 %TEMP%）。确切路径记录在 ${CBM_CACHE_DIR}/logs/cbm-daemon.log 的 diagnostics.start 事件中：

这个私有随机目录可防止其他本地账户预先在可预测的诊断路径上放置链接或特殊文件。其 <pid> 部分是共享守护进程的进程 ID，也记录在 daemon.start 事件中。请在每个 Agent 的 MCP 服务配置中的 env 块里一致地设置该变量，或在启动第一个会话前导出该变量。

需要分享的内容

提交内存／性能问题时，请附上 .ndjson 轨迹：其中不包含源代码或查询文本，只包含资源计数器。如果您不方便附上文件，也可以将其（或 Agent 对其的总结）粘贴到问题中：您的助手可以直接读取 NDJSON，并报告 rss／committed 是否持续增长、增长速度如何，以及增长与查询数量的关系；这些信息正是我们查明原因所需要的。

安装

预编译二进制文件

每个版本都包含带有 SHA-256 哈希值的 checksums.txt。该可执行文件是独立的；无需配套数据文件。Linux -portable 压缩包包含完全静态构建版本；普通平台压缩包使用其原生系统 ABI。

Windows 提示：SmartScreen 可能会对未签名软件显示警告。点击 “更多信息” → “仍要运行”。请使用 checksums.txt 验证完整性。

安装脚本

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

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

Nix（flake）

该 flake 提供两个服务软件包和独立的前端：

无需安装即可直接运行：

# Standard server
nix run github:DeusData/codebase-memory-mcp

# Server with CBM Lens embedded
nix run github:DeusData/codebase-memory-mcp#codebase-memory-mcp-ui -- --ui=true --port=9749
# then open http://127.0.0.1:9749

或者将二进制文件构建到 ./result/bin/codebase-memory-mcp：

nix build github:DeusData/codebase-memory-mcp                          # standard
nix build github:DeusData/codebase-memory-mcp#codebase-memory-mcp-ui   # with UI

在克隆仓库中工作？使用 . 替代 flake URL，例如 nix run .#codebase-memory-mcp-ui -- --ui=true；或者进入一个会将二进制文件加入 PATH 的 shell：nix shell .#codebase-memory-mcp-ui。

**注意：**手动启动（而非通过 MCP 客户端启动）时，服务会在 stdin 关闭后立即退出；这是正常的 MCP 行为。测试 UI 时请保持 stdin 开启，例如：sleep infinity | codebase-memory-mcp --ui=true --port=9749。codebase-memory-mcp-ui 软件包在构建时内嵌了 UI；使用标准 default 软件包运行 nix run 并附加 --ui=true 时，HTTP 服务将拒绝启动。

通过 Claude Code 安装

You: "Install this MCP server: https://github.com/DeusData/codebase-memory-mcp"

从源代码构建

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh --with-ui          # the shipped composition (CBM Lens embedded, needs Node.js)
scripts/build.sh                    # without the UI (development only)
# Binary at: build/c/codebase-memory-mcp   (codebase-memory-mcp.exe on Windows)

使用 --with-ui 构建时，会将 CBM Lens 和 Agent 集成模板嵌入原生可执行文件。运行该可执行文件无需 Node.js。选择启用后，可选的浏览器模型权重将单独下载。

测试

main 分支上 4d9592b5 提交时的计数，该提交加入了 CBM Lens。原生和 Go 测试计数使用 macOS 配置；不同平台的注册项有所不同。

运行原生测试套件：

scripts/test.sh                     # full: clean sanitizer build + all suites + guards
scripts/test.sh --suites <name>     # one suite, incremental, seconds
build/c/test-runner --list-suites   # what is available

前端开发和验证：

cd graph-ui
npm ci
npm run test:unit
npm run build
npm run dev

开发服务器监听端口 5173，并将 /api 和 /rpc 代理到端口 9749。请先启动匹配的 CBM 后端。

各包包装器都有自己的测试命令：在 pkg/go 中运行 go test ./...，在 pkg/npm 中运行 npm test，在 pkg/pypi 中运行 python3 -m unittest discover -s tests -p 'test_*.py'。Go 包装器要求 Go 1.26.1 或更高版本。

scripts/test.sh 是 CI 使用的 C 测试入口。标准的本地制品流程检查会构建经过剥离和未剥离的候选文件；对于这次明确未扫描的本地运行，默认选择经过剥离的候选文件；然后打包这些确切字节、解压归档并进行冒烟测试：

scripts/ci/smoke-artifact.sh <linux|darwin|windows> <amd64|arm64>

scripts/package-release.sh 是一个刻意设置在更低层级的不可变边界： 它只接受已最终确定的 --selected-binary 及其 --expected-sha256；绝不会构建、剥离、签名或重新链接可执行文件。

手动配置 MCP

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

多 Agent 支持

install 配置 45 个受支持的自动/条件客户端界面：其中 39 个可自动检测，6 个为条件启用或显式配置。“条件启用”表示：只有在文档所述的平台条件满足，或明确指定的配置路径已存在并能证明目标处于活动状态时，安装程序才会写入配置。它绝不会切换实验性功能标志、启用插件、YOLO 模式、全局权限绕过，或第三方指令信任。

对于具有文档所述自定义 Agent 格式的客户端，安装程序会根据一份规范契约创建三个完全由其管理的定义：

• Scout（Tier 1）：约 3 到 4 次范围狭窄的调用，用于快速发现正向的临时结果；不得声称不存在相关内容、影响范围穷尽无遗或代码已失效。
• Verify（Tier 2，默认）：针对任务的图证据、精确的源代码检查、对每个引用文件的路径覆盖，以及作出否定性结论前的范围覆盖。
• Auditor（Tier 3）：有界的范围、当前索引代次、完整的相关分页、更广泛的关系检查，以及明确说明尚未解决的限制。

每个直接层级都会批量调用 check_index_coverage 检查其证据路径，并直接读取标记的代码范围或跳过/排除的文件。覆盖检查结果无缺漏仅表示“未记录到缺口”，绝不代表完整性已得到证明。无法安全访问子 MCP 的客户端会获得相同的三个层级，并作为由父级交接的 Agent；父级必须提供项目、代次、分页状态、图证据和覆盖检查结果。更新只会迁移字节完全相同的旧 Verify 定义，绝不会覆盖用户修改过的 Agent。

会话、压缩和子 Agent

本项目安装的钩子采用失败开放策略，且仅提供上下文。Claude Code 的 PreToolUse 会监视 Grep/Glob/Bash，并将匹配的图谱符号作为 additionalContext 注入；Read 的 PostToolUse 会在图谱无法完整解析或索引该文件时，添加针对性的覆盖上下文。它绝不会拒绝或替换所请求的工具调用。Codex CLI 的 Bash PreToolUse 会为其 Shell 搜索提供相同的上下文。GitHub Copilot CLI 和 VS Code 的 Copilot 运行时会在搜索完成后获取上下文：它们的 preToolUse 只能决定权限，因此 Bash、 Grep 和 Glob 的 PostToolUse 条目会将图谱符号附加到工具结果中。

Claude Code、Codex CLI、Qwen Code、GitHub Copilot CLI 和 VS Code 的 Copilot 运行时，在供应商提供有文档说明的上下文输出约定时，会获得成对的会话/子 Agent 上下文。Codex 用户必须通过 /hooks 检查并信任已安装的钩子；更改钩子定义会改变其信任哈希，因此更新后可能需要重新信任。Qoder 使用 SessionStart、SubagentStart 和 Read 后的覆盖上下文，包括其在 Windows 上有文档说明的 PowerShell 执行器。Kimi 使用 UserPromptSubmit，Hermes 使用 pre_llm_call；两者都保留了各自有文档说明的 Windows 执行路径。Devin 会在 macOS/Linux 上安装 UserPromptSubmit 和 PostCompaction，并且只有在 Claude 的等效托管钩子不存在时才添加 SessionStart。GitLab Duo 会在其实验性钩子接口上添加一个范围严格限定的 macOS/Linux 用户级 SessionStart 条目。由于 GitLab Duo、Devin 和 Factory 未在 Windows 上说明确定性的 Shell/执行器约定，因此不会在 Windows 上安装它们的钩子。Gemini CLI、Factory Droid 和 Augment 也会添加有文档说明的读取/查看后覆盖上下文，但没有提供等效且有文档说明的子任务启动上下文。

对于没有稳定上下文生成生命周期事件的运行时，持久化文件会在新会话和压缩期间传递约定：验证图谱项目和索引是否最新，在父级中查询结构化事实，然后在每个委派任务中传递项目、限定名称的符号、路径和调用链证据。 Claude、Codex、Gemini、Kiro、Qwen、Copilot、CodeBuddy、OpenCode、Kilo、Vibe、 Qoder、Junie、Factory 和 Grok Build 都会获得 Scout、Verify 和 Auditor 图谱配置。 Kiro 使用 --tool-profile scout 将此 MCP 服务配置为 Scout，并使用 --tool-profile analysis 配置为 Verify/Auditor。Junie 会注册等效的命名服务别名，因为其子 Agent 架构按服务而非单个工具进行筛选。这两种进程配置都使用正向允许列表：Scout 提供七个快速检查工具，Analysis 提供十一个，而未来工具或可变更数据的工具在明确审核前均不可用。如果任一 Junie 别名与用户配置冲突，安装程序会保留用户配置，并安装父级移交配置。Qoder 会将其有文档说明的命名服务选择与精确的分级 MCP 工具 ID 结合使用。Factory 使用精确注册的 MCP 工具 ID，不使用会暴露整个服务的增补字段 mcpServers。Codex、Kilo、Vibe 和其他支持此功能的格式同样会枚举范围最窄的受支持工具集。Rovo、Cursor、Augment、Pochi 和 Cline 在直接使用子级 MCP 不可用或不安全时采用父级移交；Pochi 仅限使用 readFile，而 Cline 子 Agent 无法使用 MCP。 Cline 的文件钩子只要存在就会自动激活，而当前版本的 Cline 无法可靠地使用其上下文输出，因此不会安装自动适配器，并会清理旧的自有适配器。CodeBuddy 的测试版、受版本限制的钩子不会自动安装。Junie 的 EAP SessionStart 输出有文档说明会被忽略，因此不会安装上下文钩子。Junie 自定义 Agent 仍取决于 EAP。Qoder 可能会优先解析优先级更高的项目级或插件 Agent，而不是同名的用户级 Agent；安装或更改配置文件后，请重新加载客户端。 Cursor 上下文 钩子不会安装：会话上下文注入存在已知的竞态，subagentStart 仅用于控制，而且只读子 Agent 无法安全地获得 MCP 访问权限。Grok Build 的被动钩子事件（SessionStart、SubagentStart、PostToolUse）会丢弃标准输出，而 PreToolUse 只处理拒绝／重写决策，因此不会安装其上下文钩子；Grok 还会通过兼容层读取 Claude 和 Cursor 的 MCP、技能及钩子文件，而原生 config.toml 条目会按名称覆盖这些文件。Rovo 没有文档说明的会话上下文输出钩子，Bob 也没有文档说明合适的钩子或自定义 Agent 接口。这些接口不会通过臆造的增强方式来模拟。Kimi 插件、Amp 插件和 GitLab 实验性全局技能仍需选择启用。

OpenClaw 会在压缩后重新注入 Codebase Knowledge Graph (codebase-memory-mcp) AGENTS 部分，并将相同的指导内容放入 TOOLS.md，也就是其子 Agent 继承的引导文件。自动增强适用于当前／默认工作区。对于单独的 agents.list[].workspace 目录，需要在安装时将该工作区设为活动工作区，或将受管理的区块复制到该目录。

已安装的 Claude 垫片命名为 cbm-code-discovery-gate，以保持向后兼容；尽管名称沿用旧称，它绝不会进行门控或拦截。

手动或由 UI 管理的集成

以下集成有意不计为自动安装：Qodo MCP 通过其 UI 添加，并可能受企业允许列表限制；Warp MCP 通过 Warp Drive／UI 或按次调用进行管理（只有共享技能会自动安装）；JetBrains AI Assistant／ACP 由 IDE 管理；GitHub Copilot 编码 Agent、Jules 和 CodeRabbit 由云端／代码仓库管理；Replit 提供的是远程服务集成，而非稳定的本地用户全局客户端；BLACKBOX AI 没有文档说明稳定的任意用户全局 MCP／指令／Agent 架构；Plandex 没有可安全修改的稳定全局注册表；SWE-agent 使用显式 YAML，已不适合作为自动全局目标。

CLI 模式

每个 MCP 工具都可以作为本地的一次性命令调用。CLI 工具会连接共享协调守护进程（如果没有正在运行的实例，则启动一个），为命令运行期间获取崩溃安全的精确构建版本准入租约；它们绝不会向后台监视器注册。如果命令必须自行启动守护进程，则在命令的连接关闭且没有其他会话使用该守护进程后，守护进程也会退出。index_repository 是唯一的内部例外：它会为索引启动一个临时的、精确构建版本的受监督工作进程，然后在 CLI 命令退出前停止该进程；该工作进程会一直持有自己的租约，直到退出。

会修改图数据的命令会使用由操作系统支持的共享项目级锁。这样可将同一项目上 CLI 与 MCP 会话的冲突操作串行化，同时允许彼此无关的项目独立进行。 当标准错误输出指向交互式终端时，CLI 会自动显示生命周期和索引进度。传入 --progress，可在标准错误输出被重定向或命令以非交互方式运行时强制显示相同的反馈。传入 --quiet，可禁用自动终端进度和常规诊断信息，同时保留错误；它不能与 --progress 或外层 cli --verbose 同时使用。默认不显示常规信息日志；传入外层 cli --verbose 可将其纳入输出。进度和日志使用标准错误输出，而标准输出仅用于命令结果。读取工具默认返回精简树形结构；传入工具的 --format json 可获取机器可读的载荷 JSON，或传入外层 --json 获取完整的 MCP 信封。

大型精简树形表格可能会以响应内的 <section>_refs 目录和显式的 <section>_ref_rule 开头。像 @0+handler.go 这样的单元格，会还原为 ref 0 的前缀加上 handler.go。引用仅在同级的 <section> 表格内有效，且不会递归展开：<section>_refs 中的条目始终是原样前缀。此功能仅适用于已声明的路径和限定名称列，且只有当完全渲染后的表格至少缩小 15% 且减少 64 字节，同时模型中立的保守令牌形状代理指标也至少改善 1% 时才会启用。搜索和追踪同样会渲染直接和前缀分组的树形结构，并保留较小的完整表示，因此单条或分散的结果不会产生目录开销。每个表格只声明一次键，但绝不会用难以理解的缩写；--format json 会为机器端使用者保留稳定的字面字符串。两项门槛均为确定性的；精确的令牌数量仍取决于调用方使用的分词器。

精简响应会按语义截断，绝不会随意截断代码或标识符中的字节。排序后的图数据行优先于原始 grep 行和诊断摘要；被省略的行或部分会报告总数、has_more 以及严格递增的续传偏移量或游标。如果连第一条完整数据行都无法容纳，CBM 会要求提高预算，且不会发出导致无限循环的游标。max_output_tokens 是与模型无关的大小参考：CBM 会强制执行确定性的上限，即每个请求令牌最多对应 4 个 UTF-8 字节，因此它并非分词器精确计数。diagnostics、source_mode 和 detail 等详细信息标志用于启用较重的字段。search_code 使用 result_limit/result_offset 翻页获取排序后的数据行（limit 仍是兼容性别名），使用 raw_limit/raw_offset 翻页获取原始数据行，并使用 directory_limit/directory_offset 翻页获取目录摘要。原始行默认返回以匹配位置为中心且符合 UTF-8 安全要求的预览；每行会报告 content_start_byte、返回和总字节数、已知的匹配字节范围，以及内容续传偏移量。传入 raw_content_offset 可翻页查看原始行，而不移动原始数据行游标。match_limit 和 source_max_lines 会限制每项结果的详细信息，并提供精确的省略元数据。detect_changes 会分别翻页获取变更文件、受影响的符号和模块摘要；优先使用与快照绑定的 *_cursor 续传，这些游标会拒绝已变更的提交、工作树字节、图生成版本或语义参数，而不会静默跳过或重复数据行。

所有响应均采用标准 UTF-8。标识符、路径和原始搜索预览会保留 POSIX 字节串的原始身份：若保留的值包含格式错误的 UTF-8，则会以 @bytes:<每个原始字节的小写十六进制> 的可逆形式输出。若有效的保留值本身以保留前缀 @bytes: 或 @utf8: 开头，则会以 @utf8:<原始值> 的形式输出，从而确保解码时不存在歧义：对于字面 UTF-8，去掉一个 @utf8: 前缀；对于原始字节，对一个 @bytes: 前缀进行十六进制解码。普通的有效 UTF-8 保持不变，不会增加输出令牌开销。为确保代码可读，源码正文会将格式错误的 UTF-8 替换为 U+FFFD；如需按字节精确检查源码，请使用可翻页的原始搜索预览。 使用 cli <tool> --help 查看根据该工具输入架构生成的标志：

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'

# Force human-readable progress without contaminating stdout.
codebase-memory-mcp cli --progress index_repository --repo-path /path/to/repo
# Suppress automatic terminal progress and non-error diagnostics.
codebase-memory-mcp cli --quiet list_projects --format json
codebase-memory-mcp cli search_graph --project my-project --label Function --format json
codebase-memory-mcp cli list_projects --format json --detail stats | jq '.projects[].name'

需要参数的工具接受通过 stdin 管道传入的 JSON。只有可选参数的工具（例如 list_projects）接受标志、--args-file，或重定向的 JSON 文件，不会等待继承的管道。为保持向后兼容，仍接受内联 JSON，但已弃用，建议改用标志、--args-file 或 stdin。

MCP 工具

索引

耗时较长的索引与客户端调用截止时间。 对大型代码库执行同步 index_repository 可能会超过 MCP 客户端允许的单次工具调用时长（有些 IDE 客户端会在固定截止时间后放弃）。当客户端取消调用或断开连接时，如果没有其他等待者，守护进程会取消索引，因此重试相同的阻塞调用也无法完成。请改用异步模式：

1. index_repository(repo_path="/abs/path", async: true) 会在守护进程中启动索引（如果该项目已有索引任务在运行，则加入该任务），并立即返回包含 state（queued/running）的结果。即使客户端取消调用、超时或断开连接，任务仍会继续运行；只有停止守护进程才会终止任务。
2. index_repository(repo_path="/abs/path", status: true) 会报告 state（queued、running、cancelling、succeeded、failed、cancelled）、started_at、finished_at 和 error 摘要。持续轮询，直到状态为 succeeded、failed 或 cancelled。传入相同的 repo_path（如果索引调用使用了 name，也需传入）。

async 和 status 不能同时使用；async 不适用于 cross-repo-intelligence。两者都需要由守护进程支持的服务（默认的 codebase-memory-mcp 入口点）。临时守护进程（按需启动，而非通过 codebase-memory-mcp daemon start 启动）会在最后一个客户端断开连接时停止并取消其任务。保持 MCP 会话连接即可让它持续运行，因此可以在编辑器中使用异步模式。如果 codebase-memory-mcp cli index_repository --async 是守护进程唯一的客户端，调用会因任务在命令退出时立即终止而被明确拒绝：请先运行 codebase-memory-mcp daemon start，保持 MCP 会话打开，或在不带 --async 的情况下调用。status 在任何情况下都可用。同步调用被提前中断后，该项目接下来的 index_repository 或 status 调用会附带一个 notice，建议使用异步模式。index_status 仍会描述已发布的图及其新鲜度。

查询

manage_adr(mode='set_sections') 按名称写入一个或多个章节，并将其插入存储的文档中，因此指定章节之外的文本（包括前言、代码围栏和章节顺序）都会逐字节保留。任何 ## Heading 均有效，不限于常见的 PURPOSE / STACK / ARCHITECTURE / PATTERNS / TRADEOFFS / PHILOSOPHY 集合；名称必须完全匹配，包括大小写。同一章节重复写入不会产生任何变化，因此响应丢失后重试不会造成内容重复。

manage_adr 查询模式（get 和 sections）使用服务端缓存的查询存储，因此即使同一项目正在重新索引，也可以继续执行。如果另一个进程在重新索引期间发布了替代存储，这些查询可能会返回发布前的 ADR，直到空闲驱逐刷新该缓存。更新仍通过项目变更保护机制按顺序执行。

图数据模型

节点标签

Project、Package、Folder、File、Module、Section、Class、Struct、Interface、Trait、Enum、Type、Function、Method、Field、Variable、Constant、Macro、Decorator、Route、Channel、Table、Process、EnvVar、Resource、Chart、Image、Branch

边类型

CONTAINS_FOLDER、CONTAINS_FILE、DEFINES、DEFINES_METHOD、IMPORTS、CALLS、CALL_REFERENCE、USAGE、INHERITS、IMPLEMENTS、OVERRIDE、DECORATES、RAISES、THROWS、WRITES、DATA_FLOWS、HTTP_CALLS、GRPC_CALLS、ASYNC_CALLS、EMITS、LISTENS_ON、HANDLES、SPAWNS、CONFIGURES、INFRA_MAPS、CONNECTS_TO、DEPLOYS、DEPENDS_ON、REFERENCES_FILE、MENTIONS、TESTS、TESTS_FILE、SIMILAR_TO、SEMANTICALLY_RELATED、FILE_CHANGES_WITH、HAS_BRANCH，以及跨仓库类型 CROSS_HTTP_CALLS、CROSS_GRPC_CALLS、CROSS_GRAPHQL_CALLS、CROSS_TRPC_CALLS、CROSS_ASYNC_CALLS、CROSS_CHANNEL

MENTIONS 会将文档中的定义关联到其文档注释引用的代码（C# <see cref>、<seealso cref>、<exception cref>、<inheritdoc cref>），每对引用对应一条边，包含 via、syntax、tier（exact 或 unique）、首个 line 和 count。只有当引用名称按照该语言自身的查找规则恰好指向一个定义时，才会绑定；其余情况会按原因计入 index_status 的 doc_links 中（使用 diagnostics='full' 的示例）。

限定名称

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          # remove/disable all background watches (default: true)
codebase-memory-mcp config set doc_candidates false      # skip doc<->code candidate scoring on huge repos (default: auto = on for full, off for moderate/fast)
codebase-memory-mcp config set watcher_enabled false     # stop the watcher thread entirely (default: true)
codebase-memory-mcp config set watch_non_git true        # also poll non-git project roots (default: false)
codebase-memory-mcp config set index_max_files 250000    # optional per-index source-file limit
codebase-memory-mcp config set index_max_source_mb 16384 # optional per-index source-size limit
codebase-memory-mcp config reset auto_index              # reset to default

两个 index_max_* 设置的默认值均为 off。超出任一限制都会导致整个索引尝试失败，而不会发布不完整的图；现有的服务中索引会得到保留。请参阅 索引资源限制。

环境变量

守护进程拥有的组件（例如诊断、守护进程日志记录和进程级索引资源限制）所使用的环境变量，会从第一个启动该守护进程的守护进程会话中捕获。后续会话会加入该进程，且无法替换这些值。要更改这些值，请关闭所有守护进程会话，统一更新相关 Agent 配置，然后重启会话。CBM_ALLOWED_ROOT 仍按会话生效；冲突的 CBM_CACHE_DIR 会被拒绝；一次性 CLI 命令也不例外：它与其他会话一样连接到协调守护进程；若没有正在运行的守护进程，则会启动一个。只有当该命令的调用负责启动守护进程时，它自身的环境才会成为被捕获的守护进程环境；若加入已在运行的守护进程，则会继承该守护进程已捕获的值。

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

自定义文件扩展名

JSON 配置文件支持一个键 extra_extensions，用于将其他文件扩展名映射到受支持的语言。适用于框架专用扩展名，例如 .blade.php（Laravel）或 .mjs（ES 模块）。（其他可调参数请参阅环境变量和上方的 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"}}

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

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

对于冲突的扩展名，项目配置会覆盖全局配置。语言名称未知，或扩展名不以 . 开头的条目会被跳过，并记录为警告。缺失的配置文件会被忽略。

持久化

SQLite 数据库存储在 ~/.cache/codebase-memory-mcp/ 中。重启后数据仍会保留（WAL 模式，符合 ACID）。如需重置：rm -rf ~/.cache/codebase-memory-mcp/。

故障排除

混合 LSP

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

单独使用 Tree-sitter 只能提供语法 AST。它能很好地处理命名、结构和调用位置，但无法判断 user.profile.display_name() 指向的是在三个模块之外声明的 Profile.display_name；Tree-sitter 不会跟踪导入、泛型、继承或标准库类型。 codebase-memory-mcp 内置了轻量级 C 语言实现的类型解析算法，其结构受到主流语言服务器（tsserver / typescript-go、pyright、gopls、Roslyn、Eclipse JDT、rust-analyzer）的启发，并与之兼容，并直接嵌入原生可执行文件中。无需语言服务器进程、无需针对每个项目进行设置，也无需 API 密钥。我们将这一层称为 Hybrid LSP：它会在每次解析时与 tree-sitter 并行运行，并利用类型信息优化调用解析（CALLS / RESOLVED_CALLS）和可调用值解析（CALL_REFERENCE，同时将有歧义的值保留为 USAGE），使生成的图能够反映 IDE“转到定义”所解析的目标。

支持完整 Hybrid LSP 的语言：

双层架构：

1. Tree-sitter 阶段：快速、基于语法，对全部 162 种语言运行。提取定义、调用和导入。
2. Hybrid LSP 阶段：支持类型感知，在 tree-sitter 阶段之后按语言运行。利用导入图以及逐文件或预构建的跨文件定义注册表来优化调用边。尚未支持 Hybrid LSP 阶段的语言会回退到文本解析，覆盖率因语言和结构而异。 最终得到的知识图谱足够准确，可在软件包、继承层级和标准库调用之间执行 trace_path；无需为每个项目单独运行语言服务器进程。

语言支持

支持 162 种语言，数量按 解析器清单 中 vendored grammar 目录计算。基准测试覆盖 64 个真实的开源代码库（78 至 49K 个节点）：

也支持以下语言（尚未进行基准测试）：Ada, Agda, Apex, ArkTS, Assembly (NASM), Astro, AWK, Beancount, BibTeX, Bicep, Bitbake, Blade, Cairo, Cap'n Proto, CFML, CFScript, Chialisp, 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, Mojo, Move, Nickel, Nix, ObjectScript (UDL and routines), Odin, Pascal, Pine Script, Pkl, PL/SQL, PO (gettext), Pony, PowerShell, Prisma, .properties, Protobuf, Puppet, PureScript, QML, 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。

架构

src/
  main.c              Entry point (MCP stdio server + CLI + install/update/config)
  daemon/             Per-account session coordination, IPC, lifecycle, shared jobs/watchers
  mcp/                MCP server (17 tools, JSON-RPC 2.0, session detection, auto-index)
  cli/                Install/uninstall/update/config (45 client surfaces, 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/                 Local HTTP server + embedded CBM Lens frontend
  foundation/         Platform abstractions (threads, filesystem, logging, memory)
graph-ui/             CodeAtlasWeb: React, Monaco, and Three.js browser frontend
internal/cbm/         Vendored tree-sitter grammars (162 languages) + AST extraction engine

安全

每次发布都会经过多层流水线验证后再发布：

• VirusTotal：在 smoke/soak 测试前扫描八种发布产品中的全部 24 个可执行文件候选项（未剥离、剥离调试信息和已剥离版本）。优先要求扫描结果干净，且只有 SECURITY.md 中记录的单个 Microsoft !ml 容忍情形可以通过；返回明确结果的引擎数量会作为证据记录，但它反映的是 VirusTotal 集群的可用性，不是通过条件。选定的可执行文件在打包时 SHA-256 保持不变，发布说明会链接到与实际发布字节完全对应的判定结果；每个候选项的完整证据也会以 TSV 文件形式随发布内容一并公开，供任何人审核选择过程。此外，还会扫描从发布容器中提取的每个不同对象、install.sh、install.ps1、LICENSE、THIRD_PARTY_NOTICES.md、MCPB manifest.json 以及解包后的 UI 资源，从而覆盖完整的已发布内容，而不仅仅是可执行文件。
• SLSA Level 3：由可信的 GitHub Actions 构建工作流生成加密构建来源证明；使用 gh attestation verify <file> --repo DeusData/codebase-memory-mcp --signer-workflow DeusData/codebase-memory-mcp/.github/workflows/_build.yml 进行验证
• Sigstore cosign：所有制品均使用无密钥签名；每次发布都包含签名包
• SHA-256 校验和：每次发布都会附带 checksums.txt；两个安装脚本都会在解压前进行验证
• CodeQL SAST：如果仍有未处理的警报，则阻止发布流水线
• 无语言运行时依赖链：原生后端无需语言运行时环境；UI 构建会嵌入前端

VirusTotal 发布扫描

v0.11.0 发布说明报告称，所有 8 个随附二进制文件的扫描结果均为干净。每项结果都对应确切的可执行文件哈希。以下链接展示了这些二进制文件的报告；为便于阅读，显示的哈希已缩短。

该版本还发布了候选版本扫描结果、二进制文件来源信息和筛选记录。后续版本请参阅最新发布版本中链接的扫描证据。

帮助塑造未来

下一个创意可能就来自你。我们欢迎 OSS 社区通过我们的 Discord 社区分享创意、棘手的集成问题和反馈。如果直接交流更合适，也可以在那里联系 DeusData 或项目的共同开发者。让我们携手打造未来。

许可证

MIT