介绍
# ClawVault 🐘
大象从未遗忘。为 OpenClaw 代理提供的结构化记忆。
> **专为 [OpenClaw](https://openclaw.ai) 打造**。标准安装：npm CLI + hook install + hook enable。
## 安全与透明度
**此技能的作用：** - 读取/写入您的 vault 目录中的 markdown 文件（`CLAWVAULT_PATH` 或自动发现） - `repair-session` 读取并修改 OpenClaw 会话记录（`~/.openclaw/agents/`）—— 写入前创建备份 - 提供一个 OpenClaw **hook 包**（`hooks/clawvault/handler.js`），包含生命周期事件（`gateway:startup`、`gateway:heartbeat`、`command:new`、`session:start`、`compaction:memoryFlush`、`cron.weekly`）。Hook 是可选的，必须手动安装/启用。 - `observe --compress` 调用 LLM API（默认为 Gemini Flash）将会话记录压缩为观察结果
**使用的环境变量：** - `CLAWVAULT_PATH` — vault 位置（可选，未设置则自动发现） - `OPENCLAW_HOME` / `OPENCLAW_STATE_DIR` — 由 `repair-session` 用于查找会话记录 - `GEMINI_API_KEY` — 由 `observe` 用于 LLM 压缩（可选，仅在使用观察功能时需要）
**无云同步 —— 所有数据均保留在本地。除用于观察压缩的 LLM API 外，无网络调用。**
**这是一个完整的 CLI 工具，而非仅提供指令。** 它会写入文件、注册 hook 并运行代码。
**可审计性：** 已发布的 ClawHub skill bundle 包含 `SKILL.md`、`HOOK.md` 和 `hooks/clawvault/handler.js`，以便用户在启用前检查 hook 行为。
## 安装（标准方式）
```bash 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` 可以安装 skill 指南，但不能替代显式的 hook 包安装。
### 推荐的安全安装流程
```bash # 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 ```
## 设置
```bash # 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 ```
## 新代理快速入门
```bash # 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 ```
## 使用前的现实检查
```bash # 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` 来实现核心 vault/query 流程。
## 当前功能集
### 记忆图谱
ClawVault 从 wiki-links、tags 和 frontmatter 构建类型化知识图谱：
```bash # View graph summary clawvault graph
# Refresh graph index clawvault graph --refresh ```
图谱存储于 `.clawvault/graph-index.json` —— schema 版本化，增量重建。
### 图谱感知的上下文检索
```bash # 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" ```
### 上下文配置
| 配置 | 用途 | |---------|---------| | `default` | 平衡检索 | | `planning` | 更广泛的战略上下文 | | `incident` | 近期事件、阻碍项、紧急事项 | | `handoff` | 会话转换上下文 | | `auto` | Hook 根据会话意图选择的配置 |
### OpenClaw 兼容性诊断
```bash # Check hook wiring, event routing, handler safety clawvault compat
# Strict mode for CI clawvault compat --strict ```
## 核心命令
### Wake + Sleep（主要）
```bash clawvault wake clawvault sleep "what I was working on" --next "ship v1" --blocked "waiting for API key" ```
### 按类型存储记忆
```bash # 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" ```
### 快速捕捉到收件箱
```bash clawvault capture "TODO: Review PR tomorrow" ```
### 搜索（需要安装 qmd）
```bash # Keyword search (fast) clawvault search "client contacts"
# Semantic search (slower, more accurate) clawvault vsearch "what did we decide about the database" ```
## 上下文丢失恢复能力
### Wake（会话开始）
```bash clawvault wake ```
### Sleep（会话结束）
```bash clawvault sleep "what I was working on" --next "finish docs" --blocked "waiting for review" ```
### Checkpoint（频繁保存状态）
```bash clawvault checkpoint --working-on "PR review" --focus "type guards" --blocked "waiting for CI" ```
### Recover（手动检查）
```bash clawvault recover --clear # Shows: death time, last checkpoint, recent handoff ```
### Handoff（手动结束会话）
```bash clawvault handoff \ --working-on "ClawVault improvements" \ --blocked "npm token" \ --next "publish to npm, create skill" \ --feeling "productive" ```
### Recap（引导新会话）
```bash clawvault recap # Shows: recent handoffs, active projects, pending commitments, lessons ```
## 自动链接
Wiki-link markdown 文件中的实体提及：
```bash # 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. **自由使用 Wiki-link** — `[[person-name]]` 构建您的知识图谱
## AGENTS.md 检查清单
```markdown ## 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 拒绝并提示“unexpected tool_use_id found in tool_result blocks”时，请使用：
```bash # 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_use` ID 的孤立 `tool_result` 块 - 带有部分 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` - **Hook 启用失败 / 找不到 hook** — 运行 `openclaw hooks install clawvault`，然后 `openclaw hooks enable clawvault`，重启 gateway，并通过 `openclaw hooks list --verbose` 验证 - **图谱过期** — 运行 `clawvault graph --refresh` - **任务的上下文不正确** — 尝试 `clawvault context --profile incident` 或 `--profile planning`
## 稳定性快照
- 类型检查通过（`npm run typecheck`） - 测试套件通过（`449/449`） - 跨平台路径处理针对 Windows 进行了强化： - qmd URI/文档路径规范化 - WebDAV 路径安全和文件系统解析 - shell-init 输出预期 - OpenClaw 运行时接线已通过 `clawvault compat --strict` 验证（需要本地 `openclaw` 二进制文件以进行完整的运行时验证）
## 与 qmd 集成
ClawVault 使用 [qmd](https://github.com/tobi/qmd) 进行搜索：
```bash # 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` — 默认 vault 路径（跳过自动发现） - `OPENCLAW_HOME` — OpenClaw 主目录（由 repair-session 使用） - `OPENCLAW_STATE_DIR` — OpenClaw 状态目录（由 repair-session 使用） - `GEMINI_API_KEY` — 由 `observe` 用于 LLM 驱动的压缩（可选）
## 链接
- npm: https://www.npmjs.com/package/clawvault - GitHub: https://github.com/Versatly/clawvault - Issues: https://github.com/Versatly/clawvault/issues