clawvault 3.1.0 → 3.2.0

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-VSL7KY3M.js";
+import {
+  store_exports
+} from "../chunk-QVEERJSP.js";
+import {
+  ledger_exports
+} from "../chunk-4BQTQMJP.js";
+import {
+  registry_exports
+} from "../chunk-MM6QGW3P.js";
+import {
+  THREAD_STATUS_TRANSITIONS
+} from "../chunk-WMGIIABP.js";
+import "../chunk-2ZDO52B4.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-4BQTQMJP.js";
+import "../chunk-2ZDO52B4.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-MM6QGW3P.js";
+import "../chunk-2ZDO52B4.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-QVEERJSP.js";
+import "../chunk-4BQTQMJP.js";
+import "../chunk-MM6QGW3P.js";
+import "../chunk-2ZDO52B4.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-VSL7KY3M.js";
+import "../chunk-QVEERJSP.js";
+import "../chunk-4BQTQMJP.js";
+import "../chunk-MM6QGW3P.js";
+import "../chunk-WMGIIABP.js";
+import "../chunk-2ZDO52B4.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-2ZDO52B4.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.entries.clawvault.config.vaultPath ~/my-vault
+
+# View current config
+openclaw config get plugins.entries.clawvault
+```
+
+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.entries.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`.