@xdarkicex/openclaw-memory-libravdb 1.3.18 → 1.3.20

package/README.md

@@ -131,7 +131,7 @@ If your daemon runs elsewhere, set an explicit `sidecarPath`, for example:
 
 ```text
 OpenClaw host
-  -> memoryPromptSection (durable user/global recall)
+  -> memoryPromptSection (static capability header)
   -> memory runtime bridge (built-in memory_search)
   -> context engine (bootstrap / ingest / assemble / compact)
   -> plugin runtime

package/docs/architecture.md

@@ -10,7 +10,7 @@ repository as of the current `main` branch.
 flowchart LR
   Host["OpenClaw host process\n(TypeScript plugin shell)"]
   CE["Context engine factory\nbootstrap / ingest / assemble / compact"]
-  MPS["memoryPromptSection\nuser+global recall"]
+  MPS["memoryPromptSection\nstatic header"]
   Runtime["Plugin runtime\nlazy daemon connect + RPC client"]
   Sidecar["Go daemon process"]
   RPC["JSON-RPC over newline-delimited frames\nUnix socket or TCP loopback on Windows"]
@@ -28,7 +28,6 @@ flowchart LR
   Host --> CE
   Host --> MPS
   CE --> Runtime
-  MPS --> Runtime
   Runtime --> RPC
   RPC --> Sidecar
   Sidecar --> Embed
@@ -80,17 +79,12 @@ Important constraints from the current implementation:
 
 Implemented in [`src/memory-provider.ts`](../src/memory-provider.ts).
 
-Before the main assembly path runs, the plugin builds a lightweight recall
-section:
+Before the main assembly path runs, the plugin returns a lightweight static
+header fragment that tells the host persistent memory is active.
 
-1. search `user:<userId>`
-2. search `global`
-3. hybrid-rank the combined hits
-4. fit them to a fixed prompt budget of `800` estimated tokens
-5. return a textual header fragment for the host prompt
-
-This path does not search session memory. Its job is durable context recall, not
-active-turn recall.
+This path is intentionally synchronous and does not perform RPC retrieval.
+Durable recall now happens entirely inside `assemble`, which keeps embedded
+prompt construction compatible with OpenClaw's synchronous memory prompt hook.
 
 ### 2.3 `assemble`
 
@@ -107,7 +101,7 @@ For the current query text (last message content), the host:
 
 Current implementation details that matter:
 
-- user/global hits may be reused from the earlier prompt-section cache
+- user/global hits are cached within `assemble` and reused on repeated queries
 - `assemble` falls back to the unmodified message list on RPC failure
 - `assemble` does not mutate the original `messages` array in place; it returns
   a new array
@@ -146,7 +140,7 @@ from the original spec phrasing.
 |---|---|---|
 | Daemon unavailable on first RPC use | `getRpc()` rejects when first connect or health check fails | That hook fails or falls back, but plugin registration itself does not crash eagerly |
 | Daemon connection closes mid-session | `SidecarSupervisor` retries with exponential backoff until retry budget is exhausted, then enters degraded mode | Memory becomes unavailable until the daemon is reachable again |
-| `memoryPromptSection` RPC failure | individual searches are caught and replaced with empty result sets | Prompt section becomes empty rather than crashing the run |
+| `memoryPromptSection` failure | returns a static header with no RPC dependency | Prompt section stays available and does not block the run |
 | `assemble` RPC failure | returns original messages, original token count, and empty `systemPromptAddition` | That turn gets no recall augmentation |
 | `ingest` gating or durable insert failure | session write already happened; durable promotion is skipped | Session memory survives, durable memory may miss that turn |
 | Compaction summarizer unavailable | extractive summarizer remains required; optional abstractive path is skipped | Compaction still runs extractively when extractive is healthy |

package/docs/implementation.md

@@ -18,8 +18,8 @@ Why:
   - `ingest`
   - `assemble`
   - `compact`
-- the lightweight memory prompt section remains useful as a separate early
-  durable-recall pass
+- the lightweight memory prompt section remains useful as a synchronous
+  capability/header hook while durable recall stays in `assemble`
 
 This is why the code registers both `registerContextEngine("libravdb-memory", …)`
 and `registerMemoryPromptSection(...)` instead of relying on only one hook.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.3.18",
+  "version": "1.3.20",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/packaging/homebrew/libravdbd.rb.tmpl

@@ -26,18 +26,18 @@ class Libravdbd < Formula
   if OS.mac?
     resource "onnxruntime" do
       url "https://github.com/microsoft/onnxruntime/releases/download/v1.23.0/onnxruntime-osx-universal2-1.23.0.tgz"
-      sha256 :no_check
+      sha256 "5e4365fb4a05aef353f6232b9a1848f37e608c421c9227e9224572205c0cfc08"
     end
   elsif OS.linux?
     if Hardware::CPU.arm?
       resource "onnxruntime" do
         url "https://github.com/microsoft/onnxruntime/releases/download/v1.23.0/onnxruntime-linux-aarch64-1.23.0.tgz"
-        sha256 :no_check # TODO: pin real checksum when Linux ARM64 CI is available
+        sha256 "0b9f47d140411d938e47915824d8daaa424df95a88b5f1fc843172a75168f7a0"
       end
     else
       resource "onnxruntime" do
         url "https://github.com/microsoft/onnxruntime/releases/download/v1.23.0/onnxruntime-linux-x64-1.23.0.tgz"
-        sha256 :no_check # TODO: pin real checksum when Linux AMD64 CI is available
+        sha256 "b6deea7f2e22c10c043019f294a0ea4d2a6c0ae52a009c34847640db75ec5580"
       end
     end
   end

package/src/context-engine.ts

@@ -7,6 +7,7 @@ import {
 import {
   detectRetrievalFailure,
   expandSection7HopCandidates,
+  rankRawUserRecoveryCandidates,
   mergeSection7VariantCandidates,
   rankSection7VariantCandidates,
 } from "./scoring.js";
@@ -179,6 +180,7 @@ export function buildContextEngineFactory(
     },
     async assemble({ sessionId, userId, messages, tokenBudget }: ContextAssembleArgs) {
       const PROFILE = process.env.OPENCLAW_PROFILE_ASSEMBLE === "1";
+      const DEBUG_RECOVERY = process.env.LONGMEMEVAL_DEBUG_RANKING === "1";
 
       const queryText = messages.at(-1)?.content ?? "";
       if (!queryText) {
@@ -256,6 +258,7 @@ export function buildContextEngineFactory(
           messages,
           tokenBudget,
           profiler,
+          debugRecovery: DEBUG_RECOVERY,
         });
 
         const profileLines = profiler?.lines() ?? [];
@@ -289,6 +292,7 @@ export function buildContextEngineFactory(
       messages,
       tokenBudget,
       profiler,
+      debugRecovery,
     }: {
       rpc: Awaited<ReturnType<RpcGetter>>;
       cfg: PluginConfig;
@@ -304,6 +308,7 @@ export function buildContextEngineFactory(
       messages: Array<{ role: string; content: string }>;
       tokenBudget: number;
       profiler: { mark(label: string): void; emit(): void } | null;
+      debugRecovery: boolean;
     }): Promise<ContextAssembleResult> {
       const memoryBudget = tokenBudget * (cfg.tokenBudgetFraction ?? 0.25);
       const hardItems = authoredHard;
@@ -517,7 +522,10 @@ export function buildContextEngineFactory(
         minTopK: cfg.recoveryMinTopK ?? 4,
         meanConfidenceThresh: cfg.recoveryMinConfidenceMean ?? 0.5,
       });
-      const recoveryReserveTokens = recoveryTrigger.fire
+      const crossSessionRawRecovery =
+        rawSessionTurns.length === 0 &&
+        sessionHits.results.length === 0;
+      const recoveryReserveTokens = (recoveryTrigger.fire || crossSessionRawRecovery)
         ? Math.min(memoryBudget, Math.max(Math.floor(memoryBudget * 0.10), 16), 128)
         : 0;
       const elevatedGuidanceBudget = Math.max(
@@ -553,26 +561,83 @@ export function buildContextEngineFactory(
       // Recovery is a policy overlay — it appends raw content only when triggered,
       // it never modifies the C_total(q) output and does not spend from tau_V.
       let recoveryItems: SearchResult[] = [];
-      if (recoveryTrigger.fire) {
+      let rawUserRecoveryDebug: NonNullable<NonNullable<ContextAssembleResult["_debug"]>["rawUserRecoveryCandidates"]> = [];
+      if (recoveryTrigger.fire || crossSessionRawRecovery) {
         profiler?.mark("recovery_expand");
-        // Recovery searches immutable raw history directly — never the active view, elevated shards,
-        // or authored collections. Raw turns are immutable (storage axiom, unchanged).
         const recoveryExcludeIDs = [...excluded, ...recentTailIDs, ...theoremSelectedIDs];
-        const rawResults = await rpc.call<{ results: SearchResult[] }>("query_raw_session", {
-          sessionId,
-          text: queryText,
-          k: Math.max(cfg.topK ?? 8, 4),
-          excludeIds: recoveryExcludeIDs,
-        });
-        // Fit recovered raw items to the reserved recovery budget — never exceed it.
-        const fittedRecovery = fitPromptBudget(rawResults.results ?? [], recoveryReserveTokens);
-        recoveryItems = fittedRecovery.map((item: SearchResult) => ({
-          ...item,
-          metadata: {
-            ...item.metadata,
-            recovery_fallback: true,
-          },
-        }));
+        const recoveryCandidates: SearchResult[] = [];
+
+        if (recoveryTrigger.fire) {
+          // Recovery searches immutable raw session history directly — never the active view,
+          // elevated shards, or authored collections.
+          const rawResults = await rpc.call<{ results: SearchResult[] }>("query_raw_session", {
+            sessionId,
+            text: queryText,
+            k: Math.max(cfg.topK ?? 8, 4),
+            excludeIds: recoveryExcludeIDs,
+          });
+          recoveryCandidates.push(
+            ...(rawResults.results ?? []).map((item) => ({
+              ...item,
+              finalScore: typeof item.finalScore === "number" ? item.finalScore : item.score,
+              metadata: {
+                ...item.metadata,
+                recovery_fallback: true,
+                recovery_scope: "session_raw",
+              },
+            })),
+          );
+        }
+
+        if (crossSessionRawRecovery) {
+          // When a fresh query session has no searchable history yet, durable memory can be too
+          // coarse for exact-turn recall. Search the immutable per-user raw turn index instead of
+          // widening topK so precise historical turns still have a bounded path back into context.
+          const rawUserResults = await rpc.call<{ results: SearchResult[] }>("search_text", {
+            collection: `turns:${userId}`,
+            text: queryText,
+            k: Math.max((cfg.topK ?? 8) * 4, 8),
+            excludeIds: recoveryExcludeIDs,
+          });
+          const reranked = rankRawUserRecoveryCandidates(
+            annotateCollection(rawUserResults.results ?? [], `turns:${userId}`),
+            { queryText },
+          );
+          if (debugRecovery) {
+            rawUserRecoveryDebug = reranked.debug.slice(0, 8).map((item) => ({
+              ...item,
+              selected: false,
+            }));
+          }
+          recoveryCandidates.push(
+            ...reranked.ranked.map((item) => ({
+              ...item,
+              finalScore: typeof item.finalScore === "number" ? item.finalScore : item.score,
+              metadata: {
+                ...item.metadata,
+                recovery_fallback: true,
+                recovery_scope: "user_turns",
+              },
+            })),
+          );
+        }
+
+        const fittedRecovery = fitPromptBudget(
+          dedupeRecoveryCandidates(recoveryCandidates),
+          recoveryReserveTokens,
+        );
+        recoveryItems = fittedRecovery;
+        if (debugRecovery && rawUserRecoveryDebug.length > 0) {
+          const selectedIDs = new Set(
+            fittedRecovery
+              .filter((item) => item.metadata.recovery_scope === "user_turns")
+              .map((item: SearchResult) => item.id),
+          );
+          rawUserRecoveryDebug = rawUserRecoveryDebug.map((item) => ({
+            ...item,
+            selected: selectedIDs.has(item.id),
+          }));
+        }
       }
 
       const selected = [
@@ -598,6 +663,13 @@ export function buildContextEngineFactory(
         messages: [...selectedMessages, ...messages],
         estimatedTokens: countTokens(selectedMessages) + countTokens(messages),
         systemPromptAddition: buildMemoryHeader(selected),
+        _debug: debugRecovery
+          ? {
+              recoveryTriggerFired: recoveryTrigger.fire,
+              crossSessionRawRecovery,
+              rawUserRecoveryCandidates: rawUserRecoveryDebug,
+            }
+          : undefined,
       };
     },
     async compact({ sessionId, force, targetSize }: ContextCompactArgs) {
@@ -836,6 +908,19 @@ function groupAccessCountUpdates(items: SearchResult[]): Array<{ collection: str
   return [...grouped.entries()].map(([collection, ids]) => ({ collection, ids }));
 }
 
+function dedupeRecoveryCandidates(items: SearchResult[]): SearchResult[] {
+  const byKey = new Map<string, SearchResult>();
+  for (const item of items) {
+    const collection = typeof item.metadata.collection === "string" ? item.metadata.collection : "";
+    const key = `${collection}::${item.id}`;
+    const existing = byKey.get(key);
+    if (!existing || (item.finalScore ?? item.score) > (existing.finalScore ?? existing.score)) {
+      byKey.set(key, item);
+    }
+  }
+  return [...byKey.values()].sort((left, right) => (right.finalScore ?? right.score) - (left.finalScore ?? left.score));
+}
+
 function clampFraction(value: number | undefined): number {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     return 0;

package/src/memory-provider.ts

@@ -1,87 +1,25 @@
+import type { MemoryPromptSectionBuilder } from "openclaw/plugin-sdk/plugin-entry";
 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;
+const MEMORY_PROMPT_HEADER = [
+  "## Memory",
+  "LibraVDB persistent memory is configured. Recalled memories may appear",
+  "in context via the context-engine assembler when available and relevant.",
+  "",
+] as const;
 
 export function buildMemoryPromptSection(
-  getRpc: RpcGetter,
-  cfg: PluginConfig,
-  recallCache: RecallCache<SearchResult>,
-): (params: {
-  availableTools: Set<string>;
-  citationsMode?: string;
-  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;
+  _getRpc: RpcGetter,
+  _cfg: PluginConfig,
+  _recallCache: RecallCache<SearchResult>,
+): MemoryPromptSectionBuilder {
+  return function memoryPromptSection({
+    availableTools: _availableTools,
+    citationsMode: _citationsMode,
+  }): string[] {
+    // 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];
   };
-}
+}

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

@@ -1,4 +1,9 @@
 declare module "openclaw/plugin-sdk/plugin-entry" {
+  export type MemoryPromptSectionBuilder = (params: {
+    availableTools: Set<string>;
+    citationsMode?: string;
+  }) => string[];
+
   interface OpenClawCliCommand {
     commands?: OpenClawCliCommand[];
     command(name: string): OpenClawCliCommand;
@@ -18,7 +23,7 @@ declare module "openclaw/plugin-sdk/plugin-entry" {
       warn?(message: string): void;
     };
     registerContextEngine(id: string, factory: () => unknown): void;
-    registerMemoryPromptSection(builder: unknown): void;
+    registerMemoryPromptSection(builder: MemoryPromptSectionBuilder): void;
     registerMemoryFlushPlan?(resolver: unknown): void;
     registerMemoryRuntime?(runtime: unknown): void;
     registerMemoryEmbeddingProvider?(provider: unknown): void;

package/src/scoring.ts

@@ -32,6 +32,22 @@ interface HopOptions {
   thetaHop?: number;
 }
 
+interface RawUserRecoveryOptions {
+  queryText: string;
+  nowMs?: number;
+  recencyLambda?: number;
+}
+
+export interface RawUserRecoveryDebugCandidate {
+  id: string;
+  text: string;
+  semanticScore: number;
+  lexicalCoverage: number;
+  recencyScore: number;
+  finalScore: number;
+  rationale: string;
+}
+
 interface ExpansionOptions {
   confidenceThreshold?: number;
   maxDepth?: number;
@@ -296,6 +312,61 @@ export function expandSection7HopCandidates(
     .sort((left, right) => (right.finalScore ?? 0) - (left.finalScore ?? 0));
 }
 
+export function rankRawUserRecoveryCandidates(
+  items: SearchResult[],
+  opts: RawUserRecoveryOptions,
+): { ranked: SearchResult[]; debug: RawUserRecoveryDebugCandidate[] } {
+  const now = opts.nowMs ?? Date.now();
+  const recencyLambda = Math.max(0, opts.recencyLambda ?? 0.00001);
+  const keywords = extractKeywords(opts.queryText);
+
+  const ranked = items
+    .map((item) => {
+      const semanticScore = clamp01(typeof item.score === "number" ? item.score : 0);
+      const lexicalCoverage = normalizedKeywordCoverage(keywords, item.text);
+      const recencyScore = computeRecencyScore(item, now, recencyLambda);
+      const finalScore = clamp01((0.30 * semanticScore) + (0.60 * lexicalCoverage) + (0.10 * recencyScore));
+      const rationale = buildRawUserRecoveryRationale({
+        semanticScore,
+        lexicalCoverage,
+        recencyScore,
+      });
+
+      return {
+        ranked: {
+          ...item,
+          finalScore,
+        },
+        debug: {
+          id: item.id,
+          text: item.text,
+          semanticScore,
+          lexicalCoverage,
+          recencyScore,
+          finalScore,
+          rationale,
+        },
+      };
+    })
+    .sort((left, right) => {
+      if (right.ranked.finalScore !== left.ranked.finalScore) {
+        return (right.ranked.finalScore ?? 0) - (left.ranked.finalScore ?? 0);
+      }
+      if (right.debug.lexicalCoverage !== left.debug.lexicalCoverage) {
+        return right.debug.lexicalCoverage - left.debug.lexicalCoverage;
+      }
+      if (right.debug.semanticScore !== left.debug.semanticScore) {
+        return right.debug.semanticScore - left.debug.semanticScore;
+      }
+      return left.ranked.id.localeCompare(right.ranked.id);
+    });
+
+  return {
+    ranked: ranked.map((entry) => entry.ranked),
+    debug: ranked.map((entry) => entry.debug),
+  };
+}
+
 function clamp01(value: number): number {
   return Math.min(1, Math.max(0, value));
 }
@@ -392,6 +463,30 @@ function normalizedFrequency(accessCount: number, maxAccessCount: number): numbe
   return Math.log(1 + accessCount) / Math.log(1 + maxAccessCount + 1);
 }
 
+function computeRecencyScore(item: SearchResult, now: number, recencyLambda: number): number {
+  const ts = typeof item.metadata.ts === "number" ? item.metadata.ts : now;
+  const ageSeconds = Math.max(0, now - ts) / 1000;
+  return Math.exp(-recencyLambda * ageSeconds);
+}
+
+function buildRawUserRecoveryRationale(scores: {
+  semanticScore: number;
+  lexicalCoverage: number;
+  recencyScore: number;
+}): string {
+  const lexicalDelta = scores.lexicalCoverage - scores.semanticScore;
+  if (lexicalDelta > 0.15) {
+    return "lexical coverage lifted this candidate above its semantic score";
+  }
+  if (lexicalDelta < -0.15) {
+    return "semantic similarity carried this candidate despite weaker lexical coverage";
+  }
+  if (scores.recencyScore > 0.9) {
+    return "semantic and lexical scores were close; recency broke the tie";
+  }
+  return "semantic and lexical scores were balanced";
+}
+
 function extractKeywords(text: string): string[] {
   const tokens = normalizeTerms(text);
   const seen = new Set<string>();

package/src/types.ts

@@ -196,6 +196,20 @@ export interface ContextAssembleResult {
   estimatedTokens: number;
   systemPromptAddition: string;
   _profile?: string[];
+  _debug?: {
+    recoveryTriggerFired?: boolean;
+    crossSessionRawRecovery?: boolean;
+    rawUserRecoveryCandidates?: Array<{
+      id: string;
+      text: string;
+      selected: boolean;
+      semanticScore: number;
+      lexicalCoverage: number;
+      recencyScore: number;
+      finalScore: number;
+      rationale: string;
+    }>;
+  };
 }
 
 export interface ContextCompactArgs {