1. 项目定位与核心能力

codebase-memory-mcp 是一个面向 LLM 编程代理的代码库记忆层：将源码解析为持久化的图结构（节点 = 符号、文件；边 = CALLS / IMPORTS / DEFINES 等），并通过 Model Context Protocol 将其暴露给 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 实现，从入口到图存储大致呈如下分层：

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 的系统架构是一条 *解析 → 图化 → 查询* 的单向管道，每一层都对最终图的准确性负责；这也是上述社区缺陷几乎全部落在"提取/解析/求值"层的原因。

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 抽象语法树并行运行三类抽取器：

资料来源：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. 数据流概览

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

MCP 工具层与定位

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

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）。修复点位于 src/semantic/semantic.c 中搜索参数装配路径。资料来源：src/semantic/semantic.c:1-1

query_graph：执行一段受限 Cypher 子集，由 src/cypher/cypher.c 解析并下发到图存储。已知限制：

• WHERE 子句拒绝 coalesce()，阻碍空值安全的数值过滤（issue #874）。
• 单子句形态 RETURN DISTINCT … ORDER BY … LIMIT 会少返行，是 issue #237 的回归残留（issue #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）。
• CommonJS const f = require("./f") 同样不生成 CALLS 边（issue #871）。

export_codebase（提案）：将已索引代码库导出为单段文本，用于在执行代理前喂给 LLM 做规划草稿（issue #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）。

资料来源：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）。

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

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

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，运行前应确认以下字段：

增量索引的性能问题在 #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 中的复现路径逐项排查。

Pitfall Log / 踩坑日志

项目：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