clawvault 2.6.1 → 2.6.3

package/README.md

@@ -6,6 +6,8 @@ Structured memory system for AI agents and operators: typed markdown memory, gra
 
 > Local-first. Markdown-first. Built to survive long-running autonomous work.
 
+**$CLAW**: [`5Fjr82MTB8mvxkzi9FYtvrUsPiDGE2M29w3dYcZpump`](https://pump.fun/coin/5Fjr82MTB8mvxkzi9FYtvrUsPiDGE2M29w3dYcZpump)
+
 ## Requirements
 
 - Node.js 18+

package/dist/{chunk-TLGBDTYT.js → chunk-6546Q4OR.js}

@@ -9,7 +9,7 @@ import {
 } from "./chunk-3BTHWPMB.js";
 import {
   registerContextCommand
-} from "./chunk-XAVB4GB4.js";
+} from "./chunk-DTEHFAL7.js";
 import {
   registerEmbedCommand
 } from "./chunk-4QYGFWRM.js";

package/dist/{chunk-XAVB4GB4.js → chunk-DTEHFAL7.js}

@@ -1,6 +1,6 @@
 import {
   ClawVault
-} from "./chunk-KL4NAOMO.js";
+} from "./chunk-RCBMXTWS.js";
 import {
   parseObservationMarkdown
 } from "./chunk-FHFUXL6G.js";

package/dist/{chunk-UEOUADMO.js → chunk-PZ2AUU2W.js}

@@ -10,7 +10,7 @@ import {
 import {
   ClawVault,
   findVault
-} from "./chunk-KL4NAOMO.js";
+} from "./chunk-RCBMXTWS.js";
 import {
   hasQmd
 } from "./chunk-MAKNAHAW.js";

package/dist/{chunk-KL4NAOMO.js → chunk-RCBMXTWS.js}

@@ -624,14 +624,15 @@ var ClawVault = class {
       md += `## Recent Sessions
 `;
       for (const h of recap.recentHandoffs) {
+        const datePart = this.extractDatePart(h.created);
         if (brief) {
-          md += `- **${h.created.split("T")[0]}:** ${h.workingOn.slice(0, 2).join(", ")}`;
+          md += `- **${datePart}:** ${h.workingOn.slice(0, 2).join(", ")}`;
           if (h.nextSteps.length > 0) md += ` \u2192 ${h.nextSteps[0]}`;
           md += `
 `;
         } else {
           md += `
-### ${h.created.split("T")[0]}
+### ${datePart}
 `;
           md += `**Working on:** ${h.workingOn.join(", ")}
 `;
@@ -689,7 +690,7 @@ var ClawVault = class {
    */
   parseHandoff(doc) {
     return {
-      created: doc.frontmatter.date || doc.modified.toISOString(),
+      created: this.toDateString(doc.frontmatter.date, doc.modified.toISOString()),
       sessionKey: doc.frontmatter.sessionKey,
       workingOn: doc.frontmatter.workingOn || [],
       blocked: doc.frontmatter.blocked || [],
@@ -700,6 +701,30 @@ var ClawVault = class {
     };
   }
   // === Private helpers ===
+  /**
+   * Safely convert a date value to ISO string format.
+   * Handles Date objects, strings, and undefined values.
+   */
+  toDateString(value, fallback) {
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+    return fallback || (/* @__PURE__ */ new Date()).toISOString();
+  }
+  /**
+   * Extract the date portion (YYYY-MM-DD) from an ISO date string or Date object.
+   * Provides safe handling for various date formats.
+   */
+  extractDatePart(value) {
+    const dateStr = this.toDateString(value);
+    if (dateStr.includes("T")) {
+      return dateStr.split("T")[0];
+    }
+    return dateStr.slice(0, 10);
+  }
   applyQmdConfig(meta) {
     const collection = meta?.qmdCollection || this.config.qmdCollection || this.config.name;
     const root = meta?.qmdRoot || this.config.qmdRoot || this.config.path;

package/dist/cli/index.js

@@ -1,6 +1,6 @@
 import {
   registerCliCommands
-} from "../chunk-TLGBDTYT.js";
+} from "../chunk-6546Q4OR.js";
 import "../chunk-THRJVD4L.js";
 import "../chunk-TIGW564L.js";
 import "../chunk-IVRIKYFE.js";
@@ -8,12 +8,12 @@ import "../chunk-ME37YNW3.js";
 import "../chunk-P5EPF6MB.js";
 import "../chunk-3BTHWPMB.js";
 import "../chunk-T76H47ZS.js";
-import "../chunk-XAVB4GB4.js";
+import "../chunk-DTEHFAL7.js";
 import "../chunk-IEVLHNLU.js";
 import "../chunk-HRLWZGMA.js";
 import "../chunk-Q2J5YTUF.js";
 import "../chunk-AZYOKJYC.js";
-import "../chunk-KL4NAOMO.js";
+import "../chunk-RCBMXTWS.js";
 import "../chunk-FHFUXL6G.js";
 import "../chunk-4QYGFWRM.js";
 import "../chunk-MAKNAHAW.js";

package/dist/commands/context.js

@@ -3,8 +3,8 @@ import {
   contextCommand,
   formatContextMarkdown,
   registerContextCommand
-} from "../chunk-XAVB4GB4.js";
-import "../chunk-KL4NAOMO.js";
+} from "../chunk-DTEHFAL7.js";
+import "../chunk-RCBMXTWS.js";
 import "../chunk-FHFUXL6G.js";
 import "../chunk-MAKNAHAW.js";
 import "../chunk-2CDEETQN.js";

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 import {
   doctor
-} from "../chunk-UEOUADMO.js";
+} from "../chunk-PZ2AUU2W.js";
 import "../chunk-7ZRP733D.js";
 import "../chunk-4VQTUVH7.js";
 import "../chunk-J7ZWCI2C.js";
@@ -8,7 +8,7 @@ import "../chunk-IEVLHNLU.js";
 import "../chunk-HRLWZGMA.js";
 import "../chunk-Q2J5YTUF.js";
 import "../chunk-AZYOKJYC.js";
-import "../chunk-KL4NAOMO.js";
+import "../chunk-RCBMXTWS.js";
 import "../chunk-FHFUXL6G.js";
 import "../chunk-MAKNAHAW.js";
 import "../chunk-ITPEXLHA.js";

package/dist/commands/sleep.js

@@ -10,7 +10,7 @@ import {
 import "../chunk-AZYOKJYC.js";
 import {
   ClawVault
-} from "../chunk-KL4NAOMO.js";
+} from "../chunk-RCBMXTWS.js";
 import "../chunk-FHFUXL6G.js";
 import {
   qmdUpdate

package/dist/commands/status.d.ts

@@ -15,6 +15,8 @@ interface VaultStatus {
         collection: string;
         root: string;
         indexStatus: 'present' | 'missing' | 'root-mismatch';
+        files?: number;
+        vectors?: number;
         error?: string;
     };
     graph: {

package/dist/commands/status.js

@@ -13,7 +13,7 @@ import "../chunk-Q2J5YTUF.js";
 import "../chunk-AZYOKJYC.js";
 import {
   ClawVault
-} from "../chunk-KL4NAOMO.js";
+} from "../chunk-RCBMXTWS.js";
 import "../chunk-FHFUXL6G.js";
 import {
   QmdUnavailableError,
@@ -34,6 +34,80 @@ import "../chunk-7766SIJP.js";
 import * as fs from "fs";
 import * as path from "path";
 import { execFileSync } from "child_process";
+
+// src/lib/qmd-collections.ts
+var COLLECTION_HEADER_RE = /^(\S+)\s+\(qmd:\/\/([^)]+)\)\s*$/;
+var DETAIL_LINE_RE = /^\s+([A-Za-z][A-Za-z0-9 _-]*):\s*(.+)\s*$/;
+function normalizeDetailKey(value) {
+  return value.trim().toLowerCase().replace(/[ -]+/g, "_");
+}
+function parseCount(raw) {
+  if (!raw) return void 0;
+  const match = raw.match(/-?\d[\d,]*/);
+  if (!match) return void 0;
+  const parsed = Number.parseInt(match[0].replace(/,/g, ""), 10);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function pickDetail(details, keys) {
+  for (const key of keys) {
+    const value = details[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return void 0;
+}
+function pickCount(details, keys) {
+  for (const key of keys) {
+    const parsed = parseCount(details[key]);
+    if (parsed !== void 0) {
+      return parsed;
+    }
+  }
+  return void 0;
+}
+function parseQmdCollectionList(raw) {
+  const collections = [];
+  let current = null;
+  for (const line of raw.split(/\r?\n/)) {
+    const headerMatch = line.match(COLLECTION_HEADER_RE);
+    if (headerMatch) {
+      current = {
+        name: headerMatch[1],
+        uri: headerMatch[2],
+        details: {}
+      };
+      collections.push(current);
+      continue;
+    }
+    if (!current) continue;
+    const detailMatch = line.match(DETAIL_LINE_RE);
+    if (!detailMatch) continue;
+    const key = normalizeDetailKey(detailMatch[1]);
+    current.details[key] = detailMatch[2].trim();
+  }
+  for (const collection of collections) {
+    const root = pickDetail(collection.details, ["root", "path", "directory"]);
+    if (root) {
+      collection.root = root;
+    }
+    collection.files = pickCount(collection.details, ["files", "documents", "docs"]);
+    collection.vectors = pickCount(collection.details, ["vectors", "embeddings", "vector_embeddings"]);
+    collection.pendingEmbeddings = pickCount(collection.details, [
+      "pending",
+      "pending_vectors",
+      "pending_embeddings",
+      "unembedded",
+      "without_embeddings"
+    ]);
+    if (collection.pendingEmbeddings === void 0 && collection.files !== void 0 && collection.vectors !== void 0) {
+      collection.pendingEmbeddings = Math.max(collection.files - collection.vectors, 0);
+    }
+  }
+  return collections;
+}
+
+// src/commands/status.ts
 var CLAWVAULT_DIR = ".clawvault";
 var CHECKPOINT_FILE = "last-checkpoint.json";
 var DIRTY_DEATH_FLAG = "dirty-death.flag";
@@ -80,22 +154,18 @@ function getLatestVaultMarkdownMtime(vaultPath) {
   walk(vaultPath);
   return latest;
 }
-function parseQmdCollectionsText(raw) {
-  const names = [];
-  const regex = /^(\S+)\s+\(qmd:\/\/\1\/\)/gm;
-  let match;
-  while ((match = regex.exec(raw)) !== null) {
-    names.push(match[1]);
-  }
-  return names;
-}
 function getQmdIndexStatus(collection, root, indexName) {
   const output = execFileSync("qmd", withQmdIndexArgs(["collection", "list"], indexName), { encoding: "utf-8" });
-  const names = parseQmdCollectionsText(output);
-  if (names.includes(collection)) {
-    return "present";
+  const collections = parseQmdCollectionList(output);
+  const collectionInfo = collections.find((c) => c.name === collection);
+  if (collectionInfo) {
+    return {
+      status: "present",
+      files: collectionInfo.files,
+      vectors: collectionInfo.vectors
+    };
   }
-  return "missing";
+  return { status: "missing" };
 }
 function loadCheckpoint(vaultPath) {
   const checkpointPath = path.join(vaultPath, CLAWVAULT_DIR, CHECKPOINT_FILE);
@@ -140,12 +210,12 @@ async function getStatus(vaultPath, options = {}) {
   }
   const qmdCollection = vault.getQmdCollection();
   const qmdRoot = vault.getQmdRoot();
-  let qmdIndexStatus = "missing";
+  let qmdIndexResult = { status: "missing" };
   let qmdError;
   try {
-    qmdIndexStatus = getQmdIndexStatus(qmdCollection, qmdRoot, options.qmdIndexName);
-    if (qmdIndexStatus !== "present") {
-      issues.push(`qmd collection ${qmdIndexStatus.replace("-", " ")}`);
+    qmdIndexResult = getQmdIndexStatus(qmdCollection, qmdRoot, options.qmdIndexName);
+    if (qmdIndexResult.status !== "present") {
+      issues.push(`qmd collection ${qmdIndexResult.status.replace("-", " ")}`);
     }
   } catch (err) {
     qmdError = err?.message || "Failed to check qmd index";
@@ -197,7 +267,9 @@ async function getStatus(vaultPath, options = {}) {
     qmd: {
       collection: qmdCollection,
       root: qmdRoot,
-      indexStatus: qmdIndexStatus,
+      indexStatus: qmdIndexResult.status,
+      files: qmdIndexResult.files,
+      vectors: qmdIndexResult.vectors,
       error: qmdError
     },
     graph: graphStatus,
@@ -256,6 +328,14 @@ function formatStatus(status) {
 `;
   output += `  - Index: ${status.qmd.indexStatus}
 `;
+  if (status.qmd.files !== void 0) {
+    output += `  - Files: ${status.qmd.files}
+`;
+  }
+  if (status.qmd.vectors !== void 0) {
+    output += `  - Vectors: ${status.qmd.vectors}
+`;
+  }
   if (status.qmd.error) {
     output += `  - Error: ${status.qmd.error}
 `;

package/dist/commands/wake.js

@@ -4,7 +4,7 @@ import {
 import "../chunk-7ZRP733D.js";
 import {
   ClawVault
-} from "../chunk-KL4NAOMO.js";
+} from "../chunk-RCBMXTWS.js";
 import {
   parseObservationMarkdown
 } from "../chunk-FHFUXL6G.js";

package/dist/index.d.ts

@@ -157,6 +157,16 @@ declare class ClawVault {
      * Parse a handoff document back into structured form
      */
     private parseHandoff;
+    /**
+     * Safely convert a date value to ISO string format.
+     * Handles Date objects, strings, and undefined values.
+     */
+    private toDateString;
+    /**
+     * Extract the date portion (YYYY-MM-DD) from an ISO date string or Date object.
+     * Provides safe handling for various date formats.
+     */
+    private extractDatePart;
     private applyQmdConfig;
     private slugify;
     private saveIndex;
@@ -300,6 +310,82 @@ declare function extractWikiLinks(content: string): string[];
  */
 declare function extractTags(content: string): string[];
 
+/**
+ * ClawVault Hybrid Search — BM25 + Semantic Embeddings + RRF
+ *
+ * Proven in LongMemEval benchmarks:
+ * - v28 pipeline: 57.0% overall (up from 52.6% with BM25-only)
+ * - Multi-session: 45.9% (up from 28.6%)
+ * - Single-session-user: 85.7% (up from 72.9%)
+ *
+ * Architecture:
+ * 1. BM25 via existing qmd search
+ * 2. Semantic via @huggingface/transformers (all-MiniLM-L6-v2)
+ * 3. Reciprocal Rank Fusion (k=60)
+ */
+
+/**
+ * Compute embedding for a text string
+ */
+declare function embed(text: string): Promise<Float32Array>;
+/**
+ * Compute embeddings for multiple texts
+ */
+declare function embedBatch(texts: string[]): Promise<Float32Array[]>;
+/**
+ * Cosine similarity between two normalized vectors
+ */
+declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+/**
+ * Embedding cache — stores embeddings on disk alongside vault files
+ */
+declare class EmbeddingCache {
+    private cachePath;
+    private cache;
+    private dirty;
+    constructor(vaultPath: string);
+    /**
+     * Load cache from disk
+     */
+    load(): void;
+    /**
+     * Save cache to disk
+     */
+    save(): void;
+    get(key: string): Float32Array | undefined;
+    set(key: string, embedding: Float32Array): void;
+    has(key: string): boolean;
+    entries(): IterableIterator<[string, Float32Array]>;
+    get size(): number;
+}
+/**
+ * Reciprocal Rank Fusion of two ranked lists
+ */
+declare function reciprocalRankFusion(list1: {
+    id: string;
+    score: number;
+}[], list2: {
+    id: string;
+    score: number;
+}[], k?: number): {
+    id: string;
+    score: number;
+}[];
+/**
+ * Semantic search against embedding cache
+ */
+declare function semanticSearch(query: string, cache: EmbeddingCache, topK?: number): Promise<{
+    id: string;
+    score: number;
+}[]>;
+/**
+ * Hybrid search: combines BM25 results with semantic results via RRF
+ */
+declare function hybridSearch(query: string, bm25Results: SearchResult[], cache: EmbeddingCache, options?: {
+    topK?: number;
+    rrfK?: number;
+}): Promise<SearchResult[]>;
+
 declare const OBSERVE_PROVIDERS: readonly ["anthropic", "openai", "gemini"];
 declare const OBSERVER_COMPRESSION_PROVIDERS: readonly ["anthropic", "openai", "gemini", "openai-compatible", "ollama"];
 declare const THEMES: readonly ["neural", "minimal", "none"];
@@ -670,4 +756,4 @@ declare function runReflection(options: ReflectOptions): Promise<ReflectResult>;
 declare const VERSION: string;
 declare function registerCommanderCommands(program: Command): Command;
 
-export { type ActiveObservationCandidate, type ActiveObservationFailure, type ActiveObserveOptions, type ActiveObserveResult, type ArchiveObservationsOptions, type ArchiveObservationsResult, Category, ClawVault, type CompressionProvider, Compressor, type CompressorOptions, type ContextProfile as ConfigDefaultProfile, Document, HandoffDocument, type ManagedConfigKey, MemoryType, type ObserveCursorEntry, type ObserveCursorStore, type ObserveProvider, Observer, type ObserverCompressionProvider, type ObserverCompressor, type ObserverOptions, type ObserverReflector, type ObserverStalenessResult, QMD_INSTALL_COMMAND, QMD_INSTALL_URL, QmdUnavailableError, type ReflectOptions, type ReflectResult, Reflector, type ReflectorOptions, type RouteRule, SUPPORTED_CONFIG_KEYS, SearchEngine, SearchOptions, SearchResult, SessionRecap, SessionWatcher, type SessionWatcherOptions, StoreOptions, SyncOptions, SyncResult, type Theme, type TransitionEvent, VERSION, VaultConfig, addRouteRule, appendTransition, archiveObservations, buildTransitionEvent, countBlockedTransitions, createVault, extractTags, extractWikiLinks, findVault, formatTransitionsTable, getConfig, getConfigValue, getObserverStaleness, getScaledObservationThresholdBytes, hasQmd, isRegression, listConfig, listRouteRules, matchRouteRule, observeActiveSessions, parseSessionFile, parseSessionSourceLabel, qmdEmbed, qmdUpdate, queryTransitions, readAllTransitions, registerCommanderCommands, removeRouteRule, resetConfig, runReflection, setConfigValue, testRouteRule };
+export { type ActiveObservationCandidate, type ActiveObservationFailure, type ActiveObserveOptions, type ActiveObserveResult, type ArchiveObservationsOptions, type ArchiveObservationsResult, Category, ClawVault, type CompressionProvider, Compressor, type CompressorOptions, type ContextProfile as ConfigDefaultProfile, Document, EmbeddingCache, HandoffDocument, type ManagedConfigKey, MemoryType, type ObserveCursorEntry, type ObserveCursorStore, type ObserveProvider, Observer, type ObserverCompressionProvider, type ObserverCompressor, type ObserverOptions, type ObserverReflector, type ObserverStalenessResult, QMD_INSTALL_COMMAND, QMD_INSTALL_URL, QmdUnavailableError, type ReflectOptions, type ReflectResult, Reflector, type ReflectorOptions, type RouteRule, SUPPORTED_CONFIG_KEYS, SearchEngine, SearchOptions, SearchResult, SessionRecap, SessionWatcher, type SessionWatcherOptions, StoreOptions, SyncOptions, SyncResult, type Theme, type TransitionEvent, VERSION, VaultConfig, addRouteRule, appendTransition, archiveObservations, buildTransitionEvent, cosineSimilarity, countBlockedTransitions, createVault, embed, embedBatch, extractTags, extractWikiLinks, findVault, formatTransitionsTable, getConfig, getConfigValue, getObserverStaleness, getScaledObservationThresholdBytes, hasQmd, hybridSearch, isRegression, listConfig, listRouteRules, matchRouteRule, observeActiveSessions, parseSessionFile, parseSessionSourceLabel, qmdEmbed, qmdUpdate, queryTransitions, readAllTransitions, reciprocalRankFusion, registerCommanderCommands, removeRouteRule, resetConfig, runReflection, semanticSearch, setConfigValue, testRouteRule };

package/dist/index.js

@@ -25,7 +25,7 @@ import {
 } from "./chunk-R6SXNSFD.js";
 import {
   doctor
-} from "./chunk-UEOUADMO.js";
+} from "./chunk-PZ2AUU2W.js";
 import "./chunk-7ZRP733D.js";
 import {
   graphCommand,
@@ -45,7 +45,7 @@ import "./chunk-4VQTUVH7.js";
 import "./chunk-J7ZWCI2C.js";
 import {
   registerCliCommands
-} from "./chunk-TLGBDTYT.js";
+} from "./chunk-6546Q4OR.js";
 import {
   registerTailscaleCommands,
   registerTailscaleDiscoverCommand,
@@ -102,7 +102,7 @@ import {
   normalizeContextProfileInput,
   registerContextCommand,
   resolveContextProfile
-} from "./chunk-XAVB4GB4.js";
+} from "./chunk-DTEHFAL7.js";
 import {
   getObserverStaleness,
   getScaledObservationThresholdBytes,
@@ -128,7 +128,7 @@ import {
   ClawVault,
   createVault,
   findVault
-} from "./chunk-KL4NAOMO.js";
+} from "./chunk-RCBMXTWS.js";
 import "./chunk-FHFUXL6G.js";
 import {
   embedCommand,
@@ -220,11 +220,158 @@ import {
 } from "./chunk-QVMXF7FY.js";
 
 // src/index.ts
+import * as fs2 from "fs";
+
+// src/lib/hybrid-search.ts
 import * as fs from "fs";
+import * as path from "path";
+var embeddingPipeline = null;
+var pipelineLoading = null;
+async function getEmbeddingPipeline() {
+  if (embeddingPipeline) return embeddingPipeline;
+  if (pipelineLoading) return pipelineLoading;
+  pipelineLoading = (async () => {
+    const { pipeline } = await import("@huggingface/transformers");
+    embeddingPipeline = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2", {
+      dtype: "fp32"
+    });
+    return embeddingPipeline;
+  })();
+  return pipelineLoading;
+}
+async function embed(text) {
+  const pipe = await getEmbeddingPipeline();
+  const result = await pipe(text, { pooling: "mean", normalize: true });
+  return new Float32Array(result.data);
+}
+async function embedBatch(texts) {
+  const pipe = await getEmbeddingPipeline();
+  const results = [];
+  const batchSize = 32;
+  for (let i = 0; i < texts.length; i += batchSize) {
+    const batch = texts.slice(i, i + batchSize);
+    for (const text of batch) {
+      const result = await pipe(text, { pooling: "mean", normalize: true });
+      results.push(new Float32Array(result.data));
+    }
+  }
+  return results;
+}
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+  }
+  return dot;
+}
+var EmbeddingCache = class {
+  cachePath;
+  cache = /* @__PURE__ */ new Map();
+  dirty = false;
+  constructor(vaultPath) {
+    this.cachePath = path.join(vaultPath, ".clawvault", "embeddings.bin");
+  }
+  /**
+   * Load cache from disk
+   */
+  load() {
+    try {
+      if (!fs.existsSync(this.cachePath)) return;
+      const data = JSON.parse(fs.readFileSync(this.cachePath + ".json", "utf-8"));
+      for (const [key, arr] of Object.entries(data)) {
+        this.cache.set(key, new Float32Array(arr));
+      }
+    } catch {
+    }
+  }
+  /**
+   * Save cache to disk
+   */
+  save() {
+    if (!this.dirty) return;
+    const dir = path.dirname(this.cachePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const data = {};
+    for (const [key, arr] of this.cache.entries()) {
+      data[key] = Array.from(arr);
+    }
+    fs.writeFileSync(this.cachePath + ".json", JSON.stringify(data));
+    this.dirty = false;
+  }
+  get(key) {
+    return this.cache.get(key);
+  }
+  set(key, embedding) {
+    this.cache.set(key, embedding);
+    this.dirty = true;
+  }
+  has(key) {
+    return this.cache.has(key);
+  }
+  entries() {
+    return this.cache.entries();
+  }
+  get size() {
+    return this.cache.size;
+  }
+};
+function reciprocalRankFusion(list1, list2, k = 60) {
+  const scores = /* @__PURE__ */ new Map();
+  for (let rank = 0; rank < list1.length; rank++) {
+    const { id } = list1[rank];
+    scores.set(id, (scores.get(id) || 0) + 1 / (k + rank + 1));
+  }
+  for (let rank = 0; rank < list2.length; rank++) {
+    const { id } = list2[rank];
+    scores.set(id, (scores.get(id) || 0) + 1 / (k + rank + 1));
+  }
+  return Array.from(scores.entries()).map(([id, score]) => ({ id, score })).sort((a, b) => b.score - a.score);
+}
+async function semanticSearch(query, cache, topK = 20) {
+  const queryEmb = await embed(query);
+  const results = [];
+  for (const [id, docEmb] of cache.entries()) {
+    results.push({ id, score: cosineSimilarity(queryEmb, docEmb) });
+  }
+  results.sort((a, b) => b.score - a.score);
+  return results.slice(0, topK);
+}
+async function hybridSearch(query, bm25Results, cache, options = {}) {
+  const { topK = 20, rrfK = 60 } = options;
+  const bm25Ranked = bm25Results.map((r) => ({ id: r.document.path || r.document.id, score: r.score }));
+  const semanticRanked = await semanticSearch(query, cache, topK);
+  const fused = reciprocalRankFusion(bm25Ranked, semanticRanked, rrfK);
+  const bm25Map = new Map(bm25Results.map((r) => [r.document.path || r.document.id, r]));
+  return fused.slice(0, topK).map(({ id, score }) => {
+    const existing = bm25Map.get(id);
+    if (existing) {
+      return { ...existing, score };
+    }
+    const minimalDoc = {
+      id: id.replace(/\.md$/, ""),
+      path: id.endsWith(".md") ? id : id + ".md",
+      title: (id.split("/").pop() || id).replace(/\.md$/, ""),
+      content: "",
+      category: id.split("/")[0] || "root",
+      frontmatter: {},
+      links: [],
+      tags: [],
+      modified: /* @__PURE__ */ new Date()
+    };
+    return {
+      document: minimalDoc,
+      score,
+      snippet: "",
+      matchedTerms: []
+    };
+  });
+}
+
+// src/index.ts
 function readPackageVersion() {
   try {
     const pkgUrl = new URL("../package.json", import.meta.url);
-    const pkg = JSON.parse(fs.readFileSync(pkgUrl, "utf-8"));
+    const pkg = JSON.parse(fs2.readFileSync(pkgUrl, "utf-8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -241,6 +388,7 @@ export {
   DEFAULT_CATEGORIES,
   DEFAULT_CONFIG,
   DEFAULT_SERVE_PORT,
+  EmbeddingCache,
   MEMORY_GRAPH_SCHEMA_VERSION,
   MEMORY_TYPES,
   Observer,
@@ -273,12 +421,15 @@ export {
   completeTask,
   configureTailscaleServe,
   contextCommand,
+  cosineSimilarity,
   countBlockedTransitions,
   createProject,
   createVault,
   deterministicInjectMatches,
   discoverClawVaultPeers,
   doctor,
+  embed,
+  embedBatch,
   embedCommand,
   extractCardSlug,
   extractTags,
@@ -309,6 +460,7 @@ export {
   graphSummary,
   hasQmd,
   hasTailscale,
+  hybridSearch,
   importKanbanBoard,
   indexInjectableItems,
   inferContextProfile,
@@ -337,6 +489,7 @@ export {
   readAllTransitions,
   readProject,
   rebuildCommand,
+  reciprocalRankFusion,
   reflectCommand,
   registerArchiveCommand,
   registerCliCommands,
@@ -366,6 +519,7 @@ export {
   resolveVaultPath,
   runPromptInjection,
   runReflection,
+  semanticSearch,
   serveVault,
   sessionRecapCommand,
   setConfigValue,

package/hooks/clawvault/HOOK.md

@@ -73,11 +73,41 @@ Injection format:
 
 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 Notes
+## Configuration
 
-The hook auto-detects vault path via:
+### Plugin Configuration (Recommended)
 
-1. `CLAWVAULT_PATH` environment variable
-2. Walking up from cwd to find `.clawvault.json`
+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`.

package/hooks/clawvault/handler.js

@@ -444,9 +444,40 @@ function validateVaultPath(vaultPath) {
   return resolved;
 }
 
+// Extract plugin config from event context (set via openclaw config)
+function extractPluginConfig(event) {
+  const candidates = [
+    event?.pluginConfig,
+    event?.context?.pluginConfig,
+    event?.config?.plugins?.clawvault?.config,
+    event?.context?.config?.plugins?.clawvault?.config
+  ];
+
+  for (const candidate of candidates) {
+    if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) {
+      return candidate;
+    }
+  }
+
+  return {};
+}
+
 // Find vault by walking up directories
-function findVaultPath() {
-  // Check env first
+function findVaultPath(event) {
+  // Check plugin config first (set via openclaw config set plugins.clawvault.config.vaultPath)
+  const pluginConfig = extractPluginConfig(event);
+  if (pluginConfig.vaultPath) {
+    const validated = validateVaultPath(pluginConfig.vaultPath);
+    if (validated) return validated;
+  }
+
+  // Check OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH env (injected by OpenClaw from plugin config)
+  if (process.env.OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH) {
+    const validated = validateVaultPath(process.env.OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH);
+    if (validated) return validated;
+  }
+
+  // Check CLAWVAULT_PATH env
   if (process.env.CLAWVAULT_PATH) {
     return validateVaultPath(process.env.CLAWVAULT_PATH);
   }
@@ -571,7 +602,7 @@ function isSundayMidnightUtc(date) {
 }
 
 async function handleWeeklyReflect(event) {
-  const vaultPath = findVaultPath();
+  const vaultPath = findVaultPath(event);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping weekly reflection');
     return;
@@ -593,7 +624,7 @@ async function handleWeeklyReflect(event) {
 
 // Handle gateway startup - check for context death
 async function handleStartup(event) {
-  const vaultPath = findVaultPath();
+  const vaultPath = findVaultPath(event);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping recovery check');
     return;
@@ -632,7 +663,7 @@ async function handleStartup(event) {
 
 // Handle /new command - auto-checkpoint before reset
 async function handleNew(event) {
-  const vaultPath = findVaultPath();
+  const vaultPath = findVaultPath(event);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping auto-checkpoint');
     return;
@@ -671,7 +702,7 @@ async function handleNew(event) {
 
 // Handle session start - inject dynamic context for first prompt
 async function handleSessionStart(event) {
-  const vaultPath = findVaultPath();
+  const vaultPath = findVaultPath(event);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping context injection');
     return;
@@ -733,7 +764,7 @@ async function handleSessionStart(event) {
 
 // Handle heartbeat events - cheap stat-based trigger for active observation
 async function handleHeartbeat(event) {
-  const vaultPath = findVaultPath();
+  const vaultPath = findVaultPath(event);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping heartbeat observation check');
     return;
@@ -750,7 +781,7 @@ async function handleHeartbeat(event) {
 
 // Handle context compaction - force flush any pending session deltas
 async function handleContextCompaction(event) {
-  const vaultPath = findVaultPath();
+  const vaultPath = findVaultPath(event);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping compaction observation');
     return;

package/hooks/clawvault/handler.test.js

@@ -260,4 +260,98 @@ describe('clawvault hook handler', () => {
 
     fs.rmSync(vaultPath, { recursive: true, force: true });
   });
+
+  it('uses vaultPath from plugin config when provided in event', async () => {
+    const vaultPath = makeVaultFixture();
+
+    execFileSyncMock.mockImplementation((_command, args) => {
+      if (args[0] === 'recover') {
+        return 'Clean startup';
+      }
+      return '';
+    });
+
+    const handler = await loadHandler();
+    const event = {
+      type: 'gateway',
+      action: 'startup',
+      pluginConfig: {
+        vaultPath
+      },
+      messages: []
+    };
+
+    await handler(event);
+
+    expect(execFileSyncMock).toHaveBeenCalledWith(
+      'clawvault',
+      expect.arrayContaining(['recover', '--clear', '-v', vaultPath]),
+      expect.objectContaining({ shell: false })
+    );
+
+    fs.rmSync(vaultPath, { recursive: true, force: true });
+  });
+
+  it('uses vaultPath from context.pluginConfig when provided', async () => {
+    const vaultPath = makeVaultFixture();
+
+    execFileSyncMock.mockImplementation((_command, args) => {
+      if (args[0] === 'recover') {
+        return 'Clean startup';
+      }
+      return '';
+    });
+
+    const handler = await loadHandler();
+    const event = {
+      type: 'gateway',
+      action: 'startup',
+      context: {
+        pluginConfig: {
+          vaultPath
+        }
+      },
+      messages: []
+    };
+
+    await handler(event);
+
+    expect(execFileSyncMock).toHaveBeenCalledWith(
+      'clawvault',
+      expect.arrayContaining(['recover', '--clear', '-v', vaultPath]),
+      expect.objectContaining({ shell: false })
+    );
+
+    fs.rmSync(vaultPath, { recursive: true, force: true });
+  });
+
+  it('uses vaultPath from OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH env var', async () => {
+    const vaultPath = makeVaultFixture();
+    process.env.OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH = vaultPath;
+
+    execFileSyncMock.mockImplementation((_command, args) => {
+      if (args[0] === 'recover') {
+        return 'Clean startup';
+      }
+      return '';
+    });
+
+    const handler = await loadHandler();
+    const event = {
+      type: 'gateway',
+      action: 'startup',
+      messages: []
+    };
+
+    await handler(event);
+
+    expect(execFileSyncMock).toHaveBeenCalledWith(
+      'clawvault',
+      expect.arrayContaining(['recover', '--clear', '-v', vaultPath]),
+      expect.objectContaining({ shell: false })
+    );
+
+    delete process.env.OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH;
+    fs.rmSync(vaultPath, { recursive: true, force: true });
+  });
 });

package/openclaw.plugin.json

@@ -0,0 +1,72 @@
+{
+  "id": "clawvault",
+  "name": "ClawVault",
+  "version": "2.6.1",
+  "description": "Structured memory system for AI agents with context death resilience",
+  "kind": "memory",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "vaultPath": {
+        "type": "string",
+        "description": "Path to the ClawVault vault directory. If not set, auto-discovered from CLAWVAULT_PATH or by walking up from cwd."
+      },
+      "autoCheckpoint": {
+        "type": "boolean",
+        "description": "Enable automatic checkpointing on session events",
+        "default": true
+      },
+      "contextProfile": {
+        "type": "string",
+        "enum": ["default", "planning", "incident", "handoff", "auto"],
+        "description": "Default context profile for session start injection",
+        "default": "auto"
+      },
+      "maxContextResults": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 20,
+        "description": "Maximum number of context results to inject on session start",
+        "default": 4
+      },
+      "observeOnHeartbeat": {
+        "type": "boolean",
+        "description": "Enable observation threshold checks on gateway heartbeat",
+        "default": true
+      },
+      "weeklyReflection": {
+        "type": "boolean",
+        "description": "Enable weekly reflection on Sunday midnight UTC",
+        "default": true
+      }
+    },
+    "additionalProperties": false
+  },
+  "uiHints": {
+    "vaultPath": {
+      "label": "Vault Path",
+      "placeholder": "~/my-vault",
+      "description": "Path to your ClawVault memory vault"
+    },
+    "autoCheckpoint": {
+      "label": "Auto Checkpoint",
+      "description": "Automatically checkpoint before session resets"
+    },
+    "contextProfile": {
+      "label": "Context Profile",
+      "description": "Profile used for context injection at session start"
+    },
+    "maxContextResults": {
+      "label": "Max Context Results",
+      "description": "Number of vault memories to inject"
+    },
+    "observeOnHeartbeat": {
+      "label": "Observe on Heartbeat",
+      "description": "Check observation thresholds during heartbeat events"
+    },
+    "weeklyReflection": {
+      "label": "Weekly Reflection",
+      "description": "Run weekly reflection on Sunday midnight UTC"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawvault",
-  "version": "2.6.1",
+  "version": "2.6.3",
   "description": "Structured memory system for AI agents — typed storage, knowledge graph, context profiles, canvas dashboards, neural graph themes, and Obsidian-native task views. An elephant never forgets. 🐘",
   "type": "module",
   "main": "dist/index.cjs",
@@ -21,9 +21,11 @@
     "bin",
     "dashboard",
     "templates",
-    "hooks"
+    "hooks",
+    "openclaw.plugin.json"
   ],
   "openclaw": {
+    "plugin": "./openclaw.plugin.json",
     "hooks": [
       "./hooks/clawvault"
     ]
@@ -65,6 +67,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
     "chalk": "^5.3.0",
     "chokidar": "^5.0.0",
     "commander": "^12.0.0",