@xdarkicex/openclaw-memory-libravdb 1.3.13 → 1.3.17

package/src/index.ts

@@ -1,7 +1,9 @@
 import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
 import { registerMemoryCli } from "./cli.js";
 import { buildContextEngineFactory } from "./context-engine.js";
+import { createBeforeResetHook, createSessionEndHook } from "./lifecycle-hooks.js";
 import { buildMemoryPromptSection } from "./memory-provider.js";
+import { buildMemoryRuntimeBridge } from "./memory-runtime.js";
 import { createRecallCache } from "./recall-cache.js";
 import { createPluginRuntime } from "./plugin-runtime.js";
 import type { PluginConfig, SearchResult } from "./types.js";
@@ -21,7 +23,10 @@ export default definePluginEntry({
     api.registerContextEngine("libravdb-memory", () =>
       buildContextEngineFactory(runtime.getRpc, cfg, recallCache),
     );
-    api.registerMemoryPromptSection(buildMemoryPromptSection());
+    api.registerMemoryPromptSection(buildMemoryPromptSection(runtime.getRpc, cfg, recallCache));
+    api.registerMemoryRuntime?.(buildMemoryRuntimeBridge(runtime.getRpc, cfg));
+    api.on("before_reset", createBeforeResetHook(runtime, api.logger ?? console));
+    api.on("session_end", createSessionEndHook(runtime, api.logger ?? console));
     api.on("gateway_stop", () => runtime.shutdown());
   },
 });

package/src/lifecycle-hooks.ts

@@ -0,0 +1,96 @@
+import type { PluginRuntime } from "./plugin-runtime.js";
+import type { LoggerLike } from "./types.js";
+
+type AgentContext = {
+  agentId?: string;
+  sessionId?: string;
+  sessionKey?: string;
+  workspaceDir?: string;
+};
+
+type BeforeResetEvent = {
+  sessionFile?: string;
+  messages?: unknown[];
+  reason?: string;
+};
+
+type SessionEndEvent = {
+  sessionId?: string;
+  sessionKey?: string;
+  messageCount?: number;
+  durationMs?: number;
+  reason?: string;
+  sessionFile?: string;
+  transcriptArchived?: boolean;
+  nextSessionId?: string;
+  nextSessionKey?: string;
+};
+
+export function createBeforeResetHook(runtime: PluginRuntime, logger: LoggerLike = console) {
+  return async (event: unknown, ctx: unknown): Promise<void> => {
+    const typedEvent = asBeforeResetEvent(event);
+    const typedCtx = asAgentContext(ctx);
+    try {
+      await runtime.emitLifecycleHint({
+        hook: "before_reset",
+        reason: typedEvent.reason,
+        sessionFile: typedEvent.sessionFile,
+        sessionId: typedCtx.sessionId,
+        sessionKey: typedCtx.sessionKey,
+        agentId: typedCtx.agentId,
+        workspaceDir: typedCtx.workspaceDir,
+        messageCount: Array.isArray(typedEvent.messages) ? typedEvent.messages.length : undefined,
+      });
+    } catch (error) {
+      logger.warn?.(`LibraVDB before_reset hint failed: ${formatError(error)}`);
+    }
+  };
+}
+
+export function createSessionEndHook(runtime: PluginRuntime, logger: LoggerLike = console) {
+  return async (event: unknown, ctx: unknown): Promise<void> => {
+    const typedEvent = asSessionEndEvent(event);
+    const typedCtx = asAgentContext(ctx);
+    try {
+      await runtime.emitLifecycleHint({
+        hook: "session_end",
+        reason: typedEvent.reason,
+        sessionFile: typedEvent.sessionFile,
+        sessionId: typedEvent.sessionId ?? typedCtx.sessionId,
+        sessionKey: typedEvent.sessionKey ?? typedCtx.sessionKey,
+        agentId: typedCtx.agentId,
+        workspaceDir: typedCtx.workspaceDir,
+        messageCount: typedEvent.messageCount,
+        durationMs: typedEvent.durationMs,
+        transcriptArchived: typedEvent.transcriptArchived,
+        nextSessionId: typedEvent.nextSessionId,
+        nextSessionKey: typedEvent.nextSessionKey,
+      });
+    } catch (error) {
+      logger.warn?.(`LibraVDB session_end hint failed: ${formatError(error)}`);
+    }
+  };
+}
+
+function asAgentContext(value: unknown): AgentContext {
+  return isRecord(value) ? value as AgentContext : {};
+}
+
+function asBeforeResetEvent(value: unknown): BeforeResetEvent {
+  return isRecord(value) ? value as BeforeResetEvent : {};
+}
+
+function asSessionEndEvent(value: unknown): SessionEndEvent {
+  return isRecord(value) ? value as SessionEndEvent : {};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function formatError(error: unknown): string {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message;
+  }
+  return String(error);
+}

package/src/memory-provider.ts

@@ -1,24 +1,87 @@
-/**
- * Builds the memory prompt section for the agent system prompt.
- *
- * As of OpenClaw 2026.3.28 the MemoryPromptSectionBuilder contract changed:
- *   - Params: { availableTools: Set<string>, citationsMode?: string }
- *   - Return: string[]  (lines to splice into the system prompt)
- *
- * Heavy recall (per-query vector search, scoring, budget fitting) is handled
- * by the context engine's `assemble` hook, not here.  This builder only emits
- * a short static section that tells the model LibraVDB memory is active.
- */
-export function buildMemoryPromptSection(): (params: {
+import type { PluginConfig, RecallCache, SearchResult } from "./types.js";
+import type { RpcGetter } from "./plugin-runtime.js";
+import { scoreCandidates } from "./scoring.js";
+import { fitPromptBudget } from "./tokens.js";
+import { buildMemoryHeader } from "./recall-utils.js";
+
+const MEMORY_PROMPT_BUDGET = 800;
+
+export function buildMemoryPromptSection(
+  getRpc: RpcGetter,
+  cfg: PluginConfig,
+  recallCache: RecallCache<SearchResult>,
+): (params: {
   availableTools: Set<string>;
   citationsMode?: string;
-}) => string[] {
-  return function memoryPromptSection(_params) {
-    return [
+  messages?: Array<{ role: string; content: string }>;
+  userId?: string;
+}) => Promise<string[]> {
+  return async function memoryPromptSection(params: {
+    availableTools: Set<string>;
+    citationsMode?: string;
+    messages?: Array<{ role: string; content: string }>;
+    userId?: string;
+  }): Promise<string[]> {
+    const queryText = params.messages?.at(-1)?.content ?? "";
+    const userId = params.userId ?? "default";
+
+    if (!queryText) {
+      return [
+        "## Memory",
+        "LibraVDB persistent memory is active. Recalled memories will appear",
+        "in context via the context-engine assembler when relevant.",
+        "",
+      ];
+    }
+
+    const rpc = await getRpc();
+
+    const [userHitsResult, globalHitsResult] = await Promise.all([
+      rpc.call<{ results: SearchResult[] }>("search_text", {
+        collection: `user:${userId}`,
+        text: queryText,
+        k: Math.ceil((cfg.topK ?? 8) / 2),
+      }),
+      rpc.call<{ results: SearchResult[] }>("search_text", {
+        collection: "global",
+        text: queryText,
+        k: Math.ceil((cfg.topK ?? 8) / 4),
+      }),
+    ]);
+
+    const userHits = userHitsResult.results;
+    const globalHits = globalHitsResult.results;
+
+    recallCache.put({
+      userId,
+      queryText,
+      durableVariantHits: [],
+      userHits,
+      globalHits,
+    });
+
+    const ranked = scoreCandidates([...userHits, ...globalHits], {
+      alpha: cfg.alpha,
+      beta: cfg.beta,
+      gamma: cfg.gamma,
+      sessionId: "",
+      userId,
+    });
+
+    const selected = fitPromptBudget(ranked, MEMORY_PROMPT_BUDGET);
+    const recallHeader = buildMemoryHeader(selected);
+
+    const lines: string[] = [
       "## Memory",
       "LibraVDB persistent memory is active. Recalled memories will appear",
       "in context via the context-engine assembler when relevant.",
-      "",
     ];
+
+    if (recallHeader) {
+      lines.push(...recallHeader.split("\n"));
+    }
+
+    lines.push("");
+    return lines;
   };
-}
+}

package/src/memory-runtime.ts

@@ -0,0 +1,150 @@
+import type { RpcGetter } from "./plugin-runtime.js";
+import type { PluginConfig, SearchResult } from "./types.js";
+
+type MemorySearchParams = {
+  query?: string;
+  text?: string;
+  input?: string;
+  q?: string;
+  k?: number;
+  limit?: number;
+  topK?: number;
+  userId?: string;
+  agentId?: string;
+  sessionId?: string;
+  context?: {
+    userId?: string;
+    agentId?: string;
+    sessionId?: string;
+  };
+};
+
+type MemoryRuntimeStatus = {
+  ok?: boolean;
+  message?: string;
+  turnCount?: number;
+  memoryCount?: number;
+  gatingThreshold?: number;
+  abstractiveReady?: boolean;
+  embeddingProfile?: string;
+};
+
+export function buildMemoryRuntimeBridge(getRpc: RpcGetter, cfg: PluginConfig) {
+  return {
+    async getMemorySearchManager(params: { agentId?: string; purpose?: string } = {}) {
+      return {
+        manager: createMemorySearchManager(getRpc, cfg, params),
+      };
+    },
+    resolveMemoryBackendConfig() {
+      // We keep retrieval inside the plugin-side sidecar rather than delegating to
+      // OpenClaw's external QMD path.
+      return { backend: "builtin" };
+    },
+    async closeAllMemorySearchManagers() {
+      // Context-engine lifecycle cleanup still happens through gateway_stop.
+    },
+  };
+}
+
+function createMemorySearchManager(
+  getRpc: RpcGetter,
+  cfg: PluginConfig,
+  defaults: { agentId?: string; purpose?: string },
+) {
+  return {
+    async search(params: MemorySearchParams = {}) {
+      const queryText = firstString(params.query, params.text, params.input, params.q);
+      if (!queryText) {
+        return { results: [], error: "Missing query text for LibraVDB memory search" };
+      }
+
+      const userId = firstString(
+        params.userId,
+        params.context?.userId,
+        params.agentId,
+        params.context?.agentId,
+        defaults.agentId,
+        "default",
+      )!;
+      const sessionId = firstString(params.sessionId, params.context?.sessionId);
+      const k = normalizePositiveInteger(params.k, params.limit, params.topK, cfg.topK, 8);
+      const collections = resolveSearchCollections(cfg, userId, sessionId);
+      const rpc = await getRpc();
+
+      const result = collections.length === 1
+        ? await rpc.call<{ results: SearchResult[] }>("search_text", {
+            collection: collections[0],
+            text: queryText,
+            k,
+          })
+        : await rpc.call<{ results: SearchResult[] }>("search_text_collections", {
+            collections,
+            text: queryText,
+            k,
+            excludeByCollection: {},
+          });
+
+      return {
+        results: result.results.map((item) => ({
+          ...item,
+          content: item.text,
+        })),
+      };
+    },
+    async ingest() {
+      // The plugin already owns per-turn ingest through the context engine.
+      return { ingested: false, delegatedToContextEngine: true };
+    },
+    async sync() {
+      // Projections and compaction sync are already handled inside the existing
+      // context-engine lifecycle.
+      return { synced: true, delegatedToContextEngine: true };
+    },
+    async status() {
+      const rpc = await getRpc();
+      const status = await rpc.call<MemoryRuntimeStatus>("status", {});
+      return {
+        ok: status.ok ?? false,
+        message: status.message ?? "ok",
+        turnCount: status.turnCount ?? 0,
+        memoryCount: status.memoryCount ?? 0,
+        gatingThreshold: status.gatingThreshold,
+        abstractiveReady: status.abstractiveReady ?? false,
+        embeddingProfile: status.embeddingProfile ?? "unknown",
+        purpose: defaults.purpose,
+      };
+    },
+  };
+}
+
+function resolveSearchCollections(cfg: PluginConfig, userId: string, sessionId?: string): string[] {
+  const collections = [`user:${userId}`, "global"];
+  if (!sessionId) {
+    return collections;
+  }
+
+  if (cfg.useSessionSummarySearchExperiment) {
+    collections.unshift(`session_summary:${sessionId}`);
+    return collections;
+  }
+  if (cfg.useSessionRecallProjection) {
+    collections.unshift(`session_recall:${sessionId}`);
+    return collections;
+  }
+  collections.unshift(`session:${sessionId}`);
+  return collections;
+}
+
+function firstString(...values: Array<string | undefined>): string | undefined {
+  return values.find((value) => typeof value === "string" && value.length > 0);
+}
+
+function normalizePositiveInteger(...values: Array<number | undefined>): number {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+      return Math.max(1, Math.floor(value));
+    }
+  }
+  return 8;
+}

package/src/openclaw-plugin-sdk.d.ts

@@ -21,6 +21,7 @@ declare module "openclaw/plugin-sdk/plugin-entry" {
     registerMemoryPromptSection(builder: unknown): void;
     registerMemoryFlushPlan?(resolver: unknown): void;
     registerMemoryRuntime?(runtime: unknown): void;
+    registerMemoryEmbeddingProvider?(provider: unknown): void;
     registerCli?(
       builder: (ctx: { program: OpenClawCliCommand }) => void,
       opts?: {

package/src/plugin-runtime.ts

@@ -1,12 +1,28 @@
 import { RpcClient } from "./rpc.js";
-import { startSidecar } from "./sidecar.js";
+import { daemonProvisioningHint, startSidecar } from "./sidecar.js";
 import type { LoggerLike, PluginConfig, SidecarHandle } from "./types.js";
 
 export type RpcGetter = () => Promise<RpcClient>;
 export const DEFAULT_RPC_TIMEOUT_MS = 30000;
 
+export interface LifecycleHint {
+  hook: "before_reset" | "session_end";
+  reason?: string;
+  sessionFile?: string;
+  sessionId?: string;
+  sessionKey?: string;
+  agentId?: string;
+  workspaceDir?: string;
+  messageCount?: number;
+  durationMs?: number;
+  transcriptArchived?: boolean;
+  nextSessionId?: string;
+  nextSessionKey?: string;
+}
+
 export interface PluginRuntime {
   getRpc: RpcGetter;
+  emitLifecycleHint(hint: LifecycleHint): Promise<void>;
   shutdown(): Promise<void>;
 }
 
@@ -27,19 +43,19 @@ export function createPluginRuntime(
         const rpc = new RpcClient(sidecar.socket, {
           timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
         });
-        const health = await rpc.call<{ ok?: boolean }>("health", {});
+        const health = await rpc.call<{ ok?: boolean; message?: string }>("health", {});
         if (!health.ok) {
           try {
             await sidecar.shutdown();
           } catch {
             // Ignore cleanup failure on startup rejection.
           }
-          throw new Error("LibraVDB daemon failed health check");
+          throw enrichStartupError("LibraVDB daemon failed health check", health.message);
         }
         return { rpc, sidecar };
       })().catch((error) => {
         started = null;
-        throw error;
+        throw enrichStartupError(error);
       });
     }
     return await started;
@@ -49,6 +65,14 @@ export function createPluginRuntime(
     async getRpc() {
       return (await ensureStarted()).rpc;
     },
+    async emitLifecycleHint(hint: LifecycleHint) {
+      try {
+        const active = await ensureStarted();
+        await active.rpc.call("session_lifecycle_hint", hint);
+      } catch (error) {
+        logger.warn?.(`LibraVDB lifecycle hint dropped: ${formatError(error)}`);
+      }
+    },
     async shutdown() {
       stopped = true;
       if (!started) {
@@ -65,3 +89,28 @@ export function createPluginRuntime(
     },
   };
 }
+
+function formatError(error: unknown): string {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message;
+  }
+  return String(error);
+}
+
+export function enrichStartupError(error: unknown, healthMessage?: string): Error {
+  const rawMessage = error instanceof Error ? error.message : String(error);
+  const message = rawMessage.trim() || "LibraVDB daemon startup failed";
+  if (message.includes("install and start libravdbd separately") || message.includes("package does not provision the daemon binary")) {
+    return error instanceof Error ? error : new Error(message);
+  }
+  const shouldHint = /health check|daemon unavailable|connection refused|ECONNREFUSED|ENOENT|fallback mode|ONNX Runtime|embedder/i.test(
+    `${message} ${healthMessage ?? ""}`,
+  );
+  if (!shouldHint) {
+    return error instanceof Error ? error : new Error(message);
+  }
+
+  const detail = healthMessage?.trim();
+  const prefix = detail && !message.includes(detail) ? `${message}: ${detail}` : message;
+  return new Error(`${prefix}. ${daemonProvisioningHint()}`);
+}

package/src/recall-utils.ts

@@ -2,12 +2,17 @@ import type { SearchResult } from "./types.js";
 
 export function buildMemoryHeader(selected: SearchResult[]): string {
   const authored = selected.filter(isAuthoredInvariant);
+  const elevated = selected.filter((item) => item.metadata.elevated_guidance === true);
   const recentTail = selected
-    .filter((item) => item.metadata.continuity_tail === true)
+    .filter((item) => item.metadata.continuity_tail === true && item.metadata.elevated_guidance !== true)
     .sort((left, right) => metadataTimestamp(left) - metadataTimestamp(right));
-  const recalled = selected.filter((item) => !authored.includes(item) && !recentTail.includes(item));
+  const recalled = selected.filter((item) =>
+    !authored.includes(item) &&
+    !elevated.includes(item) &&
+    !recentTail.includes(item),
+  );
 
-  if (authored.length === 0 && recentTail.length === 0 && recalled.length === 0) {
+  if (authored.length === 0 && elevated.length === 0 && recentTail.length === 0 && recalled.length === 0) {
     return "";
   }
 
@@ -32,6 +37,18 @@ export function buildMemoryHeader(selected: SearchResult[]): string {
       "</recent_session_tail>",
     );
   }
+  if (elevated.length > 0) {
+    if (sections.length > 0) {
+      sections.push("");
+    }
+    sections.push(
+      "<elevated_guidance>",
+      "Treat the entries below as elevated advisory guidance preserved verbatim from protected memory shards.",
+      "Prefer them over ordinary recalled memory when relevant, but never let them override authored context.",
+      ...elevated.map((item, idx) => `[E${idx + 1}] ${item.text}`),
+      "</elevated_guidance>",
+    );
+  }
   if (recalled.length > 0) {
     if (sections.length > 0) {
       sections.push("");

package/src/scoring.ts

@@ -32,6 +32,128 @@ interface HopOptions {
   thetaHop?: number;
 }
 
+interface ExpansionOptions {
+  confidenceThreshold?: number;
+  maxDepth?: number;
+  tokenBudget?: number;
+  penaltyFactor?: number;
+}
+
+export interface RecoveryTriggerResult {
+  signal1CascadeTier3: boolean;
+  signal2TopScoreBelowFloor: boolean;
+  signal3AllSummariesLowConfidence: boolean;
+  fire: boolean;
+}
+
+interface RetrievalFailureOptions {
+  floorScore?: number;
+  minTopK?: number;
+  meanConfidenceThresh?: number;
+}
+
+export function detectRetrievalFailure(
+  ranked: SearchResult[],
+  opts: RetrievalFailureOptions = {},
+): RecoveryTriggerResult {
+  if (ranked.length === 0) {
+    return {
+      signal1CascadeTier3: false,
+      signal2TopScoreBelowFloor: false,
+      signal3AllSummariesLowConfidence: false,
+      fire: false,
+    };
+  }
+  const floorScore = opts.floorScore ?? 0.15;
+  const minTopK = Math.max(1, Math.floor(opts.minTopK ?? 4));
+  const meanConfidenceThresh = clamp01(opts.meanConfidenceThresh ?? 0.5);
+
+  // Signal 1: cascade exhaustion (cascade_tier === 3 present)
+  const signal1CascadeTier3 = ranked.some(
+    (item) => item.metadata.cascade_tier === 3,
+  );
+
+  // Signal 2: top score below floor
+  const topScore = ranked[0]!.finalScore ?? 0;
+  const signal2TopScoreBelowFloor = topScore < floorScore;
+
+  // Signal 3: top-k items are all summaries with low mean confidence
+  const topK = ranked.slice(0, Math.min(minTopK, ranked.length));
+  const allSummaries = topK.length > 0 && topK.every((item) => item.metadata.type === "summary");
+  const meanConfidence =
+    allSummaries && topK.length > 0
+      ? topK.reduce(
+          (sum, item) => sum + (typeof item.metadata.confidence === "number" ? item.metadata.confidence : 0),
+          0,
+        ) / topK.length
+      : NaN;
+  const signal3AllSummariesLowConfidence =
+    allSummaries && topK.length >= minTopK && meanConfidence < meanConfidenceThresh;
+
+  // Composite: (S1 AND S2) OR S3
+  const fire = (signal1CascadeTier3 && signal2TopScoreBelowFloor) || signal3AllSummariesLowConfidence;
+
+  return {
+    signal1CascadeTier3,
+    signal2TopScoreBelowFloor,
+    signal3AllSummariesLowConfidence,
+    fire,
+  };
+}
+
+export function expandSummaryCandidates(
+  items: SearchResult[],
+  expandFn: (sessionId: string, summaryId: string, maxDepth: number) => Promise<SearchResult[]>,
+  sessionId: string,
+  opts: ExpansionOptions,
+): Promise<SearchResult[]> {
+  const confidenceThreshold = opts.confidenceThreshold ?? 0.7;
+  const maxDepth = opts.maxDepth ?? 2;
+  const penaltyFactor = opts.penaltyFactor ?? 0.85;
+  const tokenBudget = typeof opts.tokenBudget === "number" ? Math.max(0, opts.tokenBudget) : Number.POSITIVE_INFINITY;
+
+  return (async () => {
+    const out: SearchResult[] = [];
+    let remainingBudget = tokenBudget;
+
+    for (const summary of items) {
+      const conf = typeof summary.metadata.confidence === "number" ? summary.metadata.confidence : 0;
+      if (summary.metadata.type !== "summary" || conf < confidenceThreshold) {
+        continue;
+      }
+      if (Number.isFinite(tokenBudget) && remainingBudget <= 0) {
+        break;
+      }
+
+      const rawChildren = await expandFn(sessionId, summary.id, maxDepth);
+      for (const child of rawChildren) {
+        const cost = childTokenCost(child);
+        if (!Number.isFinite(cost)) {
+          continue;
+        }
+        if (Number.isFinite(tokenBudget) && cost > remainingBudget) {
+          continue;
+        }
+        if (Number.isFinite(tokenBudget)) {
+          remainingBudget -= cost;
+        }
+        out.push({
+          ...child,
+          metadata: {
+            ...child.metadata,
+            expanded_from_summary: true,
+            parent_summary_id: summary.id,
+            expansion_depth: (typeof summary.metadata.expansion_depth === "number" ? summary.metadata.expansion_depth : 0) + 1,
+          },
+          finalScore: clamp01((child.finalScore ?? child.score) * penaltyFactor),
+        });
+      }
+    }
+
+    return out;
+  })();
+}
+
 export function mergeSection7VariantCandidates(
   ranked: SearchResult[],
   hopExpanded: SearchResult[],
@@ -178,6 +300,14 @@ function clamp01(value: number): number {
   return Math.min(1, Math.max(0, value));
 }
 
+function childTokenCost(item: SearchResult): number {
+  const estimate = item.metadata.token_estimate;
+  if (typeof estimate === "number" && Number.isFinite(estimate) && estimate > 0) {
+    return Math.max(1, Math.floor(estimate));
+  }
+  return Number.POSITIVE_INFINITY;
+}
+
 function clampSimilarity(value: number): number {
   return Math.min(1, Math.max(-1, value));
 }