clawvault – OpenClaw Skill

---

name: clawvault version: 1.4.0 description: Structured memory system for OpenClaw agents. Context death resilience (checkpoint/recover), structured storage, Obsidian-compatible markdown, and local semantic search. author: Versatly repository: https://github.com/Versatly/clawvault

ClawVault 🐘

An elephant never forgets. Structured memory for OpenClaw agents.

Built for OpenClaw — install via clawhub install clawvault

Install

npm install -g clawvault

Quick Setup (v1.4.0)

# Auto-discover OpenClaw memory folder and configure
clawvault setup

New in v1.4.0

• qmd required — semantic search is now core functionality
• clawvault setup — auto-discovers OpenClaw's memory folder
• clawvault status — vault health, checkpoint age, qmd index
• clawvault template — list/create/add with 7 built-in templates
• clawvault link --backlinks — see what links to a file
• clawvault link --orphans — find broken wiki-links

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

Core Commands

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

Checkpoint (save state frequently)

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

Recover (check on wake)

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

Handoff (before 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. Checkpoint every 10-15 min during heavy work
2. Handoff before session end — future you will thank you
3. Recover on wake — check if last session died
4. Use types — knowing WHAT you're storing helps WHERE to put it
5. Wiki-link liberally — [[person-name]] builds your knowledge graph

Integration with qmd

ClawVault uses qmd for search:

# Install qmd
bun 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)

Links

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

ClawVault 🐘

An elephant never forgets.

Structured memory system for AI agents. Store, search, and link memories across sessions.

Built for OpenClaw — the AI agent framework. Works standalone too.

Install for OpenClaw Agents

# Install the skill (recommended for OpenClaw agents)
clawhub install clawvault

# Or install the CLI globally
npm install -g clawvault

Requirements

• Node.js 18+
• qmd — Local semantic search (required)

# Install qmd first
bun install -g qmd   # or: npm install -g qmd

# Then install clawvault
npm install -g clawvault

Why ClawVault?

AI agents forget things. Context windows overflow, sessions end, important details get lost. ClawVault fixes that:

• Structured storage — Organized categories, not random notes
• Local search — qmd provides BM25 + semantic search with local embeddings (no API quotas)
• Wiki-links — [[connections]] visible in Obsidian's graph view
• Session continuity — Handoff/recap system for context death
• Token efficient — Search instead of loading entire memory files

Quick Start

# Initialize vault with qmd collection
clawvault init ~/memory --qmd-collection my-memory

# Store memories
clawvault remember decision "Use qmd" --content "Local embeddings, no API limits"
clawvault remember lesson "Context death is survivable" --content "Write it down"
clawvault capture "Quick note to process later"

# Search (uses qmd)
clawvault search "decision"           # BM25 keyword search
clawvault vsearch "what did I decide" # Semantic search

# Session management
clawvault handoff --working-on "task1" --next "task2"  # Before context death
clawvault recap                                          # On session start

Tip: Set CLAWVAULT_PATH environment variable to skip directory walk:

echo 'export CLAWVAULT_PATH="$HOME/memory"' >> ~/.bashrc

Search: qmd vs memory_search

Use qmd (or clawvault search) — not memory_search

Tool	Backend	Speed	API Limits
qmd search / clawvault search	Local BM25	Instant	None
qmd vsearch / clawvault vsearch	Local embeddings	Fast	None
memory_search	Gemini API	Variable	Yes, hits quotas

# ✅ Use this
qmd search "query" -c my-memory
clawvault search "query"

# ❌ Avoid (API quotas)
memory_search

Vault Structure

my-memory/
├── .clawvault.json      # Config (includes qmd collection name)
├── decisions/           # Choices with reasoning
├── lessons/             # Things learned
├── people/              # One file per person
├── projects/            # Active work
├── commitments/         # Promises and deadlines
├── inbox/               # Quick capture (process later)
└── handoffs/            # Session continuity

Commands

Store Memories

# With type classification (recommended)
clawvault remember <type> <title> --content "..."
# Types: decision, lesson, fact, commitment, project, person

# Quick capture
clawvault capture "Note to self"

# Manual store
clawvault store -c decisions -t "Title" --content "..."

Note: All write commands auto-update the qmd index. Use --no-index to skip.

Search

clawvault search "query"           # BM25 keyword
clawvault search "query" -c people # Filter by category
clawvault vsearch "query"          # Semantic (local embeddings)

Browse

clawvault list                # All documents
clawvault list decisions      # By category
clawvault get decisions/title # Specific document
clawvault stats               # Vault overview

Session Continuity

# Before context death (long pause, session end, hitting limits)
clawvault handoff \
  --working-on "building CRM, fixing webhook" \
  --blocked "waiting for API key" \
  --next "deploy to production" \
  --decisions "chose Supabase over Firebase" \
  --feeling "focused"

# On session start
clawvault recap           # Full markdown recap
clawvault recap --brief   # Token-efficient version
clawvault recap --json    # For programmatic use

# Health check
clawvault doctor

Agent Setup (AGENTS.md)

Add this to your AGENTS.md to ensure proper memory habits:

## Memory

**Write everything down. Memory doesn't survive session restarts.**

### Search (use qmd, not memory_search)
\`\`\`bash
qmd search "query" -c your-memory    # Fast keyword
qmd vsearch "query" -c your-memory   # Semantic
\`\`\`

### Store
\`\`\`bash
clawvault remember decision "Title" --content "..."
clawvault remember lesson "Title" --content "..."
\`\`\`

### Session Handoff
Before context death:
\`\`\`bash
clawvault handoff --working-on "..." --next "..."
\`\`\`

On wake:
\`\`\`bash
clawvault recap
\`\`\`

### Why qmd over memory_search?
- Local embeddings — no API quotas
- Always works — no external dependencies
- Fast — instant BM25, quick semantic

Templates

ClawVault includes templates for common memory types:

• decision.md — Choices with context and reasoning
• lesson.md — Things learned
• person.md — People you work with
• project.md — Active work
• handoff.md — Session state before context death
• daily.md — Daily notes

Use with: clawvault store -c category -t "Title" -f decision

Library Usage

import { ClawVault, createVault, findVault } from 'clawvault';

const vault = await createVault('./memory', { qmdCollection: 'my-memory' });

await vault.store({
  category: 'decisions',
  title: 'Use ClawVault',
  content: 'Decided to use ClawVault for memory.',
});

const results = await vault.find('memory', { limit: 5 });

License

MIT

---

"An elephant never forgets." — Now neither do you. 🐘