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)
```
repair-session
```
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.

```
observe --compress
```
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)

OPENCLAW_HOME

OPENCLAW_STATE_DIR

— used by

repair-session

to find session transcripts

```
GEMINI_API_KEY
```
— 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)

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

can install skill guidance, but does not replace explicit hook pack installation.

Recommended Safe Install Flow

# 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

Setup

# 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

Quick Start for New Agents

# 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

Reality Checks Before Use

# 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 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:

# View graph summary
clawvault graph
Refresh graph index

clawvault graph --refresh

Graph is stored at

.clawvault/graph-index.json

— schema versioned, incremental rebuild.

Graph-Aware Context Retrieval

# 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"

Context Profiles

Profile	Purpose
`default`	Balanced retrieval
`planning`	Broader strategic context
`incident`	Recent events, blockers, urgent items
`handoff`	Session transition context
`auto`	Hook-selected profile based on session intent

OpenClaw Compatibility Diagnostics

# Check hook wiring, event routing, handler safety
clawvault compat
Strict mode for CI

clawvault compat --strict

Core Commands

Wake + Sleep (primary)

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

Store memories by type

# 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"

Quick capture to inbox

clawvault capture "TODO: Review PR tomorrow"

Search (requires qmd installed)

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

Context Death Resilience

Wake (start of session)

clawvault wake

Sleep (end of session)

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

Checkpoint (save state frequently)

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

Recover (manual check)

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

Handoff (manual session end)

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

Recap (bootstrap new session)

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

Auto-linking

Wiki-link entity mentions in markdown files:

# Link all files
clawvault link --all
Link single file

clawvault link memory/2024-01-15.md

Folder Structure

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

Best Practices

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

## 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

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 tool_use_id found in tool_result blocks", use:

# 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

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
```
qmd --version
```
No ClawVault found — run
```
clawvault init
```
or set
```
CLAWVAULT_PATH
```
CLAWVAULT_PATH missing — run
```
clawvault shell-init
```
and add to shell rc
Too many orphan links — run
```
clawvault link --orphans
```
Inbox backlog warning — process or archive inbox items
"unexpected tool_use_id" error — run
```
clawvault repair-session
```
OpenClaw integration drift — run
```
clawvault compat
```

Hook enable fails / hook not found — run

openclaw hooks install clawvault

, then

openclaw hooks enable clawvault

, restart gateway, and verify via

openclaw hooks list --verbose

Graph out of date — run
```
clawvault graph --refresh
```

Wrong context for task — try

clawvault context --profile incident

--profile planning

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:

# 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

Environment Variables

```
CLAWVAULT_PATH
```
— Default vault path (skips auto-discovery)
```
OPENCLAW_HOME
```
— OpenClaw home directory (used by repair-session)
```
OPENCLAW_STATE_DIR
```
— OpenClaw state directory (used by repair-session)
```
GEMINI_API_KEY
```
— Used by
```
observe
```
for LLM-powered compression (optional)

ClawVault

AI Skill Market Insights

Be Part of the 0+ Developer Community

ClawVault 🐘

Security & Transparency

Install (Canonical)

Verify and reload

restart gateway process

Recommended Safe Install Flow

2) Install CLI + qmd dependency

3) Install hook pack, but DO NOT enable yet

4) Review hook source locally before enabling

5) Enable only after review

Setup

Or set env var to use existing vault

Optional: shell integration (aliases + CLAWVAULT_PATH)

Quick Start for New Agents

Capture and checkpoint during work

End your session with a handoff

Health check when something feels off

Reality Checks Before Use

Verify qmd is available

Verify OpenClaw CLI is installed in this shell

Current Feature Set

Memory Graph

Refresh graph index

Graph-Aware Context Retrieval

With a profile preset

Auto profile (used by OpenClaw hook)

Context Profiles

OpenClaw Compatibility Diagnostics

Strict mode for CI

Core Commands

Wake + Sleep (primary)

Store memories by type

Quick capture to inbox

Search (requires qmd installed)

Semantic search (slower, more accurate)

Context Death Resilience

Wake (start of session)

Sleep (end of session)

Checkpoint (save state frequently)

Recover (manual check)

Handoff (manual session end)

Recap (bootstrap new session)

Auto-linking

Link single file

Folder Structure

Best Practices

Checklist for AGENTS.md

Session Transcript Repair (v1.5.0+)

Fix it

Repair a specific session

List available sessions

Troubleshooting

Stability Snapshot

Integration with qmd

Alternative

Add vault as collection

Update index

Environment Variables

Links

Quick Start

Manual Installation

TEAR & SHARE

Tags

Channels

Learn

Compare

Company