@xdarkicex/openclaw-memory-libravdb 1.4.0 → 1.4.2

package/docs/contributing.md

@@ -75,3 +75,14 @@ Before opening a PR:
 - any new gating signal must come with calibration or invariant coverage
 - any retrieval math change must be reflected in [mathematics-v2.md](./mathematics-v2.md)
 - any gating change must be reflected in [gating.md](./gating.md)
+
+## Release Versioning
+
+`package.json` is the source of truth for the release version.
+
+The release automation syncs `openclaw.plugin.json` from `package.json` during the
+auto-bump/tag flow, and the publish workflow refuses to publish if the Git tag,
+`package.json`, and `openclaw.plugin.json` versions do not all match.
+
+The daemon release workflow enforces the same alignment before generating the
+Homebrew formula, so package, manifest, tag, and formula versioning stay in lockstep.

package/docs/gating.md

@@ -76,8 +76,15 @@ The repetition term is a product, not a sum:
 \[ R(t) = F(t) \cdot (1 - S(t)) \]
 
 with:
-\[ F(t) = \min\left(\frac{\mathrm{hitsAbove}(\mathrm{turns:userId}, 0.80, k=10)}{5}, 1\right) \]
-\[ S(t) = \min\left(\frac{\mathrm{hitsAbove}(\mathrm{user:userId}, 0.85, k=5)}{3}, 1\right) \]
+\[ F(t) = \min\left(\frac{\mathrm{hitsAbove}(\mathrm{turns:u}, 0.80, k=10)}{5}, 1\right) \]
+\[ S(t) = \min\left(\frac{\mathrm{hitsAbove}(\mathrm{user:u}, 0.85, k=5)}{3}, 1\right) \]
+
+where $u$ is the resolved durable namespace used by the host boundary. The
+resolver chooses $u$ in this order: explicit `userId`, then the
+session-key-derived namespace, then `agentId`, and finally the resolver
+fallback/default when no host identity is available. When the host does not
+provide a `userId`, the gate still measures repetition and saturation against a
+stable durable scope.
 
 Why a product? High input frequency should help only if durable memory is not already saturated. High saturation must veto the repetition term regardless of frequency. The veto property is structural: $S(t) = 1 \Rightarrow R(t) = 0$.
 

package/docs/mathematics-v2.md

@@ -61,7 +61,7 @@ $$
 S(d)=
 \begin{cases}
 1.0 & \text{if } d \text{ is from the active session} \\
-0.6 & \text{if } d \text{ is from durable user memory} \\
+0.6 & \text{if } d \text{ is from durable namespace memory} \\
 0.3 & \text{if } d \text{ is from global memory}
 \end{cases}
 $$
@@ -182,7 +182,7 @@ product $\lambda_s \Delta t_d$ is dimensionless, as required by the exponential.
 The current implementation uses different constants by scope:
 
 - active session: $\lambda_s = 0.0001$
-- durable user memory: $\lambda_s = 0.00001$
+- durable namespace memory: $\lambda_s = 0.00001$
 - global memory: $\lambda_s = 0.000002$
 
 The implied half-lives make the decay constants auditable at a glance:
@@ -200,9 +200,15 @@ $$
 If those half-lives feel wrong for a given deployment, adjust $\lambda_s$ via
 config — do not change the decay formula itself.
 
-This makes session context fade fastest, user memory fade more slowly, and
+This makes session context fade fastest, durable namespace memory fade more slowly, and
 global memory remain the most stable.
 
+When the host supplies an explicit `userId`, the durable namespace matches that
+`userId`. When the host does not provide a `userId`, the plugin derives a stable
+durable namespace from the session key, or falls back to `session:${sessionId}`
+when both `userId` and `sessionKey` are absent, so the retrieval math and scope
+weighting stay unchanged even when the host does not expose a separate user principal.
+
 **Note on symbol disambiguation.** The symbol $\lambda_s$ here denotes the
 scope-specific recency decay constant with units $\mathrm{s}^{-1}$. Section 7.3
 uses $\lambda_r$ for a separate recency constant in the planned authority weight.

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "libravdb-memory",
   "name": "LibraVDB Memory",
   "description": "Persistent vector memory with three-tier hybrid scoring",
-  "version": "1.3.11",
+  "version": "1.4.2",
   "kind": ["memory", "context-engine"],
   "configSchema": {
     "type": "object",

package/package.json

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

package/src/cli.ts

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import { resolveDurableNamespace } from "./durable-namespace.js";
 import type { PluginRuntime } from "./plugin-runtime.js";
 import type { LoggerLike, PluginConfig } from "./types.js";
 
@@ -26,6 +27,7 @@ type ExportResult = {
 
 type CliOptionBag = {
   userId?: string;
+  sessionKey?: string;
   sessionId?: string;
   limit?: string | number;
   yes?: boolean;
@@ -70,12 +72,13 @@ export function registerMemoryCli(
         .action(() => void runStatus(runtime, cfg, logger));
 
       const flush = ensureCommand(root, "flush")
-        .description("Wipe a user memory namespace after confirmation");
+        .description("Wipe a durable memory namespace after confirmation");
       if (flush.requiredOption) {
         flush.requiredOption("--user-id <userId>", "User id whose durable memory should be deleted");
       } else {
         flush.option("--user-id <userId>", "User id whose durable memory should be deleted");
       }
+      flush.option("--session-key <sessionKey>", "Session key whose derived durable namespace should be deleted");
       flush
         .option("--yes", "Skip the confirmation prompt")
         .action((opts) => void runFlush(runtime, opts, logger));
@@ -83,6 +86,7 @@ export function registerMemoryCli(
       const exportCmd = ensureCommand(root, "export")
         .description("Stream stored memories as newline-delimited JSON");
       exportCmd.option("--user-id <userId>", "Restrict export to a single user namespace");
+      exportCmd.option("--session-key <sessionKey>", "Restrict export to a derived session-key namespace");
       exportCmd.action((opts) => void runExport(runtime, opts, logger));
 
       const journal = ensureCommand(root, "journal")
@@ -147,15 +151,15 @@ async function runStatus(runtime: PluginRuntime, cfg: PluginConfig, logger: Logg
 }
 
 async function runFlush(runtime: PluginRuntime, opts: CliOptionBag | undefined, logger: LoggerLike): Promise<void> {
-  const userId = opts?.userId?.trim();
-  if (!userId) {
-    logger.error("LibraVDB flush requires --user-id <userId>.");
+  const namespace = resolveCliNamespace(opts);
+  if (!namespace) {
+    logger.error("LibraVDB flush requires --user-id <userId> or --session-key <sessionKey>.");
     process.exitCode = 1;
     return;
   }
 
   if (!opts?.yes) {
-    const confirmed = await confirm(`Delete durable memory collection user:${userId}? [y/N] `);
+    const confirmed = await confirm(`Delete durable memory namespace ${namespace}? [y/N] `);
     if (!confirmed) {
       console.log("Aborted.");
       return;
@@ -164,8 +168,8 @@ async function runFlush(runtime: PluginRuntime, opts: CliOptionBag | undefined,
 
   try {
     const rpc = await runtime.getRpc();
-    await rpc.call("flush_namespace", { userId });
-    console.log(`Deleted durable memory namespace user:${userId}.`);
+    await rpc.call("flush_namespace", { namespace });
+    console.log(`Deleted durable memory namespace ${namespace}.`);
   } catch (error) {
     logger.error(`LibraVDB flush failed: ${formatError(error)}`);
     process.exitCode = 1;
@@ -176,7 +180,7 @@ async function runExport(runtime: PluginRuntime, opts: CliOptionBag | undefined,
   try {
     const rpc = await runtime.getRpc();
     const result = await rpc.call<ExportResult>("export_memory", {
-      userId: opts?.userId?.trim() || undefined,
+      namespace: resolveCliNamespace(opts),
     });
     for (const record of result.records ?? []) {
       stdout.write(`${JSON.stringify(record)}\n`);
@@ -233,6 +237,15 @@ function normalizeLimit(limit: string | number | undefined): number | undefined
   return undefined;
 }
 
+function resolveCliNamespace(opts: CliOptionBag | undefined): string | undefined {
+  const userId = opts?.userId?.trim();
+  const sessionKey = opts?.sessionKey?.trim();
+  if (!userId && !sessionKey) {
+    return undefined;
+  }
+  return resolveDurableNamespace({ userId, sessionKey });
+}
+
 type CliRegistrar = {
   registerCli?(
     builder: (ctx: { program: CliProgram }) => void,

package/src/context-engine.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import {
   DEFAULT_CONTINUITY_MIN_TURNS,
   DEFAULT_CONTINUITY_PRIOR_CONTEXT_TOKENS,
@@ -19,6 +20,7 @@ import {
 } from "./temporal.js";
 import type { TemporalRecoveryRankingResult } from "./temporal.js";
 import { countTokens, estimateTokens, fitPromptBudget, fitPromptBudgetFirstFit } from "./tokens.js";
+import { resolveDurableNamespace } from "./durable-namespace.js";
 import type { RpcGetter } from "./plugin-runtime.js";
 import type {
   ContextAssembleArgs,
@@ -27,6 +29,7 @@ import type {
   ContextCompactArgs,
   ContextIngestArgs,
   GatingResult,
+  MemoryMessage,
   PluginConfig,
   RecallCache,
   SearchResult,
@@ -42,6 +45,8 @@ const SESSION_RAW_COLLECTION_PREFIX = "session_raw:";
 const SESSION_SUMMARY_COLLECTION_PREFIX = "session_summary:";
 const SESSION_EDGE_COLLECTION_PREFIX = "session_edge:";
 const SESSION_STATE_COLLECTION_PREFIX = "session_state:";
+const AFTER_TURN_DEDUPE_TTL_MS = 60 * 60 * 1000;
+const AFTER_TURN_DEDUPE_MAX_ENTRIES = 1024;
 
 export function buildContextEngineFactory(
   getRpc: RpcGetter,
@@ -52,8 +57,9 @@ export function buildContextEngineFactory(
   let authoredSoftCache: SearchResult[] | null = null;
   let authoredVariantCache: SearchResult[] | null = null;
   const authoredVariantRecallCache = new Map<string, SearchResult[]>();
+  const afterTurnIngestedKeys = new Map<string, number>();
 
-  // Session-scoped elevated-guidance cache keyed by sessionId + generation + userId + queryText
+  // Session-scoped elevated-guidance cache keyed by sessionId + generation + durable namespace + queryText
   const elevatedRecallCache = new Map<string, SearchResult[]>();
   const elevatedRecallGeneration = new Map<string, number>();
 
@@ -63,9 +69,10 @@ export function buildContextEngineFactory(
   }
 
   return {
-    info: { id: "libravdb-memory" },
+    info: { id: "libravdb-memory", name: "LibraVDB Memory", ownsCompaction: true },
     ownsCompaction: true,
-    async bootstrap({ sessionId, userId }: ContextBootstrapArgs) {
+    async bootstrap({ sessionId, sessionKey, userId }: ContextBootstrapArgs) {
+      const durableNamespace = resolveDurableNamespace({ userId, sessionKey, fallback: `session:${sessionId}` });
       const rpc = await getRpc();
       await rpc.call("ensure_collections", {
         collections: [
@@ -75,8 +82,8 @@ export function buildContextEngineFactory(
           sessionEdgeCollection(sessionId),
           sessionStateCollection(sessionId),
           ...(useSessionRecallProjection(cfg) ? [sessionRecallCollection(sessionId)] : []),
-          `turns:${userId}`,
-          `user:${userId}`,
+          `turns:${durableNamespace}`,
+          `user:${durableNamespace}`,
           "global",
           AUTHORED_HARD_COLLECTION,
           AUTHORED_SOFT_COLLECTION,
@@ -98,110 +105,93 @@ export function buildContextEngineFactory(
       validateSection7StartupHardReserve(cfg, authoredHard);
       return { ok: true };
     },
-    async ingest({ sessionId, userId, message, isHeartbeat }: ContextIngestArgs) {
+    async ingest({ sessionId, sessionKey, userId, message, isHeartbeat }: ContextIngestArgs) {
       if (isHeartbeat) {
         return { ingested: false };
       }
 
-      const rpc = await getRpc();
-      const ts = Date.now();
-      const sessionMeta = {
-        role: message.role,
-        ts,
-        userId,
-        sessionId,
-        type: "turn",
-        provenance_class: "session_turn",
-        stability_weight: stabilityWeightForMessage(message.role),
-      };
-      // Elevated cache is session-scoped, so invalidate immediately on every ingest
-      clearElevatedCacheForSession(sessionId);
-      const rawSessionId = `${sessionId}:${ts}`;
-      const rawSessionInsert = rpc.call("insert_session_turn", {
+      const result = await ingestCanonicalMessage({
+        getRpc,
+        cfg,
+        recallCache,
+        clearElevatedCacheForSession,
         sessionId,
-        id: rawSessionId,
-        text: message.content,
-        metadata: sessionMeta,
+        sessionKey,
+        userId,
+        message,
       });
-      if (useSessionRecallProjection(cfg)) {
-        try {
-          await rawSessionInsert;
-          await rebuildSessionRecallProjection(rpc, cfg, sessionId);
-        } catch (error) {
-          console.error(error);
-        }
-      } else {
-        void rawSessionInsert.catch(console.error);
+      return { ingested: result.ingested };
+    },
+    async afterTurn({ sessionId, sessionKey, userId, messages, prePromptMessageCount, isHeartbeat }: {
+      sessionId: string;
+      sessionKey?: string;
+      userId?: string;
+      messages: Array<{ role: string; content: unknown }>;
+      prePromptMessageCount: number;
+      isHeartbeat?: boolean;
+    }) {
+      if (isHeartbeat) {
+        return;
       }
 
-      if (message.role === "user") {
-        try {
-          recallCache.clearUser(userId);
-          await rpc.call("insert_text", {
-            collection: `turns:${userId}`,
-            id: `${userId}:${ts}`,
-            text: message.content,
-            metadata: {
-              ...sessionMeta,
-              provenance_class: "turn_index",
-            },
-          });
+      const startIndex = Math.max(0, prePromptMessageCount - 1);
+      const turnMessages = messages.slice(startIndex);
+      const normalizedTurnMessages = turnMessages.flatMap((turnMessage, offset) => {
+        const normalized = normalizeHostMessage(turnMessage);
+        if (!normalized) {
+          return [];
+        }
+        return [{ index: startIndex + offset, normalized }] as const;
+      });
+      for (let offset = 0; offset < normalizedTurnMessages.length; offset++) {
+        const { index, normalized } = normalizedTurnMessages[offset];
 
-          const gating = await rpc.call<GatingResult>("gating_scalar", {
-            userId,
-            text: message.content,
-          });
+        const dedupeKey = `${sessionId}\n${index}\n${normalized.role}\n${hashMessageContent(normalized.content)}`;
+        if (hasRecentAfterTurnIngest(afterTurnIngestedKeys, dedupeKey)) {
+          continue;
+        }
 
-          if (gating.g >= (cfg.ingestionGateThreshold ?? 0.35)) {
-            void rpc.call("insert_text", {
-              collection: `user:${userId}`,
-              id: `${userId}:${ts}`,
-              text: message.content,
-              metadata: {
-                role: message.role,
-                ts,
-                sessionId,
-                type: "turn",
-                userId,
-                provenance_class: "durable_user_memory",
-                stability_weight: Math.max(stabilityWeightForMessage(message.role), gating.g),
-                gating_score: gating.g,
-                gating_t: gating.t,
-                gating_h: gating.h,
-                gating_r: gating.r,
-                gating_d: gating.d,
-                gating_p: gating.p,
-                gating_a: gating.a,
-                gating_dtech: gating.dtech,
-                gating_gconv: gating.gconv,
-                gating_gtech: gating.gtech,
-              },
-            }).catch(console.error);
-          }
-        } catch {
-          // Session storage already happened; skip durable promotion on gating failure.
+        const result = await ingestCanonicalMessage({
+          getRpc,
+          cfg,
+          recallCache,
+          clearElevatedCacheForSession,
+          sessionId,
+          sessionKey,
+          userId,
+          message: {
+            ...normalized,
+            id: `after-turn:${index}`,
+          },
+          skipProjectionRebuild: offset !== normalizedTurnMessages.length - 1,
+        });
+        if (result.ingested) {
+          rememberAfterTurnIngest(afterTurnIngestedKeys, dedupeKey);
         }
       }
-
-      return { ingested: true };
     },
-    async assemble({ sessionId, userId, messages, tokenBudget }: ContextAssembleArgs) {
+    async assemble({ sessionId, sessionKey, userId, messages, tokenBudget, ...rest }: ContextAssembleArgs & Record<string, unknown>) {
       const PROFILE = process.env.OPENCLAW_PROFILE_ASSEMBLE === "1";
       const DEBUG_RECOVERY = process.env.LONGMEMEVAL_DEBUG_RANKING === "1";
+      const durableNamespace = resolveDurableNamespace({ userId, sessionKey, fallback: `session:${sessionId}` });
+      const originalMessages = messages;
+      const normalizedMessages = normalizeConversationMessages(messages as Array<{ role: string; content: unknown }>);
 
-      const queryText = messages.at(-1)?.content ?? "";
+      const queryText =
+        (typeof rest.prompt === "string" && rest.prompt.trim() ? rest.prompt : undefined) ??
+        normalizedMessages.at(-1)?.content ?? "";
       if (!queryText) {
         return {
-          messages,
-          estimatedTokens: countTokens(messages),
+          messages: originalMessages,
+          estimatedTokens: countTokens(originalMessages),
           systemPromptAddition: "",
         } satisfies ContextAssembleResult;
       }
       const temporalQuery = detectTemporalQuerySignal(queryText);
       const temporalSelectorGuard = decideTemporalSelectorGuard(queryText, temporalQuery);
 
-      const excluded = recentIds(messages, 4);
-      const cached = recallCache.take({ userId, queryText });
+      const excluded = recentIds(normalizedMessages, 4);
+      const cached = recallCache.take({ userId: durableNamespace, queryText });
 
       const rpc = await getRpc();
 
@@ -265,8 +255,9 @@ export function buildContextEngineFactory(
           temporalQuery,
           temporalSelectorGuard,
           sessionId,
-          userId,
-          messages,
+          userId: durableNamespace,
+          visibleMessages: originalMessages,
+          messages: normalizedMessages,
           tokenBudget,
           profiler,
           debugRecovery: DEBUG_RECOVERY,
@@ -282,8 +273,8 @@ export function buildContextEngineFactory(
           : result;
       } catch {
         return {
-          messages,
-          estimatedTokens: countTokens(messages),
+          messages: originalMessages,
+          estimatedTokens: countTokens(originalMessages),
           systemPromptAddition: "",
         } satisfies ContextAssembleResult;
       }
@@ -302,6 +293,7 @@ export function buildContextEngineFactory(
       temporalSelectorGuard,
       sessionId,
       userId,
+      visibleMessages,
       messages,
       tokenBudget,
       profiler,
@@ -320,6 +312,7 @@ export function buildContextEngineFactory(
       temporalSelectorGuard: ReturnType<typeof decideTemporalSelectorGuard>;
       sessionId: string;
       userId: string;
+      visibleMessages: MemoryMessage[];
       messages: Array<{ role: string; content: string }>;
       tokenBudget: number;
       profiler: { mark(label: string): void; emit(): void } | null;
@@ -369,8 +362,8 @@ export function buildContextEngineFactory(
           content: buildInjectedMemoryMessageContent(item),
         }));
         return {
-          messages: [...selectedMessages, ...messages],
-          estimatedTokens: countTokens(selectedMessages) + countTokens(messages),
+          messages: [...selectedMessages, ...visibleMessages],
+          estimatedTokens: countTokens(selectedMessages) + countTokens(visibleMessages),
           systemPromptAddition: buildDegradedMemoryHeader(degradedReasons, selected),
         };
       }
@@ -706,8 +699,8 @@ export function buildContextEngineFactory(
       }));
 
       return {
-        messages: [...selectedMessages, ...messages],
-        estimatedTokens: countTokens(selectedMessages) + countTokens(messages),
+        messages: [...selectedMessages, ...visibleMessages],
+        estimatedTokens: countTokens(selectedMessages) + countTokens(visibleMessages),
         systemPromptAddition: buildMemoryHeader(selected),
         _debug: debugRecovery
           ? {
@@ -981,6 +974,207 @@ function clampFraction(value: number | undefined): number {
   return Math.min(1, Math.max(0, value));
 }
 
+async function ingestCanonicalMessage(params: {
+  getRpc: RpcGetter;
+  cfg: PluginConfig;
+  recallCache: RecallCache<SearchResult>;
+  clearElevatedCacheForSession: (sessionId: string) => void;
+  sessionId: string;
+  sessionKey?: string;
+  userId?: string;
+  message: MemoryMessage;
+  skipProjectionRebuild?: boolean;
+}): Promise<{ ingested: boolean }> {
+  const normalized = normalizeMemoryMessage(params.message);
+  if (!normalized) {
+    return { ingested: false };
+  }
+
+  const rpc = await params.getRpc();
+  const ts = Date.now();
+  const durableNamespace = resolveDurableNamespace({
+    userId: params.userId,
+    sessionKey: params.sessionKey,
+    fallback: `session:${params.sessionId}`,
+  });
+  const turnId = normalized.id ?? `${ts}`;
+  const sessionMeta = {
+    role: normalized.role,
+    ts,
+    userId: durableNamespace,
+    sessionId: params.sessionId,
+    type: "turn",
+    provenance_class: "session_turn",
+    stability_weight: stabilityWeightForMessage(normalized.role),
+    source_turn_id: turnId,
+  };
+
+  params.clearElevatedCacheForSession(params.sessionId);
+  const rawSessionInsert = rpc.call("insert_session_turn", {
+    sessionId: params.sessionId,
+    id: `${params.sessionId}:${turnId}`,
+    text: normalized.content,
+    metadata: sessionMeta,
+  });
+  try {
+    await rawSessionInsert;
+    if (useSessionRecallProjection(params.cfg) && !params.skipProjectionRebuild) {
+      await rebuildSessionRecallProjection(rpc, params.cfg, params.sessionId);
+    }
+  } catch {
+    return { ingested: false };
+  }
+
+  if (normalized.role !== "user") {
+    return { ingested: true };
+  }
+
+  try {
+    params.recallCache.clearUser(durableNamespace);
+    await rpc.call("insert_text", {
+      collection: `turns:${durableNamespace}`,
+      id: `${durableNamespace}:${turnId}`,
+      text: normalized.content,
+      metadata: {
+        ...sessionMeta,
+        provenance_class: "turn_index",
+      },
+    });
+
+    const gating = await rpc.call<GatingResult>("gating_scalar", {
+      userId: durableNamespace,
+      text: normalized.content,
+    });
+
+    if (gating.g >= (params.cfg.ingestionGateThreshold ?? 0.35)) {
+      void rpc.call("insert_text", {
+        collection: `user:${durableNamespace}`,
+        id: `${durableNamespace}:${turnId}`,
+        text: normalized.content,
+        metadata: {
+          role: normalized.role,
+          ts,
+          sessionId: params.sessionId,
+          type: "turn",
+          userId: durableNamespace,
+          source_turn_id: turnId,
+          provenance_class: "durable_user_memory",
+          stability_weight: Math.max(stabilityWeightForMessage(normalized.role), gating.g),
+          gating_score: gating.g,
+          gating_t: gating.t,
+          gating_h: gating.h,
+          gating_r: gating.r,
+          gating_d: gating.d,
+          gating_p: gating.p,
+          gating_a: gating.a,
+          gating_dtech: gating.dtech,
+          gating_gconv: gating.gconv,
+          gating_gtech: gating.gtech,
+        },
+      }).catch(console.error);
+    }
+  } catch {
+    // Session storage already happened; skip durable promotion on gating failure.
+  }
+
+  return { ingested: true };
+}
+
+function hashMessageContent(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function pruneAfterTurnIngestKeys(cache: Map<string, number>, now: number): void {
+  for (const [key, seenAt] of cache) {
+    if (now - seenAt > AFTER_TURN_DEDUPE_TTL_MS) {
+      cache.delete(key);
+    }
+  }
+  while (cache.size > AFTER_TURN_DEDUPE_MAX_ENTRIES) {
+    const oldestKey = cache.keys().next().value;
+    if (!oldestKey) {
+      break;
+    }
+    cache.delete(oldestKey);
+  }
+}
+
+function hasRecentAfterTurnIngest(cache: Map<string, number>, key: string): boolean {
+  const now = Date.now();
+  pruneAfterTurnIngestKeys(cache, now);
+  return cache.has(key);
+}
+
+function rememberAfterTurnIngest(cache: Map<string, number>, key: string): void {
+  const now = Date.now();
+  cache.delete(key);
+  cache.set(key, now);
+  pruneAfterTurnIngestKeys(cache, now);
+}
+
+function normalizeHostMessage(message: { role: string; content: unknown } | undefined): MemoryMessage | null {
+  if (!message || !shouldIngestRole(message.role)) {
+    return null;
+  }
+  const content = extractMessageText(message.content);
+  if (!content) {
+    return null;
+  }
+  return {
+    role: message.role,
+    content,
+  };
+}
+
+function normalizeConversationMessages(messages: Array<{ role: string; content: unknown }>): MemoryMessage[] {
+  return messages
+    .map((message) => normalizeHostMessage(message))
+    .filter((message): message is MemoryMessage => message !== null);
+}
+
+function normalizeMemoryMessage(message: MemoryMessage): MemoryMessage | null {
+  if (!shouldIngestRole(message.role)) {
+    return null;
+  }
+  const content = extractMessageText(message.content);
+  if (!content) {
+    return null;
+  }
+  return {
+    ...message,
+    content,
+  };
+}
+
+function shouldIngestRole(role: string): boolean {
+  return role === "user" || role === "assistant" || role === "system";
+}
+
+function extractMessageText(content: unknown): string {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return "";
+  }
+  return content
+    .flatMap((part) => {
+      if (!part || typeof part !== "object") {
+        return [];
+      }
+      const type = (part as { type?: unknown }).type;
+      if (
+        (type === "text" || type === "input_text" || type === "output_text") &&
+        typeof (part as { text?: unknown }).text === "string"
+      ) {
+        return [(part as { text: string }).text];
+      }
+      return [];
+    })
+    .join("\n")
+    .trim();
+}
+
 function validateSection7StartupHardReserve(cfg: PluginConfig, authoredHard: SearchResult[]): void {
   if (authoredHard.length === 0) {
     return;

package/src/durable-namespace.ts

@@ -0,0 +1,34 @@
+const SESSION_KEY_NAMESPACE_PREFIX = "session-key:";
+const AGENT_ID_NAMESPACE_PREFIX = "agent-id:";
+
+export function resolveDurableNamespace(params: {
+  userId?: string;
+  sessionKey?: string;
+  agentId?: string;
+  fallback?: string;
+}): string {
+  const explicitUserId = firstNonEmpty(params.userId);
+  if (explicitUserId) {
+    return explicitUserId;
+  }
+
+  const sessionKey = firstNonEmpty(params.sessionKey);
+  if (sessionKey) {
+    return `${SESSION_KEY_NAMESPACE_PREFIX}${sessionKey}`;
+  }
+
+  const agentId = firstNonEmpty(params.agentId);
+  if (agentId) {
+    return `${AGENT_ID_NAMESPACE_PREFIX}${agentId}`;
+  }
+
+  return firstNonEmpty(params.fallback) ?? "default";
+}
+
+function firstNonEmpty(value: string | undefined): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}

package/src/memory-runtime.ts

@@ -1,4 +1,5 @@
 import type { RpcGetter } from "./plugin-runtime.js";
+import { resolveDurableNamespace } from "./durable-namespace.js";
 import type { PluginConfig, SearchResult } from "./types.js";
 
 type MemorySearchParams = {
@@ -12,10 +13,12 @@ type MemorySearchParams = {
   userId?: string;
   agentId?: string;
   sessionId?: string;
+  sessionKey?: string;
   context?: {
     userId?: string;
     agentId?: string;
     sessionId?: string;
+    sessionKey?: string;
   };
 };
 
@@ -32,8 +35,9 @@ type MemoryRuntimeStatus = {
 export function buildMemoryRuntimeBridge(getRpc: RpcGetter, cfg: PluginConfig) {
   return {
     async getMemorySearchManager(params: { agentId?: string; purpose?: string } = {}) {
+      const status = await readStatus(getRpc, params.purpose);
       return {
-        manager: createMemorySearchManager(getRpc, cfg, params),
+        manager: createMemorySearchManager(getRpc, cfg, params, status),
       };
     },
     resolveMemoryBackendConfig() {
@@ -51,23 +55,36 @@ function createMemorySearchManager(
   getRpc: RpcGetter,
   cfg: PluginConfig,
   defaults: { agentId?: string; purpose?: string },
+  initialStatus: MemoryRuntimeStatus & Record<string, unknown>,
 ) {
+  let cachedStatus = initialStatus;
+
   return {
-    async search(params: MemorySearchParams = {}) {
+    async search(queryOrParams: string | MemorySearchParams = {}, opts: MemorySearchParams = {}) {
+      const legacyCall = typeof queryOrParams === "string";
+      const params = legacyCall
+        ? {
+            query: queryOrParams,
+            limit: opts.limit ?? opts.k ?? opts.topK,
+            sessionId: opts.sessionId,
+            sessionKey: opts.sessionKey,
+            userId: opts.userId,
+            agentId: opts.agentId,
+            context: opts.context,
+          }
+        : queryOrParams;
       const queryText = firstString(params.query, params.text, params.input, params.q);
       if (!queryText) {
-        return { results: [], error: "Missing query text for LibraVDB memory search" };
+        return legacyCall ? { 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 userId = resolveDurableNamespace({
+        userId: firstString(params.userId, params.context?.userId),
+        sessionKey: firstString(params.sessionKey, params.context?.sessionKey),
+        agentId: firstString(params.agentId, params.context?.agentId, defaults.agentId),
+        fallback: sessionId ? `session:${sessionId}` : undefined,
+      });
       const k = normalizePositiveInteger(params.k, params.limit, params.topK, cfg.topK, 8);
       const collections = resolveSearchCollections(cfg, userId, sessionId);
       const rpc = await getRpc();
@@ -85,11 +102,24 @@ function createMemorySearchManager(
             excludeByCollection: {},
           });
 
+      const legacyResults = result.results.map((item) => ({
+        ...item,
+        content: item.text,
+      }));
+      if (legacyCall) {
+        return { results: legacyResults };
+      }
+      return result.results.map(toMemorySearchResult);
+    },
+    async readFile(params: { relPath: string; from?: number; lines?: number }) {
+      const located = await loadSearchResultText(getRpc, params.relPath);
+      const fromLine = Math.max(1, params.from ?? 1);
+      const lineCount = Math.max(1, params.lines ?? 200);
+      const lines = located.text.split("\n");
+      const text = lines.slice(fromLine - 1, fromLine - 1 + lineCount).join("\n");
       return {
-        results: result.results.map((item) => ({
-          ...item,
-          content: item.text,
-        })),
+        text,
+        path: located.path,
       };
     },
     async ingest() {
@@ -97,24 +127,26 @@ function createMemorySearchManager(
       return { ingested: false, delegatedToContextEngine: true };
     },
     async sync() {
-      // Projections and compaction sync are already handled inside the existing
-      // context-engine lifecycle.
+      cachedStatus = await readStatus(getRpc, defaults.purpose);
       return { synced: true, delegatedToContextEngine: true };
     },
-    async status() {
-      const rpc = await getRpc();
-      const status = await rpc.call<MemoryRuntimeStatus>("status", {});
+    status() {
+      return cachedStatus;
+    },
+    async probeEmbeddingAvailability() {
       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,
+        ok: cachedStatus.ok ?? false,
+        ...(cachedStatus.ok === false && typeof cachedStatus.message === "string"
+          ? { error: cachedStatus.message }
+          : {}),
       };
     },
+    async probeVectorAvailability() {
+      return cachedStatus.ok ?? false;
+    },
+    async close() {
+      // The sidecar connection is shared by the plugin runtime.
+    },
   };
 }
 
@@ -140,6 +172,84 @@ function firstString(...values: Array<string | undefined>): string | undefined {
   return values.find((value) => typeof value === "string" && value.length > 0);
 }
 
+function toMemorySearchResult(item: SearchResult) {
+  const collection = typeof item.metadata.collection === "string" ? item.metadata.collection : "memory";
+  return {
+    path: encodeSearchResultPath(collection, item.id),
+    startLine: 1,
+    endLine: Math.max(1, item.text.split("\n").length),
+    score: item.score,
+    snippet: item.text,
+    source: collection.startsWith("session:") || collection.startsWith("session_") ? "sessions" : "memory",
+    citation: `${collection}:${item.id}`,
+  };
+}
+
+async function loadSearchResultText(getRpc: RpcGetter, relPath: string): Promise<{ path: string; text: string }> {
+  const { collection, id } = decodeSearchResultPath(relPath);
+  const rpc = await getRpc();
+  const result = await rpc.call<{ results: SearchResult[] }>("list_collection", { collection });
+  const item = result.results.find((entry) => entry.id === id);
+  if (!item) {
+    throw new Error(`LibraVDB memory path not found: ${relPath}`);
+  }
+  return {
+    path: relPath,
+    text: item.text,
+  };
+}
+
+function encodeSearchResultPath(collection: string, id: string): string {
+  return `${encodeURIComponent(collection)}::${encodeURIComponent(id)}`;
+}
+
+function decodeSearchResultPath(relPath: string): { collection: string; id: string } {
+  const separator = relPath.indexOf("::");
+  if (separator <= 0) {
+    throw new Error(`Unsupported LibraVDB memory path: ${relPath}`);
+  }
+  return {
+    collection: decodeURIComponent(relPath.slice(0, separator)),
+    id: decodeURIComponent(relPath.slice(separator + 2)),
+  };
+}
+
+async function readStatus(
+  getRpc: RpcGetter,
+  purpose: string | undefined,
+): Promise<MemoryRuntimeStatus & Record<string, unknown>> {
+  try {
+    const rpc = await getRpc();
+    const status = await rpc.call<MemoryRuntimeStatus & Record<string, unknown>>("status", {});
+    return {
+      ...status,
+      backend: "builtin",
+      provider: "libravdb",
+      model: status.embeddingProfile ?? "unknown",
+      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,
+    };
+  } catch (error) {
+    return {
+      backend: "builtin",
+      provider: "libravdb",
+      model: "unknown",
+      ok: false,
+      message: error instanceof Error && error.message ? error.message : String(error),
+      turnCount: 0,
+      memoryCount: 0,
+      embeddingProfile: "unknown",
+      purpose,
+    };
+  }
+}
+
 function normalizePositiveInteger(...values: Array<number | undefined>): number {
   for (const value of values) {
     if (typeof value === "number" && Number.isFinite(value) && value > 0) {

package/src/types.ts

@@ -172,21 +172,20 @@ export interface RecallCache<T = unknown> {
   clearUser(userId: string): void;
 }
 
-export interface ContextBootstrapArgs {
+export interface ContextNamespaceArgs {
   sessionId: string;
-  userId: string;
+  sessionKey?: string;
+  userId?: string;
 }
 
-export interface ContextIngestArgs {
-  sessionId: string;
-  userId: string;
+export interface ContextBootstrapArgs extends ContextNamespaceArgs {}
+
+export interface ContextIngestArgs extends ContextNamespaceArgs {
   message: MemoryMessage;
   isHeartbeat?: boolean;
 }
 
-export interface ContextAssembleArgs {
-  sessionId: string;
-  userId: string;
+export interface ContextAssembleArgs extends ContextNamespaceArgs {
   messages: MemoryMessage[];
   tokenBudget: number;
 }