clawvault 3.0.0 → 3.2.0

package/README.md

@@ -1,17 +1,301 @@
+<div align="center">
+
 # ClawVault 🐘
 
-Structured memory system for AI agents and operators: typed markdown memory, graph-aware context, task/project primitives, Obsidian views, and OpenClaw hook integration.
+**Persistent Memory for AI Agents**
 
+[![Tests](https://img.shields.io/badge/tests-466%20passing-brightgreen)](https://github.com/Versatly/clawvault)
 [![npm](https://img.shields.io/npm/v/clawvault)](https://www.npmjs.com/package/clawvault)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![PRs Merged](https://img.shields.io/badge/PRs%20merged-20%2B-purple)](https://github.com/Versatly/clawvault/pulls?q=is%3Amerged)
+[![Contributors](https://img.shields.io/badge/contributors-6-orange)](https://github.com/Versatly/clawvault/graphs/contributors)
+
+*An elephant never forgets. Neither should your AI.*
+
+[Documentation](https://clawvault.dev) · [npm Package](https://www.npmjs.com/package/clawvault) · [Obsidian Plugin](https://clawvault.dev/obsidian) · [GitHub](https://github.com/Versatly/clawvault)
+
+</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│    │(qmd/vec) │             │
+│   │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
+
+```bash
+# Install ClawVault CLI
+npm install -g clawvault
+
+# Install qmd (required for search/context features)
+npm install -g github:tobi/qmd
+```
+
+### Initialize Your Vault
+
+```bash
+# Create a new vault
+clawvault init ~/memory --name my-brain
+
+# Optional: Set up Obsidian integration
+clawvault setup --theme neural --canvas
+```
+
+### Basic Workflow
+
+```bash
+# 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
+
+```bash
+# 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"
+```
+
+---
+
+## 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
 
-> Local-first. Markdown-first. Built to survive long-running autonomous work.
+- **466 tests** passing across **71 test files**
+- **20+ PRs** merged from **6 external contributors**
+- Published on npm as [`clawvault`](https://www.npmjs.com/package/clawvault)
+- Active development since February 2026
+
+---
+
+## Features
+
+### Memory Graph
+
+ClawVault builds a typed knowledge graph from wiki-links, tags, and frontmatter:
+
+```bash
+# 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 |
+
+```bash
+clawvault context --profile incident "production outage"
+```
+
+### Task Management
+
+Full task lifecycle with Kanban support:
+
+```bash
+# 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:
+
+```bash
+clawvault inject "How should we handle the deployment?"
+clawvault inject --enable-llm "What's our pricing strategy?"
+```
+
+---
+
+## 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 canvas` generates visual dashboards
+- **Kanban round-trip** — Export/import between ClawVault and Obsidian Kanban
+
+```bash
+# Generate canvas dashboard
+clawvault canvas --template brain
+
+# Set up Obsidian integration
+clawvault setup --theme neural --canvas --bases
+```
+
+---
+
+## OpenClaw Integration
+
+For hook-based lifecycle integration with OpenClaw:
+
+```bash
+# 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:
+- Detects context death and injects recovery alerts
+- Auto-checkpoints before session resets
+- Provides `--profile auto` for context queries
+
+### 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.
+
+See [docs/openclaw-plugin-usage.md](docs/openclaw-plugin-usage.md) for detailed guidance on this pattern.
+
+---
 
 ## Requirements
 
 - Node.js 18+
-- `qmd` installed and available on `PATH`
+- `qmd` installed and available on `PATH` (for search/context features)
+
+## LLM Providers
+
+ClawVault supports multiple LLM providers for features like context generation, observation compression, and semantic search. Set the appropriate environment variable to enable a provider:
 
-ClawVault currently relies on `qmd` for core vault/query flows. Install it before first use.
+| 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
+
+```bash
+# 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
 
@@ -68,35 +352,39 @@ Append these to your existing memory workflow. Do not replace your full prompt s
 - Use `clawvault context "<task>"` or `clawvault inject "<message>"` before complex decisions.
 ```
 
-## Real CLI Surface (Current)
+---
+
+## CLI Reference
 
-Core:
+### Core Commands
 
 - `init`, `setup`, `store`, `capture`
 - `remember`, `list`, `get`, `stats`, `reindex`, `sync`
 
-Context + memory:
+### Context + Memory
 
 - `search`, `vsearch`, `context`, `inject`
 - `observe`, `reflect`, `session-recap`
 - `graph`, `entities`, `link`, `embed`
 
-Resilience:
+### Resilience
 
 - `wake`, `sleep`, `handoff`, `recap`
 - `checkpoint`, `recover`, `status`, `clean-exit`, `repair-session`
 - `compat`, `doctor`
 
-Execution primitives:
+### Execution Primitives
 
 - `task ...`, `backlog ...`, `blocked`, `project ...`, `kanban ...`
 - `canvas` (generates default `dashboard.canvas`)
 
-Networking:
+### Networking
 
 - `tailscale-status`, `tailscale-sync`, `tailscale-serve`, `tailscale-discover`
 
-## Quick Usage
+---
+
+## Quick Usage Examples
 
 ```bash
 # Store and retrieve memory
@@ -119,15 +407,7 @@ clawvault kanban sync
 clawvault canvas
 ```
 
-## Obsidian Integration
-
-- Setup can generate:
-  - graph theme/snippet config (`--theme neural|minimal|none`)
-  - Bases views (`all-tasks.base`, `blocked.base`, `by-project.base`, `by-owner.base`, `backlog.base`)
-  - default canvas (`dashboard.canvas`) via `--canvas` or `clawvault canvas`
-- Kanban round-trip:
-  - export: `clawvault kanban sync`
-  - import lane changes back to task metadata: `clawvault kanban import`
+---
 
 ## Tailscale + WebDAV
 
@@ -139,6 +419,29 @@ clawvault tailscale-serve --vault ~/memory
 clawvault tailscale-discover
 ```
 
+---
+
+## Vault Structure
+
+```
+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
+```
+
+---
+
 ## Troubleshooting
 
 - Hook not found after enable:
@@ -154,6 +457,35 @@ clawvault tailscale-discover
 - Session transcript corruption:
   - run `clawvault repair-session --dry-run` then `clawvault repair-session`
 
+---
+
+## Links
+
+| Resource | URL |
+|----------|-----|
+| **Documentation** | [clawvault.dev](https://clawvault.dev) |
+| **npm Package** | [npmjs.com/package/clawvault](https://www.npmjs.com/package/clawvault) |
+| **GitHub** | [github.com/Versatly/clawvault](https://github.com/Versatly/clawvault) |
+| **Issues** | [github.com/Versatly/clawvault/issues](https://github.com/Versatly/clawvault/issues) |
+| **Obsidian Plugin** | [clawvault.dev/obsidian](https://clawvault.dev/obsidian) |
+
+---
+
+## Contributing
+
+We welcome contributions! ClawVault has had **20+ PRs merged** from **6 external contributors**.
+
+1. Fork the repository
+2. Create a feature branch
+3. Run tests: `npm test`
+4. Submit a PR
+
+See our [contribution guidelines](https://github.com/Versatly/clawvault/blob/main/CONTRIBUTING.md) for details.
+
+---
+
+**$CLAW**: [`5Fjr82MTB8mvxkzi9FYtvrUsPiDGE2M29w3dYcZpump`](https://pump.fun/coin/5Fjr82MTB8mvxkzi9FYtvrUsPiDGE2M29w3dYcZpump)
+
 ## License
 
 MIT

package/bin/clawvault.js

@@ -23,13 +23,16 @@ import { registerProjectCommands } from './register-project-commands.js';
 
 import { registerTaskCommands } from './register-task-commands.js';
 
+import { registerWorkgraphCommands } from './register-workgraph-commands.js';
 import { registerTailscaleCommands } from './register-tailscale-commands.js';
 import {
   getVault,
   resolveVaultPath,
   runQmd,
   printQmdMissing,
-  QmdUnavailableError
+  printQmdConfigError,
+  QmdUnavailableError,
+  QmdConfigurationError
 } from './command-runtime.js';
 import {
   createVault
@@ -66,7 +69,9 @@ registerQueryCommands(program, {
   getVault,
   resolveVaultPath,
   QmdUnavailableError,
-  printQmdMissing
+  QmdConfigurationError,
+  printQmdMissing,
+  printQmdConfigError
 });
 
 registerSessionLifecycleCommands(program, {
@@ -104,6 +109,7 @@ registerProjectCommands(program, {
   resolveVaultPath
 });
 
+registerWorkgraphCommands(program, { chalk, resolveVaultPath });
 registerTailscaleCommands(program, { chalk });
 registerConfigCommands(program, { chalk, resolveVaultPath });
 registerRouteCommands(program, { chalk, resolveVaultPath });

package/bin/command-registration.test.js

@@ -83,7 +83,8 @@ describe('CLI command registration modules', () => {
       'sync',
       'reindex',
       'remember',
-      'shell-init'
+      'shell-init',
+      'dashboard'
     ]));
   });
 
@@ -129,6 +130,7 @@ describe('CLI command registration modules', () => {
       'archive',
       'migrate-observations',
       'replay',
+      'sync-bd',
       'checkpoint',
       'recover',
       'status',

package/bin/command-runtime.js

@@ -4,6 +4,7 @@ import path from 'path';
 import {
   ClawVault,
   QmdUnavailableError,
+  QmdConfigurationError,
   QMD_INSTALL_COMMAND,
   resolveVaultPath as resolveConfiguredVaultPath
 } from '../dist/index.js';
@@ -90,4 +91,11 @@ export function printQmdMissing() {
   console.log(chalk.dim(`Install: ${QMD_INSTALL_COMMAND}`));
 }
 
-export { QmdUnavailableError };
+export function printQmdConfigError(err) {
+  console.error(chalk.red(`Error: ${err.message}`));
+  if (err.hint) {
+    console.log(chalk.yellow(`Hint: ${err.hint}`));
+  }
+}
+
+export { QmdUnavailableError, QmdConfigurationError };

package/bin/register-core-commands.js

@@ -19,6 +19,7 @@ export function registerCoreCommands(
     .option('--no-tasks', 'Skip tasks/ and backlog/ directories')
     .option('--no-graph', 'Skip initial graph build')
     .option('--categories <list>', 'Comma-separated list of custom categories to create')
+    .option('--canvas', 'Generate a vault status canvas dashboard on init')
     .option('--theme <style>', 'Graph color theme to apply (neural, minimal, none) (default: none)', 'none')
     .option('--minimal', 'Create minimal vault (memory categories only, no tasks/bases/graph)')
     .action(async (vaultPath, options) => {
@@ -80,14 +81,8 @@ export function registerCoreCommands(
             '**/*.md'
           ]);
           console.log(chalk.green('✓ qmd collection created'));
-        } catch (err) {
-          if (err instanceof QmdUnavailableError || err?.message?.includes('ENOENT') || err?.message?.includes('ERR_MODULE_NOT_FOUND')) {
-            console.log(chalk.yellow('⚠ qmd not available — skipping semantic search setup'));
-            console.log(chalk.dim('  Install qmd for semantic search: npm install -g github:tobi/qmd'));
-            console.log(chalk.dim('  Vault initialized successfully without qmd.'));
-          } else {
-            console.log(chalk.yellow('⚠ qmd collection may already exist'));
-          }
+        } catch {
+          console.log(chalk.yellow('⚠ qmd collection may already exist'));
         }
 
         // Apply theme if requested
@@ -97,6 +92,7 @@ export function registerCoreCommands(
             await setupCommand({
               graphColors: true,
               bases: false,
+              canvas: false,
               theme: options.theme,
               vault: resolvedPath
             });
@@ -105,6 +101,22 @@ export function registerCoreCommands(
           }
         }
 
+        // Generate canvas if requested
+        if (options.canvas) {
+          try {
+            const { setupCommand } = await import('../dist/commands/setup.js');
+            await setupCommand({
+              graphColors: false,
+              bases: false,
+              canvas: true,
+              theme: 'none',
+              vault: resolvedPath
+            });
+          } catch {
+            console.log(chalk.yellow(`⚠ Could not generate canvas`));
+          }
+        }
+
         console.log(chalk.green('\n✅ ClawVault ready!\n'));
         console.log('  ' + chalk.bold('Try these:'));
         console.log(chalk.dim('  clawvault capture "my first thought"     # quick capture'));
@@ -128,8 +140,9 @@ export function registerCoreCommands(
     .option('--no-graph-colors', 'Skip graph color configuration')
     .option('--bases', 'Generate Obsidian Bases views for task management')
     .option('--no-bases', 'Skip Bases file generation')
+    .option('--canvas', 'Generate vault status canvas dashboard')
+    .option('--no-canvas', 'Skip canvas generation')
     .option('--theme <style>', 'Graph color theme (neural, minimal, none) (default: neural)', 'neural')
-    .option('--from <path>', 'Import from existing agent memory directory (MEMORY.md, memory/*.md, etc)')
     .option('--force', 'Overwrite existing configuration files')
     .option('-v, --vault <path>', 'Vault path')
     .action(async (options) => {
@@ -138,8 +151,8 @@ export function registerCoreCommands(
         await setupCommand({
           graphColors: options.graphColors,
           bases: options.bases,
+          canvas: options.canvas,
           theme: options.theme,
-          from: options.from,
           force: options.force,
           vault: options.vault
         });

package/bin/register-maintenance-commands.js

@@ -26,8 +26,8 @@ export function registerMaintenanceCommands(program, { chalk }) {
 
         console.log(chalk.cyan('\n🩺 ClawVault Health Check\n'));
         console.log(chalk.dim(`Vault: ${report.vaultPath}`));
-        if (report.qmdCollection) console.log(chalk.dim(`qmd collection: ${report.qmdCollection}`));
-        if (report.qmdRoot) console.log(chalk.dim(`qmd root: ${report.qmdRoot}`));
+        console.log(chalk.dim(`qmd collection: ${report.qmdCollection}`));
+        console.log(chalk.dim(`qmd root: ${report.qmdRoot}`));
         console.log();
 
         for (const check of report.checks) {
@@ -36,7 +36,7 @@ export function registerMaintenanceCommands(program, { chalk }) {
             : check.status === 'warn'
               ? chalk.yellow('⚠')
               : chalk.red('✗');
-          const line = check.detail ? `${check.label}: ${check.detail}` : check.label;
+          const line = `${check.label}: ${check.detail}`;
           const renderedLine = check.status === 'ok'
             ? chalk.green(line)
             : check.status === 'warn'
@@ -80,6 +80,25 @@ export function registerMaintenanceCommands(program, { chalk }) {
       }
     });
 
+  // === REBUILD-EMBEDDINGS ===
+  program
+    .command('rebuild-embeddings')
+    .description('Rebuild local embedding cache for hybrid search (uses all-MiniLM-L6-v2)')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--force', 'Force rebuild all embeddings (ignore cache)')
+    .action(async (options) => {
+      try {
+        const { rebuildEmbeddingsCommand } = await import('../dist/commands/rebuild-embeddings.js');
+        await rebuildEmbeddingsCommand({
+          vaultPath: options.vault,
+          force: options.force
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
   // === COMPAT (OpenClaw compatibility) ===
   program
     .command('compat')
@@ -262,4 +281,21 @@ export function registerMaintenanceCommands(program, { chalk }) {
     });
 
   // === SYNC-BD ===
+  program
+    .command('sync-bd')
+    .description('Sync active Beads tasks into views/now.md (optional)')
+    .option('--dry-run', 'Show sync output without writing')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (options) => {
+      try {
+        const { syncBdCommand } = await import('../dist/commands/sync-bd.js');
+        await syncBdCommand({
+          vaultPath: options.vault,
+          dryRun: options.dryRun
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
 }