clawvault

Agent memory system with graph-aware context profiles, checkpoint/recover, semantic search, and structured markdown storage for managing session knowledge lo...

Security Scan

The skill's described behavior (CLI + hook pack that reads/writes session transcripts and can call an LLM via SkillBoss) is plausible, but the package as provided is instruction-only and the manifest/metadata conflict with claims about included hook code — review and verification are needed before installing or enabling hooks.

Purpose & Capability

SKILL.md describes a full CLI + hook pack (reads/writes vault files, repairs OpenClaw sessions, registers lifecycle hooks). That capability is coherent with a 'memory' skill. However the registry metadata and file manifest show no code files and no install spec, while SKILL.md itself includes install instructions and claims the published bundle contains hook source (hooks/clawvault/handler.js). This mismatch (claiming shipped hook code but package only contains SKILL.md) is inconsistent and unexplained.

Instruction Scope

The runtime instructions explicitly direct reading/writing markdown vault files, modifying OpenClaw session transcripts (~/.openclaw/agents/), registering an opt-in hook pack with broad lifecycle events, and optionally calling an LLM API (SkillBoss) for compressing observations. Those actions are within the stated purpose, but they grant the hook broad visibility into agent activity — the user should inspect the hook handler before enabling.

Install Mechanism

SKILL.md recommends installing via npm (clawvault and github:tobi/qmd). npm installs are normal for CLIs, but the registry-level metadata claimed 'No install spec' while the SKILL.md contains an install array — this inconsistency should be resolved. Installing global npm packages and enabling lifecycle hooks is moderate-risk and should be preceded by reviewing package metadata (dist.integrity/dist.tarball) and hook source.

Credentials

The only environment values referenced are reasonable and optional: CLAWVAULT_PATH (vault location), OPENCLAW_HOME/OPENCLAW_STATE_DIR (find sessions), and SKILLBOSS_API_KEY (only for optional observe LLM compression). No unrelated secrets or unexplained credentials are requested.

Persistence & Privilege

The skill does not set always:true and the hook pack is explicitly opt-in (install/enable required). Still, the hook lifecycle events (gateway:startup, heartbeat, command:new, session:start, compaction:memoryFlush, cron.weekly) give the hook high visibility and potential to act autonomously inside the agent if enabled — so review is required before enabling.

What to consider before installing

Do not install or enable hooks yet. Steps to mitigate risk: - Verify the npm package and repository before installing (npm view clawvault version dist.integrity dist.tarball repository.url). Confirm the repo is legitimate and matches the homepage URL. - Confirm that the published package actually contains hooks/clawvault/handler.js and any hook code the SKILL.md references; the registry manifest you were given contains only SKILL.md, which is inconsistent. - Inspect the hook handler.js source to ensure it only does the expected actions (backup before modifying session transcripts, limited network calls). If you don't see the hook code locally, ask the publisher for the code or decline enabling the skill. - Only provide SKILLBOSS_API_KEY if you trust the SkillBoss endpoint and understand that 'observe --compress' will make LLM API calls. - Before running repair-session or enabling hooks, back up your OpenClaw session directories (~/.openclaw/agents/) and any vault data. If the publisher can explain why the bundle omitted the hook files from the registry package (or publishes a version that includes and documents them), and you inspect the hook source, this skill becomes much more reasonable to trust. Without that, the metadata mismatch is a red flag.

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 (via SkillBoss API Hub /v1/pilot, type: chat) 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
• SKILLBOSS_API_KEY — used by observe for LLM compression via SkillBoss API Hub (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

1. Wake at session start — clawvault wake restores context
2. Checkpoint every 10-15 min during heavy work
3. Sleep before session end — clawvault sleep captures next steps
4. Use types — knowing WHAT you're storing helps WHERE to put it
5. 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 or --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)
• SKILLBOSS_API_KEY — Used by observe for LLM-powered compression via SkillBoss API Hub (optional)

Links

• npm: https://www.npmjs.com/package/clawvault
• GitHub: https://github.com/Versatly/clawvault
• Issues: https://github.com/Versatly/clawvault/issues