clawvault 3.0.0 → 3.1.0

package/README.md

@@ -1,158 +1,209 @@
-# ClawVault 🐘
+# ClawVault
 
-Structured memory system for AI agents and operators: typed markdown memory, graph-aware context, task/project primitives, Obsidian views, and OpenClaw hook integration.
+Structured memory for AI agents. Typed markdown primitives that compound over time.
 
 [![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.
+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.
 
 ## 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.
+- [`qmd`](https://github.com/qmd-project/qmd) installed and on `PATH` (hybrid BM25 + vector search)
 
 ## Install
 
+### As an OpenClaw Plugin (recommended)
+
 ```bash
-npm install -g clawvault
+openclaw plugins install clawvault
 ```
 
-## 5-Minute Setup
+This installs ClawVault as a memory plugin. It replaces OpenClaw's built-in memory with:
 
-```bash
-# 1) Create or initialize a vault
-clawvault init ~/memory --name my-brain
+- **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`
 
-# 2) Optional vault bootstrap for Obsidian
-clawvault setup --theme neural --canvas
+After install, configure the vault path:
 
-# 3) Verify OpenClaw compatibility in this environment
-clawvault compat
+```bash
+openclaw config set plugins.clawvault.config.vaultPath ~/my-vault
 ```
 
-## OpenClaw Setup (Canonical)
-
-If you want hook-based lifecycle integration, use this sequence:
+### As a Standalone CLI
 
 ```bash
-# Install CLI
 npm install -g clawvault
+```
 
-# Install and enable hook pack
-openclaw hooks install clawvault
-openclaw hooks enable clawvault
+## Quick Start
 
-# Verify
-openclaw hooks list --verbose
-openclaw hooks info clawvault
-openclaw hooks check
-clawvault compat
+```bash
+# Initialize a new vault
+clawvault init ~/my-vault --name my-brain
+
+# Set up Obsidian Bases views (tasks, projects, backlog)
+clawvault setup
+
+# Check vault health
+clawvault doctor
+
+# Search your vault
+clawvault search "deployment decision"
 ```
 
-Important:
+## How It Works
+
+### Typed Primitives
+
+Every piece of memory has a type defined by a template:
+
+```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
+---
+```
 
-- `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.
+Default templates: `task`, `decision`, `lesson`, `person`, `project`, `checkpoint`, `handoff`, `daily`, `trigger`, `run`, `party`, `workspace`.
 
-## Minimal AGENTS.md Additions
+### Malleable Schemas
 
-Append these to your existing memory workflow. Do not replace your full prompt setup:
+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.
 
-```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.
-```
+### Hybrid Search
 
-## Real CLI Surface (Current)
+ClawVault uses `qmd` for search — BM25 keyword matching combined with vector similarity and reranking. Entirely local. No API keys needed.
 
-Core:
+### Obsidian Integration
 
-- `init`, `setup`, `store`, `capture`
-- `remember`, `list`, `get`, `stats`, `reindex`, `sync`
+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:
 
-Context + memory:
+- All tasks
+- Blocked items  
+- By project
+- By owner
+- Backlog
 
-- `search`, `vsearch`, `context`, `inject`
-- `observe`, `reflect`, `session-recap`
-- `graph`, `entities`, `link`, `embed`
+## CLI Commands
 
-Resilience:
+### Core
 
-- `wake`, `sleep`, `handoff`, `recap`
-- `checkpoint`, `recover`, `status`, `clean-exit`, `repair-session`
-- `compat`, `doctor`
+| 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 |
 
-Execution primitives:
+### Search & Context
 
-- `task ...`, `backlog ...`, `blocked`, `project ...`, `kanban ...`
-- `canvas` (generates default `dashboard.canvas`)
+| 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 |
 
-Networking:
+### Session Lifecycle
 
-- `tailscale-status`, `tailscale-sync`, `tailscale-serve`, `tailscale-discover`
+| 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 |
 
-## Quick Usage
+### Observation Pipeline
 
-```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
-```
+| Command | Description |
+|---------|-------------|
+| `observe` | Process sessions into observational memory |
+| `reflect` | Promote observations to weekly reflections |
+| `reweave` | Backward consolidation — mark superseded observations |
 
-## Obsidian Integration
+### Tasks & Projects
 
-- 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`
+| Command | Description |
+|---------|-------------|
+| `task` | Task management (create, list, update, transition) |
+| `project` | Project management |
+| `kanban` | Kanban board view |
+| `status` | Vault health and statistics |
 
-## Tailscale + WebDAV
+### Utilities
 
-ClawVault can serve vault content for sync over Tailscale and exposes WebDAV under `/webdav` for mobile-oriented workflows.
+| 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 |
 
-```bash
-clawvault tailscale-status
-clawvault tailscale-serve --vault ~/memory
-clawvault tailscale-discover
+## Architecture
+
+```
+     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
 ```
 
-## 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`
+## OpenClaw Plugin Details
+
+The plugin hooks into the OpenClaw lifecycle:
+
+- **`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
+
+Configuration in `openclaw.plugin.json`:
+
+| 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.
 
 ## License
 

package/bin/clawvault.js

@@ -23,7 +23,6 @@ import { registerProjectCommands } from './register-project-commands.js';
 
 import { registerTaskCommands } from './register-task-commands.js';
 
-import { registerTailscaleCommands } from './register-tailscale-commands.js';
 import {
   getVault,
   resolveVaultPath,
@@ -104,7 +103,6 @@ registerProjectCommands(program, {
   resolveVaultPath
 });
 
-registerTailscaleCommands(program, { chalk });
 registerConfigCommands(program, { chalk, resolveVaultPath });
 registerRouteCommands(program, { chalk, resolveVaultPath });
 

package/bin/register-core-commands.js

@@ -129,7 +129,6 @@ export function registerCoreCommands(
     .option('--bases', 'Generate Obsidian Bases views for task management')
     .option('--no-bases', 'Skip Bases file 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) => {
@@ -139,7 +138,6 @@ export function registerCoreCommands(
           graphColors: options.graphColors,
           bases: options.bases,
           theme: options.theme,
-          from: options.from,
           force: options.force,
           vault: options.vault
         });
@@ -221,4 +219,24 @@ export function registerCoreCommands(
         process.exit(1);
       }
     });
+  // === PLUGIN-PATH ===
+  program
+    .command('plugin-path')
+    .description('Print the OpenClaw plugin path for configuration')
+    .action(() => {
+      const pluginDir = path.dirname(path.dirname(new URL(import.meta.url).pathname));
+      const pluginPath = path.join(pluginDir, 'dist', 'plugin', 'index.js');
+      if (fs.existsSync(pluginPath)) {
+        console.log(pluginPath);
+      } else {
+        // Dev mode — use source
+        const srcPath = path.join(pluginDir, 'src', 'plugin', 'index.ts');
+        if (fs.existsSync(srcPath)) {
+          console.log(srcPath);
+        } else {
+          console.error('Plugin not found. Run: npm run build');
+          process.exit(1);
+        }
+      }
+    });
 }

package/dist/{chunk-3D6BCTP6.js → chunk-33UGEQRT.js}

@@ -4,8 +4,6 @@ import * as path from "path";
 import matter from "gray-matter";
 import { spawnSync } from "child_process";
 import { fileURLToPath } from "url";
-var REQUIRED_HOOK_EVENTS = ["gateway:startup", "command:new", "session:start"];
-var REQUIRED_HOOK_BIN = "clawvault";
 function readOptionalFile(filePath) {
   try {
     if (!fs.existsSync(filePath)) return null;
@@ -24,19 +22,6 @@ function findPackageRoot() {
   }
   return path.dirname(fileURLToPath(import.meta.url));
 }
-function resolveOpenClawHooksDir() {
-  const candidates = [
-    path.join(process.env.HOME || "", ".openclaw", "hooks", "clawvault"),
-    path.join(process.env.OPENCLAW_HOME || "", "hooks", "clawvault"),
-    path.join(process.env.OPENCLAW_STATE_DIR || "", "hooks", "clawvault")
-  ].filter((p) => p && !p.startsWith(path.sep + "hooks"));
-  for (const candidate of candidates) {
-    if (fs.existsSync(candidate)) {
-      return candidate;
-    }
-  }
-  return null;
-}
 function resolveProjectFile(relativePath, baseDir) {
   if (baseDir) {
     return path.resolve(baseDir, relativePath);
@@ -45,20 +30,6 @@ function resolveProjectFile(relativePath, baseDir) {
   if (fs.existsSync(fromCwd)) {
     return fromCwd;
   }
-  if (relativePath.startsWith("hooks/clawvault/")) {
-    const hooksDir = resolveOpenClawHooksDir();
-    if (hooksDir) {
-      const hookRelative = relativePath.replace("hooks/clawvault/", "");
-      const fromHooks = path.resolve(hooksDir, hookRelative);
-      if (fs.existsSync(fromHooks)) {
-        return fromHooks;
-      }
-      const fromNestedHooks = path.resolve(hooksDir, "hooks", "clawvault", hookRelative);
-      if (fs.existsSync(fromNestedHooks)) {
-        return fromNestedHooks;
-      }
-    }
-  }
   return path.resolve(findPackageRoot(), relativePath);
 }
 function checkOpenClawCli() {
@@ -68,7 +39,7 @@ function checkOpenClawCli() {
       label: "openclaw CLI available",
       status: "warn",
       detail: "openclaw binary not found",
-      hint: "Install OpenClaw CLI to enable hook runtime validation."
+      hint: "Install OpenClaw CLI to enable plugin runtime validation."
     };
   }
   if (typeof result.status === "number" && result.status !== 0) {
@@ -89,152 +60,106 @@ function checkOpenClawCli() {
   }
   return { label: "openclaw CLI available", status: "ok" };
 }
-function checkPackageHookRegistration(options) {
-  let packageRaw = readOptionalFile(resolveProjectFile("package.json", options.baseDir));
-  if (packageRaw && !options.baseDir) {
-    try {
-      const parsed = JSON.parse(packageRaw);
-      if (!parsed.openclaw?.hooks) {
-        const fallbackPath = path.resolve(findPackageRoot(), "package.json");
-        const fallbackRaw = readOptionalFile(fallbackPath);
-        if (fallbackRaw) packageRaw = fallbackRaw;
-      }
-    } catch {
-    }
-  }
-  if (!packageRaw) {
+function checkPluginManifest(options) {
+  const manifestRaw = readOptionalFile(
+    resolveProjectFile("openclaw.plugin.json", options.baseDir)
+  );
+  if (!manifestRaw) {
     return {
-      label: "package hook registration",
+      label: "plugin manifest",
       status: "error",
-      detail: "package.json not found"
+      detail: "openclaw.plugin.json not found",
+      hint: "Create openclaw.plugin.json with id, kind, and configSchema fields."
     };
   }
   try {
-    const parsed = JSON.parse(packageRaw);
-    const registeredHooks = parsed.openclaw?.hooks ?? [];
-    if (registeredHooks.includes("./hooks/clawvault")) {
+    const manifest = JSON.parse(manifestRaw);
+    const issues = [];
+    if (!manifest.id) issues.push("missing id");
+    if (!manifest.kind) issues.push("missing kind");
+    if (!manifest.configSchema) issues.push("missing configSchema");
+    if (issues.length > 0) {
       return {
-        label: "package hook registration",
-        status: "ok",
-        detail: "./hooks/clawvault"
+        label: "plugin manifest",
+        status: "error",
+        detail: issues.join(", ")
       };
     }
     return {
-      label: "package hook registration",
-      status: "error",
-      detail: "Missing ./hooks/clawvault in package openclaw.hooks"
+      label: "plugin manifest",
+      status: "ok",
+      detail: `id=${manifest.id} kind=${manifest.kind}`
     };
   } catch (err) {
     return {
-      label: "package hook registration",
+      label: "plugin manifest",
       status: "error",
-      detail: err?.message || "Unable to parse package.json"
+      detail: err?.message || "Unable to parse openclaw.plugin.json"
     };
   }
 }
-function checkHookManifest(options) {
-  const hookRaw = readOptionalFile(resolveProjectFile("hooks/clawvault/HOOK.md", options.baseDir));
-  if (!hookRaw) {
+function checkPluginExtensions(options) {
+  let packageRaw = readOptionalFile(
+    resolveProjectFile("package.json", options.baseDir)
+  );
+  if (packageRaw && !options.baseDir) {
+    try {
+      const parsed = JSON.parse(packageRaw);
+      if (!parsed.openclaw?.extensions) {
+        const fallbackPath = path.resolve(findPackageRoot(), "package.json");
+        const fallbackRaw = readOptionalFile(fallbackPath);
+        if (fallbackRaw) packageRaw = fallbackRaw;
+      }
+    } catch {
+    }
+  }
+  if (!packageRaw) {
     return {
-      label: "hook manifest",
+      label: "plugin extensions registration",
       status: "error",
-      detail: "HOOK.md not found"
+      detail: "package.json not found"
     };
   }
   try {
-    const parsed = matter(hookRaw);
-    const openclaw = parsed.data?.metadata?.openclaw;
-    const events = Array.isArray(openclaw?.events) ? openclaw?.events ?? [] : [];
-    const missingEvents = REQUIRED_HOOK_EVENTS.filter((event) => !events.includes(event));
-    if (missingEvents.length === 0) {
+    const parsed = JSON.parse(packageRaw);
+    const extensions = parsed.openclaw?.extensions ?? [];
+    if (extensions.length === 0) {
       return {
-        label: "hook manifest events",
-        status: "ok",
-        detail: events.join(", ")
+        label: "plugin extensions registration",
+        status: "error",
+        detail: "Missing openclaw.extensions in package.json",
+        hint: 'Add openclaw.extensions: ["./dist/plugin/index.js"] to package.json.'
       };
     }
-    return {
-      label: "hook manifest events",
-      status: "error",
-      detail: `Missing events: ${missingEvents.join(", ")}`
-    };
-  } catch (err) {
-    return {
-      label: "hook manifest events",
-      status: "error",
-      detail: err?.message || "Unable to parse HOOK.md frontmatter"
-    };
-  }
-}
-function checkHookManifestRequirements(options) {
-  const hookRaw = readOptionalFile(resolveProjectFile("hooks/clawvault/HOOK.md", options.baseDir));
-  if (!hookRaw) {
-    return {
-      label: "hook manifest requirements",
-      status: "error",
-      detail: "HOOK.md not found"
-    };
-  }
-  try {
-    const parsed = matter(hookRaw);
-    const requiresBins = parsed.data?.metadata?.openclaw?.requires?.bins;
-    const bins = Array.isArray(requiresBins) ? requiresBins : [];
-    if (bins.includes(REQUIRED_HOOK_BIN)) {
+    const baseDir = options.baseDir || findPackageRoot();
+    const missing = extensions.filter(
+      (ext) => !fs.existsSync(path.resolve(baseDir, ext))
+    );
+    if (missing.length > 0) {
       return {
-        label: "hook manifest requirements",
-        status: "ok",
-        detail: `bins: ${bins.join(", ")}`
+        label: "plugin extensions registration",
+        status: "error",
+        detail: `Entry file(s) not found: ${missing.join(", ")}`,
+        hint: "Run npm run build to generate dist files."
       };
     }
     return {
-      label: "hook manifest requirements",
-      status: "warn",
-      detail: `Missing required hook bin "${REQUIRED_HOOK_BIN}"`,
-      hint: 'Add metadata.openclaw.requires.bins: ["clawvault"] to hooks/clawvault/HOOK.md.'
+      label: "plugin extensions registration",
+      status: "ok",
+      detail: extensions.join(", ")
     };
   } catch (err) {
     return {
-      label: "hook manifest requirements",
-      status: "error",
-      detail: err?.message || "Unable to parse HOOK.md frontmatter"
-    };
-  }
-}
-function checkHookHandlerSafety(options) {
-  const handlerRaw = readOptionalFile(resolveProjectFile("hooks/clawvault/handler.js", options.baseDir));
-  if (!handlerRaw) {
-    return {
-      label: "hook handler script",
+      label: "plugin extensions registration",
       status: "error",
-      detail: "handler.js not found"
-    };
-  }
-  const usesExecFileSync = handlerRaw.includes("execFileSync");
-  const usesExecSync = /\bexecSync\b/.test(handlerRaw);
-  const enablesShell = /\bshell\s*:\s*true\b/.test(handlerRaw);
-  const delegatesAutoProfile = /['"]--profile['"]\s*,\s*['"]auto['"]/.test(handlerRaw);
-  const violations = [];
-  if (!usesExecFileSync || usesExecSync) {
-    violations.push("execFileSync-only execution path");
-  }
-  if (enablesShell) {
-    violations.push("shell:false execution option");
-  }
-  if (!delegatesAutoProfile) {
-    violations.push("shared context profile delegation (--profile auto)");
-  }
-  if (violations.length > 0) {
-    return {
-      label: "hook handler safety",
-      status: "warn",
-      detail: `Missing conventions: ${violations.join(", ")}`,
-      hint: "Use execFileSync (no shell), avoid execSync, and delegate profile inference via --profile auto."
+      detail: err?.message || "Unable to parse package.json"
     };
   }
-  return { label: "hook handler safety", status: "ok" };
 }
 function checkSkillMetadata(options) {
-  const skillRaw = readOptionalFile(resolveProjectFile("SKILL.md", options.baseDir));
+  const skillRaw = readOptionalFile(
+    resolveProjectFile("SKILL.md", options.baseDir)
+  );
   if (!skillRaw) {
     return {
       label: "skill metadata",
@@ -273,10 +198,8 @@ function checkSkillMetadata(options) {
 function checkOpenClawCompatibility(options = {}) {
   const checks = [
     checkOpenClawCli(),
-    checkPackageHookRegistration(options),
-    checkHookManifest(options),
-    checkHookManifestRequirements(options),
-    checkHookHandlerSafety(options),
+    checkPluginManifest(options),
+    checkPluginExtensions(options),
     checkSkillMetadata(options)
   ];
   const warnings = checks.filter((check) => check.status === "warn").length;
@@ -296,7 +219,9 @@ function formatCompatibilityReport(report) {
   lines.push("");
   for (const check of report.checks) {
     const prefix = check.status === "ok" ? "\u2713" : check.status === "warn" ? "\u26A0" : "\u2717";
-    lines.push(`${prefix} ${check.label}${check.detail ? ` \u2014 ${check.detail}` : ""}`);
+    lines.push(
+      `${prefix} ${check.label}${check.detail ? ` \u2014 ${check.detail}` : ""}`
+    );
     if (check.hint) {
       lines.push(`  ${check.hint}`);
     }