Clawvault
🐘 An elephant never forgets. Structured memory system for AI agents.
Install / Use
/learn @Versatly/ClawvaultREADME
ClawVault 🐘
Persistent Memory for AI Agents
An elephant never forgets. Neither should your AI.
Documentation · npm Package · Obsidian Plugin · GitHub
</div>What is ClawVault?
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.
┌─────────────────────────────────────────────────────────────────────────────┐
│ 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 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
The 8 Primitives
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.
Quick Start
Installation
# 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
Initialize Your Vault
# 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")
- Hybrid Search — BM25 + semantic embeddings + Reciprocal Rank Fusion (RRF)
Project Stats
- 466 tests passing across 71 test files
- 20+ PRs merged from 6 external contributors
- Published on npm as
clawvault - Active development since February 2026
Features
v3.3 Highlights
- In-process hybrid search engine — BM25 + hosted semantic embeddings + cross-encoder reranking, with
qmdnow optional. - Python SDK (
clawvault-py) — PyPI package with aVaultclass, BM25 search, and checkpoint/wake lifecycle helpers. - Inbox + background workers —
clawvault inbox addandclawvault maintainwith Curator, Janitor, Distiller, and Surveyor workers.
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
Context Profiles
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"
Task Management
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
Dynamic Prompt Injection
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?"
Python SDK (clawvault-py)
pip install clawvault-py
from clawvault import Vault
vault = Vault("~/memory")
results = vault.search_bm25("postgresql decision")
vault.checkpoint("working on auth rollout")
Obsidian Integration
ClawVault is designed to work seamlessly with Obsidian:
- Graph themes — Neural/minimal themes with colored nodes by category
- Bases views — Auto-generated task views (
all-tasks.base,blocked.base,by-project.base) - Canvas dashboards —
clawvault canvasgenerates visual dashboards - Kanban round-trip — Export/import between ClawVault and Obsidian Kanban
# Generate canvas das
