Installation

ClawVault requires Node.js 18+ and qmd for search functionality. This guide covers installation for both OpenClaw users and standalone usage.

Prerequisites

Node.js 18+

ClawVault is built with modern Node.js. Check your version:

node --version
# Should show v18.0.0 or higher

If you need to install or upgrade Node.js:

macOS/Linux: Use nvm
Windows: Download from nodejs.org

qmd (Required)

ClawVault uses qmd for local semantic search. Install it globally:

# Using bun (recommended)
bun install -g qmd

# Using npm
npm install -g qmd

Verify qmd installation:

qmd --version

Installation Methods

For OpenClaw Users (Recommended)

If you're using OpenClaw, install ClawVault as a skill:

# Install the skill
clawhub install clawvault

# Enable the hook system for automatic session continuity
openclaw hooks enable clawvault

This gives you:

ClawVault CLI available globally
Automatic checkpoint before /new commands
Context death detection on startup
Session start context injection

Standalone Installation

Install ClawVault globally via npm:

npm install -g clawvault

Verify installation:

clawvault --version

Initial Setup

1. Initialize Your Vault

Create your first vault with qmd integration:

clawvault init ~/memory --qmd-collection my-memory

Init Options

Flag	Description	Default
`--qmd-collection <name>`	Register with qmd for semantic search	None
`--theme <name>`	Apply a vault theme (`neural`)	None
`--canvas <template>`	Generate an initial canvas (`brain`, `project-board`)	None
`--minimal`	Memory categories only, no tasks or bases	`false`
`--no-tasks`	Skip task system setup	`false`
`--no-bases`	Skip Obsidian Bases views	`false`
`--categories <list>`	Comma-separated custom categories	All defaults

Example Flows

Full setup for an OpenClaw agent:

clawvault init ~/memory \
  --qmd-collection agent-memory \
  --theme neural \
  --canvas brain

Minimal memory-only vault:

clawvault init ~/memory --minimal --qmd-collection my-notes

Custom categories for a specific use case:

clawvault init ~/memory \
  --categories "research,experiments,datasets,papers" \
  --no-tasks --no-bases

Directory Structure (v2.4+)

A full init creates:

~/memory/
├── .clawvault.json          # Config file
├── .clawvault/              # Internal state
│   └── graph-index.json     # Memory graph index
├── ledger/                  # Transition audit logs
│   └── task-transitions.jsonl
├── tasks/                   # Active task files
├── backlog/                 # Future work items
├── decisions/               # Key choices
├── lessons/                 # Things learned
├── people/                  # Relationships
├── projects/                # Active work
├── commitments/             # Promises & deadlines
├── inbox/                   # Quick captures
├── handoffs/                # Session continuity
├── all-tasks.base           # Obsidian Bases: all tasks
├── blocked.base             # Obsidian Bases: blocked tasks
├── by-project.base          # Obsidian Bases: by project
├── by-owner.base            # Obsidian Bases: by owner
└── backlog.base             # Obsidian Bases: backlog

Setup for Existing Vaults

If you already have a folder you want to turn into a ClawVault vault (or upgrade an older vault):

# Add ClawVault structure to an existing folder
clawvault setup --theme neural --canvas brain

# Force re-setup (overwrites config)
clawvault setup --force

# Add just a canvas to an existing vault
clawvault setup --canvas project-board

2. Environment Setup (Optional)

Set your vault path to avoid auto-discovery overhead:

export CLAWVAULT_PATH="$HOME/memory"

Or use shell integration for aliases and environment setup:

# Add to your shell profile (~/.bashrc, ~/.zshrc)
eval "$(clawvault shell-init)"

This adds helpful aliases:

cv → clawvault
wake → clawvault wake
sleep → clawvault sleep
capture → clawvault capture

3. Verify Setup

Run a health check to ensure everything is configured correctly:

clawvault doctor

You should see:

✓ ClawVault found: ~/memory
✓ qmd available: v1.2.3
✓ Collection registered: my-memory
✓ Graph index: healthy
✓ Task system: active
✓ Bases views: 5 files
✓ OpenClaw hooks: enabled (if using OpenClaw)

Configuration

Vault Config (`.clawvault.json`)

{
 "version": "2.0.0",
 "qmdCollection": "my-memory",
 "createdAt": "2024-01-15T10:00:00Z"
}

Environment Variables

Variable	Purpose	Default
`CLAWVAULT_PATH`	Vault location	Auto-discovery
`GEMINI_API_KEY`	For observation compression	None (optional)
`OPENCLAW_HOME`	OpenClaw directory	`~/.openclaw`

Troubleshooting

Common Issues

"qmd not found"

# Install qmd globally
npm install -g qmd
# or
bun install -g qmd

"No vault found"

# Set explicit path
export CLAWVAULT_PATH="/path/to/vault"

# Or initialize a new vault
clawvault init ~/memory

"Collection not registered"

# Register your vault with qmd
qmd collection add ~/memory --name my-memory --mask "**/*.md"
qmd update && qmd embed

Get Help

Check status: clawvault doctor
OpenClaw compatibility: clawvault compat
GitHub Issues: clawvault/issues
Discord: OpenClaw Community

Next Steps

Now that ClawVault is installed, head to the Quick Start Guide to learn the essential commands and workflows.

Installation

On this page