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│ │(qmd/vec) │ │
│ │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
# Install qmd (required for search/context features)
npm install -g github:tobi/qmd
# 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"
# Keyword search
clawvault search "postgresql"
# Semantic search
clawvault vsearch "what did we decide about storage"
# 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:
clawvaultClawVault 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?"
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
For hook-based lifecycle integration with OpenClaw:
# Install and enable hook pack
openclaw hooks install clawvault
openclaw hooks enable clawvault
# Verify
openclaw hooks list --verbose
openclaw hooks check
clawvault compat
The hook automatically:
--profile auto for context queriesIf 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 installed and available on PATH (for search/context features)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
If you want hook-based lifecycle integration, use this sequence:
# Install CLI
npm install -g clawvault
# Install and enable hook pack
openclaw hooks install clawvault
openclaw hooks enable clawvault
# Verify
openclaw hooks list --verbose
openclaw hooks info clawvault
openclaw hooks check
clawvault compat
Important:
clawhub install clawvault installs skill guidance, but does not replace hook-pack installation.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
openclaw hooks install clawvault firstopenclaw hooks enable clawvaultopenclaw hooks list --verboseqmd errors:
qmd --version works from same shellclawvault setup after qmd installclawvault 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 779 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.
Research
/Security News
Attackers compromised Trivy GitHub Actions by force-updating tags to deliver malware, exposing CI/CD secrets across affected pipelines.
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.