clawvault 2.6.1 → 2.6.4

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-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-maintenance-commands.js

@@ -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')

package/bin/register-query-commands.js

@@ -9,13 +9,15 @@ export function registerQueryCommands(
     getVault,
     resolveVaultPath,
     QmdUnavailableError,
-    printQmdMissing
+    QmdConfigurationError,
+    printQmdMissing,
+    printQmdConfigError
   }
 ) {
   // === SEARCH ===
   program
     .command('search <query>')
-    .description('Search the vault via qmd (BM25)')
+    .description('Search the vault via qmd (BM25), optionally with semantic hybrid search')
     .option('-n, --limit <n>', 'Max results (default: 10)', '10')
     .option('-c, --category <category>', 'Filter by category')
     .option('--tags <tags>', 'Filter by tags (comma-separated)')
@@ -23,20 +25,57 @@ export function registerQueryCommands(
     .option('--full', 'Include full content in results')
     .option('-v, --vault <path>', 'Vault path')
     .option('--json', 'Output as JSON')
+    .option('--semantic', 'Enable hybrid search (BM25 + semantic with RRF)')
+    .option('--rebuild-embeddings', 'Rebuild the embedding cache before searching')
     .action(async (query, options) => {
       try {
+        const vaultPath = resolveVaultPath(options.vault);
         const vault = await getVault(options.vault);
 
-        const results = await vault.find(query, {
-          limit: parseInt(options.limit, 10),
+        // Handle --rebuild-embeddings flag
+        if (options.rebuildEmbeddings) {
+          const { rebuildEmbeddingsForVault } = await import('../dist/commands/rebuild-embeddings.js');
+          console.log(chalk.cyan('Rebuilding embedding cache...'));
+          const stats = await rebuildEmbeddingsForVault(vaultPath, { 
+            onProgress: (current, total) => {
+              process.stdout.write(`\r  Embedding ${current}/${total} documents...`);
+            }
+          });
+          console.log(chalk.green(`\n  Done. ${stats.total} embeddings (${stats.added} new, ${stats.skipped} cached)`));
+          console.log();
+        }
+
+        // Get BM25 results
+        const bm25Results = await vault.find(query, {
+          limit: options.semantic ? 50 : parseInt(options.limit, 10),
           category: options.category,
           tags: options.tags?.split(',').map((value) => value.trim()),
           fullContent: options.full,
           temporalBoost: options.recent
         });
 
+        let results = bm25Results;
+        let searchMode = 'BM25';
+
+        // Apply hybrid search if --semantic flag is set
+        if (options.semantic) {
+          const { EmbeddingCache, hybridSearch } = await import('../dist/lib/hybrid-search.js');
+          const cache = new EmbeddingCache(vaultPath);
+          cache.load();
+
+          if (cache.size === 0) {
+            console.log(chalk.yellow('Warning: No embeddings found. Run with --rebuild-embeddings to build the cache.'));
+          } else {
+            results = await hybridSearch(query, bm25Results, cache, {
+              topK: parseInt(options.limit, 10),
+              rrfK: 60
+            });
+            searchMode = 'Hybrid (BM25 + Semantic)';
+          }
+        }
+
         if (options.json) {
-          console.log(JSON.stringify(results, null, 2));
+          console.log(JSON.stringify({ searchMode, results }, null, 2));
           return;
         }
 
@@ -45,7 +84,8 @@ export function registerQueryCommands(
           return;
         }
 
-        console.log(chalk.cyan(`\n🔍 Found ${results.length} result(s) for "${query}":\n`));
+        const icon = options.semantic ? '🔍🧠' : '🔍';
+        console.log(chalk.cyan(`\n${icon} Found ${results.length} result(s) for "${query}" [${searchMode}]:\n`));
 
         for (const result of results) {
           const scoreBar = '█'.repeat(Math.round(result.score * 10)).padEnd(10, '░');
@@ -62,6 +102,10 @@ export function registerQueryCommands(
           printQmdMissing();
           process.exit(1);
         }
+        if (err instanceof QmdConfigurationError) {
+          printQmdConfigError(err);
+          process.exit(1);
+        }
         console.error(chalk.red(`Error: ${err.message}`));
         process.exit(1);
       }
@@ -117,6 +161,10 @@ export function registerQueryCommands(
           printQmdMissing();
           process.exit(1);
         }
+        if (err instanceof QmdConfigurationError) {
+          printQmdConfigError(err);
+          process.exit(1);
+        }
         console.error(chalk.red(`Error: ${err.message}`));
         process.exit(1);
       }
@@ -163,6 +211,10 @@ export function registerQueryCommands(
           printQmdMissing();
           process.exit(1);
         }
+        if (err instanceof QmdConfigurationError) {
+          printQmdConfigError(err);
+          process.exit(1);
+        }
         console.error(chalk.red(`Error: ${err.message}`));
         process.exit(1);
       }