clawvault 3.1.0 → 3.2.1

package/README.md

@@ -1,209 +1,490 @@
-# ClawVault
+<div align="center">
 
-Structured memory for AI agents. Typed markdown primitives that compound over time.
+# ClawVault 🐘
 
+**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)
 
-Every memory is a markdown file with YAML frontmatter — a task, a decision, a person, a lesson — each following a schema defined in `templates/`. The agent reads and writes these files. The human browses them in Obsidian. No database. No vendor lock-in. Just files.
+*An elephant never forgets. Neither should your AI.*
 
-## Requirements
+[Documentation](https://clawvault.dev) · [npm Package](https://www.npmjs.com/package/clawvault) · [Obsidian Plugin](https://clawvault.dev/obsidian) · [Community](https://github.com/Versatly/clawvault/discussions) · [GitHub](https://github.com/Versatly/clawvault)
 
-- Node.js 18+
-- [`qmd`](https://github.com/qmd-project/qmd) installed and on `PATH` (hybrid BM25 + vector search)
+</div>
 
-## Install
+---
+
+## 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 |
 
-### As an OpenClaw Plugin (recommended)
+These primitives map directly to CLI commands and vault structure, creating a coherent system for agent memory.
+
+---
+
+## Quick Start
+
+### Installation
 
 ```bash
-openclaw plugins install clawvault
+# Install ClawVault CLI
+npm install -g clawvault
+
+# Install qmd (required for search/context features)
+npm install -g github:tobi/qmd
 ```
 
-This installs ClawVault as a memory plugin. It replaces OpenClaw's built-in memory with:
+### Initialize Your Vault
 
-- **Auto-recall** — injects relevant memories before each agent turn
-- **Auto-capture** — observes conversations and stores durable knowledge automatically
-- **Session recap** — on wake, provides context from active tasks, recent decisions, and preferences
-- **4 tools** — `memory_search`, `memory_store`, `memory_get`, `memory_forget`
+```bash
+# Create a new vault
+clawvault init ~/memory --name my-brain
 
-After install, configure the vault path:
+# Optional: Set up Obsidian integration
+clawvault setup --theme neural --canvas
+```
+
+### Basic Workflow
 
 ```bash
-openclaw config set plugins.clawvault.config.vaultPath ~/my-vault
+# 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"
 ```
 
-### As a Standalone CLI
+### Search and Context
 
 ```bash
-npm install -g clawvault
+# 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"
 ```
 
-## Quick Start
+---
+
+## 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`](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
-# Initialize a new vault
-clawvault init ~/my-vault --name my-brain
+# View graph summary
+clawvault graph
+
+# Refresh graph index
+clawvault graph --refresh
+```
 
-# Set up Obsidian Bases views (tasks, projects, backlog)
-clawvault setup
+### Context Profiles
 
-# Check vault health
-clawvault doctor
+Different tasks need different context. Use profiles to tune retrieval:
 
-# Search your vault
-clawvault search "deployment decision"
+| 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"
 ```
 
-## How It Works
+### Task Management
 
-### Typed Primitives
+Full task lifecycle with Kanban support:
+
+```bash
+# Create tasks
+clawvault task add "Ship v2 onboarding" --owner agent --project core --priority high
 
-Every piece of memory has a type defined by a template:
+# 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
+```
 
-```yaml
 ---
-primitive: task
-fields:
-  status:
-    type: string
-    required: true
-    default: open
-    enum: [open, in-progress, blocked, done]
-  priority:
-    type: string
-    enum: [critical, high, medium, low]
-  owner:
-    type: string
-  due:
-    type: date
+
+## 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` (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:
+
+| 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"
 ```
 
-Default templates: `task`, `decision`, `lesson`, `person`, `project`, `checkpoint`, `handoff`, `daily`, `trigger`, `run`, `party`, `workspace`.
+## Install
 
-### Malleable Schemas
+```bash
+npm install -g clawvault
+```
 
-Don't like the defaults? Drop your own template in your vault's `templates/` directory. Add fields, remove fields, create entirely new types. The plugin reads YOUR schemas, not ours.
+## 5-Minute Setup
 
-### Hybrid Search
+```bash
+# 1) Create or initialize a vault
+clawvault init ~/memory --name my-brain
 
-ClawVault uses `qmd` for search — BM25 keyword matching combined with vector similarity and reranking. Entirely local. No API keys needed.
+# 2) Optional vault bootstrap for Obsidian
+clawvault setup --theme neural --canvas
 
-### Obsidian Integration
+# 3) Verify OpenClaw compatibility in this environment
+clawvault compat
+```
 
-Your vault IS an Obsidian vault. Tasks become Kanban boards. Decisions are searchable. Wiki-links build a knowledge graph. Five generated Bases views out of the box:
+## OpenClaw Setup (Canonical)
 
-- All tasks
-- Blocked items  
-- By project
-- By owner
-- Backlog
+If you want hook-based lifecycle integration, use this sequence:
 
-## CLI Commands
+```bash
+# Install CLI
+npm install -g clawvault
 
-### Core
+# Install and enable hook pack
+openclaw hooks install clawvault
+openclaw hooks enable clawvault
 
-| Command | Description |
-|---------|-------------|
-| `init [path]` | Initialize a new vault |
-| `setup` | Auto-discover and configure a vault, create Obsidian views |
-| `store` | Store a new typed memory document |
-| `capture <note>` | Quick-capture a note to inbox |
-| `doctor` | Diagnose vault health |
+# Verify
+openclaw hooks list --verbose
+openclaw hooks info clawvault
+openclaw hooks check
+clawvault compat
+```
 
-### Search & Context
+Important:
 
-| Command | Description |
-|---------|-------------|
-| `search <query>` | BM25 keyword search via qmd |
-| `vsearch <query>` | Semantic vector search via qmd |
-| `context <task>` | Generate task-relevant context |
-| `inject <message>` | Inject relevant rules and decisions |
+- `clawhub install clawvault` installs skill guidance, but does not replace hook-pack installation.
+- After enabling hooks, restart the OpenClaw gateway process so hook registration reloads.
 
-### Session Lifecycle
+## Minimal AGENTS.md Additions
 
-| Command | Description |
-|---------|-------------|
-| `wake` | Start a session (recover + recap) |
-| `sleep <summary>` | End a session with a handoff |
-| `checkpoint` | Save state for context-death resilience |
-| `recover` | Check for and recover from context death |
+Append these to your existing memory workflow. Do not replace your full prompt setup:
 
-### Observation Pipeline
+```markdown
+## 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.
+```
 
-| Command | Description |
-|---------|-------------|
-| `observe` | Process sessions into observational memory |
-| `reflect` | Promote observations to weekly reflections |
-| `reweave` | Backward consolidation — mark superseded observations |
+---
 
-### Tasks & Projects
+## CLI Reference
 
-| Command | Description |
-|---------|-------------|
-| `task` | Task management (create, list, update, transition) |
-| `project` | Project management |
-| `kanban` | Kanban board view |
-| `status` | Vault health and statistics |
+### Core Commands
 
-### Utilities
+- `init`, `setup`, `store`, `capture`
+- `remember`, `list`, `get`, `stats`, `reindex`, `sync`
 
-| Command | Description |
-|---------|-------------|
-| `template` | Manage document templates |
-| `graph` | Show typed memory graph summary |
-| `entities` | List all linkable entities |
-| `link [file]` | Auto-link entity mentions |
-| `compat` | Check OpenClaw compatibility |
-| `embed` | Run qmd embedding for pending documents |
+### Context + Memory
 
-## Architecture
+- `search`, `vsearch`, `context`, `inject`
+- `observe`, `reflect`, `session-recap`
+- `graph`, `entities`, `link`, `embed`
 
+### Resilience
+
+- `wake`, `sleep`, `handoff`, `recap`
+- `checkpoint`, `recover`, `status`, `clean-exit`, `repair-session`
+- `compat`, `doctor`
+
+### Execution Primitives
+
+- `task ...`, `backlog ...`, `blocked`, `project ...`, `kanban ...`
+- `canvas` (generates default `dashboard.canvas`)
+
+### Networking
+
+- `tailscale-status`, `tailscale-sync`, `tailscale-serve`, `tailscale-discover`
+
+---
+
+## Quick Usage Examples
+
+```bash
+# 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
 ```
-     HUMAN (Obsidian)
-     Browse, edit, approve
-           │
-           ▼
-  ┌─── VAULT (markdown) ───┐
-  │  Typed primitives       │
-  │  Knowledge graph        │
-  │  Template schemas       │
-  └───┬──────────────┬──────┘
-      │              │
- AGENT (Plugin)   CLI (Developer)
- Auto-capture     Direct CRUD
- Auto-recall      Search, graph
- Session recap    Tasks, projects
+
+---
+
+## Tailscale + WebDAV
+
+ClawVault can serve vault content for sync over Tailscale and exposes WebDAV under `/webdav` for mobile-oriented workflows.
+
+```bash
+clawvault tailscale-status
+clawvault tailscale-serve --vault ~/memory
+clawvault tailscale-discover
 ```
 
-## OpenClaw Plugin Details
+---
 
-The plugin hooks into the OpenClaw lifecycle:
+## Vault Structure
 
-- **`before_agent_start`** — auto-recall: searches vault for context relevant to the current conversation and injects it
-- **`message_received`** — auto-capture: observes incoming messages for durable information worth storing  
-- **`agent_end`** — captures any final observations from the agent's response
-- **`before_compaction`** — preserves important context before conversation compaction
+```
+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:
+  - run `openclaw hooks install clawvault` first
+  - then `openclaw hooks enable clawvault`
+  - restart gateway
+  - verify with `openclaw hooks list --verbose`
+- `qmd` errors:
+  - ensure `qmd --version` works from same shell
+  - rerun `clawvault setup` after qmd install
+- OpenClaw integration drift:
+  - run `clawvault compat`
+- Session transcript corruption:
+  - run `clawvault repair-session --dry-run` then `clawvault repair-session`
+
+---
+
+## Links
 
-Configuration in `openclaw.plugin.json`:
+| 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.
+
+---
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `vaultPath` | — | Path to vault directory |
-| `collection` | `clawvault` | qmd search collection name |
-| `autoRecall` | `true` | Inject memories before each turn |
-| `autoCapture` | `true` | Auto-store from conversations |
-| `recallLimit` | `5` | Max memories per recall |
-
-## What Compounds
-
-- **Decisions** accumulate into institutional knowledge
-- **Lessons** prevent repeated mistakes  
-- **Tasks** with transition ledgers track how work happened
-- **Projects** group related work across hundreds of sessions
-- **Wiki-links** build a knowledge graph that grows richer over time
-
-The agent that runs for a year generates compounding value. Every lesson stored makes the next task cheaper.
+**$CLAWVAULT**: [`5Fjr82MTB8mvxkzi9FYtvrUsPiDGE2M29w3dYcZpump`](https://pump.fun/coin/5Fjr82MTB8mvxkzi9FYtvrUsPiDGE2M29w3dYcZpump)
 
 ## License
 

package/bin/clawvault.js

@@ -23,12 +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
@@ -65,7 +69,9 @@ registerQueryCommands(program, {
   getVault,
   resolveVaultPath,
   QmdUnavailableError,
-  printQmdMissing
+  QmdConfigurationError,
+  printQmdMissing,
+  printQmdConfigError
 });
 
 registerSessionLifecycleCommands(program, {
@@ -103,6 +109,8 @@ registerProjectCommands(program, {
   resolveVaultPath
 });
 
+registerWorkgraphCommands(program, { chalk, resolveVaultPath });
+registerTailscaleCommands(program, { chalk });
 registerConfigCommands(program, { chalk, resolveVaultPath });
 registerRouteCommands(program, { chalk, resolveVaultPath });