clawvault 2.5.1 → 2.5.3

package/README.md

@@ -1,199 +1,159 @@
-# ClawVault™ 🐘
-
-**An elephant never forgets.**
-
-Structured memory system for AI agents. Typed storage, knowledge graph, task management, and Obsidian-native dashboards — all local, all markdown.
-
-[![npm](https://img.shields.io/npm/v/clawvault)](https://www.npmjs.com/package/clawvault) [![tests](https://img.shields.io/badge/tests-361%20passing-brightgreen)]()
-
-🌐 [clawvault.dev](https://clawvault.dev) · 📚 [docs.clawvault.dev](https://docs.clawvault.dev) · 🛠️ [ClawHub Skill](https://clawhub.com/skills/clawvault)
-
-> Works with [OpenClaw](https://openclaw.ai) agents or standalone. No cloud. No API keys. Just files.
-
-## Install
-
-```bash
-npm install -g clawvault
-```
-
-## Quick Start
-
-```bash
-# Create a vault
-clawvault init ~/memory --name my-brain
-
-# Store memories by type
-clawvault remember decision "Use PostgreSQL" --content "Chose for JSONB support"
-clawvault remember lesson "Always checkpoint" --content "Context death is real"
-clawvault capture "Quick thought to process later"
-
-# Search
-clawvault search "postgresql"           # Keyword (BM25)
-clawvault vsearch "what database?"      # Semantic (local embeddings)
-
-# Session lifecycle
-clawvault wake                          # Start session, load context
-clawvault sleep "built auth system" \   # End session with handoff
-  --next "deploy to staging"
-
-# Task management
-clawvault task add "Ship v2" --owner agent --project acme --priority high
-clawvault task list
-clawvault blocked
-clawvault backlog add "Explore caching" --project acme
-
-# Visual dashboards (Obsidian JSON Canvas)
-clawvault canvas --template brain           # System architecture overview
-clawvault canvas --template project-board   # Task board by owner
-```
-
-## Features
-
-### 📁 Typed Memory Storage
-Every memory has a category: `decisions/`, `lessons/`, `people/`, `projects/`, `commitments/`. No more dumping everything into one file. "Show me all decisions" actually works.
-
-### 🧠 Knowledge Graph
-Wiki-links (`[[connections]]`) build a typed graph index. Query with graph-aware context that blends semantic search with relationship traversal.
-
-```bash
-clawvault graph                              # Graph summary
-clawvault context "database migration" \     # Graph-aware context
-  --profile planning --budget 2000
-```
-
-### ✅ Task Management
-Tasks and backlog stored as markdown with frontmatter. Agents and humans share the same system.
-
-```bash
-clawvault task add "Fix auth" --owner bot --priority critical
-clawvault task update fix-auth --status blocked --blocked-by "api-key"
-clawvault blocked                            # Triage blocked work
-clawvault backlog promote explore-caching    # Backlog → active task
-```
-
-### 🎨 Obsidian Dashboards
-Generate visual dashboards as [JSON Canvas](https://jsoncanvas.org) files:
-
-| Template | Description |
-|----------|-------------|
-| `brain` | 4-quadrant architecture: vault structure, direction, agent workspace, knowledge graph |
-| `project-board` | Owner-centric kanban with status columns, priority icons, agent/human cards |
-| `default` | Two-column dashboard with activity metrics and task triage |
-| `sprint` | Weekly focus with sprint metrics and open loops |
-
-```bash
-clawvault canvas --template brain
-clawvault canvas --template project-board --owner my-agent
-```
-
-### 🔭 Observational Memory
-Auto-compress conversations into prioritized observations. Critical items route to vault categories automatically.
-
-```bash
-clawvault observe --compress session.md      # One-shot compression
-clawvault observe --active                   # Incremental from transcripts
-```
-
-### 🛡️ Context Death Recovery
-Checkpoint/recover system keeps agents alive across crashes and session resets.
-
-```bash
-clawvault checkpoint --working-on "migration" --focus "step 3"
-clawvault recover                            # After crash/reset
-```
-
-### 🌐 Tailscale Networking
-Multi-vault collaboration over Tailscale with trust levels and cross-vault search.
-
-```bash
-clawvault serve                              # Start API server
-clawvault peers                              # Manage vault peers
-clawvault net-search "query"                 # Search across vaults
-```
-
-## Setup & Customization
-
-```bash
-# Full setup with neural graph theme + Obsidian Bases views
-clawvault setup --theme neural --canvas brain
-
-# Minimal agent vault
-clawvault init ./memory --minimal
-
-# Custom categories
-clawvault init ./memory --categories "notes,research,code"
-
-# Skip visual config
-clawvault setup --no-graph-colors --no-bases
-```
-
-### Graph Themes
-
-| Theme | Description |
-|-------|-------------|
-| `neural` | Dark background, colored nodes by category, green network links, golden glow |
-| `minimal` | Subtle category colors, no background changes |
-| `none` | Skip graph theming |
-
-## Vault Structure
-
-```
-memory/
-├── .clawvault.json          # Vault config
-├── .clawvault/
-│   └── graph-index.json     # Knowledge graph
-├── tasks/                   # Active tasks (markdown + frontmatter)
-├── backlog/                 # Ideas and future work
-├── decisions/               # Choices with reasoning
-├── lessons/                 # Things learned
-├── people/                  # One file per person
-├── projects/                # Active work
-├── commitments/             # Promises and deadlines
-├── inbox/                   # Quick captures
-├── handoffs/                # Session continuity
-├── ledger/
-│   ├── raw/                 # Raw session transcripts
-│   ├── observations/        # Compressed observations
-│   └── reflections/         # Weekly reflections
-├── all-tasks.base           # Obsidian Bases view
-├── by-owner.base            # Tasks by owner
-└── dashboard.canvas         # Generated dashboard
-```
-
-## For OpenClaw Agents
-
-```bash
-# Install as a skill
-clawhub install clawvault
-
-# Or add to your agent's tools
-npm install -g clawvault
-```
-
-Add to your `AGENTS.md`:
-
-```markdown
-## Memory
-- `clawvault wake` on session start
-- `clawvault sleep "summary" --next "next steps"` on session end
-- `clawvault checkpoint` every 10-15 min during heavy work
-- `clawvault remember <type> "title" --content "..."` for important items
-- `clawvault search "query"` before asking questions
-```
-
-## Requirements
-
-- **Node.js 18+**
-- **[qmd](https://github.com/Versatly/qmd)** — Local semantic search (optional but recommended)
-
-## Docs
-
-Full documentation at **[docs.clawvault.dev](https://docs.clawvault.dev)**
-
-## License
-
-MIT
-
----
-
-*Built by [Versatly](https://versatly.com) — autonomous AI employees for businesses.* 🐘
+# ClawVault 🐘
+
+Structured memory system for AI agents and operators: typed markdown memory, graph-aware context, task/project primitives, Obsidian views, and OpenClaw hook integration.
+
+[![npm](https://img.shields.io/npm/v/clawvault)](https://www.npmjs.com/package/clawvault)
+
+> Local-first. Markdown-first. Built to survive long-running autonomous work.
+
+## Requirements
+
+- Node.js 18+
+- `qmd` installed and available on `PATH`
+
+ClawVault currently relies on `qmd` for core vault/query flows. Install it before first use.
+
+## Install
+
+```bash
+npm install -g clawvault
+```
+
+## 5-Minute Setup
+
+```bash
+# 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
+```
+
+## OpenClaw Setup (Canonical)
+
+If you want hook-based lifecycle integration, use this sequence:
+
+```bash
+# 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.
+- After enabling hooks, restart the OpenClaw gateway process so hook registration reloads.
+
+## Minimal AGENTS.md Additions
+
+Append these to your existing memory workflow. Do not replace your full prompt setup:
+
+```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.
+```
+
+## Real CLI Surface (Current)
+
+Core:
+
+- `init`, `setup`, `store`, `capture`
+- `remember`, `list`, `get`, `stats`, `reindex`, `sync`
+
+Context + memory:
+
+- `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
+
+```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
+```
+
+## 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
+
+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
+```
+
+## 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`
+
+## License
+
+MIT

package/bin/clawvault.js

@@ -1,112 +1,112 @@
-#!/usr/bin/env node
-
-/**
- * ClawVault CLI 🐘
- * An elephant never forgets.
- */
-
-import { Command } from 'commander';
-import chalk from 'chalk';
-import * as fs from 'fs';
-import * as path from 'path';
-import { registerMaintenanceCommands } from './register-maintenance-commands.js';
-import { registerCoreCommands } from './register-core-commands.js';
-import { registerQueryCommands } from './register-query-commands.js';
-import { registerResilienceCommands } from './register-resilience-commands.js';
-import { registerSessionLifecycleCommands } from './register-session-lifecycle-commands.js';
-import { registerTemplateCommands } from './register-template-commands.js';
-import { registerVaultOperationsCommands } from './register-vault-operations-commands.js';
-import { registerConfigCommands } from './register-config-commands.js';
-import { registerRouteCommands } from './register-route-commands.js';
-import { registerKanbanCommands } from './register-kanban-commands.js';
-import { registerProjectCommands } from './register-project-commands.js';
-
-import { registerTaskCommands } from './register-task-commands.js';
-
-import { registerTailscaleCommands } from './register-tailscale-commands.js';
-import {
-  getVault,
-  resolveVaultPath,
-  runQmd,
-  printQmdMissing,
-  QmdUnavailableError
-} from './command-runtime.js';
-import {
-  createVault
-} from '../dist/index.js';
-
-const program = new Command();
-
-const CLI_VERSION = (() => {
-  try {
-    const pkgUrl = new URL('../package.json', import.meta.url);
-    const pkg = JSON.parse(fs.readFileSync(pkgUrl, 'utf-8'));
-    return pkg.version || '0.0.0';
-  } catch {
-    return '0.0.0';
-  }
-})();
-
-program
-  .name('clawvault')
-  .description('🐘 An elephant never forgets. Structured memory for AI agents.')
-  .version(CLI_VERSION);
-
-registerCoreCommands(program, {
-  chalk,
-  path,
-  fs,
-  createVault,
-  getVault,
-  runQmd
-});
-
-registerQueryCommands(program, {
-  chalk,
-  getVault,
-  resolveVaultPath,
-  QmdUnavailableError,
-  printQmdMissing
-});
-
-registerSessionLifecycleCommands(program, {
-  chalk,
-  resolveVaultPath,
-  QmdUnavailableError,
-  printQmdMissing,
-  getVault,
-  runQmd
-});
-
-registerTemplateCommands(program, { chalk });
-registerMaintenanceCommands(program, { chalk });
-registerResilienceCommands(program, { chalk, resolveVaultPath });
-registerVaultOperationsCommands(program, {
-  chalk,
-  fs,
-  getVault,
-  runQmd,
-  resolveVaultPath,
-  path
-});
-
-
-registerTaskCommands(program, {
-  chalk,
-  resolveVaultPath
-});
-registerKanbanCommands(program, {
-  chalk,
-  resolveVaultPath
-});
-registerProjectCommands(program, {
-  chalk,
-  resolveVaultPath
-});
-
-registerTailscaleCommands(program, { chalk });
-registerConfigCommands(program, { chalk, resolveVaultPath });
-registerRouteCommands(program, { chalk, resolveVaultPath });
-
-// Parse and run
+#!/usr/bin/env node
+
+/**
+ * ClawVault CLI 🐘
+ * An elephant never forgets.
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+import { registerMaintenanceCommands } from './register-maintenance-commands.js';
+import { registerCoreCommands } from './register-core-commands.js';
+import { registerQueryCommands } from './register-query-commands.js';
+import { registerResilienceCommands } from './register-resilience-commands.js';
+import { registerSessionLifecycleCommands } from './register-session-lifecycle-commands.js';
+import { registerTemplateCommands } from './register-template-commands.js';
+import { registerVaultOperationsCommands } from './register-vault-operations-commands.js';
+import { registerConfigCommands } from './register-config-commands.js';
+import { registerRouteCommands } from './register-route-commands.js';
+import { registerKanbanCommands } from './register-kanban-commands.js';
+import { registerProjectCommands } from './register-project-commands.js';
+
+import { registerTaskCommands } from './register-task-commands.js';
+
+import { registerTailscaleCommands } from './register-tailscale-commands.js';
+import {
+  getVault,
+  resolveVaultPath,
+  runQmd,
+  printQmdMissing,
+  QmdUnavailableError
+} from './command-runtime.js';
+import {
+  createVault
+} from '../dist/index.js';
+
+const program = new Command();
+
+const CLI_VERSION = (() => {
+  try {
+    const pkgUrl = new URL('../package.json', import.meta.url);
+    const pkg = JSON.parse(fs.readFileSync(pkgUrl, 'utf-8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+})();
+
+program
+  .name('clawvault')
+  .description('🐘 An elephant never forgets. Structured memory for AI agents.')
+  .version(CLI_VERSION);
+
+registerCoreCommands(program, {
+  chalk,
+  path,
+  fs,
+  createVault,
+  getVault,
+  runQmd
+});
+
+registerQueryCommands(program, {
+  chalk,
+  getVault,
+  resolveVaultPath,
+  QmdUnavailableError,
+  printQmdMissing
+});
+
+registerSessionLifecycleCommands(program, {
+  chalk,
+  resolveVaultPath,
+  QmdUnavailableError,
+  printQmdMissing,
+  getVault,
+  runQmd
+});
+
+registerTemplateCommands(program, { chalk });
+registerMaintenanceCommands(program, { chalk });
+registerResilienceCommands(program, { chalk, resolveVaultPath });
+registerVaultOperationsCommands(program, {
+  chalk,
+  fs,
+  getVault,
+  runQmd,
+  resolveVaultPath,
+  path
+});
+
+
+registerTaskCommands(program, {
+  chalk,
+  resolveVaultPath
+});
+registerKanbanCommands(program, {
+  chalk,
+  resolveVaultPath
+});
+registerProjectCommands(program, {
+  chalk,
+  resolveVaultPath
+});
+
+registerTailscaleCommands(program, { chalk });
+registerConfigCommands(program, { chalk, resolveVaultPath });
+registerRouteCommands(program, { chalk, resolveVaultPath });
+
+// Parse and run
 program.parse();