ClawVault

核心用法

ClawVault是专为OpenClaw Agent设计的结构化记忆CLI工具，通过wake/sleep生命周期管理、类型化记忆存储（decision/lesson/commitment等8类）、记忆图谱构建和上下文感知检索来解决"上下文死亡"问题。核心工作流：会话开始时执行clawvault wake恢复上下文，工作中用checkpoint保存状态、capture快速捕获、remember结构化记录，结束时clawvault sleep生成交接文档。支持语义搜索（依赖qmd）和图谱感知检索（--profile auto/planning/incident/handoff）。

显著优点

• 深度OpenClaw集成：提供官方hook包，支持gateway启动/心跳/会话开始等生命周期事件自动触发
• 防上下文死亡设计：自动检查点、死亡检测警报、会话修复（repair-session可修复Anthropic API的tool_use_id错误）
• 本地优先：无云服务同步，仅可选调用Gemini API做观察压缩
• 结构化知识图谱：wiki链接自动构建实体关系图，支持增量重建
• 多平台 hardened：Windows路径处理、WebDAV安全经过专项加固

潜在缺点/局限性

• 外部依赖较重：核心查询功能依赖qmd（需单独安装），否则搜索不可用
• 可选LLM调用不透明：observe --compress和observe --active需GEMINI_API_KEY，但文档未明确说明数据如何被处理
• Hook启用流程复杂：需手动执行install+enable+gateway重启+验证四步，易遗漏
• Windows生态适配：虽经hardened，但shell-init等特性在Windows预期行为可能差异
• 图谱索引本地存储：.clawvault/graph-index.json无版本控制，损坏需手动--refresh

适合人群

• 长期使用OpenClaw的Agent开发者，需跨会话保持项目上下文
• 多Agent协作场景，需结构化交接和知识沉淀
• 对数据本地存储有强要求的隐私敏感用户

常规风险

• repair-session会修改OpenClaw会话转录文件（虽有自动备份）
• Hook误配可能导致gateway事件循环异常（clawvault compat可检测）
• 环境变量配置错误（CLAWVAULT_PATH/OpenClaw路径）会导致静默失败或错误写入
• 长期未compact的观察数据可能积累存储膨胀

核心用法

ClawVault是为OpenClaw Agent设计的结构化记忆系统，通过CLI工具clawvault实现。核心工作流围绕「Wake-Work-Sleep」循环：

• Wake：clawvault wake —— 会话开始时恢复上下文、加载记忆图谱、注入相关背景
• Checkpoint：clawvault checkpoint —— 工作中定期保存状态（建议10-15分钟一次）
• Capture：clawvault capture —— 快速记录想法到收件箱
• Remember：clawvault remember <type> —— 按类型存储决策、教训、承诺等结构化记忆
• Sleep：clawvault sleep —— 会话结束时生成交接文档，记录下一步与阻塞项

记忆存储采用本地Markdown文件系统，按decisions/lessons/people/projects/handoffs/inbox自动组织，支持Wiki链接[[entity]]构建知识图谱。语义搜索依赖qmd工具，可选Gemini API进行LLM压缩。

显著优点

1. 上下文死亡防护：OpenClaw hook自动检测会话中断，注入恢复提示，显著降低长任务「失忆」风险
2. 图谱感知检索：不仅关键词匹配，还能基于记忆图谱的实体关系进行关联召回
3. 会话修复能力：repair-session可修复Anthropic API报错的损坏会话转录（tool_use_id孤儿问题）
4. 数据主权：纯本地存储，无云同步、无遥测、无分析，符合隐私优先场景
5. OpenClaw深度集成：通过hook pack监听生命周期事件，实现自动checkpoint、观察刷新、意图识别

潜在缺点与局限性

1. 外部依赖较重：核心搜索功能强制依赖qmd（需单独安装），LLM压缩需Gemini API key
2. Node.js生态锁定：npm全局安装，对非Node环境用户不够友好
3. Windows路径处理：虽已加固，但跨平台边缘场景仍有潜在问题
4. Hook启用复杂度：需执行install+enable+重启gateway三步，新手易遗漏
5. 无内置同步：多设备场景需自行解决vault目录同步（如Syncthing、git）

适合人群

• 高频使用OpenClaw/Claude Code等Agent工具、面临「上下文死亡」困扰的开发者
• 需要长期项目记忆、跨会话保持一致性的AI辅助编程用户
• 注重数据本地化的隐私敏感型用户
• 愿意投入时间维护个人知识图谱的工程师

常规风险

• CLI工具链信任：Skill本身为纯文档，但实际功能依赖安装的clawvault二进制，需关注npm包供应链
• Gemini API调用：使用observe --compress时会产生外部网络调用，API key需安全保管
• 会话转录修改：repair-session会读写~/.openclaw/agents/下的文件，虽有备份但涉及敏感数据操作
• Vault路径配置：错误设置CLAWVAULT_PATH可能导致数据写入意外位置