核心用法
ClawVault 是专为 OpenClaw 代理设计的结构化记忆 CLI 工具，采用「大象永不忘」的设计理念，解决长期 AI 会话中的上下文丢失（context death）问题。核心工作流围绕 wake（启动恢复）、checkpoint（定时保存）、sleep（会话结束）三个生命周期命令展开，形成完整的记忆闭环。
主要功能模块：
1. 记忆图谱（Memory Graph）：自动解析 markdown 中的 wiki 链接、标签和 frontmatter，构建类型化知识图谱，存储于 .clawvault/graph-index.json，支持增量重建与语义邻居检索。
2. 上下文画像（Context Profiles）：提供 default、planning、incident、handoff、auto 五种预设画像，针对不同场景（战略规划、故障处理、会话交接）调整检索策略，钩子系统可自动根据会话意图选择画像。
3. 检查点/恢复机制：checkpoint 命令保存当前工作状态（进行事项、关注焦点、阻塞项），recover 检测上下文死亡时间并提供修复建议，repair-session 可修复 Anthropic API 返回的 "unexpected tool_use_id" 错误。
4. 结构化存储：按类型（decision、lesson、person、project、handoff 等）组织 markdown 文件，配合 remember、capture 命令快速入库。
5. 语义搜索：依赖 qmd 后端提供关键词检索与向量语义搜索（search/vsearch）。
6. OpenClaw 钩子集成：提供完整的钩子包（hooks/clawvault/handler.js），响应 gateway:startup、gateway:heartbeat、session:start 等生命周期事件，实现自动检查点、主动观察刷新、上下文注入等能力。
显著优点
- 上下文死亡韧性：通过自动化检查点和会话交接机制，显著降低长时任务中断后的恢复成本
- 本地优先架构：无云同步，所有数据驻留本地 vault 目录，符合隐私敏感场景需求
- 图谱增强检索：相比纯向量搜索，结合知识图谱的邻居遍历能召回更相关的背景信息
- 细粒度审计：钩子代码开源可审查，安装流程明确区分「安装」与「启用」步骤，给予用户充分的知情决策空间
- 跨平台兼容：近期版本强化了 Windows 路径处理与 WebDAV 安全校验
潜在缺点与局限性
- 外部依赖较重：核心搜索功能依赖 qmd（需单独安装），且 qmd 并非 npm 官方源包，而是 GitHub 直接引用，供应链风险需关注
- Gemini API 可选依赖：
observe --compress和--active功能需GEMINI_API_KEY，虽为可选但部分高级功能受限 - 钩子启用复杂度：完整功能需手动执行 hook install → 审查 → hook enable → 重启 gateway 四步，对非技术用户门槛较高
- OpenClaw 生态绑定：虽 CLI 可独立使用，但设计理念和高级功能深度耦合 OpenClaw 运行时，迁移成本较高
- 存储格式锁定：markdown + wiki-link 的存储方式虽通用，但图谱索引的 JSON schema 为私有格式，长期数据可移植性存疑
适合人群
- 使用 OpenClaw 进行长时间、多会话复杂任务的开发者与知识工作者
- 对 AI 会话连续性有高要求，愿意投入 setup 成本换取 context 韧性的用户
- 偏好本地优先、拒绝云同步的隐私敏感型用户
- 习惯 markdown 原生工作流、熟悉命令行工具的技术用户
常规风险
- 钩子权限：启用后具备读取/修改 OpenClaw 会话转录文件的权限，虽自动备份但仍存在误操作导致会话损坏的理论风险
- 供应链安全：qmd 依赖来自 GitHub 而非 npm registry，建议固定 commit hash 或进行本地审计
- API 密钥管理：若使用 Gemini 压缩功能，需妥善保管
GEMINI_API_KEY，避免泄露至共享环境 - 版本漂移：OpenClaw 运行时升级后可能出现钩子兼容性 drift，需定期运行
clawvault compat --strict验证 - 数据备份：虽本地存储，但
.clawvault/目录含有关键索引，建议纳入常规备份策略，避免图谱损坏导致检索失效