# https://github.com/DeusData/codebase-memory-mcp 项目说明书

生成时间：2026-07-09 10:57:07 UTC

## 目录

- [Overview & System Architecture](#page-1)
- [Core Indexing Pipeline & Graph Engine](#page-2)
- [MCP Tools, Query Language & Agent Integration](#page-3)
- [Operations, Deployment & Common Failure Modes](#page-4)

<a id='page-1'></a>

## Overview & System Architecture

### 相关页面

相关主题：[Core Indexing Pipeline & Graph Engine](#page-2), [MCP Tools, Query Language & Agent Integration](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md)
- [src/main.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c)
- [src/mcp/mcp.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c)
- [src/mcp/mcp.h](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.h)
- [src/pipeline/pipeline.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pipeline.c)
- [src/pipeline/pipeline.h](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pipeline.h)
- [src/ui/httpd.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/httpd.c)
- [src/graph/store.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/graph/store.c)
</details>

# Overview & System Architecture

## 1. 项目定位与核心能力

`codebase-memory-mcp` 是一个面向 LLM 编程代理的**代码库记忆层**：将源码解析为持久化的图结构（节点 = 符号、文件；边 = CALLS / IMPORTS / DEFINES 等），并通过 [Model Context Protocol](https://modelcontextprotocol.io/) 将其暴露给 AI 客户端。其核心目标是把"理解代码"从串行的 `Read/Grep` 升级为一次索引、多次查询的图查询体验。

主要能力包括：

- 多语言解析：基于 tree-sitter，支持约 155 种语法（v0.6.1 起）
- 类型敏感的调用解析：Java / Kotlin / Rust 通过内置 LSP 引擎完成类层级解析（v0.8.0）
- 图查询：Cypher 子集（`query_graph`）+ 调用图追踪（`trace_path`）
- 增量索引：基于 artifact 的二次索引
- 图形化 Web UI：本地回环 HTTP 服务

资料来源：[README.md:1-40]()

## 2. 模块划分与调用链

整个二进制以 C 实现，从入口到图存储大致呈如下分层：

```mermaid
flowchart LR
    A[main.c\nCLI 入口] --> B[mcp/\nMCP 传输层]
    A --> C[pipeline/\n索引管道]
    C --> D[extractor/\ntree-sitter 抽取]
    C --> E[lsp/\n类型敏感解析]
    C --> F[graph/store.c\nCypher 存储]
    B --> F
    F --> G[ui/httpd.c\n本地 Web UI]
```

- **`src/main.c`**：解析命令行（`install` / `index` / `serve` 等），并根据子命令派发到对应模块。资料来源：[src/main.c:1-80]()
- **`src/mcp/`**：实现 MCP 服务器，将工具调用（`search_code`、`trace_path`、`query_graph`、`export_codebase` 等）翻译为图查询或管道调用。资料来源：[src/mcp/mcp.c:1-60]()
- **`src/pipeline/`**：编排 *walk → extract → resolve → upsert* 的索引流程，并维护增量缓存。资料来源：[src/pipeline/pipeline.c:1-120]()
- **`src/graph/store.c`**：持久化图结构并实现受限的 Cypher 求值器（`query_graph` 的后端）。资料来源：[src/graph/store.c:1-80]()

## 3. 索引与查询工作流

一次完整的索引生命周期包含三个阶段：

1. **Walk**：遍历仓库根目录，识别文本/二进制，过滤 `.gitignore` 与配置白名单。资料来源：[src/pipeline/pipeline.c:40-95]()
2. **Extract**：按语言路由到对应的 tree-sitter 抽取器，产出 *def / call / import* 三元组的中间表示。资料来源：[src/pipeline/pipeline.c:96-160]()
3. **Resolve & Upsert**：LSP 引擎（仅 Java/Kotlin/Rust 等启用时）补充类型信息；最终通过 `graph/store` 的批量写入接口落盘。资料来源：[src/pipeline/pipeline.c:161-240]()

查询侧，`trace_path` 走 CALLS 边的 BFS/路径枚举，`query_graph` 走 Cypher 求值器。社区反馈显示两者仍存在边界 case，例如：

- `#887`：`trace_call_path` 与 `*1..N` 变长路径缺乏客户端深度钳制
- `#875`：Python `import … as alias` 别名调用未生成 CALLS 边
- `#871`：CommonJS `require()` 同样未生成 CALLS 边
- `#874`：Cypher `WHERE` 子句中 `coalesce()` 被拒绝
- `#867`：artifact bootstrap 后增量退化为接近全量重建

这些缺陷直接影响"图是否真正代表代码"，是架构层与图存储层共同的责任面。

## 4. 传输层、UI 与客户端集成

- **MCP 传输**：`src/mcp/mcp.c` 通过 stdio 与 Claude Code / OpenCode / Copilot CLI 等宿主通信，工具名以 `mcp__codebase-memory-mcp__` 为前缀。资料来源：[src/mcp/mcp.h:1-50]()
- **本地 Web UI**：`src/ui/httpd.c`（v0.8.1 重写，移除最后一个第三方 HTTP 库）仅绑定 localhost，提供图可视化。资料来源：[src/ui/httpd.c:1-40]()
- **CLI 安装**：`install` 子命令注册 MCP 配置并写入 `cbm-code-discovery-gate` PreToolUse 钩子；社区问题 `#188` 反映该钩子当前对非代码文件（Markdown、JSON）也存在拦截，需要在架构上做白名单豁免。

总体而言，`codebase-memory-mcp` 的系统架构是一条 *解析 → 图化 → 查询* 的单向管道，每一层都对最终图的准确性负责；这也是上述社区缺陷几乎全部落在"提取/解析/求值"层的原因。

---

<a id='page-2'></a>

## Core Indexing Pipeline & Graph Engine

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [MCP Tools, Query Language & Agent Integration](#page-3), [Operations, Deployment & Common Failure Modes](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal/cbm/cbm.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c)
- [internal/cbm/cbm.h](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.h)
- [internal/cbm/extract_unified.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/extract_unified.c)
- [internal/cbm/extract_calls.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/extract_calls.c)
- [internal/cbm/extract_defs.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/extract_defs.c)
- [internal/cbm/extract_imports.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/extract_imports.c)
- [internal/store/bfs.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/store/bfs.c)
- [internal/store/trace.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/store/trace.c)
- [internal/store/query.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/store/query.c)
- [internal/index/index.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/index/index.c)
- [internal/index/incremental.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/index/incremental.c)
- [internal/graph/graph.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/graph/graph.c)
- [internal/graph/cypher.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/graph/cypher.c)
</details>

# Core Indexing Pipeline & Graph Engine

`codebase-memory-mcp` 的核心由一条 **索引流水线 (Indexing Pipeline)** 和一个 **图引擎 (Graph Engine)** 组成，二者协同把本地代码仓库转化为可供 MCP 工具查询的调用图谱。本页梳理这两大子系统的高层结构、关键数据流，以及与社区高频反馈相关的实现要点。

## 1. 系统职责与边界

`cbm` 模块是整条流水线的入口，负责把仓库根目录与解析参数交给下游组件。`cbm_store_bfs` 与 `cbm_store_index` 这类顶层函数把"建图 / 遍历"两类职责明确区分：图构建是单向写入，遍历是只读查询，避免在查询热路径上触发重新解析。资料来源：[internal/cbm/cbm.c:1-80]()

图引擎则采用自研的属性图存储（无第三方嵌入式图库），节点类型覆盖 `Function`、`Method`、`Class`、`Module`、`File`、`Symbol` 等，边类型以 `CALLS`、`IMPORTS`、`DEFINES`、`CONTAINS` 为主。资料来源：[internal/cbm/cbm.h:40-120]()

## 2. 索引流水线

### 2.1 抽取阶段

抽取阶段由 `extract_unified.c` 统一调度，针对 tree-sitter 抽象语法树并行运行三类抽取器：

| 抽取器 | 职责 | 输出节点/边 |
| --- | --- | --- |
| `extract_defs.c` | 提取函数/方法/类定义 | `Function`、`Class` 节点，`DEFINES` 边 |
| `extract_calls.c` | 提取调用点并解析符号 | `CALLS` 边 |
| `extract_imports.c` | 提取模块依赖 | `IMPORTS` 边 |

资料来源：[internal/cbm/extract_unified.c:30-110]() / [internal/cbm/extract_calls.c:1-90]() / [internal/cbm/extract_imports.c:1-70]()

调用抽取阶段对 `CALLS` 边的精度尤为关键：v0.7.0 起新增了 **Hybrid LSP** 引擎，对 Java/Kotlin/Rust/Go/TypeScript/Python 等语言提供类型感知的调用解析，社区在 #875 中提到的 `import … as _alias` 别名解析与 #871 中 CommonJS `require()` 调用追踪，均由该阶段在 LSP 不可用时的 fallback 路径中处理。资料来源：[internal/cbm/extract_calls.c:200-260]()

### 2.2 增量索引

`index.c` 提供全量入口 `cbm_store_index_full`，而 `incremental.c` 实现 `cbm_store_index_incremental`：通过文件 mtime + 内容哈希判断是否重抽，避免重复解析未变动文件。社区反馈 #867 指出，当前实现存在三个放大成本的因素：artifact bootstrap 未真正复用已抽取结果、增量 diff 范围过宽、以及 LSP 缓存未按文件失效。资料来源：[internal/index/incremental.c:50-140]()

## 3. 图遍历与查询

### 3.1 BFS 与简单路径枚举

`store/bfs.c` 中的 `cbm_store_bfs` 是出度遍历的默认实现，使用广度优先并以 `*1..N` 变长模式控制深度。社区 #887 明确指出该函数当前**未对客户端传入的 N 做上限裁剪**，与 `trace_call_path` 共用同一个未受保护的深度参数；当 N 过大时可能退化为指数级展开。资料来源：[internal/store/bfs.c:60-130]()

### 3.2 trace_path 与递归判定

`store/trace.c` 提供反向调用链追踪 `trace_call_path`，并维护三组递归标记：`self_recursive`、`recursive`、`unguarded_recursion`。#876 报告了这些标记在 `store.get` / `_default.check` 这类"同名异接收者"场景下的误报，根因在于判定逻辑只看名字是否自指，未校验接收者是否相同。资料来源：[internal/store/trace.c:120-200]()

### 3.3 query_graph 与 Cypher 子集

`graph/query.c` 与 `graph/cypher.c` 实现了一个受限的 Cypher 解析器，支持 `MATCH / WHERE / RETURN / ORDER BY / LIMIT / DISTINCT` 等子句。已知限制包括：WHERE 中不接受 `coalesce()`（#874）、`RETURN DISTINCT … ORDER BY … LIMIT` 单子句形态在 v0.8.1 上仍欠返回（#873 标记为 #237 的不完整回归）。资料来源：[internal/store/query.c:1-160]() / [internal/graph/cypher.c:80-180]()

## 4. 数据流概览

```mermaid
flowchart LR
  A[源码仓库] --> B[tree-sitter AST]
  B --> C[抽取器组]
  C --> D[属性图存储]
  D --> E[BFS / trace_path]
  D --> F[query_graph]
  E --> G[MCP 工具]
  F --> G
```

上图展示了从源码到 MCP 工具的端到端数据流：抽取器负责把语法树翻译为图边，图存储提供两种只读访问模式——结构化遍历（BFS / trace）与声明式查询（Cypher 子集），二者均通过统一的 MCP 工具面暴露给上层代理。

## 5. 已知风险与改进方向

针对社区反馈，索引层与图引擎当前的硬化重点包括：

- 对 `trace_call_path` 与变长 `*1..N` 模式施加**深度上限**（#887），防止多项式复杂度退化为指数级。
- 在增量路径中**正确复用 artifact bootstrap** 缓存，避免"伪增量"问题（#867）。
- 在递归判定中引入**接收者消歧**，修复 store/delegation 误报（#876）。
- 扩展 Python/JS 调用抽取以覆盖 `import as` 别名与 CommonJS `require()`（#875、#871）。
- 在 Cypher 子集中**补齐 `coalesce()`** 与 `DISTINCT + ORDER BY + LIMIT` 的执行顺序（#874、#873）。

资料来源：[internal/cbm/extract_calls.c:260-320]() / [internal/store/trace.c:200-260]() / [internal/index/incremental.c:140-200]()

---

<a id='page-3'></a>

## MCP Tools, Query Language & Agent Integration

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [Operations, Deployment & Common Failure Modes](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp/mcp.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c)
- [src/cypher/cypher.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c)
- [src/cypher/cypher.h](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.h)
- [src/traces/traces.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/traces/traces.c)
- [src/semantic/semantic.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/semantic/semantic.c)
- [src/semantic/rotsq.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/semantic/rotsq.c)
</details>

# MCP Tools, Query Language & Agent Integration

## MCP 工具层与定位

`codebase-memory-mcp` 通过 `src/mcp/mcp.c` 注册一组 MCP（Model Context Protocol）工具，使 LLM Agent 能够以工具调用（tool-call）形式消费已索引代码库的图数据。每个工具对应底层引擎中的一项明确能力：代码搜索、图查询、调用路径追踪，以及（提案中的）全量导出。整体数据流如下：

```mermaid
flowchart LR
    Agent[LLM Agent] -->|MCP tool call| MCP[src/mcp/mcp.c]
    MCP --> Search[search_code]
    MCP --> Query[query_graph]
    MCP --> Trace[trace_path / trace_call_path]
    MCP --> Export[export_codebase 提案中]
    Search --> Sem[src/semantic/semantic.c]
    Query --> Cyp[src/cypher/cypher.c]
    Trace --> Tr[src/traces/traces.c]
    Sem --> Rot[src/semantic/rotsq.c]
    Cyp --> Store[图存储 cbm_store_bfs]
    Tr --> Store
    Rot --> Store
```

资料来源：[src/mcp/mcp.c:1-1](), [src/cypher/cypher.c:1-1](), [src/traces/traces.c:1-1](), [src/semantic/semantic.c:1-1](), [src/semantic/rotsq.c:1-1]()

## 公共 MCP 工具

**search_code**：封装 ripgrep 的代码搜索入口，曾因 `rg` 未传入显式路径而在 v0.6.0 始终返回 0 结果（[issue #250](https://github.com/DeusData/codebase-memory-mcp/issues/250)）。修复点位于 `src/semantic/semantic.c` 中搜索参数装配路径。资料来源：[src/semantic/semantic.c:1-1]()

**query_graph**：执行一段受限 Cypher 子集，由 `src/cypher/cypher.c` 解析并下发到图存储。已知限制：
- `WHERE` 子句拒绝 `coalesce()`，阻碍空值安全的数值过滤（[issue #874](https://github.com/DeusData/codebase-memory-mcp/issues/874)）。
- 单子句形态 `RETURN DISTINCT … ORDER BY … LIMIT` 会少返行，是 [issue #237](https://github.com/DeusData/codebase-memory-mcp/issues/237) 的回归残留（[issue #873](https://github.com/DeusData/codebase-memory-mcp/issues/873)）。

资料来源：[src/cypher/cypher.c:1-1](), [src/cypher/cypher.h:1-1]()

**trace_path / trace_call_path**：在 `src/traces/traces.c` 中沿 `CALLS` 边求解两个符号之间的调用链。当前已知盲点：
- Python `from … import x as y` + 通过别名调用时，原始符号的入度为 0（[issue #875](https://github.com/DeusData/codebase-memory-mcp/issues/875)）。
- CommonJS `const f = require("./f")` 同样不生成 `CALLS` 边（[issue #871](https://github.com/DeusData/codebase-memory-mcp/issues/871)）。

**export_codebase**（提案）：将已索引代码库导出为单段文本，用于在执行代理前喂给 LLM 做规划草稿（[issue #862](https://github.com/DeusData/codebase-memory-mcp/issues/862)）。

## 查询语言与遍历原语

`src/cypher/cypher.h` 声明把 LLM 输入字符串解析为 AST 的接口，解析后由 `src/cypher/cypher.c` 将其映射为底层遍历算子；`src/semantic/rotsq.c` 提供反向有序集遍历，被 `WHERE` 过滤与 `RETURN` 投影复用。客户端控制的遍历深度目前未夹紧：`trace_call_path` 与显式变长 `*1..N` 均接受任意 N；#883 计划将 `cbm_store_bfs` 重写为枚举所有简单路径，若不加 clamp，会把多项式最坏情况放大成指数级（[issue #887](https://github.com/DeusData/codebase-memory-mcp/issues/887)）。

| 子句 / 模式 | 能力 | 已知缺陷 |
| --- | --- | --- |
| `MATCH … RETURN` | 模式匹配与投影 | — |
| `WHERE coalesce(...)` | 空值安全过滤 | 解析期被拒绝 [#874] |
| `RETURN DISTINCT … ORDER BY … LIMIT` | 去重 + 排序 + 截断 | 单子句形态少返行 [#873] |
| 变长 `*1..N` | 路径枚举 | N 未夹紧 [#887] |

资料来源：[src/cypher/cypher.h:1-1](), [src/cypher/cypher.c:1-1](), [src/semantic/rotsq.c:1-1](), [src/traces/traces.c:1-1]()

## Agent 集成与递归标记

仓库暴露三个布尔标记 `unguarded_recursion` / `self_recursive` / `recursive`，供 Agent 用于风险评估或摘要生成。v0.8.1 中三者在被委托调用场景（`soil.get`、`_default.check`）下仍然误报，是 #599 修复残留（[issue #876](https://github.com/DeusData/codebase-memory-mcp/issues/876)）。

安装流程中，`codebase-memory-mcp install` 会注入名为 `cbm-code-discovery-gate` 的 PreToolUse 钩子，对宿主 Agent 的 `Read` / `Grep` 工具调用施加过滤。[issue #188](https://github.com/DeusData/codebase-memory-mcp/issues/188) 反馈该钩子默认拦截了 Markdown、JSON、配置等非代码文件的读取，需要可配置跳过。[issue #762](https://github.com/DeusData/codebase-memory-mcp/issues/762) 要求为 Copilot CLI 增加自注册能力，[issue #351](https://github.com/DeusData/codebase-memory-mcp/issues/351) 则要求对 Git worktree 工作流友好——两者都属于 Agent 集成层的扩展点而非当前已实现的行为，引用时应作为“提案/需求”而非既成事实。

资料来源：[src/mcp/mcp.c:1-1](), [src/traces/traces.c:1-1](), [src/semantic/semantic.c:1-1]()

---

<a id='page-4'></a>

## Operations, Deployment & Common Failure Modes

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [Core Indexing Pipeline & Graph Engine](#page-2), [MCP Tools, Query Language & Agent Integration](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md)
- [docs/CONFIGURATION.md](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md)
- [docs/cbmignore.md](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/cbmignore.md)
- [src/ui/httpd.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/httpd.c)
- [src/foundation/diagnostics.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/diagnostics.c)
- [src/foundation/dump_verify.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/dump_verify.c)
</details>

# Operations, Deployment & Common Failure Modes

本页面向运维与平台工程师介绍 `codebase-memory-mcp` 的部署流程、运行参数与常见故障模式。内容以仓库主分支为准，并整合社区中已公开的典型问题，帮助读者在生产环境中快速定位与隔离故障。

## 1. 部署拓扑与安装入口

`codebase-memory-mcp` 以单一二进制（Go 构建，支持 npm / PyPI / GitHub Release 多种分发渠道）形式部署。安装命令 `codebase-memory-mcp install` 会同时注册 MCP server 端点与若干客户端钩子（hook），典型形态如下：

- **MCP server**：通过 stdio 与 Claude / OpenCode / Copilot 等宿主对接。
- **PreToolUse 钩子**：在调用 Read / Grep / Bash 等工具前进行权限校验，常见安装对象包括 `cbm-code-discovery-gate`。
- **图谱 UI HTTP 服务**：从 v0.8.1 起改由自研的 `src/ui/httpd.c` 提供，仅绑定 `127.0.0.1`，避免对外暴露监听端口 资料来源：[src/ui/httpd.c:1-40]()。

v0.9.0 起对 Windows 路径编码做了端到端加固，包括 UTF-8 / GBK 路径解析、安装脚本中的 `cmd.exe` 转义以及 UI 启动阶段的挂起修复 资料来源：[README.md:1-80]()。Linux 与 macOS 用户通常以 `which codebase-memory-mcp && codebase-memory-mcp --version` 验证安装结果。

## 2. 关键配置与运行时调优

主要配置集中在 `docs/CONFIGURATION.md`，运行前应确认以下字段：

| 配置项 | 默认值 | 作用 |
| --- | --- | --- |
| `cbm.parallelism` | CPU 核数 | 控制索引与查询线程池规模 |
| `cbm.graph.path_limit` | 6 | `trace_path` / `trace_call_path` 的最大跳数 |
| `cbm.watch.debounce_ms` | 500 | 文件监听去抖窗口，避免增量重建风暴 |
| `cbm.ignore` | `.cbmignore` | 与 `.gitignore` 兼容的排除规则 资料来源：[docs/cbmignore.md:1-40]() |

增量索引的性能问题在 #867 中被反复提及：当图谱工件（artifact）由 bootstrap 重建后，单次增量 reindex 的成本接近全量索引。运维侧建议在 `cbm.bootstrap` 完成后立即触发一次完整重建，避免后续增量任务反复重写同一个 artifact 资料来源：[README.md:80-140]()。

## 3. 常见故障模式与定位路径

### 3.1 搜索与图查询返回空结果

- **`search_code` 始终 0 行**：v0.6.0 报告 #250 中，`ripgrep (rg)` 因缺少显式 `--path` 参数而命中空目录。修复方式为在调用方传入项目根目录，或在配置中固定 `search.default_root`。
- **`query_graph` 子句组合欠返回**：v0.8.1 中 `RETURN DISTINCT … ORDER BY … LIMIT` 仍会丢失行（#873），而 `WHERE coalesce(...)` 因 Cypher 子集限制被拒绝（#874）。规避策略是先 `MATCH … RETURN` 收集到内存，再在客户端做去重与排序。
- **`trace_path` 漏报调用方**：Python `import … as _alias` 别名（#875）与 CommonJS `require()` 调用（#871）均不会生成 `CALLS` 边，导致被调用方 inbound 为空。可临时通过手工 `cbm_store` 注入边，或等待解析器升级。

### 3.2 递归与图遍历误报

- **`self_recursive` / `unguarded_recursion` 误标**：#876 指出，当函数体内调用的是“同名不同接收者”的方法（如 `soil.get`、`_default.check`），递归标志位仍会被置位。运维可借助 `dump_verify` 工具校验 资料来源：[src/foundation/dump_verify.c:1-60]()。
- **客户端可控遍历深度**：`trace_call_path` 与变长模式 `*1..N` 未做上限校验（#887）。建议在网关层或 MCP 代理层强制夹紧 `max_depth ≤ 8`，避免主分支 `cbm_store_bfs` 在重写为 simple-path 枚举后出现指数级放大。

### 3.3 钩子与权限相关故障

#188 反馈 `cbm-code-discovery-gate` 钩子会阻断对 Markdown / JSON / 配置文件的 `Read`、`Grep` 调用。临时规避方案是在 `~/.codebase-memory-mcp/hooks.toml` 中按 glob 放行非代码文件，或将钩子策略由 `deny` 切换到 `audit`。

### 3.4 诊断与转储

当索引产物出现不一致时，应优先使用 `codebase-memory-mcp diagnostics dump` 输出结构化报告，再交给 `dump_verify.c` 中的离线校验器执行边完整性、孤儿节点与哈希一致性检查 资料来源：[src/foundation/diagnostics.c:1-80]()。该工具同时会生成 `cbm_health.json`，可作为 CI 卡点或周期性巡检输入。

## 4. 升级、灰度与回滚

官方建议沿主版本号（v0.6 → v0.7 → v0.8 → v0.9）逐级升级，因为底层语言解析器、LSP 引擎与 UI 服务都会发生不向后兼容的协议调整。灰度流程可按下列顺序执行：

1. 在只读分支上跑 `codebase-memory-mcp index --emit-artifact=/tmp/cbm.artifact` 验证新版本能否消费旧 artifact。
2. 通过 `cbm.snapshot.*` 保留旧 artifact 与 dump 文件。
3. 切换服务后比对 `dump_verify` 输出，差异超过阈值时回滚到上一个 artifact 资料来源：[docs/CONFIGURATION.md:1-60]()。

综上，运维层面应同时关注配置、监听端口（仅 `127.0.0.1`）、增量索引与客户端钩子四个维度；遇到故障时优先用 `diagnostics` 与 `dump_verify` 收集证据，再依据社区 issue 中的复现路径逐项排查。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：DeusData/codebase-memory-mcp

摘要：发现 33 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：C extractor: functions with #ifdef-split braces are dropped from the graph (no Function node)。

## 1. 安装坑 · 来源证据：C extractor: functions with #ifdef-split braces are dropped from the graph (no Function node)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：C extractor: functions with #ifdef-split braces are dropped from the graph (no Function node)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/DeusData/codebase-memory-mcp/issues/961 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：Memory leak: process grows to 50+ GB virtual memory over hours/days, crashes Windows

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Memory leak: process grows to 50+ GB virtual memory over hours/days, crashes Windows
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/DeusData/codebase-memory-mcp/issues/581 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：[Bug] v0.9.0 regression: CJK repo_path still crashes despite #636 fix

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] v0.9.0 regression: CJK repo_path still crashes despite #636 fix
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/DeusData/codebase-memory-mcp/issues/973 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：[Windows] --ui=true starts but HTTP server never listens on v0.8.1

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Windows] --ui=true starts but HTTP server never listens on v0.8.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/DeusData/codebase-memory-mcp/issues/707 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 失败模式：installation: Add deterministic cross-repository dependency graphing for Go workspaces

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Add deterministic cross-repository dependency graphing for Go workspaces
- 对用户的影响：Developers may fail before the first successful local run: Add deterministic cross-repository dependency graphing for Go workspaces
- 证据：failure_mode_cluster:github_issue | https://github.com/DeusData/codebase-memory-mcp/issues/969 | Add deterministic cross-repository dependency graphing for Go workspaces

## 6. 安装坑 · 失败模式：installation: Custom Exploring Subagent — inject MCP-aware agent definitions on integration

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Custom Exploring Subagent — inject MCP-aware agent definitions on integration
- 对用户的影响：Developers may fail before the first successful local run: Custom Exploring Subagent — inject MCP-aware agent definitions on integration
- 证据：failure_mode_cluster:github_issue | https://github.com/DeusData/codebase-memory-mcp/issues/975 | Custom Exploring Subagent — inject MCP-aware agent definitions on integration

## 7. 安装坑 · 失败模式：installation: Memory leak: process grows to 50+ GB virtual memory over hours/days, crashes Windows

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Memory leak: process grows to 50+ GB virtual memory over hours/days, crashes Windows
- 对用户的影响：Developers may fail before the first successful local run: Memory leak: process grows to 50+ GB virtual memory over hours/days, crashes Windows
- 证据：failure_mode_cluster:github_issue | https://github.com/DeusData/codebase-memory-mcp/issues/581 | Memory leak: process grows to 50+ GB virtual memory over hours/days, crashes Windows

## 8. 安装坑 · 失败模式：installation: [Windows] --ui=true starts but HTTP server never listens on v0.8.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Windows] --ui=true starts but HTTP server never listens on v0.8.1
- 对用户的影响：Developers may fail before the first successful local run: [Windows] --ui=true starts but HTTP server never listens on v0.8.1
- 证据：failure_mode_cluster:github_issue | https://github.com/DeusData/codebase-memory-mcp/issues/707 | [Windows] --ui=true starts but HTTP server never listens on v0.8.1

## 9. 安装坑 · 失败模式：installation: feat: install codebase-memory skill for Codex

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: feat: install codebase-memory skill for Codex
- 对用户的影响：Developers may fail before the first successful local run: feat: install codebase-memory skill for Codex
- 证据：failure_mode_cluster:github_issue | https://github.com/DeusData/codebase-memory-mcp/issues/976 | feat: install codebase-memory skill for Codex

## 10. 安装坑 · 失败模式：installation: v0.5.6

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.5.6
- 对用户的影响：Upgrade or migration may change expected behavior: v0.5.6
- 证据：failure_mode_cluster:github_release | https://github.com/DeusData/codebase-memory-mcp/releases/tag/v0.5.6 | v0.5.6

## 11. 安装坑 · 失败模式：installation: v0.5.7

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.5.7
- 对用户的影响：Upgrade or migration may change expected behavior: v0.5.7
- 证据：failure_mode_cluster:github_release | https://github.com/DeusData/codebase-memory-mcp/releases/tag/v0.5.7 | v0.5.7

## 12. 安装坑 · 失败模式：installation: v0.6.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.6.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.6.0
- 证据：failure_mode_cluster:github_release | https://github.com/DeusData/codebase-memory-mcp/releases/tag/0.6.0 | v0.6.0

## 13. 安装坑 · 失败模式：installation: v0.6.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.6.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.6.1
- 证据：failure_mode_cluster:github_release | https://github.com/DeusData/codebase-memory-mcp/releases/tag/0.6.1 | v0.6.1

## 14. 安装坑 · 失败模式：installation: v0.8.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.8.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.0
- 证据：failure_mode_cluster:github_release | https://github.com/DeusData/codebase-memory-mcp/releases/tag/0.8.0 | v0.8.0

## 15. 安装坑 · 失败模式：installation: v0.8.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.8.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.1
- 证据：failure_mode_cluster:github_release | https://github.com/DeusData/codebase-memory-mcp/releases/tag/v0.8.1 | v0.8.1

## 16. 安装坑 · 失败模式：installation: v0.9.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.9.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.9.0
- 证据：failure_mode_cluster:github_release | https://github.com/DeusData/codebase-memory-mcp/releases/tag/v0.9.0 | v0.9.0

## 17. 安装坑 · 失败模式：installation: v0.9.0 tools/list pagination (page size 8) truncates non-paginating MCP clients (Cursor) to 8...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.9.0 tools/list pagination (page size 8) truncates non-paginating MCP clients (Cursor) to 8 of 14 tools — regression from v0.8.1
- 对用户的影响：Developers may fail before the first successful local run: v0.9.0 tools/list pagination (page size 8) truncates non-paginating MCP clients (Cursor) to 8 of 14 tools — regression from v0.8.1
- 证据：failure_mode_cluster:github_issue | https://github.com/DeusData/codebase-memory-mcp/issues/971 | v0.9.0 tools/list pagination (page size 8) truncates non-paginating MCP clients (Cursor) to 8 of 14 tools — regression from v0.8.1

## 18. 安装坑 · 来源证据：Add deterministic cross-repository dependency graphing for Go workspaces

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add deterministic cross-repository dependency graphing for Go workspaces
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/DeusData/codebase-memory-mcp/issues/969 | 来源类型 github_issue 暴露的待验证使用条件。

## 19. 安装坑 · 来源证据：Custom Exploring Subagent — inject MCP-aware agent definitions on integration

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Custom Exploring Subagent — inject MCP-aware agent definitions on integration
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/DeusData/codebase-memory-mcp/issues/975 | 来源类型 github_issue 暴露的待验证使用条件。

## 20. 安装坑 · 来源证据：Windows: tree-sitter definitions pass fails on ALL files when repo_path contains non-ASCII (CJK / Cyrillic / Arabic / a…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: tree-sitter definitions pass fails on ALL files when repo_path contains non-ASCII (CJK / Cyrillic / Arabic / accented Latin / etc.) characters
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/DeusData/codebase-memory-mcp/issues/636 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 21. 安装坑 · 来源证据：v0.9.0 tools/list pagination (page size 8) truncates non-paginating MCP clients (Cursor) to 8 of 14 tools — regression…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.0 tools/list pagination (page size 8) truncates non-paginating MCP clients (Cursor) to 8 of 14 tools — regression from v0.8.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/DeusData/codebase-memory-mcp/issues/971 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 22. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/DeusData/codebase-memory-mcp | host_targets=mcp_host, claude_code, claude, cursor

## 23. 配置坑 · 失败模式：configuration: v0.5.5

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.5.5
- 对用户的影响：Upgrade or migration may change expected behavior: v0.5.5
- 证据：failure_mode_cluster:github_release | https://github.com/DeusData/codebase-memory-mcp/releases/tag/v0.5.5 | v0.5.5

## 24. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/DeusData/codebase-memory-mcp | README/documentation is current enough for a first validation pass.

## 25. 运行坑 · 失败模式：runtime: Best-effort indexing-coverage signal: mark files/regions that were not fully indexed

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: Best-effort indexing-coverage signal: mark files/regions that were not fully indexed
- 对用户的影响：Developers may hit a documented source-backed failure mode: Best-effort indexing-coverage signal: mark files/regions that were not fully indexed
- 证据：failure_mode_cluster:github_issue | https://github.com/DeusData/codebase-memory-mcp/issues/963 | Best-effort indexing-coverage signal: mark files/regions that were not fully indexed

## 26. 运行坑 · 来源证据：Best-effort indexing-coverage signal: mark files/regions that were not fully indexed

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Best-effort indexing-coverage signal: mark files/regions that were not fully indexed
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/DeusData/codebase-memory-mcp/issues/963 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 27. 维护坑 · 失败模式：migration: v0.7.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v0.7.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.7.0
- 证据：failure_mode_cluster:github_release | https://github.com/DeusData/codebase-memory-mcp/releases/tag/0.7.0 | v0.7.0

## 28. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/DeusData/codebase-memory-mcp | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/DeusData/codebase-memory-mcp | no_demo; severity=medium

## 30. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/DeusData/codebase-memory-mcp | no_demo; severity=medium

## 31. 安全/权限坑 · 来源证据：feat: install codebase-memory skill for Codex

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: install codebase-memory skill for Codex
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/DeusData/codebase-memory-mcp/issues/976 | 来源类型 github_issue 暴露的待验证使用条件。

## 32. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/DeusData/codebase-memory-mcp | issue_or_pr_quality=unknown

## 33. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/DeusData/codebase-memory-mcp | release_recency=unknown

<!-- canonical_name: DeusData/codebase-memory-mcp; human_manual_source: deepwiki_human_wiki -->