clawvault 3.1.0 → 3.2.1

package/dist/registry-BR4326o0.d.ts

@@ -0,0 +1,30 @@
+import { FieldDefinition, PrimitiveTypeDefinition, Registry } from './workgraph/types.js';
+
+/**
+ * Dynamic primitive type registry.
+ *
+ * Agents can define new primitive types at runtime. The registry is stored
+ * as `.clawvault/registry.json` in the vault. Built-in types are seeded on
+ * first access and cannot be deleted (but CAN be extended with new fields).
+ */
+
+declare function registryPath(vaultPath: string): string;
+declare function loadRegistry(vaultPath: string): Registry;
+declare function saveRegistry(vaultPath: string, registry: Registry): void;
+declare function defineType(vaultPath: string, name: string, description: string, fields: Record<string, FieldDefinition>, actor: string, directory?: string): PrimitiveTypeDefinition;
+declare function getType(vaultPath: string, name: string): PrimitiveTypeDefinition | undefined;
+declare function listTypes(vaultPath: string): PrimitiveTypeDefinition[];
+declare function extendType(vaultPath: string, name: string, newFields: Record<string, FieldDefinition>, actor: string): PrimitiveTypeDefinition;
+
+declare const registry_defineType: typeof defineType;
+declare const registry_extendType: typeof extendType;
+declare const registry_getType: typeof getType;
+declare const registry_listTypes: typeof listTypes;
+declare const registry_loadRegistry: typeof loadRegistry;
+declare const registry_registryPath: typeof registryPath;
+declare const registry_saveRegistry: typeof saveRegistry;
+declare namespace registry {
+  export { registry_defineType as defineType, registry_extendType as extendType, registry_getType as getType, registry_listTypes as listTypes, registry_loadRegistry as loadRegistry, registry_registryPath as registryPath, registry_saveRegistry as saveRegistry };
+}
+
+export { loadRegistry as a, registryPath as b, defineType as d, extendType as e, getType as g, listTypes as l, registry as r, saveRegistry as s };

package/dist/store-CA-6sKCJ.d.ts

@@ -0,0 +1,34 @@
+import { PrimitiveInstance } from './workgraph/types.js';
+
+/**
+ * Workgraph store — CRUD for primitive instances.
+ *
+ * Primitives are markdown files with YAML frontmatter. The store reads/writes
+ * them and logs every mutation to the ledger. Schemas are soft: unknown fields
+ * are preserved, missing optional fields get defaults.
+ */
+
+declare function create(vaultPath: string, typeName: string, fields: Record<string, unknown>, body: string, actor: string): PrimitiveInstance;
+declare function read(vaultPath: string, relPath: string): PrimitiveInstance | null;
+declare function list(vaultPath: string, typeName: string): PrimitiveInstance[];
+declare function update(vaultPath: string, relPath: string, fieldUpdates: Record<string, unknown>, bodyUpdate: string | undefined, actor: string): PrimitiveInstance;
+declare function remove(vaultPath: string, relPath: string, actor: string): void;
+declare function findByField(vaultPath: string, typeName: string, field: string, value: unknown): PrimitiveInstance[];
+declare function openThreads(vaultPath: string): PrimitiveInstance[];
+declare function activeThreads(vaultPath: string): PrimitiveInstance[];
+declare function blockedThreads(vaultPath: string): PrimitiveInstance[];
+
+declare const store_activeThreads: typeof activeThreads;
+declare const store_blockedThreads: typeof blockedThreads;
+declare const store_create: typeof create;
+declare const store_findByField: typeof findByField;
+declare const store_list: typeof list;
+declare const store_openThreads: typeof openThreads;
+declare const store_read: typeof read;
+declare const store_remove: typeof remove;
+declare const store_update: typeof update;
+declare namespace store {
+  export { store_activeThreads as activeThreads, store_blockedThreads as blockedThreads, store_create as create, store_findByField as findByField, store_list as list, store_openThreads as openThreads, store_read as read, store_remove as remove, store_update as update };
+}
+
+export { activeThreads as a, blockedThreads as b, create as c, remove as d, findByField as f, list as l, openThreads as o, read as r, store as s, update as u };

package/dist/thread-B9LhXNU0.d.ts

@@ -0,0 +1,41 @@
+import { PrimitiveInstance } from './workgraph/types.js';
+
+/**
+ * Thread lifecycle operations.
+ *
+ * Threads are the core coordination primitive. This module handles the
+ * claim/release/block/done lifecycle with ledger-backed exclusivity.
+ */
+
+declare function createThread(vaultPath: string, title: string, goal: string, actor: string, opts?: {
+    priority?: string;
+    deps?: string[];
+    parent?: string;
+    context_refs?: string[];
+    tags?: string[];
+}): PrimitiveInstance;
+declare function claim(vaultPath: string, threadPath: string, actor: string): PrimitiveInstance;
+declare function release(vaultPath: string, threadPath: string, actor: string, reason?: string): PrimitiveInstance;
+declare function block(vaultPath: string, threadPath: string, actor: string, blockedBy: string, reason?: string): PrimitiveInstance;
+declare function unblock(vaultPath: string, threadPath: string, actor: string): PrimitiveInstance;
+declare function done(vaultPath: string, threadPath: string, actor: string, output?: string): PrimitiveInstance;
+declare function cancel(vaultPath: string, threadPath: string, actor: string, reason?: string): PrimitiveInstance;
+declare function decompose(vaultPath: string, parentPath: string, subthreads: Array<{
+    title: string;
+    goal: string;
+    deps?: string[];
+}>, actor: string): PrimitiveInstance[];
+
+declare const thread_block: typeof block;
+declare const thread_cancel: typeof cancel;
+declare const thread_claim: typeof claim;
+declare const thread_createThread: typeof createThread;
+declare const thread_decompose: typeof decompose;
+declare const thread_done: typeof done;
+declare const thread_release: typeof release;
+declare const thread_unblock: typeof unblock;
+declare namespace thread {
+  export { thread_block as block, thread_cancel as cancel, thread_claim as claim, thread_createThread as createThread, thread_decompose as decompose, thread_done as done, thread_release as release, thread_unblock as unblock };
+}
+
+export { claim as a, block as b, cancel as c, createThread as d, decompose as e, done as f, release as r, thread as t, unblock as u };

package/dist/{types-Y2_Um2Ls.d.ts → types-BbWJoC1c.d.ts}

@@ -70,49 +70,6 @@ interface SearchOptions {
     fullContent?: boolean;
     /** Boost recent documents in ranking */
     temporalBoost?: boolean;
-    /**
-     * v2.7 — Enable chunk-level BM25 pre-filtering before semantic search.
-     * Chunks documents into ~600-char sentence windows and ranks chunks by
-     * keyword overlap so that relevant content deep in long documents isn't
-     * silently dropped by fixed-N embedding limits.
-     */
-    chunkPrefilter?: boolean;
-    /**
-     * v2.7 — Exhaustive threshold-based retrieval for aggregation queries.
-     * Instead of a fixed top_k, keeps pulling results until the normalised
-     * relevance score drops below this threshold (0-1).  Set to e.g. 0.01
-     * for aggregation / "list all" queries.  Overrides `limit` when set.
-     */
-    relevanceThreshold?: number;
-    /**
-     * v2.7 — Maximum results when using relevanceThreshold.
-     * Prevents runaway result sets. Default 40.
-     */
-    thresholdMaxResults?: number;
-}
-/**
- * v2.7 — A date reference extracted from document content at ingest time.
- */
-interface ExtractedDate {
-    /** ISO date string (YYYY-MM-DD) or "duration:<value>" */
-    date: string;
-    /** Surrounding context snippet (~150 chars) */
-    context: string;
-    /** Document id the date was extracted from */
-    documentId: string;
-}
-/**
- * v2.7 — An extracted user preference from conversation content.
- */
-interface ExtractedPreference {
-    /** The preference category (tool, hobby, brand, etc.) */
-    category: string;
-    /** The preference value */
-    value: string;
-    /** Document id it was extracted from */
-    documentId: string;
-    /** Surrounding context snippet */
-    context: string;
 }
 interface StoreOptions {
     /** Category to store in */
@@ -202,4 +159,4 @@ interface SessionRecap {
 }
 declare const DEFAULT_CONFIG: Partial<VaultConfig>;
 
-export { type Category as C, type Document as D, type ExtractedDate as E, type HandoffDocument as H, type MemoryType as M, type StoreOptions as S, TYPE_TO_CATEGORY as T, type VaultConfig as V, type SearchOptions as a, type SearchResult as b, type SyncOptions as c, type SyncResult as d, type SessionRecap as e, type ExtractedPreference as f, DEFAULT_CATEGORIES as g, DEFAULT_CONFIG as h, MEMORY_TYPES as i, type VaultMeta as j };
+export { type Category as C, type Document as D, type HandoffDocument as H, type MemoryType as M, type SessionRecap as S, TYPE_TO_CATEGORY as T, type VaultConfig as V, type StoreOptions as a, type SearchOptions as b, type SearchResult as c, type SyncOptions as d, type SyncResult as e, DEFAULT_CATEGORIES as f, DEFAULT_CONFIG as g, MEMORY_TYPES as h, type VaultMeta as i };

package/dist/workgraph/index.d.ts

@@ -0,0 +1,5 @@
+export { FieldDefinition, LedgerEntry, LedgerOp, PrimitiveInstance, PrimitiveTypeDefinition, Registry, THREAD_STATUS_TRANSITIONS, ThreadStatus } from './types.js';
+export { r as registry } from '../registry-BR4326o0.js';
+export { l as ledger } from '../ledger-B7g7jhqG.js';
+export { s as store } from '../store-CA-6sKCJ.js';
+export { t as thread } from '../thread-B9LhXNU0.js';

package/dist/workgraph/index.js

@@ -0,0 +1,23 @@
+import {
+  thread_exports
+} from "../chunk-ERNE2FZ5.js";
+import {
+  store_exports
+} from "../chunk-HR4KN6S2.js";
+import {
+  ledger_exports
+} from "../chunk-K7PNYS45.js";
+import {
+  registry_exports
+} from "../chunk-NTOPJI7W.js";
+import {
+  THREAD_STATUS_TRANSITIONS
+} from "../chunk-WMGIIABP.js";
+import "../chunk-U67V476Y.js";
+export {
+  THREAD_STATUS_TRANSITIONS,
+  ledger_exports as ledger,
+  registry_exports as registry,
+  store_exports as store,
+  thread_exports as thread
+};

package/dist/workgraph/ledger.d.ts

@@ -0,0 +1,2 @@
+import './types.js';
+export { a as activityOf, b as allClaims, c as append, d as currentOwner, h as historyOf, i as isClaimed, e as ledgerPath, r as readAll, f as readSince, g as recent } from '../ledger-B7g7jhqG.js';

package/dist/workgraph/ledger.js

@@ -0,0 +1,25 @@
+import {
+  activityOf,
+  allClaims,
+  append,
+  currentOwner,
+  historyOf,
+  isClaimed,
+  ledgerPath,
+  readAll,
+  readSince,
+  recent
+} from "../chunk-K7PNYS45.js";
+import "../chunk-U67V476Y.js";
+export {
+  activityOf,
+  allClaims,
+  append,
+  currentOwner,
+  historyOf,
+  isClaimed,
+  ledgerPath,
+  readAll,
+  readSince,
+  recent
+};

package/dist/workgraph/registry.d.ts

@@ -0,0 +1,2 @@
+import './types.js';
+export { d as defineType, e as extendType, g as getType, l as listTypes, a as loadRegistry, b as registryPath, s as saveRegistry } from '../registry-BR4326o0.js';

package/dist/workgraph/registry.js

@@ -0,0 +1,19 @@
+import {
+  defineType,
+  extendType,
+  getType,
+  listTypes,
+  loadRegistry,
+  registryPath,
+  saveRegistry
+} from "../chunk-NTOPJI7W.js";
+import "../chunk-U67V476Y.js";
+export {
+  defineType,
+  extendType,
+  getType,
+  listTypes,
+  loadRegistry,
+  registryPath,
+  saveRegistry
+};

package/dist/workgraph/store.d.ts

@@ -0,0 +1,2 @@
+import './types.js';
+export { a as activeThreads, b as blockedThreads, c as create, f as findByField, l as list, o as openThreads, r as read, d as remove, u as update } from '../store-CA-6sKCJ.js';

package/dist/workgraph/store.js

@@ -0,0 +1,25 @@
+import {
+  activeThreads,
+  blockedThreads,
+  create,
+  findByField,
+  list,
+  openThreads,
+  read,
+  remove,
+  update
+} from "../chunk-HR4KN6S2.js";
+import "../chunk-K7PNYS45.js";
+import "../chunk-NTOPJI7W.js";
+import "../chunk-U67V476Y.js";
+export {
+  activeThreads,
+  blockedThreads,
+  create,
+  findByField,
+  list,
+  openThreads,
+  read,
+  remove,
+  update
+};

package/dist/workgraph/thread.d.ts

@@ -0,0 +1,2 @@
+import './types.js';
+export { b as block, c as cancel, a as claim, d as createThread, e as decompose, f as done, r as release, u as unblock } from '../thread-B9LhXNU0.js';

package/dist/workgraph/thread.js

@@ -0,0 +1,25 @@
+import {
+  block,
+  cancel,
+  claim,
+  createThread,
+  decompose,
+  done,
+  release,
+  unblock
+} from "../chunk-ERNE2FZ5.js";
+import "../chunk-HR4KN6S2.js";
+import "../chunk-K7PNYS45.js";
+import "../chunk-NTOPJI7W.js";
+import "../chunk-WMGIIABP.js";
+import "../chunk-U67V476Y.js";
+export {
+  block,
+  cancel,
+  claim,
+  createThread,
+  decompose,
+  done,
+  release,
+  unblock
+};

package/dist/workgraph/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Workgraph type definitions.
+ *
+ * Three layers:
+ *   1. Registry  — what primitive types exist (agent-extensible)
+ *   2. Ledger    — what happened (append-only, source of truth for claims/state)
+ *   3. Store     — the actual markdown files (the primitives themselves)
+ */
+interface FieldDefinition {
+    type: 'string' | 'number' | 'boolean' | 'list' | 'date' | 'ref' | 'any';
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+}
+interface PrimitiveTypeDefinition {
+    name: string;
+    description: string;
+    fields: Record<string, FieldDefinition>;
+    /** Directory under vault root where instances live (default: `<name>s/`). */
+    directory: string;
+    /** Whether this type was defined by an agent at runtime vs built-in. */
+    builtIn: boolean;
+    /** ISO timestamp of when this type was registered. */
+    createdAt: string;
+    /** Who registered it (agent name or "system"). */
+    createdBy: string;
+}
+interface Registry {
+    version: number;
+    types: Record<string, PrimitiveTypeDefinition>;
+}
+type LedgerOp = 'create' | 'update' | 'delete' | 'claim' | 'release' | 'block' | 'unblock' | 'done' | 'cancel' | 'define' | 'decompose';
+interface LedgerEntry {
+    ts: string;
+    actor: string;
+    op: LedgerOp;
+    target: string;
+    type?: string;
+    data?: Record<string, unknown>;
+}
+type ThreadStatus = 'open' | 'active' | 'blocked' | 'done' | 'cancelled';
+declare const THREAD_STATUS_TRANSITIONS: Record<ThreadStatus, ThreadStatus[]>;
+interface PrimitiveInstance {
+    /** File path relative to vault root. */
+    path: string;
+    /** Primitive type name. */
+    type: string;
+    /** Frontmatter fields. */
+    fields: Record<string, unknown>;
+    /** Markdown body content. */
+    body: string;
+}
+
+export { type FieldDefinition, type LedgerEntry, type LedgerOp, type PrimitiveInstance, type PrimitiveTypeDefinition, type Registry, THREAD_STATUS_TRANSITIONS, type ThreadStatus };

package/dist/workgraph/types.js

@@ -0,0 +1,7 @@
+import {
+  THREAD_STATUS_TRANSITIONS
+} from "../chunk-WMGIIABP.js";
+import "../chunk-U67V476Y.js";
+export {
+  THREAD_STATUS_TRANSITIONS
+};

package/hooks/clawvault/HOOK.md

@@ -0,0 +1,113 @@
+---
+name: clawvault
+description: "Context resilience - recovery detection, auto-checkpoint, and session context injection"
+metadata:
+  openclaw:
+    emoji: "🐘"
+    events: ["gateway:startup", "gateway:heartbeat", "command:new", "session:start", "compaction:memoryFlush", "cron.weekly"]
+    requires:
+      bins: ["clawvault"]
+---
+
+# ClawVault Hook
+
+Integrates ClawVault's context death resilience into OpenClaw:
+
+- **On gateway startup**: Checks for context death, alerts agent
+- **On heartbeat**: Runs cheap threshold checks and observes active sessions when needed
+- **On /new command**: Auto-checkpoints before session reset
+- **On context compaction**: Forces incremental observation flush before context is lost
+- **On session start**: Injects relevant vault context for the initial prompt
+- **On weekly cron**: Runs `clawvault reflect` every Sunday midnight (UTC)
+
+## Installation
+
+```bash
+npm install -g clawvault
+openclaw hooks install clawvault
+openclaw hooks enable clawvault
+
+# Verify
+openclaw hooks list --verbose
+openclaw hooks info clawvault
+openclaw hooks check
+```
+
+After enabling, restart your OpenClaw gateway process so hook registration reloads.
+
+## Requirements
+
+- ClawVault CLI installed globally
+- Vault initialized (`clawvault setup` or `CLAWVAULT_PATH` set)
+
+## What It Does
+
+### Gateway Startup
+
+1. Runs `clawvault recover --clear`
+2. If context death detected, injects warning into first agent turn
+3. Clears dirty death flag for clean session start
+
+### Command: /new
+
+1. Creates automatic checkpoint with session info
+2. Captures state even if agent forgot to handoff
+3. Ensures continuity across session resets
+
+### Session Start
+
+1. Extracts the initial user prompt (`context.initialPrompt` or first user message)
+2. Runs `clawvault context "<prompt>" --format json --profile auto -v <vaultPath>`
+   - Delegates profile selection to the shared context intent policy (`incident`, `planning`, `handoff`, or `default`)
+3. Injects up to 4 relevant context bullets into session messages
+
+Injection format:
+
+```text
+[ClawVault] Relevant context for this task:
+- <title> (<age>): <snippet>
+- <title> (<age>): <snippet>
+```
+
+### Event Compatibility
+
+The hook accepts canonical OpenClaw events (`gateway:startup`, `gateway:heartbeat`, `command:new`, `session:start`, `compaction:memoryFlush`, `cron.weekly`) and tolerates alias payload shapes (`event`, `eventName`, `name`, `hook`, `trigger`) to remain robust across runtime wrappers.
+
+## Configuration
+
+### Plugin Configuration (Recommended)
+
+Configure the plugin via OpenClaw's config system:
+
+```bash
+# Set vault path
+openclaw config set plugins.clawvault.config.vaultPath ~/my-vault
+
+# View current config
+openclaw config get plugins.clawvault.config
+```
+
+Available configuration options:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `vaultPath` | string | (auto-detected) | Path to the ClawVault vault directory |
+| `autoCheckpoint` | boolean | `true` | Enable automatic checkpointing on session events |
+| `contextProfile` | string | `"auto"` | Default context profile (`default`, `planning`, `incident`, `handoff`, `auto`) |
+| `maxContextResults` | integer | `4` | Maximum context results to inject on session start |
+| `observeOnHeartbeat` | boolean | `true` | Enable observation threshold checks on heartbeat |
+| `weeklyReflection` | boolean | `true` | Enable weekly reflection on Sunday midnight UTC |
+
+### Vault Path Resolution
+
+The hook resolves the vault path in this order:
+
+1. Plugin config (`plugins.clawvault.config.vaultPath` set via `openclaw config`)
+2. `OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH` environment variable
+3. `CLAWVAULT_PATH` environment variable
+4. Walking up from cwd to find `.clawvault.json`
+5. Checking `memory/` subdirectory (OpenClaw convention)
+
+### Troubleshooting
+
+If `openclaw hooks enable clawvault` fails with hook-not-found, run `openclaw hooks install clawvault` first and verify discovery with `openclaw hooks list --verbose`.