Doramagic.ai
English

Doramagic 项目包 · 项目说明书

cavemem 项目

面向编码助手的跨智能体持久化记忆：压缩存储、快速检索，默认本地运行。

cavemem System Overview & Architecture

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

章节 相关页面

继续阅读本节完整说明和来源证据。

项目定位与设计目标

cavemem 是面向编码助手的跨智能体（cross-agent）持久化记忆系统，其核心目标是在多个 IDE 会话之间保留上下文，并尽量降低存储与检索成本。系统通过 IDE 钩子（hooks）在会话边界触发采集，使用 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）。

graph LR
    A[IDE 钩子] --> B[redact <private>]
    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/configpackages/config基于 Zod 的自描述 schema，导出 settingsDocs() 用于 cavemem config show。资料来源：packages/config/CHANGELOG.md:8-15
@cavemem/compresspackages/compresscaveman 文法压缩/解压，是写路径必经环节。资料来源：packages/compress/package.json:1-30
@cavemem/embeddingpackages/embedding懒加载单例嵌入器，MCP 握手阶段不阻塞。资料来源：packages/embedding/CHANGELOG.md:18-21
@cavemem/workerapps/worker嵌入构建后台守护，空闲自动退出。资料来源：apps/worker/package.json:1-25
@cavemem/mcp-serverapps/mcp-server提供四个检索工具（search、timeline、get_observations、list_sessions）。资料来源：apps/mcp-server/CHANGELOG.md:14-18
@cavemem/hookspackages/hooksIDE 钩子协议适配，同时支持 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

来源：https://github.com/JuliusBrussee/cavemem / 项目说明书

Compression Grammar, Settings & Privacy Controls

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

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

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

数据流概览：

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 数据流描述

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

IDE Installers, Hooks & MCP Server

cavemem 是一个跨代理持久记忆系统，由三类协作模块组成。IDE 安装器负责在每个受支持的编码助手（Claude Code、Cursor、Gemini CLI、OpenCode、Codex）中注入钩子命令；钩子处理包在会话边界（SessionStart / SessionEnd）以及工具调用后（PostToolUse）触发压缩与写库；MCP 服务器则通过 stdio 向...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 安装器接口与契约

继续阅读本节完整说明和来源证据。

章节 支持的 IDE 与配置差异

继续阅读本节完整说明和来源证据。

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

继续阅读本节完整说明和来源证据。

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

概述与组件职责

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

资料来源：README.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、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、#40、#23）。

资料来源：packages/installers/src/codex.ts:38-67、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、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

跨平台已知问题

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

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、#49）。
  • 工具 I/O 无选择性捕获：PostToolUse 钩子注册时未指定 matcher，敏感 MCP 工具的输入输出默认全部入库（#50）。
  • 会话上下文跨项目泄漏：session-start 钩子未按 cwd 作用域隔离，可能在项目 A 中注入项目 B 的历史摘要（#39）。
  • Worker HTTP 鉴权缺失：127.0.0.1:37777 绑定无身份验证，存在 CSRF / DNS-rebinding 风险（#51）。
  • 原生绑定兼容性：Node.js 26.0.0 的 V8 14.6 破坏 better-sqlite3 原生绑定（#37）；WSL 安装也可能失败（#22）。

另请参阅

  • 持久化与压缩架构
  • 嵌入提供者配置
  • 发布与端到端验证流程

资料来源：README.md、CLAUDE.md

CLI Commands, Worker & Known Failure Modes

cavemem 是一个面向多 IDE 的本地持久化记忆系统，由 apps/cli、本地 apps/worker 守护进程与 apps/mcp-server 三个进程协作构成。CLI 负责用户面命令、配置管理与 IDE 集成；Worker 提供只读查看器和后台嵌入回填；MCP Server 暴露查询工具。CLAUDE.md 将整体布局描述为 apps/cli（用户二进制）、a...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

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]。

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

CLI 命令总览

CLI 基于 commander 与 kleur 构建，并使用 tsup 打包发布，@modelcontextprotocol/sdk 出现在依赖中以支持 cavemem mcp 子命令 资料来源：[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]

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

Worker 守护进程

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

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

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]。e2e-publish.sh 在打包后将所有钩子事件与真实 Claude Code 负载对齐，从而在全局安装场景下也能端到端工作 资料来源：[packages/hooks/CHANGELOG.md]。

已知故障模式

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

现象触发条件状态 / 备注
cavemem mcp 静默退出打包后 isMainEntry() 判定失败，main() 未执行已在 v0.2.1 由 c756051 修复：CLI 直接调用 main 而非依赖 import 副作用 资料来源：[apps/cli/CHANGELOG.md]
cavemem start 报 spawn EFTYPEWindows 全局安装后 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 failbetter_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：用户面向的快速上手与命令清单
  • CLAUDE.md：仓库布局、不变式与开发工作流
  • packages/embedding：嵌入提供方（local / ollama / openai / none）的选型与配置
  • packages/installers：各 IDE 钩子的实现细节与已知差异
  • apps/mcp-server：stdio MCP 工具集合（search / timeline / get_observations / list_sessions）

来源：https://github.com/JuliusBrussee/cavemem / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Codex installer is out of date

可能增加新用户试用和生产接入成本。

high 来源证据：cavemem start fails with spawn EFTYPE on Windows

可能阻塞安装或首次运行。

high 来源证据：session-start: prior-session context not scoped to cwd, leaks across unrelated projects

可能增加新用户试用和生产接入成本。

high 失败模式：security_permissions: 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

Pitfall Log / 踩坑日志

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

来源：Doramagic 发现、验证与编译记录