ClawVault 🐘

大象永不遗忘。为 OpenClaw 智能体提供结构化记忆。

专为OpenClaw构建。标准安装：npm CLI + 钩子安装 + 钩子启用。

安全与透明

此技能的功能：

• 在你的保险库目录（CLAWVAULT_PATH或自动发现）中读取/写入 Markdown 文件
• repair-session读取和修改 OpenClaw 会话记录（~/.openclaw/agents/）——在写入前创建备份
• 提供一个 OpenClaw钩子包（hooks/clawvault/handler.js），包含生命周期事件（gateway:startup、gateway:heartbeat、命令：新建，会话：开始，压缩：内存刷新，每周定时任务）。钩子是可选的，必须安装/启用。
• 观察 --压缩调用LLM API（默认为Gemini Flash），将会话记录压缩为观察结果

使用的环境变量：

• CLAWVAULT_PATH— 存储库位置（可选，如未设置则自动发现）
• OPENCLAW_HOME/OPENCLAW_STATE_DIR— 被修复会话用于查找会话记录
• GEMINI_API_KEY— 被观察用于LLM压缩（可选，仅在启用观察功能时使用）

无云端同步——所有数据均保留在本地。除用于观察压缩的LLM API外，无任何网络调用。

这是一个完整的CLI工具，而非仅提供指令。它能够写入文件、注册钩子并运行代码。

可审计性：已发布的ClawHub技能包包含SKILL.md、HOOK.md以及hooks/clawvault/handler.js文件，以便用户在启用前可审查钩子行为。

安装（标准方式）

npm install -g clawvault
openclaw hooks install clawvault
openclaw hooks enable clawvault

# Verify and reload
openclaw hooks list --verbose
openclaw hooks info clawvault
openclaw hooks check
# restart gateway process

clawhub install clawvault可安装技能指导，但不能替代显式的钩子包安装。

推荐的安全安装流程

# 1) Review package metadata before install
npm view clawvault version dist.integrity dist.tarball repository.url

# 2) Install CLI + qmd dependency
npm install -g clawvault@latest
npm install -g github:tobi/qmd

# 3) Install hook pack, but DO NOT enable yet
openclaw hooks install clawvault

# 4) Review hook source locally before enabling
node -e "const fs=require('fs');const p='hooks/clawvault/handler.js';console.log(fs.existsSync(p)?p:'hook file not found in current directory')"
openclaw hooks info clawvault

# 5) Enable only after review
openclaw hooks enable clawvault
openclaw hooks check

设置

# Initialize vault (creates folder structure + templates)
clawvault init ~/my-vault

# Or set env var to use existing vault
export CLAWVAULT_PATH=/path/to/memory

# Optional: shell integration (aliases + CLAWVAULT_PATH)
clawvault shell-init >> ~/.bashrc

新代理快速入门

# Start your session (recover + recap + summary)
clawvault wake

# Capture and checkpoint during work
clawvault capture "TODO: Review PR tomorrow"
clawvault checkpoint --working-on "PR review" --focus "type guards"

# End your session with a handoff
clawvault sleep "PR review + type guards" --next "respond to CI" --blocked "waiting for CI"

# Health check when something feels off
clawvault doctor

使用前的现实检查

# Verify runtime compatibility with current OpenClaw setup
clawvault compat

# Verify qmd is available
qmd --version

# Verify OpenClaw CLI is installed in this shell
openclaw --version

ClawVault当前依赖qmd作为核心保险库/查询流程的基础。

当前功能集

记忆图谱

ClawVault 从维基链接、标签和前置元数据构建类型化知识图谱：

# View graph summary
clawvault graph

# Refresh graph index
clawvault graph --refresh

图谱存储于.clawvault/graph-index.json—— 架构版本化，支持增量重建。

图谱感知上下文检索

# Default context (semantic + graph neighbors)
clawvault context "database decision"

# With a profile preset
clawvault context --profile planning "Q1 roadmap"
clawvault context --profile incident "production outage"
clawvault context --profile handoff "session end"

# Auto profile (used by OpenClaw hook)
clawvault context --profile auto "current task"

上下文配置文件

OpenClaw 兼容性诊断

# Check hook wiring, event routing, handler safety
clawvault compat

# Strict mode for CI
clawvault compat --strict

核心命令

唤醒 + 休眠（主要）

clawvault wake
clawvault sleep "what I was working on" --next "ship v1" --blocked "waiting for API key"

按类型存储记忆

# Types: fact, feeling, decision, lesson, commitment, preference, relationship, project
clawvault remember decision "Use Postgres over SQLite" --content "Need concurrent writes for multi-agent setup"
clawvault remember lesson "Context death is survivable" --content "Checkpoint before heavy work"
clawvault remember relationship "Justin Dukes" --content "Client contact at Hale Pet Door"

快速捕获至收件箱

clawvault capture "TODO: Review PR tomorrow"

搜索（需安装 qmd）

# Keyword search (fast)
clawvault search "client contacts"

# Semantic search (slower, more accurate)
clawvault vsearch "what did we decide about the database"

上下文死亡恢复能力

唤醒（会话开始）

clawvault wake

休眠（会话结束）

clawvault sleep "what I was working on" --next "finish docs" --blocked "waiting for review"

检查点（频繁保存状态）

clawvault checkpoint --working-on "PR review" --focus "type guards" --blocked "waiting for CI"

恢复（手动检查）

clawvault recover --clear
# Shows: death time, last checkpoint, recent handoff

移交（手动结束会话）

clawvault handoff \
  --working-on "ClawVault improvements" \
  --blocked "npm token" \
  --next "publish to npm, create skill" \
  --feeling "productive"

回顾（引导新会话）

clawvault recap
# Shows: recent handoffs, active projects, pending commitments, lessons

自动链接

在 Markdown 文件中维基链接实体提及：

# Link all files
clawvault link --all

# Link single file
clawvault link memory/2024-01-15.md

文件夹结构

vault/
├── .clawvault/           # Internal state
│   ├── last-checkpoint.json
│   └── dirty-death.flag
├── decisions/            # Key choices with reasoning
├── lessons/              # Insights and patterns
├── people/               # One file per person
├── projects/             # Active work tracking
├── handoffs/             # Session continuity
├── inbox/                # Quick captures
└── templates/            # Document templates

最佳实践

1. 在会话开始时唤醒—clawvault wake恢复上下文
2. 每 10-15 分钟设置检查点在繁重工作期间
3. 在会话结束前休眠—clawvault sleep捕捉下一步行动
4. 使用类型——了解你存储的内容有助于确定存放位置
5. 大量使用维基链接——[[人名]]构建你的知识图谱

AGENTS.md 检查清单

## Memory Checklist
- [ ] Run `clawvault wake` at session start
- [ ] Checkpoint during heavy work
- [ ] Capture key decisions/lessons with `clawvault remember`
- [ ] Use wiki-links like `[[person-name]]`
- [ ] End with `clawvault sleep "..." --next "..." --blocked "..."`
- [ ] Run `clawvault doctor` when something feels off

将此检查清单附加到现有的记忆指令中。除非你打算替换完整的 AGENTS.md 行为，否则不要替换。

会话记录修复（v1.5.0+）

当 Anthropic API 因“发现意外的 tool_use_id 存在于 tool_result 块中”而拒绝时，使用：

# See what's wrong (dry-run)
clawvault repair-session --dry-run

# Fix it
clawvault repair-session

# Repair a specific session
clawvault repair-session --session <id> --agent <agent-id>

# List available sessions
clawvault repair-session --list

修复内容：

• 孤立的tool_result块引用了不存在的tool_useID
• 包含部分 JSON 的中止工具调用
• 损坏的父链引用

备份会自动创建（使用--no-backup以跳过）。

故障排除

• qmd 未安装— 安装 qmd，然后通过以下命令确认qmd --version
• 未找到 ClawVault— 运行clawvault init或设置CLAWVAULT_PATH
• CLAWVAULT_PATH 缺失— 运行clawvault shell-init并添加到 shell rc 文件
• 孤儿链接过多— 运行clawvault link --orphans
• 收件箱积压警告— 处理或归档收件箱项目
• “unexpected tool_use_id”错误— 运行clawvault repair-session
• OpenClaw 集成漂移— 运行clawvault compat
• 钩子启用失败 / 钩子未找到— 运行openclaw hooks install clawvault，然后openclaw hooks enable clawvault，重启网关，并通过openclaw hooks list --verbose
• 验证图表已过期— 运行
• clawvault graph --refresh任务上下文错误— 尝试clawvault context --profile incident或

--profile planning

• 稳定性快照类型检查通过 (npm run typecheck
• )测试套件通过 (449/449
• )
  • 跨平台路径处理已在以下方面针对Windows进行了强化：
  • WebDAV路径安全性与文件系统解析
  • shell初始化输出预期
• 由以下验证OpenClaw运行时连接clawvault compat --strict（需要本地openclaw二进制文件以进行完整的运行时验证）

与qmd的集成

ClawVault使用qmd进行搜索：

# Install qmd
bun install -g github:tobi/qmd

# Alternative
npm install -g github:tobi/qmd

# Add vault as collection
qmd collection add /path/to/vault --name my-memory --mask "**/*.md"

# Update index
qmd update && qmd embed

环境变量

• CLAWVAULT_PATH— 默认保险库路径（跳过自动发现）
• OPENCLAW_HOME— OpenClaw主目录（由repair-session使用）
• OPENCLAW_STATE_DIR— OpenClaw状态目录（由repair-session使用）
• GEMINI_API_KEY— 由observe用于LLM驱动的压缩（可选）

链接

• npm（Node包管理器）：https://www.npmjs.com/package/clawvault
• GitHub（代码托管平台）：https://github.com/Versatly/clawvault
• 问题反馈：https://github.com/Versatly/clawvault/issues