ClawVault is a structured memory system for AI agents that uses markdown as the storage primitive. It solves the fundamental problem of AI agents losing context between sessions — what we call "context death."
Unlike vector databases or cloud-based memory solutions, ClawVault is:
Local-first — Your data stays on your machine. No cloud sync, no vendor lock-in.
Markdown-native — Human-readable, git-friendly, works with Obsidian out of the box.
Graph-aware — Wiki-links build a knowledge graph that enriches context retrieval.
Session-resilient — Checkpoint/recover primitives survive crashes and context resets.
Fact-aware — Write-time extraction builds structured facts with conflict resolution.
# Create a new vault
clawvault init ~/memory --name my-brain
# Optional: Set up Obsidian integration
clawvault setup --theme neural --canvas
Basic Workflow
# Start your session
clawvault wake
# Store memories as you work
clawvault remember decision "Use PostgreSQL" --content "Chosen for JSONB support"
clawvault capture "TODO: Review PR tomorrow"
# Checkpoint during heavy work
clawvault checkpoint --working-on "auth rollout" --focus "token refresh"
# End your session
clawvault sleep "finished auth rollout" --next "implement migration"
Search and Context
# In-process hybrid search (BM25 + semantic reranking)
clawvault search "postgresql"
# Semantic/vector search commands (requires hosted embeddings configured)
clawvault vsearch "what did we decide about storage"
# Configure hosted embeddings (OpenAI/Gemini/Ollama)
clawvault config set search.embeddings.provider openai
clawvault config set search.embeddings.model text-embedding-3-small
clawvault config set search.embeddings.apiKey "$OPENAI_API_KEY"
clawvault rebuild-embeddings
# Get context for a task
clawvault context "database migration"
clawvault context --profile planning "Q1 roadmap"
v3.0 — Structured Memory
ClawVault v3 adds write-time fact extraction and entity graphs to the core memory pipeline:
Fact Store — Extracts structured facts (preferences, attributes, relationships) at write time with conflict resolution and deduplication
Entity Graph — Builds a relational graph enabling multi-hop queries ("Alice works at Google + Google is in CA → Alice is in CA")
Kanban round-trip — Export/import between ClawVault and Obsidian Kanban
# Generate canvas dashboard
clawvault canvas --template brain
# Set up Obsidian integration
clawvault setup --theme neural --canvas --bases
OpenClaw Integration
ClawVault integrates with OpenClaw as a plugin. Install the npm package, then configure it in your OpenClaw config:
# 1. Install the ClawVault package
npm install clawvault
# 2. Register the plugin and memory slot in openclaw.json
openclaw config set plugins.entries.clawvault.package clawvault
openclaw config set plugins.slots.memory clawvault
# 3. Configure your vault path
openclaw config set plugins.entries.clawvault.config.vaultPath ~/my-vault
# 4. Verify
clawvault compat
The plugin automatically:
Detects context death and injects recovery alerts
Auto-checkpoints before session resets
Provides --profile auto for context queries
Legacy note: The older openclaw hooks install / openclaw hooks enable flow is no longer the recommended path. Use the plugin model above.
MEMORY.md vs Vault
If you use both a MEMORY.md workspace file and a ClawVault vault, understand their roles:
MEMORY.md = Boot context (executive summary the agent sees instantly)
Vault = Full knowledge store (searchable, structured, versioned)
MEMORY.md should contain high-level identity, key decisions, and current focus. The vault stores everything else. Update MEMORY.md periodically to reflect vault state, but it doesn't need to mirror it.
ClawVault supports multiple LLM providers for features like context generation, observation compression, and semantic search. Set the appropriate environment variable to enable a provider:
| Provider | Environment Variable | Default Model | Notes |
|----------|---------------------|---------------|-------|
| Anthropic | ANTHROPIC_API_KEY | claude-3-5-haiku-latest | Claude models |
| OpenAI | OPENAI_API_KEY | gpt-4o-mini | GPT models |
| Google Gemini | GEMINI_API_KEY | gemini-2.0-flash | Gemini models |
| xAI (Grok) | XAI_API_KEY | grok-2-latest | Grok models via OpenAI-compatible API |
| Ollama | (local) | llama3.2 | Local models, no API key needed |
| OpenAI-compatible | OPENAI_API_KEY | gpt-4o-mini | Any OpenAI-compatible endpoint |
# Example: Use xAI (Grok) as your LLM provider
export XAI_API_KEY="your-xai-api-key"
# Example: Use Anthropic
export ANTHROPIC_API_KEY="your-anthropic-api-key"
Install
npm install -g clawvault
5-Minute Setup
# 1) Create or initialize a vault
clawvault init ~/memory --name my-brain
# 2) Optional vault bootstrap for Obsidian
clawvault setup --theme neural --canvas
# 3) Verify OpenClaw compatibility in this environment
clawvault compat
OpenClaw Setup (Canonical)
ClawVault integrates with OpenClaw as a plugin. Use this sequence:
# Install ClawVault
npm install clawvault
# Register plugin and memory slot
openclaw config set plugins.entries.clawvault.package clawvault
openclaw config set plugins.slots.memory clawvault
# Configure vault path and desired features
openclaw config set plugins.entries.clawvault.config.vaultPath ~/my-vault
openclaw config set plugins.entries.clawvault.config.enableStartupRecovery true
openclaw config set plugins.entries.clawvault.config.enableSessionContextInjection true
# Verify
clawvault compat
Important:
clawhub install clawvault installs skill guidance, but does not replace plugin configuration.
After changing plugin config, restart the OpenClaw gateway process so plugin registration reloads.
Minimal AGENTS.md Additions
Append these to your existing memory workflow. Do not replace your full prompt setup:
## ClawVault
- Run `clawvault wake` at session start.
- Run `clawvault checkpoint` during heavy work.
- Run `clawvault sleep "summary" --next "next steps"` before ending.
- Use `clawvault context "<task>"` or `clawvault inject "<message>"` before complex decisions.
