# https://github.com/JuliusBrussee/cavemem 项目说明书

生成时间：2026-06-14 22:41:13 UTC

## 目录

- [cavemem System Overview & Architecture](#page-1)
- [Compression Grammar, Settings & Privacy Controls](#page-2)
- [IDE Installers, Hooks & MCP Server](#page-3)
- [CLI Commands, Worker & Known Failure Modes](#page-4)

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

## cavemem System Overview & Architecture

### 相关页面

相关主题：[Compression Grammar, Settings & Privacy Controls](#page-2), [IDE Installers, Hooks & MCP Server](#page-3)

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

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

- [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md)
- [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md)
- [package.json](https://github.com/JuliusBrussee/cavemem/blob/main/package.json)
- [apps/worker/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/worker/CHANGELOG.md)
- [packages/embedding/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/embedding/CHANGELOG.md)
- [packages/hooks/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/hooks/CHANGELOG.md)
- [packages/storage/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/storage/CHANGELOG.md)
- [packages/config/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/config/CHANGELOG.md)
- [packages/core/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/core/CHANGELOG.md)
- [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md)
- [apps/mcp-server/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/mcp-server/CHANGELOG.md)
- [apps/worker/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/worker/package.json)
- [packages/compress/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/package.json)
- [packages/config/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/config/package.json)
- [packages/compress/src/lexicon.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/lexicon.json)
- [CONTRIBUTING.md](https://github.com/JuliusBrussee/cavemem/blob/main/CONTRIBUTING.md)
</details>

# cavemem System Overview & Architecture

## 项目定位与设计目标

cavemem 是面向编码助手的跨智能体（cross-agent）持久化记忆系统，其核心目标是在多个 IDE 会话之间保留上下文，并尽量降低存储与检索成本。系统通过 IDE 钩子（hooks）在会话边界触发采集，使用 [caveman 语法](https://github.com/JuliusBrussee/caveman) 对散文文本进行确定性压缩（约 75% token 缩减），最终写入本地 SQLite + 向量索引。资料来源：[README.md:1-30]()

设计上有四个显著特征：

- **本地优先**：默认无网络调用；可选用远端嵌入提供者。
- **压缩落盘**：所有持久化文本必须经过 `@cavemem/compress`，技术 token（代码块、文件路径、URL、版本号等）按字节保留。资料来源：[CLAUDE.md:18-30]()
- **渐进式检索**：通过 MCP 工具 `search` / `timeline` / `get_observations` / `list_sessions` 让模型先过滤再拉取正文。资料来源：[README.md:34-50]()
- **混合检索**：基于 SQLite FTS5 关键词 + 本地向量索引，配合可调的 ranker。资料来源：[README.md:18-25]()

当前版本（v0.2.1）支持的 IDE 包括：Claude Code、Cursor、Gemini CLI、OpenCode、Codex。资料来源：[README.md:9-12]()

## 系统架构与组件

cavemem 采用 monorepo 结构，使用 pnpm 工作区进行管理，Node 版本要求 ≥ 20.0.0。资料来源：[package.json:6-19]() 顶层包结构包含 `apps/`（CLI、worker、MCP server）和 `packages/`（config、core、storage、embedding、hooks、compress）。

```mermaid
graph LR
    A[IDE 钩子] --> B[redact &lt;private&gt;]
    B --> C[@cavemem/compress]
    C --> D[MemoryStore]
    D --> E[(SQLite + FTS5)]
    D --> F[(本地向量索引)]
    G[MCP 客户端] --> H[@cavemem/mcp-server]
    H --> E
    I[浏览器] --> J[Worker HTTP Viewer<br/>127.0.0.1:37777]
    J --> E
    H --> K[Embedder Worker<br/>懒加载]
    K --> F
```

关键组件职责：

| 组件 | 路径 | 职责 |
|------|------|------|
| `@cavemem/config` | `packages/config` | 基于 Zod 的自描述 schema，导出 `settingsDocs()` 用于 `cavemem config show`。资料来源：[packages/config/CHANGELOG.md:8-15]() |
| `@cavemem/compress` | `packages/compress` | caveman 文法压缩/解压，是写路径必经环节。资料来源：[packages/compress/package.json:1-30]() |
| `@cavemem/embedding` | `packages/embedding` | 懒加载单例嵌入器，MCP 握手阶段不阻塞。资料来源：[packages/embedding/CHANGELOG.md:18-21]() |
| `@cavemem/worker` | `apps/worker` | 嵌入构建后台守护，空闲自动退出。资料来源：[apps/worker/package.json:1-25]() |
| `@cavemem/mcp-server` | `apps/mcp-server` | 提供四个检索工具（`search`、`timeline`、`get_observations`、`list_sessions`）。资料来源：[apps/mcp-server/CHANGELOG.md:14-18]() |
| `@cavemem/hooks` | `packages/hooks` | IDE 钩子协议适配，同时支持 Claude Code 新旧字段名。资料来源：[packages/hooks/CHANGELOG.md:18-22]() |

## 数据流与生命周期

写路径遵循 CLAUDE.md 中列出的"非协商规则"：所有持久化散文必须经过 `MemoryStore`，它内部强制调用 `@cavemem/compress`。资料来源：[CLAUDE.md:18-30]() 钩子以同步方式写入 SQLite，绝不阻塞于守护进程。

嵌入后台进程由首次钩子事件触发（`embedding.autoStart` 控制），模型加载采用懒加载单例以保持 MCP 握手速度；`embedding.idleShutdownMs` 控制空闲自动关闭。资料来源：[packages/config/CHANGELOG.md:8-15]() 与 [packages/embedding/CHANGELOG.md:18-21]()

读路径分为两类：

- **模型面**：MCP 工具默认返回摘要/元数据（`search` 返回 `{id, score, snippet, session_id, ts}`），正文按需 `get_observations`。资料来源：[README.md:34-50]()
- **人类面**：Worker HTTP Viewer 在 `http://127.0.0.1:37777` 提供浏览器 UI，解压后的散文供人阅读。资料来源：[README.md:22-26]()

`@cavemem/compress` 提供多档压缩档位（lite / full / ultra），针对 articles、hedges、pleasantries、abbreviations 等类别分别裁剪；技术 token 的保护由 `packages/compress/src/tokenize.ts` 唯一权威化。资料来源：[packages/compress/src/lexicon.json:1-40]() 与 [CLAUDE.md:22-30]()

## CLI 命令与配置

CLI 入口 `cavemem` 提供如下顶层命令：

| 命令 | 作用 |
|------|------|
| `install [--ide <name>]` | 注册钩子到指定 IDE（claude-code / cursor / gemini-cli / opencode / codex） |
| `status` | 单屏仪表盘：设置路径、数据目录、数据库计数、已装 IDE、嵌入后端、worker pid 与运行时长。资料来源：[apps/cli/CHANGELOG.md:6-12]() |
| `start \| stop \| restart` | 控制 worker 守护（一般无需手动启动） |
| `viewer` | 打开 `http://127.0.0.1:37777` 浏览器界面 |
| `doctor` | 校验安装完整性 |
| `search <query> [--limit N] [--no-semantic]` | BM25 + 可选余弦重排 |
| `compress <file>` | 对文件执行 caveman 压缩 |
| `reindex` | 重建 FTS5 + 向量索引 |
| `export <out.jsonl>` | 导出观测为 JSONL |
| `mcp` | 启动 stdio MCP 服务 |
| `config show \| get \| set \| open \| path \| reset` | 基于 Zod `.describe()` 的自描述配置操作。资料来源：[apps/cli/CHANGELOG.md:8-15]() |

配置文件位于 `~/.cavemem/settings.json`，关键字段包括 `dataDir`（默认 `~/.cavemem`）、`privacy.redactSecrets`、`privacy.excludePatterns`、`embedding.{provider,model,batchSize,autoStart,idleShutdownMs}`。资料来源：[README.md:55-60]()

## 已知问题与社区反馈

下列社区高频问题对架构理解有直接影响：

- **#51 Viewer 未鉴权**：worker 在 `127.0.0.1:37777` 无任何鉴权即返回解压后的记忆；本地进程或经 CSRF / DNS rebinding 的网页可读取全部内容。架构层应将 Viewer 默认视为受信通道，但部署时需注意。资料来源：[Issue #51]()
- **#50 钩子无 matcher**：Claude Code 安装器注册的 `PostToolUse` 钩子未指定 matcher，导致所有工具 I/O 全部入库；`privacy.excludePatterns` 在文档中承诺"永不读取"但代码层未消费（#48），`privacy.redactSecrets` 是无操作占位符（#49）。
- **#11 / #43 Windows 兼容性**：Windows 下 `cavemem start` 报 `spawn EFTYPE`；Claude Code 钩子命令中的反斜杠在 git-bash 下被吞并为 `C:Usershp...`，安装路径需在 Windows 上特殊处理。
- **#37 better-sqlite3 在 Node 26 失败**：V8 14.6 ABI 变更导致原生绑定加载失败；社区讨论提议用 `bun:sqlite` 兜底。
- **#39 跨项目上下文泄漏**：`session-start` 钩子的"上一次会话摘要"未按 cwd 范围过滤，可能在项目 A 注入项目 B 的内容。
- **#17 Codex 安装器过期**：写入 `~/.codex/config.json`，而 Codex 实际读取 `config.toml`，且钩子功能需 `features.codex_hooks = true` 显式开启。
- **#3 MCP 静默退出（v0.1.3）**：CLI 的 `mcp` 子命令通过动态 `import('@cavemem/mcp-server')` 期望副作用启动，但 `isMainEntry()` 守卫使 `main()` 未执行。v0.2.1 的补丁 c756051 修复该问题。

## See Also

- [cavemem Compression Pipeline & Lexicon]()
- [cavemem MCP Server Reference]()
- [cavemem Hooks & IDE Integrations]()
- [cavemem Storage Schema & FTS5]()
- [cavemem Configuration Reference]()

---

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

## Compression Grammar, Settings & Privacy Controls

### 相关页面

相关主题：[cavemem System Overview & Architecture](#page-1), [CLI Commands, Worker & Known Failure Modes](#page-4)

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

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

- [packages/compress/src/tokenize.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/tokenize.ts)
- [packages/compress/src/compress.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/compress.ts)
- [packages/compress/src/expand.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/expand.ts)
- [packages/compress/src/lexicon.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/lexicon.ts)
- [packages/compress/src/lexicon.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/lexicon.json)
- [packages/compress/src/privacy.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/privacy.ts)
- [packages/compress/src/count.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/count.ts)
- [packages/compress/src/types.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/types.ts)
- [packages/compress/src/index.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/index.ts)
- [packages/config/src/schema.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/config/src/schema.ts)
- [packages/compress/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/package.json)
- [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md)
- [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/JuliusBrussee/cavemem/blob/main/CONTRIBUTING.md)
</details>

# Compression Grammar, Settings & Privacy Controls

## 概述

cavemem 的核心价值主张是「压缩态持久化」(compression-at-rest)：会话事件经过语法压缩后再写入 SQLite，由本地工作者在后台重建向量索引以支持语义检索。本页说明负责这套机制的三块基石——压缩语法、设置架构、隐私控制——以及它们在源码中的真实行为。

数据流概览：

```mermaid
flowchart LR
    Hook[Hook 事件] --> Redact[redactPrivate]
    Redact --> Compress[Compress 引擎]
    Compress --> Storage[(SQLite + FTS5)]
    Storage --> Worker[后台 Worker]
    Worker --> Embed[向量索引]
    Storage --> MCP[MCP 工具]
```

资料来源：[packages/compress/src/privacy.ts:1-15]()、[README.md]() 数据流描述

---

## 压缩语法系统 (Compression Grammar)

### 强度等级

`@cavemem/compress` 包通过 `Intensity` 类型暴露三个压缩档位：`lite`、`full`、`ultra`，调用方可通过 `CompressOptions.intensity` 字段切换。词库 (`lexicon.json`) 为每个强度分别维护了 `fillers`、`articles`、`hedges`、`pleasantries` 和 `abbreviations` 五类替换规则。

- `lite`：保留虚词与冠词，仅做最小限度的常见名词缩写。
- `full`：移除冠词 (`the`/`a`/`an`)、中等数量的语气词与对冲词。
- `ultra`：在 `full` 基础上进一步删除 `i think`、`maybe`、`perhaps` 等不确定表达，并将 `because → b/c`、`with → w/`、`and → &` 等高频词压到最短形。

资料来源：[packages/compress/src/lexicon.json]()（五类规则的字面数据）、[packages/compress/src/lexicon.ts:1-22]()（规则访问入口）

### 往返保证 (Round-trip)

CLAUDE.md 将「code 与 path 按字节保留」列为不可破坏的不变量：`packages/compress/src/tokenize.ts` 是识别这些技术词元的唯一权威。词库同时维护一组 `expansions` 反向映射表，确保 `impl → implementation`、`cfg → configuration` 等缩写能在 `expand` 阶段无损还原。`expand.ts` 通过该映射表重建人类可读文本，因此压缩比与可读性不会相互抵消。

新规则需遵循 `CONTRIBUTING.md` 的步骤：编辑 `lexicon.json`、在 `packages/compress/test/fixtures/` 加入往返夹具、运行 `pnpm --filter @cavemem/compress test` 直至全绿。

资料来源：[CLAUDE.md]() 第 2–3 条不变量、[packages/compress/src/lexicon.ts:18-20]() 的 `expansions()` 导出、[CONTRIBUTING.md]() 中 "Adding a compression rule"

### 词元估算

`packages/compress/src/count.ts` 提供轻量级的 `countTokens(text)`：取 `max(单词数, round(字符数 / 4))`。该实现声明为「近似而非真实分词器」，但足以在压缩前后稳定对比，便于 benchmark 输出。

资料来源：[packages/compress/src/count.ts:1-13]()

---

## 设置架构 (Settings Schema)

`@cavemem/config` 通过 Zod 严格模式 (`z.strict()`) 定义 `SettingsSchema`。关键子集：

| 配置项 | 类型 / 默认值 | 实际行为 |
|---|---|---|
| `privacy.excludePatterns` | `string[]`，默认 `[]` | 在 schema 中声明，但 **README 与 CLAUDE.md 描述的「匹配路径永不读取」并未在 hooks 实现中被消费**；请参考社区 issue #48 |
| `privacy.redactSecrets` | `boolean`，默认 `true` | 默认开启但代码中**没有任何密钥/令牌检测器**；仅 `redactPrivate()` 生效。请参考社区 issue #49 |
| `ides` | `Record<string, boolean>` | 记录各 IDE 是否安装，由 `cavemem install` 子命令写入 |
| `dataDir` / `workerPort` | string / number | 决定 SQLite 与本地 Worker HTTP 端口 (默认 37777) |

需要强调的是，`redactSecrets` 在语义上是「密钥脱敏开关」，但其默认值被设置并未消费。社区 issue #51 还指出 worker HTTP 端口绑定在 `127.0.0.1:37777`，未做身份验证即可返回解压缩后的会话内容，运维部署时需结合外部防火墙。

资料来源：[packages/config/src/schema.ts:privacy 子段]()、[apps/cli/package.json]() 端口与依赖声明

---

## 隐私控制 (Privacy Controls)

### 已实现的写边界

`packages/compress/src/privacy.ts` 仅暴露 `redactPrivate(input)`：

- 正则 `/<private>[\s\S]*?<\/private>/gi` 移除所有闭合的私有块。
- 若存在未闭合的 `<private>` 起始标签，则将「从该标签到输入末尾」整段丢弃，确保意外标签不会泄漏后半段内容。
- 该函数在压缩与写入之前调用，符合 CLAUDE.md 第 6 条不变量。

资料来源：[packages/compress/src/privacy.ts:1-14]()

### 与文档的不一致点

1. **`excludePatterns`**：README 与 CLAUDE.md 都将其描述为强制执行，但 hooks 路径上未读取该字段（社区 issue #48）。在配置中加入 `["**/.env", "**/secrets/**"]` 并不能阻止这些路径被捕获。
2. **`redactSecrets`**：schema 默认为 `true`，但代码中无任何密钥/令牌识别器（社区 issue #49）。`<private>` 是**唯一**真正生效的脱敏机制。
3. **PostToolUse 捕获范围**：Claude Code 安装器以**无 matcher** 注册 `PostToolUse` 钩子，导致所有 MCP 工具的输入输出都被记录（社区 issue #50）。

### 实践建议

- 若需排除敏感工具的 I/O，当前唯一可靠的方式是在提示中用 `<private>...</private>` 显式包裹，并在写入前做脱敏。
- 关注上述三个 issue 的修复进度，在升级前避免依赖 `excludePatterns` 或 `redactSecrets` 的承诺行为。

资料来源：[packages/compress/src/privacy.ts:1-14]() 与社区 issue #48、#49、#50

---

## See Also

- [README.md]() — 安装与命令速查
- [CLAUDE.md]() — 项目级不变量
- [CONTRIBUTING.md]() — 新增压缩规则流程
- 社区追踪：issue #48 (`excludePatterns` 未生效)、#49 (`redactSecrets` 无实现)、#50 (`PostToolUse` 无 matcher)、#51 (worker HTTP 未鉴权)

---

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

## IDE Installers, Hooks & MCP Server

### 相关页面

相关主题：[cavemem System Overview & Architecture](#page-1), [CLI Commands, Worker & Known Failure Modes](#page-4)

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

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

- [packages/installers/src/types.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/installers/src/types.ts)
- [packages/installers/src/codex.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/installers/src/codex.ts)
- [packages/installers/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/installers/package.json)
- [apps/cli/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/package.json)
- [apps/mcp-server/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/mcp-server/package.json)
- [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md)
- [apps/mcp-server/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/mcp-server/CHANGELOG.md)
- [apps/worker/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/worker/CHANGELOG.md)
- [packages/installers/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/installers/CHANGELOG.md)
- [packages/hooks/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/hooks/CHANGELOG.md)
- [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md)
- [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/JuliusBrussee/cavemem/blob/main/CONTRIBUTING.md)
</details>

# IDE 安装器、钩子与 MCP 服务器

## 概述与组件职责

cavemem 是一个跨代理持久记忆系统，由三类协作模块组成。IDE 安装器负责在每个受支持的编码助手（Claude Code、Cursor、Gemini CLI、OpenCode、Codex）中注入钩子命令；钩子处理包在会话边界（`SessionStart` / `SessionEnd`）以及工具调用后（`PostToolUse`）触发压缩与写库；MCP 服务器则通过 stdio 向代理暴露查询工具。三者共同保证「写入路径上无守护进程、读取路径上有本地守护进程」这一非协商性约束，使得钩子延迟不会反馈到代理的响应时间。

资料来源：[README.md](README.md)、[CLAUDE.md](CLAUDE.md)

## IDE 安装器架构

### 安装器接口与契约

`Installer` 接口定义了四个核心成员：`id`、`label`、`detect(ctx)`、`install(ctx)`、`uninstall(ctx)`。上下文 `InstallContext` 同时携带 IDE 配置目录、CLI 入口绝对路径、Node 二进制绝对路径以及本地数据目录。源码注释明确指出：IDE 配置必须以 `nodeBin cliPath …` 形式 spawn，**不能直接 spawn 裸的 `.js` 文件**——在 Windows 上后者会触发 `EFTYPE` 错误，因为 `.js` 没有关联的 binfmt 处理程序。

资料来源：[packages/installers/src/types.ts:1-29](https://github.com/JuliusBrussee/cavemem/blob/main/packages/installers/src/types.ts#L1-L29)、[packages/installers/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/installers/CHANGELOG.md)

### 支持的 IDE 与配置差异

CLI 在 `cavemem install` 命令中注册的 IDE 列表由注册表（registry）驱动；当前受支持的目标为 `claude-code`、`gemini-cli`、`opencode`、`codex`、`cursor`。Codex 安装器使用 `smol-toml` 解析 `~/.codex/config.toml`，按官方规范向 `[features]` 段添加 `codex_hooks = true`，并在 `mcp_servers` 中注册 `cavemem`，同时独立写入 `~/.codex/hooks.json`。社区请求中的 Trae SOLO、Antigravity、GitHub Copilot 暂未列入注册表（[#38](https://github.com/JuliusBrussee/cavemem/issues/38)、[#40](https://github.com/JuliusBrussee/cavemem/issues/40)、[#23](https://github.com/JuliusBrussee/cavemem/issues/23)）。

资料来源：[packages/installers/src/codex.ts:38-67](https://github.com/JuliusBrussee/cavemem/blob/main/packages/installers/src/codex.ts#L38-L67)、[packages/installers/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/installers/package.json)

## 钩子系统与跨平台行为

### 写入路径上的无守护进程约束

CLAUDE.md 明确指出：钩子可以「detach-spawn」worker，但**永远不能等待**它——观察值必须同步写入 SQLite。该约束确保 IDE 钩子的延迟不会进入代理的关键路径。钩子处理包按职责组织为独立的 5 个 handler（runner + 全部 5 个 lifecycle 事件 + 热路径预算检查），分别覆盖 `session-start`、`session-end`、`post-tool-use` 等事件。

资料来源：[CLAUDE.md](CLAUDE.md)、[packages/hooks/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/hooks/CHANGELOG.md)

### 字段映射与协议演进

CLI 0.2.x 修订了钩子协议：处理器现在读取 Claude Code 实际发送的字段名 `tool_name`、`tool_response`、`last_assistant_message`、`source`、`reason`，同时保留旧字段别名 `tool`、`tool_output`、`turn_summary` 以兼容其他 IDE 与历史测试套件。该变化由 `scripts/e2e-publish.sh` 端到端验证——脚本会把工件打包、安装到隔离前缀、并用真实 Claude Code payload 驱动每个钩子事件。

资料来源：[apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md)

### 跨平台已知问题

社区已记录多个与平台相关的故障：Windows 上的 `spawn EFTYPE` 已在 0.2.x 通过 `nodeBin + cliPath` 修复；Windows + Git Bash 环境下反斜杠路径被 bash 解析坍缩为 `C:Usershp…`（[#43](https://github.com/JuliusBrussee/cavemem/issues/43)）；OpenCode 桌面版没有钩子系统，仅暴露 MCP 协议，因此不会向 cavemem 数据库写入任何观察值，查询工具始终返回空（[#45](https://github.com/JuliusBrussee/cavemem/issues/45)）。

## MCP 服务器

MCP 服务器以 stdio 模式启动，通过 `@modelcontextprotocol/sdk` 提供四个渐进式披露工具：`search`、`timeline`、`get_observations`、`list_sessions`。其中 `search` 与 `timeline` 返回紧凑结果（id、score、snippet、ts），`get_observations` 按需取回完整正文。0.2.x 引入了「惰性单例」embedder：MCP 握手保持快速，模型仅在首次调用 `search` 时加载；新增的 `embedding.batchSize` / `embedding.autoStart` / `embedding.idleShutdownMs` 字段由 zod `.describe()` 自文档化。

资料来源：[apps/mcp-server/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/mcp-server/package.json)、[apps/mcp-server/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/mcp-server/CHANGELOG.md)、[README.md](README.md)

v0.2.1 修复了 `cavemem mcp` 命令静默退出的问题：CLI 的 `mcp` 子命令通过 `await import('@cavemem/mcp-server')` 触发导入副作用以启动服务器，但服务器模块将 `main()` 守护在 `isMainEntry()` 检查之后——动态导入时 `import.meta.url` 不等于 `process.argv[1]`，因此 `main()` 从未运行。补丁将 `mcp` 子命令改为直接执行 stdio 服务器入口文件。

资料来源：[apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md)

```mermaid
flowchart LR
  A[IDE 代理] -->|SessionStart/SessionEnd/PostToolUse| B[钩子脚本]
  B -->|同步写入| C[(SQLite + FTS5)]
  B -.->|detach-spawn| D[Worker 守护进程]
  D -->|回填嵌入| C
  D -->|HTTP 127.0.0.1:37777| E[只读 Viewer]
  A -->|MCP stdio| F[MCP Server]
  F -->|查询| C
  F -->|惰性加载| G[Embedder]
```

## 已知问题与社区反馈

* **隐私设置未生效**：`privacy.redactSecrets` 默认 `true` 但代码中未被消费；`privacy.excludePatterns` 文档声称「never read」但实际未被读取，匹配路径仍会被捕获（[#48](https://github.com/JuliusBrussee/cavemem/issues/48)、[#49](https://github.com/JuliusBrussee/cavemem/issues/49)）。
* **工具 I/O 无选择性捕获**：`PostToolUse` 钩子注册时未指定 `matcher`，敏感 MCP 工具的输入输出默认全部入库（[#50](https://github.com/JuliusBrussee/cavemem/issues/50)）。
* **会话上下文跨项目泄漏**：`session-start` 钩子未按 `cwd` 作用域隔离，可能在项目 A 中注入项目 B 的历史摘要（[#39](https://github.com/JuliusBrussee/cavemem/issues/39)）。
* **Worker HTTP 鉴权缺失**：`127.0.0.1:37777` 绑定无身份验证，存在 CSRF / DNS-rebinding 风险（[#51](https://github.com/JuliusBrussee/cavemem/issues/51)）。
* **原生绑定兼容性**：Node.js 26.0.0 的 V8 14.6 破坏 `better-sqlite3` 原生绑定（[#37](https://github.com/JuliusBrussee/cavemem/issues/37)）；WSL 安装也可能失败（[#22](https://github.com/JuliusBrussee/cavemem/issues/22)）。

## 另请参阅

* [持久化与压缩架构]()
* [嵌入提供者配置]()
* [发布与端到端验证流程]()

---

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

## CLI Commands, Worker & Known Failure Modes

### 相关页面

相关主题：[cavemem System Overview & Architecture](#page-1), [Compression Grammar, Settings & Privacy Controls](#page-2), [IDE Installers, Hooks & MCP Server](#page-3)

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

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

- [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md)
- [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md)
- [apps/cli/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/package.json)
- [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md)
- [apps/worker/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/worker/CHANGELOG.md)
- [apps/mcp-server/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/mcp-server/CHANGELOG.md)
- [packages/hooks/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/hooks/CHANGELOG.md)
- [packages/hooks/src/types.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/hooks/src/types.ts)
</details>

# CLI Commands, Worker & Known Failure Modes

## 概述

cavemem 是一个面向多 IDE 的本地持久化记忆系统，由 `apps/cli`、本地 `apps/worker` 守护进程与 `apps/mcp-server` 三个进程协作构成。CLI 负责用户面命令、配置管理与 IDE 集成；Worker 提供只读查看器和后台嵌入回填；MCP Server 暴露查询工具。`CLAUDE.md` 将整体布局描述为 `apps/cli`（用户二进制）、`apps/worker`（本地 HTTP 守护进程）以及 `apps/mcp-server`（stdio MCP）三段式 [资料来源：[CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md)]。

本页聚焦三个问题：CLI 公开了哪些命令、Worker 的运行时模型与边界、社区与仓库 issue 中反复出现的故障模式。

## CLI 命令总览

CLI 基于 `commander` 与 `kleur` 构建，并使用 `tsup` 打包发布，`@modelcontextprotocol/sdk` 出现在依赖中以支持 `cavemem mcp` 子命令 [资料来源：[apps/cli/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/package.json)]。`README.md` 列出了当前稳定的顶层命令：

| 命令 | 用途 |
|------|------|
| `cavemem install` | 在 Claude Code / Cursor / Gemini CLI / OpenCode / Codex 中注册钩子 |
| `cavemem status` | 单窗格仪表板：settings 路径、数据目录、DB 计数、已安装 IDE、嵌入模型、worker pid 与运行时长 |
| `cavemem config show\|get\|set\|open\|path\|reset` | 基于 zod `.describe()` 的自文档化配置管理 |
| `cavemem start\|stop\|restart` | 控制 worker 守护进程（一般无需手动操作，钩子会触发自动启动） |
| `cavemem viewer` | 在浏览器中打开只读记忆查看器 |
| `cavemem doctor` | 验证安装完整性 |
| `cavemem search <query> [--limit N] [--no-semantic]` | BM25 + 余弦重排搜索记忆 |
| `cavemem compress <file>` | 用 caveman 语法压缩文件 |
| `cavemem reindex` | 重建 FTS5 + 向量索引 |
| `cavemem export <out.jsonl>` | 将观察记录导出为 JSONL |
| `cavemem mcp` | 启动 stdio MCP 服务器 |

[资料来源：[README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md)]

`apps/cli/CHANGELOG.md` 强调新增的 `cavemem config` 子命令以 zod schema 的 `.describe()` 字符串为唯一信息源，避免文档与代码漂移；`settingsDocs()` 导出为每个字段提供 `{path, type, default, description}` [资料来源：[apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md)]。

## Worker 守护进程

`apps/worker` 在 `127.0.0.1:<workerPort>`（默认 `37777`）上绑定本地 HTTP 端点，承担两件事：提供浏览器端只读 viewer，以及在后台循环为新写入的观察生成向量嵌入 [资料来源：[CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md)]。`apps/worker/CHANGELOG.md` 进一步说明 worker 与三个嵌入配置项 `embedding.batchSize`、`embedding.autoStart`、`embedding.idleShutdownMs` 联动 [资料来源：[apps/worker/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/worker/CHANGELOG.md)]。

CLAUDE.md 文档化的"非协商规则"是理解 worker 行为的关键：**钩子可以 `detach-spawn` 启动 worker，但绝不能 `wait` 在它上面**；观察记录必须同步写入 [资料来源：[CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md)]。这意味着写入路径完全不依赖 worker 可达，写入失败也只与 SQLite 相关，与 worker 进程解耦。

```mermaid
flowchart LR
  Hook[IDE Hook 脚本] -->|同步写入| DB[(SQLite + FTS5 + 向量)]
  Hook -.->|detach-spawn| Worker[Worker Daemon<br/>127.0.0.1:37777]
  Worker -->|回填嵌入| DB
  Worker --> Viewer[浏览器只读 UI]
  MCP[MCP stdio Server] -->|查询| DB
  CLI[apps/cli] -->|status / search / viewer| DB
  CLI -.->|按需| Worker
```

## 钩子协议契约

钩子事件载荷在 `packages/hooks/src/types.ts` 中定义，并同时支持 Claude Code 的新字段（`tool_name`、`tool_response`、`last_assistant_message`、`source`、`reason`）与遗留别名（`tool`、`tool_output`、`turn_summary`）[资料来源：[packages/hooks/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/hooks/CHANGELOG.md)]。`e2e-publish.sh` 在打包后将所有钩子事件与真实 Claude Code 负载对齐，从而在全局安装场景下也能端到端工作 [资料来源：[packages/hooks/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/hooks/CHANGELOG.md)]。

## 已知故障模式

下表汇总了社区与 issue 中反复出现、可被运维或升级流程提前识别的故障模式（事件与版本信息来自仓库 issue 与 release notes）：

| 现象 | 触发条件 | 状态 / 备注 |
|------|---------|------|
| `cavemem mcp` 静默退出 | 打包后 `isMainEntry()` 判定失败，`main()` 未执行 | 已在 v0.2.1 由 `c756051` 修复：CLI 直接调用 main 而非依赖 import 副作用 [资料来源：[apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md)] |
| `cavemem start` 报 `spawn EFTYPE` | Windows 全局安装后 npm shim 触发 | 同时影响钩子的 worker 自动启动 |
| `better-sqlite3` 加载失败 | Node.js 26.0.0（V8 14.6）原生绑定不兼容 | 社区建议以 `bun:sqlite` 作为回退 |
| Claude Code 钩子路径折叠 | Windows 下 `C:\Users\hp\...` 在 `bash -c` 中被解析为 `C:Usershp...` | 安装器需改写为正斜杠或跨平台序列化 |
| `cavemem status` 报 DB `fail` | `better_sqlite3.node` 是为旧版 V8 编译的 | WSL/Linux 全局安装常见 |
| `session-start` 跨项目泄漏 | 钩子未按 `cwd` 过滤"最近会话" | 启动 B 项目时可能注入 A 项目上下文 |
| Codex 钩子未安装 | 安装器把配置写到 `config.json`，而 Codex 实际读取 `config.toml` | 需要在 `~/.codex/config.toml` 启用 `codex_hooks` |
| OpenCode 桌面端不工作 | opencode 没有钩子系统，只有 MCP | 桌面端无数据来源，仅查询可用 |

## 安全注意事项

下列问题源自仓库 issue，反映出当前版本在隐私与本地暴露面方面的边界：

- **Worker 查看器无认证**（issue #51）：`127.0.0.1:37777` 上多条路由返回**解压后**的记忆内容，本地进程或通过 CSRF / DNS-rebinding 攻击的网页均可读取。
- **无工具级白名单**（issue #50）：Claude Code 安装器注册 `PostToolUse` 时没有 `matcher`，`post-tool-use.ts` 默认捕获**全部**工具的输入与输出。
- **`redactSecrets` 是空操作**（issue #49）：配置项 `privacy.redactSecrets` 默认 `true`，但代码中没有任何消费点，工具输出中的密钥以明文存储。
- **`privacy.excludePatterns` 不被读取**（issue #48）：README 与 CLAUDE 声称"在写入边界强制执行"，但实际从未读取，匹配路径仍被捕获。

这些已知问题意味着 `cavemem status` 通过、`cavemem doctor` 通过，并不等于隐私边界已就位；用户在公开机器上运行前应额外审计。

## See Also

- [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md)：用户面向的快速上手与命令清单
- [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md)：仓库布局、不变式与开发工作流
- `packages/embedding`：嵌入提供方（local / ollama / openai / none）的选型与配置
- `packages/installers`：各 IDE 钩子的实现细节与已知差异
- `apps/mcp-server`：stdio MCP 工具集合（`search` / `timeline` / `get_observations` / `list_sessions`）

---

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

---

## Doramagic 踩坑日志

项目：JuliusBrussee/cavemem

摘要：发现 35 个潜在踩坑项，其中 8 个为 high/blocking；最高优先级：安装坑 - 来源证据：Codex installer is out of date。

## 1. 安装坑 · 来源证据：Codex installer is out of date

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex installer is out of date
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/17 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：cavemem start fails with spawn EFTYPE on Windows

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：cavemem start fails with spawn EFTYPE on Windows
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/11 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 3. 配置坑 · 来源证据：session-start: prior-session context not scoped to cwd, leaks across unrelated projects

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：session-start: prior-session context not scoped to cwd, leaks across unrelated projects
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/39 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 安全/权限坑 · 失败模式：security_permissions: No per-tool capture allowlist/matcher: sensitive MCP tool I/O captured by default

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: No per-tool capture allowlist/matcher: sensitive MCP tool I/O captured by default
- 对用户的影响：Developers may expose sensitive permissions or credentials: No per-tool capture allowlist/matcher: sensitive MCP tool I/O captured by default
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/50 | No per-tool capture allowlist/matcher: sensitive MCP tool I/O captured by default

## 5. 安全/权限坑 · 失败模式：security_permissions: Windows: hook commands written with backslashes break under bash -c (path collapse to `C:User...

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: Windows: hook commands written with backslashes break under bash -c (path collapse to `C:Usershp...`)
- 对用户的影响：Developers may expose sensitive permissions or credentials: Windows: hook commands written with backslashes break under bash -c (path collapse to `C:Usershp...`)
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/43 | Windows: hook commands written with backslashes break under bash -c (path collapse to `C:Usershp...`)

## 6. 安全/权限坑 · 失败模式：security_permissions: Worker HTTP viewer on 127.0.0.1:37777 is unauthenticated and serves decompressed memory

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: Worker HTTP viewer on 127.0.0.1:37777 is unauthenticated and serves decompressed memory
- 对用户的影响：Developers may expose sensitive permissions or credentials: Worker HTTP viewer on 127.0.0.1:37777 is unauthenticated and serves decompressed memory
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/51 | Worker HTTP viewer on 127.0.0.1:37777 is unauthenticated and serves decompressed memory

## 7. 安全/权限坑 · 失败模式：security_permissions: privacy.excludePatterns is documented as enforced but is never read (matching paths still cap...

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: privacy.excludePatterns is documented as enforced but is never read (matching paths still captured)
- 对用户的影响：Developers may expose sensitive permissions or credentials: privacy.excludePatterns is documented as enforced but is never read (matching paths still captured)
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/48 | privacy.excludePatterns is documented as enforced but is never read (matching paths still captured)

## 8. 安全/权限坑 · 失败模式：security_permissions: redactSecrets is a no-op: secrets in tool output are stored verbatim (no output-side scrubber)

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: redactSecrets is a no-op: secrets in tool output are stored verbatim (no output-side scrubber)
- 对用户的影响：Developers may expose sensitive permissions or credentials: redactSecrets is a no-op: secrets in tool output are stored verbatim (no output-side scrubber)
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/49 | redactSecrets is a no-op: secrets in tool output are stored verbatim (no output-side scrubber)

## 9. 安装坑 · 失败模式：installation: Add Antigravity IDE support

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Add Antigravity IDE support
- 对用户的影响：Developers may fail before the first successful local run: Add Antigravity IDE support
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/38 | Add Antigravity IDE support

## 10. 安装坑 · 失败模式：installation: Add Trae SOLO IDE support

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Add Trae SOLO IDE support
- 对用户的影响：Developers may fail before the first successful local run: Add Trae SOLO IDE support
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/40 | Add Trae SOLO IDE support

## 11. 安装坑 · 失败模式：installation: Codex installer is out of date

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Codex installer is out of date
- 对用户的影响：Developers may fail before the first successful local run: Codex installer is out of date
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/17 | Codex installer is out of date

## 12. 安装坑 · 失败模式：installation: cavemem start fails with spawn EFTYPE on Windows

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: cavemem start fails with spawn EFTYPE on Windows
- 对用户的影响：Developers may fail before the first successful local run: cavemem start fails with spawn EFTYPE on Windows
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/11 | cavemem start fails with spawn EFTYPE on Windows

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

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

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

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

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

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

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

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

## 17. 安装坑 · 来源证据：Add Antigravity IDE support

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add Antigravity IDE support
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/38 | 来源类型 github_issue 暴露的待验证使用条件。

## 18. 安装坑 · 来源证据：Add Trae SOLO IDE support

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add Trae SOLO IDE support
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/40 | 来源类型 github_issue 暴露的待验证使用条件。

## 19. 安装坑 · 来源证据：No per-tool capture allowlist/matcher: sensitive MCP tool I/O captured by default

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：No per-tool capture allowlist/matcher: sensitive MCP tool I/O captured by default
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/50 | 来源类型 github_issue 暴露的待验证使用条件。

## 20. 安装坑 · 来源证据：Windows: hook commands written with backslashes break under bash -c (path collapse to `C:Usershp...`)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: hook commands written with backslashes break under bash -c (path collapse to `C:Usershp...`)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/43 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 21. 安装坑 · 来源证据：bug: better-sqlite3 native bindings fail on Node.js 26.0.0 (v147) - use bun:sqlite as fallback?

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: better-sqlite3 native bindings fail on Node.js 26.0.0 (v147) - use bun:sqlite as fallback?
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/37 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 22. 安装坑 · 来源证据：privacy.excludePatterns is documented as enforced but is never read (matching paths still captured)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：privacy.excludePatterns is documented as enforced but is never read (matching paths still captured)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/48 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

## 24. 配置坑 · 来源证据：Cavemen with Opecode Desktop App on windows not working

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Cavemen with Opecode Desktop App on windows not working
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/45 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

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

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

## 26. 维护坑 · 失败模式：migration: bug: better-sqlite3 native bindings fail on Node.js 26.0.0 (v147) - use bun:sqlite as fallback?

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: bug: better-sqlite3 native bindings fail on Node.js 26.0.0 (v147) - use bun:sqlite as fallback?
- 对用户的影响：Developers may hit a documented source-backed failure mode: bug: better-sqlite3 native bindings fail on Node.js 26.0.0 (v147) - use bun:sqlite as fallback?
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/37 | bug: better-sqlite3 native bindings fail on Node.js 26.0.0 (v147) - use bun:sqlite as fallback?

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

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | github_repo:1213956965 | https://github.com/JuliusBrussee/cavemem | no_demo; severity=medium

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

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

## 30. 安全/权限坑 · 来源证据：Worker HTTP viewer on 127.0.0.1:37777 is unauthenticated and serves decompressed memory

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Worker HTTP viewer on 127.0.0.1:37777 is unauthenticated and serves decompressed memory
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/51 | 来源类型 github_issue 暴露的待验证使用条件。

## 31. 安全/权限坑 · 来源证据：redactSecrets is a no-op: secrets in tool output are stored verbatim (no output-side scrubber)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：redactSecrets is a no-op: secrets in tool output are stored verbatim (no output-side scrubber)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/49 | 来源类型 github_issue 暴露的待验证使用条件。

## 32. 能力坑 · 失败模式：capability: session-start: prior-session context not scoped to cwd, leaks across unrelated projects

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: session-start: prior-session context not scoped to cwd, leaks across unrelated projects
- 对用户的影响：Developers may hit a documented source-backed failure mode: session-start: prior-session context not scoped to cwd, leaks across unrelated projects
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/39 | session-start: prior-session context not scoped to cwd, leaks across unrelated projects

## 33. 运行坑 · 失败模式：performance: Cavemen with Opecode Desktop App on windows not working

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: Cavemen with Opecode Desktop App on windows not working
- 对用户的影响：Developers may hit a documented source-backed failure mode: Cavemen with Opecode Desktop App on windows not working
- 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/45 | Cavemen with Opecode Desktop App on windows not working

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

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

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

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

<!-- canonical_name: JuliusBrussee/cavemem; human_manual_source: deepwiki_human_wiki -->