clawvault 3.4.0 → 3.4.1

package/README.md

@@ -267,23 +267,24 @@ clawvault setup --theme neural --canvas --bases
 
 ## OpenClaw Integration
 
-For hook-based lifecycle integration with OpenClaw:
+ClawVault integrates with OpenClaw as a plugin package (not the deprecated `openclaw hooks install/enable` flow):
 
 ```bash
-# Install and enable hook pack
-openclaw hooks install clawvault
-openclaw hooks enable clawvault
+# Install ClawVault
+npm install -g clawvault
+
+# Add ClawVault package path to plugins.load.paths in openclaw.json
+# (You can use `npm root -g` to locate node_modules)
 
-# Verify
-openclaw hooks list --verbose
-openclaw hooks check
+# Enable plugin + memory slot in openclaw.json:
+# plugins.slots.memory = "clawvault"
+# plugins.entries.clawvault.enabled = true
+
+# Verify runtime assumptions
 clawvault compat
 ```
 
-The hook automatically:
-- Detects context death and injects recovery alerts
-- Auto-checkpoints before session resets
-- Provides `--profile auto` for context queries
+The plugin provides lifecycle hooks, memory tools, and protocol-safe messaging behavior for OpenClaw sessions.
 
 ### MEMORY.md vs Vault
 
@@ -351,27 +352,26 @@ clawvault compat
 
 ## OpenClaw Setup (Canonical)
 
-If you want hook-based lifecycle integration, use this sequence:
+Use this sequence for plugin-based OpenClaw integration:
 
 ```bash
 # Install CLI
 npm install -g clawvault
 
-# Install and enable hook pack
-openclaw hooks install clawvault
-openclaw hooks enable clawvault
+# Locate global node_modules
+npm root -g
 
-# Verify
-openclaw hooks list --verbose
-openclaw hooks info clawvault
-openclaw hooks check
-clawvault compat
+# In openclaw.json:
+# - add <npm-root>/clawvault to plugins.load.paths
+# - set plugins.slots.memory = "clawvault"
+# - set plugins.entries.clawvault.enabled = true
+# - set plugins.entries.clawvault.config.vaultPath as needed
 ```
 
 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.
+- `clawhub install clawvault` installs skill guidance, but does not configure OpenClaw plugin loading.
+- After changing plugin config, restart the OpenClaw gateway process.
 
 ## Minimal AGENTS.md Additions
 
@@ -488,10 +488,10 @@ vault/
 - `qmd` fallback errors:
   - `qmd` is optional; in-process BM25 search is available without it
   - if you want fallback compatibility, ensure `qmd --version` works in the same shell
-- Hook/plugin not active in OpenClaw:
-  - run `openclaw hooks install clawvault`
-  - run `openclaw hooks enable clawvault`
-  - verify with `openclaw hooks list --verbose`
+- Plugin not active in OpenClaw:
+  - verify `plugins.load.paths` includes the ClawVault package path
+  - verify `plugins.slots.memory` is `clawvault`
+  - verify `plugins.entries.clawvault.enabled` is `true`
 - OpenClaw integration drift:
   - run `clawvault compat`
 - Session transcript corruption:

package/dist/{chunk-QYQAGBTM.js → chunk-PLNK37JD.js}

@@ -833,38 +833,128 @@ function truncateRecapSnippet(snippet) {
   if (safe.length <= MAX_RECAP_SNIPPET_LENGTH) return safe;
   return `${safe.slice(0, MAX_RECAP_SNIPPET_LENGTH - 3).trimEnd()}...`;
 }
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function parseTopLevelJson(output) {
+  const text = output.trim();
+  if (!text) return null;
+  const tryParse = (candidate) => {
+    try {
+      const parsed = JSON.parse(candidate);
+      return isRecord2(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  };
+  const direct = tryParse(text);
+  if (direct) return direct;
+  const findJsonEnd = (start) => {
+    const open = text[start];
+    if (open !== "{" && open !== "[") return -1;
+    const stack = [open];
+    let inString = false;
+    let escaped = false;
+    for (let i = start + 1; i < text.length; i += 1) {
+      const ch = text[i];
+      if (inString) {
+        if (escaped) {
+          escaped = false;
+          continue;
+        }
+        if (ch === "\\") {
+          escaped = true;
+          continue;
+        }
+        if (ch === '"') {
+          inString = false;
+        }
+        continue;
+      }
+      if (ch === '"') {
+        inString = true;
+        continue;
+      }
+      if (ch === "{" || ch === "[") {
+        stack.push(ch);
+        continue;
+      }
+      if (ch === "}" || ch === "]") {
+        const expected = ch === "}" ? "{" : "[";
+        const top = stack[stack.length - 1];
+        if (top !== expected) return -1;
+        stack.pop();
+        if (stack.length === 0) {
+          return i;
+        }
+      }
+    }
+    return -1;
+  };
+  for (let start = 0; start < text.length; start += 1) {
+    const ch = text[start];
+    if (ch !== "{" && ch !== "[") continue;
+    const end = findJsonEnd(start);
+    if (end < 0) continue;
+    const parsed = tryParse(text.slice(start, end + 1));
+    if (parsed) return parsed;
+  }
+  return null;
+}
+function resolveEntryArray(parsed, keys) {
+  for (const key of keys) {
+    const value = parsed[key];
+    if (!Array.isArray(value)) continue;
+    return value.filter((item) => isRecord2(item));
+  }
+  return [];
+}
 function parseContextJson(output, maxResults) {
-  try {
-    const parsed = JSON.parse(output);
-    if (!parsed || !Array.isArray(parsed.context)) return [];
-    return parsed.context.slice(0, maxResults).map((entry) => ({
-      title: sanitizeForDisplay(entry.title ?? "Untitled"),
-      path: sanitizeForDisplay(entry.path ?? ""),
-      age: sanitizeForDisplay(entry.age ?? "unknown age"),
-      snippet: truncateSnippet(String(entry.snippet ?? "")),
-      score: Number.isFinite(Number(entry.score)) ? Number(entry.score) : 0
-    })).filter((entry) => entry.snippet.length > 0);
-  } catch {
+  const parsed = parseTopLevelJson(output);
+  if (!parsed) {
     return [];
   }
+  const rows = resolveEntryArray(parsed, ["context", "results", "entries", "memories"]);
+  return rows.slice(0, maxResults).map((entry) => {
+    const nestedDocument = isRecord2(entry.document) ? entry.document : null;
+    const title = sanitizeForDisplay(
+      entry.title ?? nestedDocument?.title ?? nestedDocument?.id ?? entry.path ?? "Untitled"
+    );
+    const resolvedPath = sanitizeForDisplay(
+      entry.path ?? entry.relPath ?? nestedDocument?.path ?? ""
+    );
+    const resolvedAge = sanitizeForDisplay(entry.age ?? entry.modified ?? "unknown age");
+    const snippetSource = String(
+      entry.snippet ?? entry.text ?? entry.content ?? nestedDocument?.snippet ?? nestedDocument?.content ?? ""
+    );
+    return {
+      title,
+      path: resolvedPath,
+      age: resolvedAge,
+      snippet: truncateSnippet(snippetSource),
+      score: Number.isFinite(Number(entry.score)) ? Number(entry.score) : 0
+    };
+  }).filter((entry) => entry.snippet.length > 0);
 }
 function parseSessionRecapJson(output, maxResults) {
-  try {
-    const parsed = JSON.parse(output);
-    if (!parsed || !Array.isArray(parsed.messages)) return [];
-    return parsed.messages.map((entry) => {
-      const role = typeof entry.role === "string" ? entry.role.toLowerCase() : "";
-      if (role !== "user" && role !== "assistant") return null;
-      const text = truncateRecapSnippet(typeof entry.text === "string" ? entry.text : "");
-      if (!text) return null;
-      return {
-        role: role === "user" ? "User" : "Assistant",
-        text
-      };
-    }).filter((entry) => Boolean(entry)).slice(-maxResults);
-  } catch {
+  const parsed = parseTopLevelJson(output);
+  if (!parsed) {
     return [];
   }
+  const rows = resolveEntryArray(parsed, ["messages", "turns", "recap"]);
+  return rows.map((entry) => {
+    const role = typeof entry.role === "string" ? entry.role.toLowerCase() : "";
+    const normalizedRole = role === "user" || role === "human" ? "User" : role === "assistant" || role === "ai" ? "Assistant" : "";
+    if (!normalizedRole) return null;
+    const text = truncateRecapSnippet(
+      typeof entry.text === "string" ? entry.text : typeof entry.content === "string" ? entry.content : ""
+    );
+    if (!text) return null;
+    return {
+      role: normalizedRole,
+      text
+    };
+  }).filter((entry) => Boolean(entry)).slice(-maxResults);
 }
 function formatSessionContextInjection(recapEntries, memoryEntries) {
   const lines = [
@@ -1132,8 +1222,8 @@ function toSafeFilePath(vaultPath, relPath) {
   if (!mapped || mapped.includes("..")) {
     throw new Error("Invalid memory path");
   }
-  if (mapped !== "MEMORY.md" && !mapped.startsWith("memory/")) {
-    throw new Error("memory_get only allows MEMORY.md or memory/* paths");
+  if (!mapped.toLowerCase().endsWith(".md")) {
+    throw new Error("memory_get only allows Markdown note paths inside the vault");
   }
   const absolute = path4.resolve(vaultPath, mapped);
   const vaultRootWithSep = vaultPath.endsWith(path4.sep) ? vaultPath : `${vaultPath}${path4.sep}`;
@@ -1260,8 +1350,17 @@ function buildToolSchema(properties, required = []) {
     additionalProperties: false
   };
 }
+function resolveToolInput(toolCallIdOrInput, maybeInput) {
+  if (maybeInput && typeof maybeInput === "object" && !Array.isArray(maybeInput)) {
+    return maybeInput;
+  }
+  if (toolCallIdOrInput && typeof toolCallIdOrInput === "object" && !Array.isArray(toolCallIdOrInput)) {
+    return toolCallIdOrInput;
+  }
+  return {};
+}
 function createMemorySearchToolFactory(memoryManager) {
-  return () => {
+  return (_toolContext) => {
     const inputSchema = buildToolSchema({
       query: {
         type: "string",
@@ -1284,7 +1383,8 @@ function createMemorySearchToolFactory(memoryManager) {
         description: "Optional OpenClaw session key for scoped recall."
       }
     }, ["query"]);
-    const execute = async (input) => {
+    const execute = async (toolCallIdOrInput, maybeInput) => {
+      const input = resolveToolInput(toolCallIdOrInput, maybeInput);
       const query = typeof input.query === "string" ? input.query : "";
       if (!query.trim()) {
         return { query, count: 0, results: [] };
@@ -1301,6 +1401,7 @@ function createMemorySearchToolFactory(memoryManager) {
       };
     };
     return {
+      label: "Memory Search",
       name: "memory_search",
       description: "Search ClawVault memory for relevant snippets before answering.",
       inputSchema,
@@ -1313,11 +1414,15 @@ function createMemorySearchToolFactory(memoryManager) {
   };
 }
 function createMemoryGetToolFactory(memoryManager) {
-  return () => {
+  return (_toolContext) => {
     const inputSchema = buildToolSchema({
+      path: {
+        type: "string",
+        description: "Relative path from memory_search result (for OpenClaw compatibility)."
+      },
       relPath: {
         type: "string",
-        description: "Relative path from memory_search result (e.g. memory/2026-01-01.md)."
+        description: "Alias of path (e.g. memory/2026-01-01.md)."
       },
       from: {
         type: "number",
@@ -1330,9 +1435,11 @@ function createMemoryGetToolFactory(memoryManager) {
         maximum: 400,
         description: "Optional number of lines to read."
       }
-    }, ["relPath"]);
-    const execute = async (input) => {
-      const relPath = typeof input.relPath === "string" ? input.relPath : "";
+    });
+    inputSchema.anyOf = [{ required: ["path"] }, { required: ["relPath"] }];
+    const execute = async (toolCallIdOrInput, maybeInput) => {
+      const input = resolveToolInput(toolCallIdOrInput, maybeInput);
+      const relPath = typeof input.path === "string" ? input.path : typeof input.relPath === "string" ? input.relPath : "";
       if (!relPath.trim()) {
         return { path: relPath, text: "" };
       }
@@ -1343,6 +1450,7 @@ function createMemoryGetToolFactory(memoryManager) {
       });
     };
     return {
+      label: "Memory Get",
       name: "memory_get",
       description: "Read a specific memory file or line range from ClawVault.",
       inputSchema,
@@ -1509,11 +1617,27 @@ async function fetchMemoryContextEntries(options) {
     vaultPath
   ];
   const contextResult = runClawvault(contextArgs, options.pluginConfig, { timeoutMs: 25e3 });
-  if (!contextResult.success) {
+  if (contextResult.success) {
+    return {
+      entries: parseContextJson(contextResult.output, maxResults),
+      vaultPath
+    };
+  }
+  const fallbackSearchArgs = [
+    "search",
+    prompt,
+    "--json",
+    "-n",
+    String(maxResults),
+    "-v",
+    vaultPath
+  ];
+  const fallbackSearchResult = runClawvault(fallbackSearchArgs, options.pluginConfig, { timeoutMs: 25e3 });
+  if (!fallbackSearchResult.success) {
     return { entries: [], vaultPath };
   }
   return {
-    entries: parseContextJson(contextResult.output, maxResults),
+    entries: parseContextJson(fallbackSearchResult.output, maxResults),
     vaultPath
   };
 }
@@ -2007,8 +2131,10 @@ async function registerOpenClawPlugin(api) {
       warn: api.logger.warn
     }
   });
-  api.registerTool(createMemorySearchToolFactory(memoryManager), { name: "memory_search" });
-  api.registerTool(createMemoryGetToolFactory(memoryManager), { name: "memory_get" });
+  const memorySearchTool = createMemorySearchToolFactory(memoryManager)();
+  const memoryGetTool = createMemoryGetToolFactory(memoryManager)();
+  api.registerTool(memorySearchTool, { name: "memory_search" });
+  api.registerTool(memoryGetTool, { name: "memory_get" });
   api.on("before_prompt_build", createBeforePromptBuildHandler({
     pluginConfig,
     runtimeState

package/dist/index.js

@@ -60,7 +60,7 @@ import {
   openclaw_plugin_default,
   plausibilityScore,
   registerMemorySlot
-} from "./chunk-QYQAGBTM.js";
+} from "./chunk-PLNK37JD.js";
 import {
   buildRecallResult,
   classifyRecallQuery

package/dist/openclaw-plugin.js

@@ -1,7 +1,7 @@
 import {
   createMemorySlotPlugin,
   openclaw_plugin_default
-} from "./chunk-QYQAGBTM.js";
+} from "./chunk-PLNK37JD.js";
 import "./chunk-RL2L6I6K.js";
 import "./chunk-NSXYM6EZ.js";
 import "./chunk-35JCYSRR.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawvault",
-  "version": "3.4.0",
+  "version": "3.4.1",
   "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",