@xdarkicex/openclaw-memory-libravdb 1.3.19 → 1.3.21

package/src/context-engine.ts

@@ -12,7 +12,9 @@ import {
   rankSection7VariantCandidates,
 } from "./scoring.js";
 import { buildInjectedMemoryMessageContent, buildMemoryHeader, recentIds } from "./recall-utils.js";
-import { countTokens, estimateTokens, fitPromptBudget } from "./tokens.js";
+import { detectTemporalQuerySignal, rankTemporalRecoveryCandidates } from "./temporal.js";
+import type { TemporalRecoveryRankingResult } from "./temporal.js";
+import { countTokens, estimateTokens, fitPromptBudget, fitPromptBudgetFirstFit } from "./tokens.js";
 import type { RpcGetter } from "./plugin-runtime.js";
 import type {
   ContextAssembleArgs,
@@ -57,6 +59,7 @@ export function buildContextEngineFactory(
   }
 
   return {
+    info: { id: "libravdb-memory" },
     ownsCompaction: true,
     async bootstrap({ sessionId, userId }: ContextBootstrapArgs) {
       const rpc = await getRpc();
@@ -190,6 +193,7 @@ export function buildContextEngineFactory(
           systemPromptAddition: "",
         } satisfies ContextAssembleResult;
       }
+      const temporalQuery = detectTemporalQuerySignal(queryText);
 
       const excluded = recentIds(messages, 4);
       const cached = recallCache.take({ userId, queryText });
@@ -253,6 +257,7 @@ export function buildContextEngineFactory(
           cached,
           excluded,
           queryText,
+          temporalQuery,
           sessionId,
           userId,
           messages,
@@ -287,6 +292,7 @@ export function buildContextEngineFactory(
       cached,
       excluded,
       queryText,
+      temporalQuery,
       sessionId,
       userId,
       messages,
@@ -303,6 +309,7 @@ export function buildContextEngineFactory(
       cached: ReturnType<RecallCache<SearchResult>["take"]>;
       excluded: string[];
       queryText: string;
+      temporalQuery: ReturnType<typeof detectTemporalQuerySignal>;
       sessionId: string;
       userId: string;
       messages: Array<{ role: string; content: string }>;
@@ -562,6 +569,7 @@ export function buildContextEngineFactory(
       // it never modifies the C_total(q) output and does not spend from tau_V.
       let recoveryItems: SearchResult[] = [];
       let rawUserRecoveryDebug: NonNullable<NonNullable<ContextAssembleResult["_debug"]>["rawUserRecoveryCandidates"]> = [];
+      let temporalRecoveryResult: TemporalRecoveryRankingResult | null = null;
       if (recoveryTrigger.fire || crossSessionRawRecovery) {
         profiler?.mark("recovery_expand");
         const recoveryExcludeIDs = [...excluded, ...recentTailIDs, ...theoremSelectedIDs];
@@ -599,14 +607,44 @@ export function buildContextEngineFactory(
             k: Math.max((cfg.topK ?? 8) * 4, 8),
             excludeIds: recoveryExcludeIDs,
           });
-          const reranked = rankRawUserRecoveryCandidates(
-            annotateCollection(rawUserResults.results ?? [], `turns:${userId}`),
-            { queryText },
-          );
+          const annotatedUserResults = annotateCollection(rawUserResults.results ?? [], `turns:${userId}`);
+          temporalRecoveryResult = temporalQuery.active
+            ? rankTemporalRecoveryCandidates(annotatedUserResults, {
+                queryText,
+                maxSelected: 3,
+                nowMs: Date.now(),
+                recencyLambda: cfg.recencyLambdaUser ?? 0.00001,
+              })
+            : null;
+          const reranked = temporalRecoveryResult
+            ? temporalRecoveryResult
+            : rankRawUserRecoveryCandidates(annotatedUserResults, { queryText });
           if (debugRecovery) {
             rawUserRecoveryDebug = reranked.debug.slice(0, 8).map((item) => ({
-              ...item,
+              id: item.id,
+              text: item.text,
               selected: false,
+              tokenEstimate: estimateTokens(item.text),
+              temporalAnchorDensity: "temporalAnchorDensity" in item && typeof item.temporalAnchorDensity === "number"
+                ? item.temporalAnchorDensity
+                : 0,
+              semanticScore: "semanticScore" in item && typeof item.semanticScore === "number"
+                ? item.semanticScore
+                : 0,
+              slotCoverage: "slotCoverage" in item && typeof item.slotCoverage === "number"
+                ? item.slotCoverage
+                : undefined,
+              slotMatches: "slotMatches" in item && Array.isArray(item.slotMatches)
+                ? item.slotMatches
+                : undefined,
+              lexicalCoverage: "lexicalCoverage" in item && typeof item.lexicalCoverage === "number"
+                ? item.lexicalCoverage
+                : ("slotCoverage" in item && typeof item.slotCoverage === "number" ? item.slotCoverage : 0),
+              recencyScore: "recencyScore" in item && typeof item.recencyScore === "number"
+                ? item.recencyScore
+                : 0,
+              finalScore: typeof item.finalScore === "number" ? item.finalScore : 0,
+              rationale: typeof item.rationale === "string" ? item.rationale : "",
             }));
           }
           recoveryCandidates.push(
@@ -622,7 +660,7 @@ export function buildContextEngineFactory(
           );
         }
 
-        const fittedRecovery = fitPromptBudget(
+        const fittedRecovery = fitPromptBudgetFirstFit(
           dedupeRecoveryCandidates(recoveryCandidates),
           recoveryReserveTokens,
         );
@@ -667,6 +705,11 @@ export function buildContextEngineFactory(
           ? {
               recoveryTriggerFired: recoveryTrigger.fire,
               crossSessionRawRecovery,
+              recoveryReserveTokens,
+              temporalQueryIndicator: temporalQuery.indicator,
+              temporalQueryActive: temporalQuery.active,
+              temporalQueryPatterns: temporalQuery.matchedPatterns,
+              temporalRecoverySlots: temporalRecoveryResult?.slots,
               rawUserRecoveryCandidates: rawUserRecoveryDebug,
             }
           : undefined,

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

@@ -1,4 +1,5 @@
 import type { SearchResult } from "./types.js";
+import { getTemporalAnchorDensity } from "./temporal.js";
 
 interface HybridOptions {
   alpha?: number;
@@ -41,6 +42,7 @@ interface RawUserRecoveryOptions {
 export interface RawUserRecoveryDebugCandidate {
   id: string;
   text: string;
+  temporalAnchorDensity: number;
   semanticScore: number;
   lexicalCoverage: number;
   recencyScore: number;
@@ -319,17 +321,29 @@ export function rankRawUserRecoveryCandidates(
   const now = opts.nowMs ?? Date.now();
   const recencyLambda = Math.max(0, opts.recencyLambda ?? 0.00001);
   const keywords = extractKeywords(opts.queryText);
+  const intentPhrases = extractIntentPhrases(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 temporalAnchorDensity = getTemporalAnchorDensity(
+        `${typeof item.metadata.collection === "string" ? item.metadata.collection : "unknown"}::${item.id}`,
+        item.text,
+      );
+      const intentAlignmentBonus = computeIntentAlignmentBonus(item.text, intentPhrases);
+      const finalScore = clamp01(
+        (0.30 * semanticScore) +
+        (0.60 * lexicalCoverage) +
+        (0.10 * recencyScore) +
+        intentAlignmentBonus,
+      );
       const rationale = buildRawUserRecoveryRationale({
         semanticScore,
         lexicalCoverage,
         recencyScore,
+        intentAlignmentBonus,
       });
 
       return {
@@ -340,6 +354,7 @@ export function rankRawUserRecoveryCandidates(
         debug: {
           id: item.id,
           text: item.text,
+          temporalAnchorDensity,
           semanticScore,
           lexicalCoverage,
           recencyScore,
@@ -473,7 +488,11 @@ function buildRawUserRecoveryRationale(scores: {
   semanticScore: number;
   lexicalCoverage: number;
   recencyScore: number;
+  intentAlignmentBonus: number;
 }): string {
+  if (scores.intentAlignmentBonus >= 0.04) {
+    return "intent phrase overlap lifted this candidate toward the query's direct ask";
+  }
   const lexicalDelta = scores.lexicalCoverage - scores.semanticScore;
   if (lexicalDelta > 0.15) {
     return "lexical coverage lifted this candidate above its semantic score";
@@ -487,6 +506,79 @@ function buildRawUserRecoveryRationale(scores: {
   return "semantic and lexical scores were balanced";
 }
 
+function computeIntentAlignmentBonus(text: string, intentPhrases: string[]): number {
+  if (intentPhrases.length === 0) {
+    return 0;
+  }
+  const normalized = normalizeTextForPhraseMatch(text);
+  const matched = intentPhrases.filter((phrase) => normalized.includes(phrase)).length;
+  if (matched === 0) {
+    return 0;
+  }
+  return Math.min(0.08, matched * 0.02);
+}
+
+function extractIntentPhrases(text: string): string[] {
+  const terms = normalizeTerms(text).filter((term) => !INTENT_STOPWORDS.has(term));
+  const phrases: string[] = [];
+  for (let size = 4; size >= 2; size -= 1) {
+    for (let i = 0; i <= terms.length - size; i += 1) {
+      const phraseTerms = terms.slice(i, i + size);
+      if (phraseTerms.some((term) => term.length < 3)) {
+        continue;
+      }
+      const phrase = phraseTerms.join(" ");
+      if (!phrases.includes(phrase)) {
+        phrases.push(phrase);
+      }
+    }
+  }
+  return phrases.slice(0, 12);
+}
+
+function normalizeTextForPhraseMatch(text: string): string {
+  return normalizeTerms(text).join(" ");
+}
+
+const INTENT_STOPWORDS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "that",
+  "this",
+  "have",
+  "from",
+  "your",
+  "what",
+  "when",
+  "where",
+  "which",
+  "would",
+  "could",
+  "should",
+  "about",
+  "into",
+  "some",
+  "before",
+  "after",
+  "them",
+  "they",
+  "been",
+  "just",
+  "want",
+  "looking",
+  "look",
+  "help",
+  "need",
+  "recommend",
+  "suggestions",
+  "suggest",
+  "advice",
+  "think",
+  "also",
+]);
+
 function extractKeywords(text: string): string[] {
   const tokens = normalizeTerms(text);
   const seen = new Set<string>();

package/src/sidecar.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
@@ -268,13 +269,42 @@ export function daemonProvisioningHint(): string {
 }
 
 export function defaultEndpoint(platform = process.platform, homeDir = os.homedir()): string {
+  // Honour the daemon's own env var first (set by Homebrew LaunchAgent / systemd unit).
+  const envEndpoint = process.env.LIBRAVDB_RPC_ENDPOINT?.trim();
+  if (envEndpoint && isConfiguredEndpoint(envEndpoint)) {
+    return envEndpoint;
+  }
+
   if (platform === "win32") {
     return "tcp:127.0.0.1:37421";
   }
+
+  const sockName = "libravdb.sock";
+  const candidateDirs = [
+    // User-local (npm plugin convention)
+    homeDir?.trim() ? path.join(homeDir, ".clawdb", "run") : null,
+    // Homebrew (Apple Silicon) — matches the Homebrew formula LaunchAgent
+    "/opt/homebrew/var/clawdb/run",
+    // Homebrew (Intel Mac) / manual Linux installs
+    "/usr/local/var/clawdb/run",
+  ].filter((d): d is string => d !== null);
+
+  for (const dir of candidateDirs) {
+    const sockPath = path.join(dir, sockName);
+    try {
+      if (fs.existsSync(sockPath)) {
+        return `unix:${sockPath}`;
+      }
+    } catch {
+      // Permission error or similar — skip this candidate.
+    }
+  }
+
+  // Fallback to the original user-local path so error messages stay familiar.
   const baseDir = homeDir?.trim()
     ? path.join(homeDir, ".clawdb", "run")
     : path.join(".", ".clawdb", "run");
-  return `unix:${path.join(baseDir, "libravdb.sock")}`;
+  return `unix:${path.join(baseDir, sockName)}`;
 }
 
 export function buildSidecarEnv(cfg: PluginConfig): Record<string, string> {