@xdarkicex/openclaw-memory-libravdb 1.6.28 → 1.6.30

package/dist/context-engine.js

@@ -54,15 +54,22 @@ function normalizeCompactResult(response, options = {}) {
             ? response.summaryText
             : undefined,
     };
+    // When the engine owns compaction but refuses to compact while the session
+    // exceeds the threshold, this is not a successful skip — it's a failure.
+    // Signal ok:false so OpenClaw falls back to normal transcript compaction
+    // instead of accepting a bloated session.
+    const threshold = options.threshold;
+    const overBudget = threshold != null && tokensBefore >= threshold;
+    const engineRefused = !didCompact && overBudget;
     return {
-        ok: true,
+        ok: !engineRefused,
         compacted: didCompact,
-        ...(didCompact ? {} : { reason: "not_compacted" }),
+        ...(didCompact ? {} : { reason: engineRefused ? "overbudget_not_compacted" : "not_compacted" }),
         result: {
             tokensBefore,
             ...(details.summaryMethod ? { summary: details.summaryMethod } : {}),
             ...(details.summaryText ? { summaryText: details.summaryText } : {}),
-            details,
+            details: { ...details, ...(threshold != null ? { threshold } : {}) },
         },
     };
 }
@@ -1084,8 +1091,10 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
         const request = buildCompactSessionRequest(args);
         try {
             const client = await runtime.getClient();
+            const threshold = getDynamicCompactThreshold(args.tokenBudget);
             return normalizeCompactResult(await client.compactSession(request), {
                 tokensBefore: args.currentTokenCount,
+                ...(threshold != null ? { threshold } : {}),
             });
         }
         catch (error) {

package/dist/index.js

@@ -25830,6 +25830,7 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
         query: queryOrParams,
         limit: opts.limit ?? opts.k ?? opts.maxResults ?? opts.topK,
         minScore: opts.minScore,
+        corpus: opts.corpus,
         sessionId: opts.sessionId,
         sessionKey: opts.sessionKey,
         userId: opts.userId,
@@ -25841,6 +25842,7 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
         return legacyCall ? { results: [], error: "Missing query text for LibraVDB memory search" } : [];
       }
       const dreamQuery = detectDreamQuerySignal(queryText);
+      const searchCorpus = normalizeSearchCorpus(params.corpus);
       const sessionId = firstString(params.sessionId, params.context?.sessionId);
       const explicitUserId = firstString(params.userId, params.context?.userId);
       const resolvedUserId = explicitUserId ?? getResolvedUserId(firstString(params.sessionKey, params.context?.sessionKey));
@@ -25853,17 +25855,19 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
       const k = normalizePositiveInteger(params.k, params.limit, params.maxResults, params.topK, cfg.topK, 8);
       const minScore = normalizeNumber(params.minScore);
       const client = await getClient();
-      const result = dreamQuery.active && cfg.crossSessionRecall !== false ? await client.searchText({
+      const result = dreamQuery.active && cfg.crossSessionRecall !== false && searchCorpus !== "sessions" ? await client.searchText({
         collection: resolveDreamCollection(userId),
         text: queryText,
         k
-      }) : await searchResolvedCollections(client, cfg, userId, sessionId, queryText, k);
+      }) : await searchResolvedCollections(client, cfg, userId, sessionId, queryText, k, searchCorpus);
       const filteredResults = minScore === void 0 ? result.results : result.results.filter((item) => item.score >= minScore);
       const legacyResults = filteredResults.map((item) => {
         const meta = parseMetadataJson(item);
+        const text = resolveSearchResultText(item, meta);
         return {
           ...item,
-          content: item.text || (typeof meta.text === "string" ? meta.text : "")
+          text,
+          content: text
         };
       });
       if (legacyCall) {
@@ -25872,10 +25876,10 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
       const memoryResults = filteredResults.map((item) => {
         const meta = parseMetadataJson(item);
         const collection = typeof meta.collection === "string" ? meta.collection : "memory";
-        const effectiveText = item.text || (typeof meta.text === "string" ? meta.text : "") || "";
         const relPath = encodeSearchResultPath(collection, item.id);
-        returnedSearchPaths.set(relPath, effectiveText);
-        return toMemorySearchResult(item);
+        const text = resolveSearchResultText(item, meta);
+        returnedSearchPaths.set(relPath, text);
+        return toMemorySearchResult(item, meta, text);
       });
       return memoryResults;
     },
@@ -25916,8 +25920,8 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
     }
   };
 }
-async function searchResolvedCollections(client, cfg, userId, sessionId, queryText, k) {
-  const collections = resolveSearchCollections(cfg, userId, sessionId);
+async function searchResolvedCollections(client, cfg, userId, sessionId, queryText, k, corpus) {
+  const collections = resolveSearchCollections(cfg, userId, sessionId, corpus);
   if (collections.length === 0) {
     return { results: [] };
   }
@@ -25932,16 +25936,21 @@ async function searchResolvedCollections(client, cfg, userId, sessionId, queryTe
     excludeByCollection: {}
   });
 }
-function resolveSearchCollections(cfg, userId, sessionId) {
+function resolveSearchCollections(cfg, userId, sessionId, corpus) {
+  if (corpus === "sessions") {
+    return sessionId ? [resolveSessionSearchCollection(cfg, sessionId)] : [];
+  }
+  const durableCollections = [resolveUserCollection(userId), "global"];
+  if (corpus === "memory") {
+    return durableCollections;
+  }
   if (cfg.crossSessionRecall === false) {
     return sessionId ? [resolveSessionSearchCollection(cfg, sessionId)] : [];
   }
-  const collections = [resolveUserCollection(userId), "global"];
   if (!sessionId) {
-    return collections;
+    return durableCollections;
   }
-  collections.unshift(resolveSessionSearchCollection(cfg, sessionId));
-  return collections;
+  return [resolveSessionSearchCollection(cfg, sessionId), ...durableCollections];
 }
 function resolveSessionSearchCollection(cfg, sessionId) {
   if (cfg.useSessionSummarySearchExperiment) {
@@ -25964,6 +25973,9 @@ function firstString(...values) {
   }
   return void 0;
 }
+function normalizeSearchCorpus(value) {
+  return value === "memory" || value === "sessions" ? value : "all";
+}
 function parseMetadataJson(item) {
   if (item.metadataJson && item.metadataJson.length > 0) {
     try {
@@ -25973,16 +25985,20 @@ function parseMetadataJson(item) {
   }
   return {};
 }
-function toMemorySearchResult(item) {
-  const meta = parseMetadataJson(item);
+function resolveSearchResultText(item, meta = parseMetadataJson(item)) {
+  if (typeof item.text === "string" && item.text.length > 0) {
+    return item.text;
+  }
+  return typeof meta.text === "string" ? meta.text : item.text;
+}
+function toMemorySearchResult(item, meta = parseMetadataJson(item), text = resolveSearchResultText(item, meta)) {
   const collection = typeof meta.collection === "string" ? meta.collection : "memory";
-  const effectiveText = item.text || (typeof meta.text === "string" ? meta.text : "") || "";
   return {
     path: encodeSearchResultPath(collection, item.id),
     startLine: 1,
-    endLine: Math.max(1, effectiveText.split("\n").length),
+    endLine: Math.max(1, text.split("\n").length),
     score: item.score,
-    snippet: effectiveText,
+    snippet: text,
     source: collection.startsWith("session:") || collection.startsWith("session_") ? "sessions" : "memory",
     citation: `${collection}:${item.id}`
   };
@@ -26723,15 +26739,18 @@ function normalizeCompactResult(response, options = {}) {
     meanConfidence: typeof response?.meanConfidence === "number" ? response.meanConfidence : void 0,
     summaryText: typeof response?.summaryText === "string" && response.summaryText.length > 0 ? response.summaryText : void 0
   };
+  const threshold = options.threshold;
+  const overBudget = threshold != null && tokensBefore >= threshold;
+  const engineRefused = !didCompact && overBudget;
   return {
-    ok: true,
+    ok: !engineRefused,
     compacted: didCompact,
-    ...didCompact ? {} : { reason: "not_compacted" },
+    ...didCompact ? {} : { reason: engineRefused ? "overbudget_not_compacted" : "not_compacted" },
     result: {
       tokensBefore,
       ...details.summaryMethod ? { summary: details.summaryMethod } : {},
       ...details.summaryText ? { summaryText: details.summaryText } : {},
-      details
+      details: { ...details, ...threshold != null ? { threshold } : {} }
     }
   };
 }
@@ -27583,8 +27602,10 @@ function buildContextEngineFactory(runtime, cfg, logger = console) {
     const request3 = buildCompactSessionRequest(args);
     try {
       const client = await runtime.getClient();
+      const threshold = getDynamicCompactThreshold(args.tokenBudget);
       return normalizeCompactResult(await client.compactSession(request3), {
-        tokensBefore: args.currentTokenCount
+        tokensBefore: args.currentTokenCount,
+        ...threshold != null ? { threshold } : {}
       });
     } catch (error2) {
       return {
@@ -34722,12 +34743,271 @@ var MEMORY_PROMPT_HEADER = [
   "in context via the context-engine assembler when available and relevant.",
   ""
 ];
+function buildToolGuidance(availableTools) {
+  if (!availableTools?.has("memory_search")) {
+    return [];
+  }
+  const lines = [
+    "For explicit memory lookup requests, call `memory_search` first.",
+    "Use it for prior turns, remembered facts, earliest interactions, and channel history.",
+    "Do not answer memory lookup requests from prior transcript claims or earlier `memory_search` results; perform a fresh `memory_search` for the current request.",
+    "For earliest or oldest memory questions, request enough results, compare timestamps in the returned snippets, and use `memory_get` if the snippet is not enough."
+  ];
+  if (availableTools.has("memory_get")) {
+    lines.push("After a `memory_search` hit, call `memory_get` when exact wording or more context is needed.");
+  }
+  lines.push(
+    "Do not treat a missing `MEMORY.md` file as missing memory; LibraVDB memory is vector-backed and retrieved through the memory tools.",
+    ""
+  );
+  return lines;
+}
 function buildMemoryPromptSection(_getClient, _cfg) {
   return function memoryPromptSection({
-    availableTools: _availableTools,
+    availableTools,
     citationsMode: _citationsMode
   }) {
-    return [...MEMORY_PROMPT_HEADER];
+    return [...MEMORY_PROMPT_HEADER, ...buildToolGuidance(availableTools)];
+  };
+}
+
+// src/memory-tools.ts
+var MEMORY_SEARCH_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    query: {
+      type: "string",
+      description: "Semantic recall query for prior work, preferences, decisions, dates, people, todos, or session context."
+    },
+    maxResults: {
+      type: "number",
+      minimum: 1,
+      maximum: 50,
+      description: "Maximum number of memory hits to return."
+    },
+    minScore: {
+      type: "number",
+      minimum: 0,
+      maximum: 1,
+      description: "Minimum similarity score for returned hits."
+    },
+    corpus: {
+      type: "string",
+      enum: ["memory", "wiki", "all", "sessions"],
+      description: "Corpus filter. LibraVDB serves memory/session hits; wiki is unsupported unless another plugin owns wiki tools."
+    }
+  },
+  required: ["query"]
+};
+var MEMORY_GET_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    path: {
+      type: "string",
+      description: "A path returned by memory_search."
+    },
+    from: {
+      type: "number",
+      minimum: 1,
+      description: "1-based starting line."
+    },
+    lines: {
+      type: "number",
+      minimum: 1,
+      description: "Maximum number of lines to read."
+    },
+    corpus: {
+      type: "string",
+      enum: ["memory", "wiki", "all"],
+      description: "Corpus filter. LibraVDB reads paths returned by memory_search."
+    }
+  },
+  required: ["path"]
+};
+function createLibraVdbMemoryTools(getClient, cfg, logger = console) {
+  const bridge = buildMemoryRuntimeBridge(getClient, cfg);
+  const managers = /* @__PURE__ */ new Map();
+  async function getManager(ctx, purpose) {
+    const key = managerCacheKey(ctx);
+    let manager = managers.get(key);
+    if (!manager) {
+      manager = bridge.getMemorySearchManager({
+        agentId: normalizeOptionalString(ctx.agentId),
+        purpose
+      }).then((result) => result.manager).catch((error2) => {
+        managers.delete(key);
+        throw error2;
+      });
+      managers.set(key, manager);
+    }
+    return await manager;
+  }
+  return {
+    createSearchTool(ctx = {}) {
+      return {
+        name: "memory_search",
+        label: "Memory Search",
+        description: "Mandatory fresh LibraVDB recall step: semantically search durable memory and session recall before answering questions about prior work, decisions, dates, people, preferences, todos, or history. Do not reuse prior transcript claims or older memory_search results for a new memory lookup. For earliest/oldest questions, request enough results and compare timestamps in snippets. If response has disabled=true, memory retrieval is unavailable and should be surfaced to the user.",
+        parameters: MEMORY_SEARCH_SCHEMA,
+        execute: async (_toolCallId, rawParams) => {
+          const params = asToolParamsRecord(rawParams);
+          const query = readRequiredStringParam(params, "query");
+          const corpus = readMemoryCorpus(params.corpus);
+          const maxResults = readNumberParam(params, "maxResults", { integer: true });
+          const minScore = readNumberParam(params, "minScore");
+          if (corpus === "wiki") {
+            return jsonToolResult({
+              results: [],
+              disabled: true,
+              error: "LibraVDB memory_search does not provide the wiki corpus; use corpus=memory, corpus=sessions, or corpus=all."
+            });
+          }
+          try {
+            const manager = await getManager(ctx, "tool-search");
+            const rawResults = await manager.search({
+              query,
+              corpus,
+              ...maxResults !== void 0 ? { maxResults } : {},
+              ...minScore !== void 0 ? { minScore } : {},
+              ...buildSearchContext(ctx)
+            });
+            const results = filterResultsByCorpus(rawResults, corpus);
+            const status = manager.status();
+            return jsonToolResult({
+              results,
+              provider: status.provider,
+              model: status.model,
+              backend: status.backend
+            });
+          } catch (error2) {
+            logger.warn?.(`LibraVDB memory_search failed: ${formatError(error2)}`);
+            return jsonToolResult({
+              results: [],
+              disabled: true,
+              error: formatError(error2)
+            });
+          }
+        }
+      };
+    },
+    createGetTool(ctx = {}) {
+      return {
+        name: "memory_get",
+        label: "Memory Get",
+        description: "Read a bounded exact excerpt from a LibraVDB memory path returned by memory_search. Use this after memory_search when a hit needs exact wording or more context.",
+        parameters: MEMORY_GET_SCHEMA,
+        execute: async (_toolCallId, rawParams) => {
+          const params = asToolParamsRecord(rawParams);
+          const relPath = readRequiredStringParam(params, "path");
+          const corpus = readMemoryGetCorpus(params.corpus);
+          const from = readNumberParam(params, "from", { integer: true });
+          const lines = readNumberParam(params, "lines", { integer: true });
+          if (corpus === "wiki") {
+            return jsonToolResult({
+              path: relPath,
+              text: "",
+              disabled: true,
+              error: "LibraVDB memory_get does not provide the wiki corpus; use paths returned by LibraVDB memory_search."
+            });
+          }
+          try {
+            const manager = await getManager(ctx, "tool-get");
+            const result = await manager.readFile({
+              relPath,
+              ...from !== void 0 ? { from } : {},
+              ...lines !== void 0 ? { lines } : {}
+            });
+            return jsonToolResult(result);
+          } catch (error2) {
+            logger.warn?.(`LibraVDB memory_get failed: ${formatError(error2)}`);
+            return jsonToolResult({
+              path: relPath,
+              text: "",
+              disabled: true,
+              error: formatError(error2)
+            });
+          }
+        }
+      };
+    }
+  };
+}
+function buildSearchContext(ctx) {
+  const agentId = normalizeOptionalString(ctx.agentId);
+  const sessionId = normalizeOptionalString(ctx.sessionId);
+  const sessionKey = normalizeOptionalString(ctx.sessionKey);
+  return {
+    ...agentId ? { agentId } : {},
+    ...sessionId ? { sessionId } : {},
+    ...sessionKey ? { sessionKey } : {},
+    context: {
+      ...agentId ? { agentId } : {},
+      ...sessionId ? { sessionId } : {},
+      ...sessionKey ? { sessionKey } : {}
+    }
+  };
+}
+function filterResultsByCorpus(results, corpus) {
+  if (corpus === "sessions") {
+    return results.filter((result) => result.source === "sessions");
+  }
+  if (corpus === "memory") {
+    return results.filter((result) => result.source === "memory");
+  }
+  return results;
+}
+function managerCacheKey(ctx) {
+  return [
+    normalizeOptionalString(ctx.agentId) ?? "",
+    normalizeOptionalString(ctx.sessionId) ?? "",
+    normalizeOptionalString(ctx.sessionKey) ?? ""
+  ].join("\0");
+}
+function asToolParamsRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+function readRequiredStringParam(params, key) {
+  const value = normalizeOptionalString(params[key]);
+  if (!value) {
+    throw new Error(`memory tool requires ${key}`);
+  }
+  return value;
+}
+function readNumberParam(params, key, options = {}) {
+  const value = params[key];
+  const parsed = typeof value === "number" ? value : typeof value === "string" && value.trim().length > 0 ? Number(value) : void 0;
+  if (parsed === void 0 || !Number.isFinite(parsed)) {
+    return void 0;
+  }
+  return options.integer ? Math.max(1, Math.floor(parsed)) : parsed;
+}
+function readMemoryCorpus(value) {
+  return value === "memory" || value === "wiki" || value === "all" || value === "sessions" ? value : "all";
+}
+function readMemoryGetCorpus(value) {
+  return value === "memory" || value === "wiki" || value === "all" ? value : "memory";
+}
+function normalizeOptionalString(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function jsonToolResult(details) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(details, null, 2)
+      }
+    ],
+    details
   };
 }
 
@@ -38056,7 +38336,7 @@ function enrichStartupError(error2, healthMessage) {
 // src/index.ts
 var MEMORY_ID = "libravdb-memory";
 var LIGHTWEIGHT_MODES = /* @__PURE__ */ new Set(["cli-metadata", "setup-only"]);
-var RUNTIME_CLEANUP_SHUTDOWN_REASONS = /* @__PURE__ */ new Set(["delete", "restart"]);
+var RUNTIME_CLEANUP_SHUTDOWN_REASONS = /* @__PURE__ */ new Set(["delete"]);
 function shouldShutdownRuntimeForLifecycleCleanup(reason) {
   return RUNTIME_CLEANUP_SHUTDOWN_REASONS.has(reason);
 }
@@ -38090,6 +38370,12 @@ function register(api) {
   }
   const runtimeOrNull = isLightweight ? null : createPluginRuntime(cfg, logger);
   registerMemoryCli(api, runtimeOrNull, cfg, logger);
+  const ownsMemorySlot = memSlot === MEMORY_ID;
+  if (runtimeOrNull && ownsMemorySlot) {
+    const memoryTools = createLibraVdbMemoryTools(runtimeOrNull.getClient, cfg, logger);
+    api.registerTool?.((ctx) => memoryTools.createSearchTool(ctx), { names: ["memory_search"] });
+    api.registerTool?.((ctx) => memoryTools.createGetTool(ctx), { names: ["memory_get"] });
+  }
   if (isLightweight || isDiscovery) {
     if (!isLightweight) {
       logger.info?.(

package/dist/memory-provider.js

@@ -4,10 +4,26 @@ const MEMORY_PROMPT_HEADER = [
     "in context via the context-engine assembler when available and relevant.",
     "",
 ];
+function buildToolGuidance(availableTools) {
+    if (!availableTools?.has("memory_search")) {
+        return [];
+    }
+    const lines = [
+        "For explicit memory lookup requests, call `memory_search` first.",
+        "Use it for prior turns, remembered facts, earliest interactions, and channel history.",
+        "Do not answer memory lookup requests from prior transcript claims or earlier `memory_search` results; perform a fresh `memory_search` for the current request.",
+        "For earliest or oldest memory questions, request enough results, compare timestamps in the returned snippets, and use `memory_get` if the snippet is not enough.",
+    ];
+    if (availableTools.has("memory_get")) {
+        lines.push("After a `memory_search` hit, call `memory_get` when exact wording or more context is needed.");
+    }
+    lines.push("Do not treat a missing `MEMORY.md` file as missing memory; LibraVDB memory is vector-backed and retrieved through the memory tools.", "");
+    return lines;
+}
 export function buildMemoryPromptSection(_getClient, _cfg) {
-    return function memoryPromptSection({ availableTools: _availableTools, citationsMode: _citationsMode, }) {
+    return function memoryPromptSection({ availableTools, citationsMode: _citationsMode, }) {
         // OpenClaw builds the memory prompt section synchronously for embedded runs.
         // Actual retrieval and ranking happen in the context engine during assemble().
-        return [...MEMORY_PROMPT_HEADER];
+        return [...MEMORY_PROMPT_HEADER, ...buildToolGuidance(availableTools)];
     };
 }

package/dist/memory-runtime.d.ts

@@ -10,6 +10,7 @@ type MemorySearchParams = {
     maxResults?: number;
     minScore?: number;
     topK?: number;
+    corpus?: "all" | "memory" | "sessions";
     userId?: string;
     agentId?: string;
     sessionId?: string;
@@ -49,10 +50,10 @@ export declare function buildMemoryRuntimeBridge(getClient: ClientGetter, cfg: P
                 error: string;
             } | {
                 results: {
+                    text: string;
                     content: string;
                     id: string;
                     score: number;
-                    text: string;
                     metadataJson: Uint8Array<ArrayBuffer>;
                     version: bigint;
                 }[];

package/dist/memory-runtime.js

@@ -39,6 +39,7 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
                     query: queryOrParams,
                     limit: opts.limit ?? opts.k ?? opts.maxResults ?? opts.topK,
                     minScore: opts.minScore,
+                    corpus: opts.corpus,
                     sessionId: opts.sessionId,
                     sessionKey: opts.sessionKey,
                     userId: opts.userId,
@@ -51,6 +52,7 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
                 return legacyCall ? { results: [], error: "Missing query text for LibraVDB memory search" } : [];
             }
             const dreamQuery = detectDreamQuerySignal(queryText);
+            const searchCorpus = normalizeSearchCorpus(params.corpus);
             const sessionId = firstString(params.sessionId, params.context?.sessionId);
             const explicitUserId = firstString(params.userId, params.context?.userId);
             const resolvedUserId = explicitUserId ??
@@ -64,21 +66,23 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
             const k = normalizePositiveInteger(params.k, params.limit, params.maxResults, params.topK, cfg.topK, 8);
             const minScore = normalizeNumber(params.minScore);
             const client = await getClient();
-            const result = dreamQuery.active && cfg.crossSessionRecall !== false
+            const result = dreamQuery.active && cfg.crossSessionRecall !== false && searchCorpus !== "sessions"
                 ? await client.searchText({
                     collection: resolveDreamCollection(userId),
                     text: queryText,
                     k,
                 })
-                : await searchResolvedCollections(client, cfg, userId, sessionId, queryText, k);
+                : await searchResolvedCollections(client, cfg, userId, sessionId, queryText, k, searchCorpus);
             const filteredResults = minScore === undefined
                 ? result.results
                 : result.results.filter((item) => item.score >= minScore);
             const legacyResults = filteredResults.map((item) => {
                 const meta = parseMetadataJson(item);
+                const text = resolveSearchResultText(item, meta);
                 return {
                     ...item,
-                    content: item.text || (typeof meta.text === "string" ? meta.text : ""),
+                    text,
+                    content: text,
                 };
             });
             if (legacyCall) {
@@ -87,10 +91,10 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
             const memoryResults = filteredResults.map((item) => {
                 const meta = parseMetadataJson(item);
                 const collection = typeof meta.collection === "string" ? meta.collection : "memory";
-                const effectiveText = item.text || (typeof meta.text === "string" ? meta.text : "") || "";
                 const relPath = encodeSearchResultPath(collection, item.id);
-                returnedSearchPaths.set(relPath, effectiveText);
-                return toMemorySearchResult(item);
+                const text = resolveSearchResultText(item, meta);
+                returnedSearchPaths.set(relPath, text);
+                return toMemorySearchResult(item, meta, text);
             });
             return memoryResults;
         },
@@ -134,8 +138,8 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
         },
     };
 }
-async function searchResolvedCollections(client, cfg, userId, sessionId, queryText, k) {
-    const collections = resolveSearchCollections(cfg, userId, sessionId);
+async function searchResolvedCollections(client, cfg, userId, sessionId, queryText, k, corpus) {
+    const collections = resolveSearchCollections(cfg, userId, sessionId, corpus);
     if (collections.length === 0) {
         return { results: [] };
     }
@@ -152,16 +156,21 @@ async function searchResolvedCollections(client, cfg, userId, sessionId, queryTe
             excludeByCollection: {},
         });
 }
-function resolveSearchCollections(cfg, userId, sessionId) {
+function resolveSearchCollections(cfg, userId, sessionId, corpus) {
+    if (corpus === "sessions") {
+        return sessionId ? [resolveSessionSearchCollection(cfg, sessionId)] : [];
+    }
+    const durableCollections = [resolveUserCollection(userId), "global"];
+    if (corpus === "memory") {
+        return durableCollections;
+    }
     if (cfg.crossSessionRecall === false) {
         return sessionId ? [resolveSessionSearchCollection(cfg, sessionId)] : [];
     }
-    const collections = [resolveUserCollection(userId), "global"];
     if (!sessionId) {
-        return collections;
+        return durableCollections;
     }
-    collections.unshift(resolveSessionSearchCollection(cfg, sessionId));
-    return collections;
+    return [resolveSessionSearchCollection(cfg, sessionId), ...durableCollections];
 }
 function resolveSessionSearchCollection(cfg, sessionId) {
     if (cfg.useSessionSummarySearchExperiment) {
@@ -184,6 +193,9 @@ function firstString(...values) {
     }
     return undefined;
 }
+function normalizeSearchCorpus(value) {
+    return value === "memory" || value === "sessions" ? value : "all";
+}
 function parseMetadataJson(item) {
     if (item.metadataJson && item.metadataJson.length > 0) {
         try {
@@ -195,16 +207,20 @@ function parseMetadataJson(item) {
     }
     return {};
 }
-function toMemorySearchResult(item) {
-    const meta = parseMetadataJson(item);
+function resolveSearchResultText(item, meta = parseMetadataJson(item)) {
+    if (typeof item.text === "string" && item.text.length > 0) {
+        return item.text;
+    }
+    return typeof meta.text === "string" ? meta.text : item.text;
+}
+function toMemorySearchResult(item, meta = parseMetadataJson(item), text = resolveSearchResultText(item, meta)) {
     const collection = typeof meta.collection === "string" ? meta.collection : "memory";
-    const effectiveText = item.text || (typeof meta.text === "string" ? meta.text : "") || "";
     return {
         path: encodeSearchResultPath(collection, item.id),
         startLine: 1,
-        endLine: Math.max(1, effectiveText.split("\n").length),
+        endLine: Math.max(1, text.split("\n").length),
         score: item.score,
-        snippet: effectiveText,
+        snippet: text,
         source: collection.startsWith("session:") || collection.startsWith("session_") ? "sessions" : "memory",
         citation: `${collection}:${item.id}`,
     };

package/dist/memory-tools.d.ts

@@ -0,0 +1,27 @@
+import type { ClientGetter } from "./plugin-runtime.js";
+import type { LoggerLike, PluginConfig } from "./types.js";
+type MemoryToolContext = {
+    agentId?: string;
+    sessionId?: string;
+    sessionKey?: string;
+};
+type ToolContent = {
+    type: "text";
+    text: string;
+};
+type ToolResult<TDetails> = {
+    content: ToolContent[];
+    details: TDetails;
+};
+type AgentTool = {
+    name: string;
+    label: string;
+    description: string;
+    parameters: unknown;
+    execute(toolCallId: string, params: unknown): Promise<ToolResult<unknown>>;
+};
+export declare function createLibraVdbMemoryTools(getClient: ClientGetter, cfg: PluginConfig, logger?: LoggerLike): {
+    createSearchTool(ctx?: MemoryToolContext): AgentTool;
+    createGetTool(ctx?: MemoryToolContext): AgentTool;
+};
+export {};

package/dist/memory-tools.js

@@ -0,0 +1,251 @@
+import { formatError } from "./format-error.js";
+import { buildMemoryRuntimeBridge } from "./memory-runtime.js";
+const MEMORY_SEARCH_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        query: {
+            type: "string",
+            description: "Semantic recall query for prior work, preferences, decisions, dates, people, todos, or session context.",
+        },
+        maxResults: {
+            type: "number",
+            minimum: 1,
+            maximum: 50,
+            description: "Maximum number of memory hits to return.",
+        },
+        minScore: {
+            type: "number",
+            minimum: 0,
+            maximum: 1,
+            description: "Minimum similarity score for returned hits.",
+        },
+        corpus: {
+            type: "string",
+            enum: ["memory", "wiki", "all", "sessions"],
+            description: "Corpus filter. LibraVDB serves memory/session hits; wiki is unsupported unless another plugin owns wiki tools.",
+        },
+    },
+    required: ["query"],
+};
+const MEMORY_GET_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        path: {
+            type: "string",
+            description: "A path returned by memory_search.",
+        },
+        from: {
+            type: "number",
+            minimum: 1,
+            description: "1-based starting line.",
+        },
+        lines: {
+            type: "number",
+            minimum: 1,
+            description: "Maximum number of lines to read.",
+        },
+        corpus: {
+            type: "string",
+            enum: ["memory", "wiki", "all"],
+            description: "Corpus filter. LibraVDB reads paths returned by memory_search.",
+        },
+    },
+    required: ["path"],
+};
+export function createLibraVdbMemoryTools(getClient, cfg, logger = console) {
+    const bridge = buildMemoryRuntimeBridge(getClient, cfg);
+    const managers = new Map();
+    async function getManager(ctx, purpose) {
+        const key = managerCacheKey(ctx);
+        let manager = managers.get(key);
+        if (!manager) {
+            manager = bridge
+                .getMemorySearchManager({
+                agentId: normalizeOptionalString(ctx.agentId),
+                purpose,
+            })
+                .then((result) => result.manager)
+                .catch((error) => {
+                managers.delete(key);
+                throw error;
+            });
+            managers.set(key, manager);
+        }
+        return await manager;
+    }
+    return {
+        createSearchTool(ctx = {}) {
+            return {
+                name: "memory_search",
+                label: "Memory Search",
+                description: "Mandatory fresh LibraVDB recall step: semantically search durable memory and session recall before answering questions about prior work, decisions, dates, people, preferences, todos, or history. Do not reuse prior transcript claims or older memory_search results for a new memory lookup. For earliest/oldest questions, request enough results and compare timestamps in snippets. If response has disabled=true, memory retrieval is unavailable and should be surfaced to the user.",
+                parameters: MEMORY_SEARCH_SCHEMA,
+                execute: async (_toolCallId, rawParams) => {
+                    const params = asToolParamsRecord(rawParams);
+                    const query = readRequiredStringParam(params, "query");
+                    const corpus = readMemoryCorpus(params.corpus);
+                    const maxResults = readNumberParam(params, "maxResults", { integer: true });
+                    const minScore = readNumberParam(params, "minScore");
+                    if (corpus === "wiki") {
+                        return jsonToolResult({
+                            results: [],
+                            disabled: true,
+                            error: "LibraVDB memory_search does not provide the wiki corpus; use corpus=memory, corpus=sessions, or corpus=all.",
+                        });
+                    }
+                    try {
+                        const manager = await getManager(ctx, "tool-search");
+                        const rawResults = await manager.search({
+                            query,
+                            corpus,
+                            ...(maxResults !== undefined ? { maxResults } : {}),
+                            ...(minScore !== undefined ? { minScore } : {}),
+                            ...buildSearchContext(ctx),
+                        });
+                        const results = filterResultsByCorpus(rawResults, corpus);
+                        const status = manager.status();
+                        return jsonToolResult({
+                            results,
+                            provider: status.provider,
+                            model: status.model,
+                            backend: status.backend,
+                        });
+                    }
+                    catch (error) {
+                        logger.warn?.(`LibraVDB memory_search failed: ${formatError(error)}`);
+                        return jsonToolResult({
+                            results: [],
+                            disabled: true,
+                            error: formatError(error),
+                        });
+                    }
+                },
+            };
+        },
+        createGetTool(ctx = {}) {
+            return {
+                name: "memory_get",
+                label: "Memory Get",
+                description: "Read a bounded exact excerpt from a LibraVDB memory path returned by memory_search. Use this after memory_search when a hit needs exact wording or more context.",
+                parameters: MEMORY_GET_SCHEMA,
+                execute: async (_toolCallId, rawParams) => {
+                    const params = asToolParamsRecord(rawParams);
+                    const relPath = readRequiredStringParam(params, "path");
+                    const corpus = readMemoryGetCorpus(params.corpus);
+                    const from = readNumberParam(params, "from", { integer: true });
+                    const lines = readNumberParam(params, "lines", { integer: true });
+                    if (corpus === "wiki") {
+                        return jsonToolResult({
+                            path: relPath,
+                            text: "",
+                            disabled: true,
+                            error: "LibraVDB memory_get does not provide the wiki corpus; use paths returned by LibraVDB memory_search.",
+                        });
+                    }
+                    try {
+                        const manager = await getManager(ctx, "tool-get");
+                        const result = await manager.readFile({
+                            relPath,
+                            ...(from !== undefined ? { from } : {}),
+                            ...(lines !== undefined ? { lines } : {}),
+                        });
+                        return jsonToolResult(result);
+                    }
+                    catch (error) {
+                        logger.warn?.(`LibraVDB memory_get failed: ${formatError(error)}`);
+                        return jsonToolResult({
+                            path: relPath,
+                            text: "",
+                            disabled: true,
+                            error: formatError(error),
+                        });
+                    }
+                },
+            };
+        },
+    };
+}
+function buildSearchContext(ctx) {
+    const agentId = normalizeOptionalString(ctx.agentId);
+    const sessionId = normalizeOptionalString(ctx.sessionId);
+    const sessionKey = normalizeOptionalString(ctx.sessionKey);
+    return {
+        ...(agentId ? { agentId } : {}),
+        ...(sessionId ? { sessionId } : {}),
+        ...(sessionKey ? { sessionKey } : {}),
+        context: {
+            ...(agentId ? { agentId } : {}),
+            ...(sessionId ? { sessionId } : {}),
+            ...(sessionKey ? { sessionKey } : {}),
+        },
+    };
+}
+function filterResultsByCorpus(results, corpus) {
+    if (corpus === "sessions") {
+        return results.filter((result) => result.source === "sessions");
+    }
+    if (corpus === "memory") {
+        return results.filter((result) => result.source === "memory");
+    }
+    return results;
+}
+function managerCacheKey(ctx) {
+    return [
+        normalizeOptionalString(ctx.agentId) ?? "",
+        normalizeOptionalString(ctx.sessionId) ?? "",
+        normalizeOptionalString(ctx.sessionKey) ?? "",
+    ].join("\0");
+}
+function asToolParamsRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function readRequiredStringParam(params, key) {
+    const value = normalizeOptionalString(params[key]);
+    if (!value) {
+        throw new Error(`memory tool requires ${key}`);
+    }
+    return value;
+}
+function readNumberParam(params, key, options = {}) {
+    const value = params[key];
+    const parsed = typeof value === "number"
+        ? value
+        : typeof value === "string" && value.trim().length > 0
+            ? Number(value)
+            : undefined;
+    if (parsed === undefined || !Number.isFinite(parsed)) {
+        return undefined;
+    }
+    return options.integer ? Math.max(1, Math.floor(parsed)) : parsed;
+}
+function readMemoryCorpus(value) {
+    return value === "memory" || value === "wiki" || value === "all" || value === "sessions"
+        ? value
+        : "all";
+}
+function readMemoryGetCorpus(value) {
+    return value === "memory" || value === "wiki" || value === "all" ? value : "memory";
+}
+function normalizeOptionalString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function jsonToolResult(details) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(details, null, 2),
+            },
+        ],
+        details,
+    };
+}

package/openclaw.plugin.json

@@ -2,14 +2,18 @@
   "id": "libravdb-memory",
   "name": "LibraVDB Memory",
   "description": "Persistent vector memory with three-tier hybrid scoring",
-  "version": "1.6.28",
+  "version": "1.6.30",
   "kind": [
     "memory",
     "context-engine"
   ],
   "contracts": {
     "memory": true,
-    "contextEngine": true
+    "contextEngine": true,
+    "tools": [
+      "memory_search",
+      "memory_get"
+    ]
   },
   "activation": {
     "onCommands": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.6.28",
+  "version": "1.6.30",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",