Structured memory system for AI agents — typed storage, knowledge graph, context profiles, canvas dashboards, neural graph themes, and Obsidian-native task views. An elephant never forgets. 🐘
Persistent Memory for AI Agents
An elephant never forgets. Neither should your AI.
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:
┌─────────────────────────────────────────────────────────────────────────────┐
│ ClawVault Architecture │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Agent │───▶│ Session │───▶│ Observer │───▶│ Router │ │
│ │ (Claude, │ │ Watcher │ │Compressor│ │ │ │
│ │ GPT..) │ └──────────┘ └──────────┘ └────┬─────┘ │
│ └──────────┘ │ │
│ │ ▼ │
│ │ ┌─────────────────────────────────────────────────────┐ │
│ │ │ Markdown Vault │ │
│ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ │
│ │ │ │decisions/│ │ lessons/ │ │ people/ │ │projects│ │ │
│ │ │ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ │
│ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ │
│ │ │ │ tasks/ │ │ backlog/ │ │handoffs/ │ │ inbox/ │ │ │
│ │ │ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ │
│ │ └─────────────────────────────────────────────────────┘ │
│ │ │ │
│ │ ┌──────────────────────────┴──────────────────────────┐ │
│ │ │ .clawvault/ (Internal State) │ │
│ │ │ graph-index.json │ last-checkpoint.json │ config │ │
│ │ └─────────────────────────────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ wake │◀──▶│ context │◀──▶│ Graph │◀──▶│ Search │ │
│ │ sleep │ │ profiles │ │ Traversal│ │(hybrid) │ │
│ │checkpoint│ └──────────┘ └──────────┘ └──────────┘ │
│ └──────────┘ │
│ │
│ Data Flow: Session → Observe → Score → Route → Store → Reflect → Promote │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
ClawVault is built around 8 core primitives that model how agents should interact with persistent memory:
| Primitive | Description | ClawVault Implementation |
|---|---|---|
| Goals | What the agent is trying to achieve | tasks/, projects/, --working-on flags |
| Agents | Identity and ownership tracking | --owner metadata, agent handoffs |
| State Space | Current context and environment | checkpoint, recover, session state |
| Feedback | Learning from outcomes | lessons/, observations/, reflection engine |
| Capital | Resources and constraints | Token budgets, context profiles, priority scoring |
| Institution | Rules and patterns | decisions/, preferences/, injection rules |
| Synthesis | Combining information | Graph traversal, context blending, semantic search |
| Recursion | Self-improvement loops | reflect, weekly promotion, archival |
These primitives map directly to CLI commands and vault structure, creating a coherent system for agent memory.
# Install ClawVault CLI
npm install -g clawvault
# Optional: install qmd for backward-compatible fallback paths
npm install -g github:tobi/qmd
# Quick verification
clawvault doctor
# Create a new vault
clawvault init ~/memory --name my-brain
# Optional: Set up Obsidian integration
clawvault setup --theme neural --canvas
# 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"
# 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"
ClawVault v3 adds write-time fact extraction and entity graphs to the core memory pipeline:
clawvaultqmd now optional.clawvault-py) — PyPI package with a Vault class, BM25 search, and checkpoint/wake lifecycle helpers.clawvault inbox add and clawvault maintain with Curator, Janitor, Distiller, and Surveyor workers.ClawVault builds a typed knowledge graph from wiki-links, tags, and frontmatter:
# View graph summary
clawvault graph
# Refresh graph index
clawvault graph --refresh
Different tasks need different context. Use profiles to tune retrieval:
| Profile | Purpose |
|---|---|
default | Balanced retrieval |
planning | Broader strategic context |
incident | Recent events, blockers, urgent items |
handoff | Session transition context |
auto | Hook-selected based on session intent |
clawvault context --profile incident "production outage"
Full task lifecycle with Kanban support:
# Create tasks
clawvault task add "Ship v2 onboarding" --owner agent --project core --priority high
# View blocked items
clawvault blocked
# Sync with Obsidian Kanban
clawvault kanban sync
Pull relevant decisions and preferences into agent context automatically:
clawvault inject "How should we handle the deployment?"
clawvault inject --enable-llm "What's our pricing strategy?"
pip install clawvault-py
from clawvault import Vault
vault = Vault("~/memory")
results = vault.search_bm25("postgresql decision")
vault.checkpoint("working on auth rollout")
ClawVault is designed to work seamlessly with Obsidian:
all-tasks.base, blocked.base, by-project.base)clawvault canvas generates visual dashboards# Generate canvas dashboard
clawvault canvas --template brain
# Set up Obsidian integration
clawvault setup --theme neural --canvas --bases
ClawVault integrates with OpenClaw as a plugin package (not the deprecated openclaw hooks install/enable flow):
# Install ClawVault
npm install -g clawvault
# Add ClawVault package path to plugins.load.paths in openclaw.json
# (You can use `npm root -g` to locate node_modules)
# Enable plugin + memory slot in openclaw.json:
# plugins.slots.memory = "clawvault"
# plugins.entries.clawvault.enabled = true
# Verify runtime assumptions
clawvault compat
The plugin provides lifecycle hooks, memory tools, and protocol-safe messaging behavior for OpenClaw sessions.
If you use both a MEMORY.md workspace file and a ClawVault vault, understand their roles:
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.
See docs/openclaw-plugin-usage.md for detailed guidance on this pattern.
qmd is optional (used only for backward-compatible fallback paths; in-process search is built in)For Linux-specific install and PATH guidance, see docs/getting-started/installation.md.
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 |
Provider priority (when multiple keys are set): OpenClaw > Anthropic > OpenAI > Gemini > xAI
# 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"
npm install -g clawvault
# 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
Use this sequence for plugin-based OpenClaw integration:
# Install CLI
npm install -g clawvault
# Locate global node_modules
npm root -g
# In openclaw.json:
# - add <npm-root>/clawvault to plugins.load.paths
# - set plugins.slots.memory = "clawvault"
# - set plugins.entries.clawvault.enabled = true
# - set plugins.entries.clawvault.config.vaultPath as needed
Important:
clawhub install clawvault installs skill guidance, but does not configure OpenClaw plugin loading.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.
init, setup, store, captureremember, list, get, stats, reindex, syncsearch, vsearch, context, injectobserve, reflect, session-recapgraph, entities, link, embedwake, sleep, handoff, recapcheckpoint, recover, status, clean-exit, repair-sessioncompat, doctortask ..., backlog ..., blocked, project ..., kanban ...canvas (generates default dashboard.canvas)tailscale-status, tailscale-sync, tailscale-serve, tailscale-discover# Store and retrieve memory
clawvault remember decision "Use PostgreSQL" --content "Chosen for JSONB and reliability"
clawvault search "postgresql"
clawvault vsearch "what did we decide about storage"
# Session lifecycle
clawvault wake
clawvault checkpoint --working-on "auth rollout" --focus "token refresh edge cases"
clawvault sleep "finished auth rollout plan" --next "implement migration"
# Work management
clawvault task add "Ship v2 onboarding" --owner agent --project core --priority high
clawvault blocked
clawvault project list --status active
clawvault kanban sync
# Obsidian projection
clawvault canvas
ClawVault can serve vault content for sync over Tailscale and exposes WebDAV under /webdav for mobile-oriented workflows.
clawvault tailscale-status
clawvault tailscale-serve --vault ~/memory
clawvault tailscale-discover
vault/
├── .clawvault/ # Internal state
│ ├── graph-index.json # Knowledge graph
│ ├── last-checkpoint.json
│ └── config.json
├── decisions/ # Key choices with reasoning
├── lessons/ # Insights and patterns
├── people/ # One file per person
├── projects/ # Active work tracking
├── tasks/ # Task files with frontmatter
├── backlog/ # Quick captures and ideas
├── handoffs/ # Session continuity
├── inbox/ # Quick captures
└── templates/ # Document templates
clawvault doctor after install or environment changesEACCES / permission denied:
npm config set prefix ~/.npm-globalexport PATH="$HOME/.npm-global/bin:$PATH" to your shell rc and reload shellclawvault: command not found after install:
npm config get prefix<prefix>/bin is present in your PATHqmd fallback errors:
qmd is optional; in-process BM25 search is available without itqmd --version works in the same shellplugins.load.paths includes the ClawVault package pathplugins.slots.memory is clawvaultplugins.entries.clawvault.enabled is trueclawvault compatclawvault repair-session --dry-run then clawvault repair-session| Resource | URL |
|---|---|
| Documentation | clawvault.dev |
| npm Package | npmjs.com/package/clawvault |
| GitHub | github.com/Versatly/clawvault |
| Issues | github.com/Versatly/clawvault/issues |
| Obsidian Plugin | clawvault.dev/obsidian |
We welcome contributions! ClawVault has had 20+ PRs merged from 6 external contributors.
npm testSee our contribution guidelines for details.
$CLAW: 5Fjr82MTB8mvxkzi9FYtvrUsPiDGE2M29w3dYcZpump
MIT
FAQs
Structured memory system for AI agents — typed storage, knowledge graph, context profiles, canvas dashboards, neural graph themes, and Obsidian-native task views. An elephant never forgets. 🐘
The npm package clawvault receives a total of 608 weekly downloads. As such, clawvault popularity was classified as not popular.
We found that clawvault demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ENISA’s new package manager advisory outlines the dependency security practices companies will need to demonstrate as the EU’s Cyber Resilience Act begins enforcing software supply chain requirements.
Research
/Security News
We identified over 20 additional malicious extensions, along with over 20 related sleeper extensions, some of which have already been weaponized.
Security News
TC39’s March 2026 meeting advanced eight ECMAScript proposals, including Temporal reaching Stage 4 and securing its place in the ECMAScript 2026 specification.