clawvault

核心用法

ClawVault 是专为 OpenClaw Agent 设计的记忆管理系统，通过 CLI 工具 clawvault 实现结构化记忆存储与上下文连续性保障。核心工作流围绕 Wake-Capture-Sleep 循环展开：会话开始时执行 clawvault wake 恢复上下文，工作中使用 clawvault capture 快速记录或 clawvault checkpoint 保存状态，结束时 clawvault sleep 生成交接文档。记忆按类型（fact/feeling/decision/lesson/commitment/preference/relationship/project）分类存储，支持语义搜索（需 qmd）和基于 wiki-link 的知识图谱构建。

显著优点

1. 上下文死亡免疫：自动检测上下文丢失并提供恢复机制，通过 hook 在 gateway:startup 和 command:new 事件触发时自动检查点
2. 图谱感知检索：构建类型化知识图谱（.clawvault/graph-index.json），支持多维度上下文配置（default/planning/incident/handoff）
3. 会话修复能力：独有的 repair-session 功能可修复 Anthropic API 报错导致的损坏会话转录文件，自动备份保障安全
4. 零信任网络设计：除可选的 observe --compress 功能外，所有数据本地存储，无云端同步或遥测
5. OpenClaw 原生集成：通过可选 hook 实现自动上下文注入，支持 clawvault compat 诊断集成健康度

潜在缺点与局限性

1. 外部依赖：语义搜索依赖 qmd 工具（需单独安装），功能降级时仅支持关键词搜索
2. Gemini API 可选依赖：observe --compress 需要配置 GEMINI_API_KEY，增加密钥管理负担
3. 学习曲线：记忆类型系统、wiki-link 规范、上下文配置等概念需要一定上手时间
4. Node.js 生态锁定：基于 npm 分发，对非 Node 环境用户不够友好
5. 存储膨胀风险：长期高频使用可能导致 vault 目录体积增长，需定期归档

适合的目标群体

• 长期运行的 OpenClaw Agent：需要跨会话保持上下文的复杂任务代理
• 多项目并行开发者：通过知识图谱管理技术决策、人员关系、项目状态
• 研究型工作流：需要追溯决策理由、经验教训的知识工作者
• 团队协作场景：通过标准化 handoff 文档实现 Agent 间工作交接

使用风险

1. 文件系统风险：repair-session 会修改 ~/.openclaw/agents// 下的会话文件，虽有自动备份，仍建议在关键操作前手动备份
2. 环境变量配置：CLAWVAULT_PATH 等路径配置错误可能导致 vault 无法定位，建议通过 clawvault shell-init 固化配置
3. hook 启用风险：自动检查点功能在极端高频场景下可能产生性能开销，可通过 openclaw hooks disable clawvault 临时禁用
4. qmd 版本兼容性：语义搜索功能依赖 qmd 的特定版本，升级时需注意兼容性测试

ClawVault：OpenClaw 结构化记忆系统深度评估

ClawVault 是专为 OpenClaw Agent 设计的本地优先记忆管理工具，以「大象永不遗忘」为核心理念，通过图谱化存储、上下文配置与自动恢复机制解决 Agent 会话中的「上下文死亡」问题。

核心用法

采用 Wake-Capture-Sleep 工作流：

• clawvault wake 在会话启动时自动恢复上次状态
• capture/remember 存储决策、教训、承诺等结构化记忆
• checkpoint 每 10-15 分钟保存工作快照
• sleep 结束会话时生成包含下一步与阻塞项的交接记录

v2.0 引入 Memory Graph：通过 wiki-links 和 frontmatter 构建类型化知识图谱，支持图谱感知检索（context --profile planning/incident/handoff）。

显著优点

1. 完全本地：无云服务、无遥测，数据仅存储于 CLAWVAULT_PATH 指定目录
2. 深度集成：自动注册 OpenClaw hook，实现上下文死亡检测与会话注入
3. 会话修复：repair-session 可修复 Anthropic API 的 tool_use_id 错误，自动备份原始文件
4. 零依赖安全：纯 Node.js 内置模块实现，无供应链攻击面

局限与约束

• 可选依赖：语义搜索需额外安装 qmd；observe --compress 需 Gemini API Key
• 单用户架构：无多用户同步或协作机制
• T3 来源：个人开发者维护（g9pedro），长期支持存在不确定性

适合人群

• 高频使用 Claude/OpenClaw 的深度 Agent 用户
• 需跨会话保持项目上下文的开发者、研究员
• 对数据主权敏感、拒绝云笔记的隐私优先用户

常规风险

• 路径验证依赖：虽有 validateVaultPath，仍建议避免将 vault 设在共享目录
• hook 权限：启用 clawvault hook 后具备会话级代码注入能力，需确认来源可信
• 备份习惯：repair-session 虽自动备份，关键操作建议手动版本控制

安全认证亮点

CLS-Certify v2.1.0 扫描评分 S 级/88 分，六项维度全通过：

• execFileSync + shell: false 阻断命令注入
• 无第三方依赖、无网络调用、无敏感信息硬编码
• GDPR 数据最小化原则合规

> 建议：在 AGENTS.md 中固化记忆检查清单，将 clawvault wake/sleep 纳入标准会话协议。