ClawVault 🐘
An elephant never forgets. Structured memory for OpenClaw agents.
Built for OpenClaw. Canonical install: npm CLI + hook install + hook enable.
Security & Transparency
What this skill does:
- - Reads/writes markdown files in your vault directory (
CLAWVAULT_PATH or auto-discovered) - INLINECODE1 reads and modifies OpenClaw session transcripts (
~/.openclaw/agents/) — creates backups before writing - Provides an OpenClaw hook pack (
hooks/clawvault/handler.js) with lifecycle events (gateway:startup, gateway:heartbeat, command:new, session:start, compaction:memoryFlush, cron.weekly). Hook is opt-in and must be installed/enabled. - INLINECODE10 makes LLM API calls (Gemini Flash by default) to compress session transcripts into observations
Environment variables used:
- -
CLAWVAULT_PATH — vault location (optional, auto-discovered if not set) - INLINECODE12 /
OPENCLAW_STATE_DIR — used by repair-session to find session transcripts - INLINECODE15 — used by
observe for LLM compression (optional, only if using observe features)
No cloud sync — all data stays local. No network calls except LLM API for observe compression.
This is a full CLI tool, not instruction-only. It writes files, registers hooks, and runs code.
Auditability: the published ClawHub skill bundle includes SKILL.md, HOOK.md, and hooks/clawvault/handler.js so users can inspect hook behavior before enabling it.
Install (Canonical)
CODEBLOCK0
INLINECODE20 can install skill guidance, but does not replace explicit hook pack installation.
Recommended Safe Install Flow
CODEBLOCK1
Setup
CODEBLOCK2
Quick Start for New Agents
CODEBLOCK3
Reality Checks Before Use
CODEBLOCK4
ClawVault currently depends on qmd for core vault/query flows.
Current Feature Set
Memory Graph
ClawVault builds a typed knowledge graph from wiki-links, tags, and frontmatter:
CODEBLOCK5
Graph is stored at .clawvault/graph-index.json — schema versioned, incremental rebuild.
Graph-Aware Context Retrieval
CODEBLOCK6
Context Profiles
| Profile | Purpose |
|---|
| INLINECODE23 | Balanced retrieval |
| INLINECODE24 |
Broader strategic context |
|
incident | Recent events, blockers, urgent items |
|
handoff | Session transition context |
|
auto | Hook-selected profile based on session intent |
OpenClaw Compatibility Diagnostics
CODEBLOCK7
Core Commands
Wake + Sleep (primary)
CODEBLOCK8
Store memories by type
CODEBLOCK9
Quick capture to inbox
CODEBLOCK10
Search (requires qmd installed)
CODEBLOCK11
Context Death Resilience
Wake (start of session)
CODEBLOCK12
Sleep (end of session)
CODEBLOCK13
Checkpoint (save state frequently)
CODEBLOCK14
Recover (manual check)
CODEBLOCK15
Handoff (manual session end)
CODEBLOCK16
Recap (bootstrap new session)
CODEBLOCK17
Auto-linking
Wiki-link entity mentions in markdown files:
CODEBLOCK18
Folder Structure
CODEBLOCK19
Best Practices
- 1. Wake at session start —
clawvault wake restores context - Checkpoint every 10-15 min during heavy work
- Sleep before session end —
clawvault sleep captures next steps - Use types — knowing WHAT you're storing helps WHERE to put it
- Wiki-link liberally —
[[person-name]] builds your knowledge graph
Checklist for AGENTS.md
CODEBLOCK20
Append this checklist to existing memory instructions. Do not replace your full AGENTS.md behavior unless you intend to.
Session Transcript Repair (v1.5.0+)
When the Anthropic API rejects with "unexpected tooluseid found in tool_result blocks", use:
CODEBLOCK21
What it fixes:
- - Orphaned
tool_result blocks referencing non-existent tool_use IDs - Aborted tool calls with partial JSON
- Broken parent chain references
Backups are created automatically (use --no-backup to skip).
Troubleshooting
- - qmd not installed — install qmd, then confirm with INLINECODE34
- No ClawVault found — run
clawvault init or set INLINECODE36 - CLAWVAULTPATH missing — run
clawvault shell-init and add to shell rc - Too many orphan links — run INLINECODE38
- Inbox backlog warning — process or archive inbox items
- "unexpected tooluse_id" error — run INLINECODE39
- OpenClaw integration drift — run INLINECODE40
- Hook enable fails / hook not found — run
openclaw hooks install clawvault, then openclaw hooks enable clawvault, restart gateway, and verify via INLINECODE43 - Graph out of date — run INLINECODE44
- Wrong context for task — try
clawvault context --profile incident or INLINECODE46
Stability Snapshot
- - Typecheck passes (
npm run typecheck) - Test suite passes (
449/449) - Cross-platform path handling hardened for Windows in:
- qmd URI/document path normalization
- WebDAV path safety and filesystem resolution
- shell-init output expectations
- - OpenClaw runtime wiring validated by
clawvault compat --strict (requires local openclaw binary for full runtime validation)
Integration with qmd
ClawVault uses qmd for search:
CODEBLOCK22
Environment Variables
- -
CLAWVAULT_PATH — Default vault path (skips auto-discovery) - INLINECODE52 — OpenClaw home directory (used by repair-session)
- INLINECODE53 — OpenClaw state directory (used by repair-session)
- INLINECODE54 — Used by
observe for LLM-powered compression (optional)
Links
- - npm: https://www.npmjs.com/package/clawvault
- GitHub: https://github.com/Versatly/clawvault
- Issues: https://github.com/Versatly/clawvault/issues
ClawVault 🐘
大象从不忘事。为OpenClaw智能体提供结构化记忆。
专为OpenClaw构建。标准安装方式：npm CLI + 钩子安装 + 钩子启用。
安全性与透明度
此技能的功能：
- - 在您的存储库目录（CLAWVAULT_PATH 或自动发现）中读取/写入Markdown文件
- repair-session 读取并修改OpenClaw会话记录（~/.openclaw/agents/）——在写入前创建备份
- 提供一个OpenClaw 钩子包（hooks/clawvault/handler.js），包含生命周期事件（gateway:startup、gateway:heartbeat、command:new、session:start、compaction:memoryFlush、cron.weekly）。钩子为自愿启用，需安装并启用。
- observe --compress 调用LLM API（默认使用Gemini Flash）将会话记录压缩为观察记录
使用的环境变量：
- - CLAWVAULTPATH — 存储库位置（可选，未设置时自动发现）
- OPENCLAWHOME / OPENCLAWSTATEDIR — repair-session 用于查找会话记录
- GEMINIAPIKEY — observe 用于LLM压缩（可选，仅在使用observe功能时需要）
无云端同步——所有数据保留在本地。除observe压缩的LLM API调用外，无网络请求。
这是一个完整的CLI工具，而非仅指令集。 它会写入文件、注册钩子并运行代码。
可审计性： 发布的ClawHub技能包包含 SKILL.md、HOOK.md 和 hooks/clawvault/handler.js，用户可在启用前检查钩子行为。
安装（标准方式）
bash
npm install -g clawvault
openclaw hooks install clawvault
openclaw hooks enable clawvault
验证并重新加载
openclaw hooks list --verbose
openclaw hooks info clawvault
openclaw hooks check
重启网关进程
clawhub install clawvault 可安装技能指南，但不能替代显式的钩子包安装。
推荐的安全安装流程
bash
1) 安装前审查包元数据
npm view clawvault version dist.integrity dist.tarball repository.url
2) 安装CLI + qmd依赖
npm install -g clawvault@latest
npm install -g github:tobi/qmd
3) 安装钩子包，但暂不启用
openclaw hooks install clawvault
4) 启用前在本地审查钩子源码
node -e const fs=require(fs);const p=hooks/clawvault/handler.js;console.log(fs.existsSync(p)?p:当前目录未找到钩子文件)
openclaw hooks info clawvault
5) 审查后启用
openclaw hooks enable clawvault
openclaw hooks check
设置
bash
初始化存储库（创建文件夹结构 + 模板）
clawvault init ~/my-vault
或设置环境变量以使用现有存储库
export CLAWVAULT_PATH=/path/to/memory
可选：Shell集成（别名 + CLAWVAULT_PATH）
clawvault shell-init >> ~/.bashrc
新智能体快速入门
bash
开始会话（恢复 + 回顾 + 总结）
clawvault wake
工作中捕获并设置检查点
clawvault capture TODO: 明天审查PR
clawvault checkpoint --working-on PR审查 --focus 类型守卫
结束会话并交接
clawvault sleep PR审查 + 类型守卫 --next 响应CI --blocked 等待CI
感觉异常时进行健康检查
clawvault doctor
使用前的现实检查
bash
验证与当前OpenClaw设置的运行时兼容性
clawvault compat
验证qmd是否可用
qmd --version
验证当前Shell中是否安装了OpenClaw CLI
openclaw --version
ClawVault当前依赖 qmd 实现核心存储库/查询流程。
当前功能集
记忆图谱
ClawVault从Wiki链接、标签和前置元数据构建类型化知识图谱：
bash
查看图谱摘要
clawvault graph
刷新图谱索引
clawvault graph --refresh
图谱存储在 .clawvault/graph-index.json — 带版本控制，增量重建。
图谱感知的上下文检索
bash
默认上下文（语义 + 图谱邻居）
clawvault context 数据库决策
使用预设配置
clawvault context --profile planning 第一季度路线图
clawvault context --profile incident 生产故障
clawvault context --profile handoff 会话结束
自动配置（由OpenClaw钩子使用）
clawvault context --profile auto 当前任务
上下文配置
更广泛的战略上下文 |
| incident | 近期事件、阻塞项、紧急事项 |
| handoff | 会话过渡上下文 |
| auto | 基于会话意图的钩子选择配置 |
OpenClaw兼容性诊断
bash
检查钩子连接、事件路由、处理器安全性
clawvault compat
CI严格模式
clawvault compat --strict
核心命令
唤醒 + 休眠（主要）
bash
clawvault wake
clawvault sleep 我正在处理的工作 --next 发布v1 --blocked 等待API密钥
按类型存储记忆
bash
类型：事实、感受、决策、经验教训、承诺、偏好、关系、项目
clawvault remember decision 使用Postgres而非SQLite --content 需要多智能体设置的并发写入
clawvault remember lesson 上下文丢失是可存活的 --content 在繁重工作前设置检查点
clawvault remember relationship Justin Dukes --content Hale Pet Door的客户联系人
快速捕获到收件箱
bash
clawvault capture TODO: 明天审查PR
搜索（需要安装qmd）
bash
关键词搜索（快速）
clawvault search 客户联系人
语义搜索（较慢，更准确）
clawvault vsearch 我们关于数据库做了什么决定
上下文丢失恢复能力
唤醒（会话开始）
bash
clawvault wake
休眠（会话结束）
bash
clawvault sleep 我正在处理的工作 --next 完成文档 --blocked 等待审查
检查点（频繁保存状态）
bash
clawvault checkpoint --working-on PR审查 --focus 类型守卫 --blocked 等待CI
恢复（手动检查）
bash
clawvault recover --clear
显示：丢失时间、最后检查点、最近交接
交接（手动会话结束）
bash
clawvault handoff \
--working-on ClawVault改进 \
--blocked npm令牌 \
--next 发布到npm，创建技能 \
--feeling 高效
回顾（引导新会话）
bash
clawvault recap
显示：最近交接、活跃项目、待处理承诺、经验教训
自动链接
在Markdown文件中Wiki链接实体提及：
bash
链接所有文件
clawvault link --all
链接单个文件
clawvault link memory/2024-01-15.md
文件夹结构
vault/
├── .clawvault/ # 内部状态
│ ├── last-checkpoint.json
│ └── dirty-death.flag
├── decisions/ # 关键决策及理由
├── lessons/ # 见解和模式
├── people/ # 每人一个文件
├── projects/ # 活跃工作跟踪
├── handoffs/ # 会话连续性
├── inbox/ # 快速捕获
└── templates/ # 文档模板
最佳实践
- 1. 会话开始时唤醒 — clawvault wake 恢复上下文
- 繁重工作中每10-15分钟设置检查点
- 会话结束前休眠 — clawvault sleep 捕获后续步骤
- 使用类型 — 知道存储
