@remnic/core 10.0.3 → 10.0.4

package/src/orchestration/projection-rebuild-schedule.ts

@@ -8,6 +8,15 @@
  * maintenance request — interval-throttled, single-flighted, never awaited,
  * never throws.
  *
+ * The rebuild runs in a forked child so the corpus and lifecycle ledger are
+ * not allocated in the daemon heap. An unlocked secure store stays in-process:
+ * the key is process-local and is never placed on the child's argv or env.
+ * The child is killed on scheduler dispose and on parent exit. If the parent
+ * dies without running those hooks, the child sees the IPC channel close and
+ * stops before it publishes the projection.
+ * When the daemon heap is already above `projectionRebuildHeapUsageLimit`,
+ * the job is postponed with the failure backoff instead of starting.
+ *
  * `projectionRebuildEnabled` gates it (via the lifecycle capabilities
  * resolver, default true); `projectionRebuildIntervalMs` is the cadence.
  *
@@ -24,6 +33,11 @@
  * not yet scheduled here (they are still served by their own rebuild paths);
  * the fallback WARN surfaces staleness for any namespace that lags.
  */
+import { existsSync } from "node:fs";
+import { fork, type ChildProcess } from "node:child_process";
+import path from "node:path";
+import v8 from "node:v8";
+import { fileURLToPath } from "node:url";
 import { log } from "../logger.js";
 import type { PluginConfig } from "../types.js";
 import { resolveMemoryLifecycleCapabilities } from "../capabilities.js";
@@ -31,7 +45,10 @@ import {
   rebuildMemoryProjection,
   type RebuildMemoryProjectionOptions,
 } from "../maintenance/rebuild-memory-projection.js";
+import { PROJECTION_REBUILD_RUNNER_FLAG } from "../maintenance/rebuild-memory-projection-runner.js";
 import { readProjectionRebuiltAt } from "../maintenance/projection-support.js";
+import { DEFAULT_PROJECTION_REBUILD_HEAP_USAGE_LIMIT } from "../projection-rebuild-config.js";
+import { fullCorpusHeapPressure, type HeapLimitStatistics } from "./full-corpus-heap-guard.js";
 
 type InjectedStorage = NonNullable<RebuildMemoryProjectionOptions["storage"]>;
 
@@ -45,20 +62,250 @@ export interface ProjectionRebuildScheduleState {
   lastFailureAtMs: number;
 }
 
+export interface ProjectionRebuildForkRequest {
+  memoryDir: string;
+  defaultNamespace: string;
+  now: Date;
+}
+
+export interface ProjectionRebuildForkResult {
+  currentRows: number;
+  timelineRows: number;
+  entityMentionRows: number;
+}
+
 /** Bounded retry cadence after a failure — short enough to self-heal promptly
  * once a transient cause clears, long enough to keep a persistently-failing
  * rebuild off every maintenance tick. */
 const FAILURE_RETRY_BACKOFF_MS = 5 * 60 * 1000;
 
+/** Floor for a hung child. A short interval must not make this tighter:
+ * a large corpus can legitimately run longer than 30 minutes. When the
+ * configured interval is longer, the child may use that whole interval. */
+const FORK_TIMEOUT_MS = 30 * 60 * 1000;
+
+/** Hang cap for one scheduled fork. At least 30 minutes, otherwise the interval,
+ * and never above Node's 32-bit setTimeout limit. A larger delay overflows
+ * and fires in 1ms, which would kill every rebuild. */
+const MAX_SETTIMEOUT_MS = 2_147_483_647;
+
+export function projectionRebuildForkTimeoutMs(intervalMs: number): number {
+  const timeout = !Number.isFinite(intervalMs) || intervalMs < FORK_TIMEOUT_MS
+    ? FORK_TIMEOUT_MS
+    : intervalMs;
+  return Math.min(timeout, MAX_SETTIMEOUT_MS);
+}
+
+const projectionRebuildChildren = new Map<ProjectionRebuildScheduleState | undefined, Set<ChildProcess>>();
+let parentExitHookInstalled = false;
+
+function rememberProjectionRebuildChild(
+  child: ChildProcess,
+  owner: ProjectionRebuildScheduleState | undefined,
+): void {
+  let children = projectionRebuildChildren.get(owner);
+  if (!children) {
+    children = new Set();
+    projectionRebuildChildren.set(owner, children);
+  }
+  children.add(child);
+  const forget = () => {
+    children.delete(child);
+    if (children.size === 0) projectionRebuildChildren.delete(owner);
+  };
+  child.once("exit", forget);
+  child.once("error", forget);
+  if (!parentExitHookInstalled) {
+    parentExitHookInstalled = true;
+    // The exit listener is invoked with the exit code. Ignore that argument
+    // so a non-zero code is not treated as a scheduler owner.
+    process.on("exit", () => {
+      terminateScheduledProjectionRebuilds();
+    });
+  }
+}
+
+/**
+ * SIGKILL scheduled rebuild children. A scheduler dispose passes its own
+ * state so another instance's child keeps running. Process exit passes no
+ * owner and kills every child.
+ */
+export function terminateScheduledProjectionRebuilds(
+  owner?: ProjectionRebuildScheduleState,
+): void {
+  const groups = owner
+    ? [projectionRebuildChildren.get(owner)]
+    : [...projectionRebuildChildren.values()];
+  for (const children of groups) {
+    if (!children) continue;
+    for (const child of children) child.kill("SIGKILL");
+  }
+}
+
+const CHILD_ENV_ALLOWLIST = [
+  "PATH",
+  "NODE_OPTIONS",
+  "HOME",
+  "USERPROFILE",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TZ",
+  "SystemRoot",
+  "windir",
+  "PATHEXT",
+  "COMSPEC",
+  "NODE_PATH",
+] as const;
+
 export function createProjectionRebuildScheduleState(): ProjectionRebuildScheduleState {
   return { inFlight: false, lastRebuildAtMs: 0, lastFailureAtMs: 0 };
 }
 
+/**
+ * Environment for the rebuild child. Only runtime locators are copied.
+ * API keys, tokens, and secure-store unlock material are not passed.
+ */
+export function projectionRebuildChildEnv(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const key of CHILD_ENV_ALLOWLIST) {
+    const value = parent[key];
+    if (value !== undefined) env[key] = value;
+  }
+  return env;
+}
+
+function projectionRebuildRunnerPath(): string {
+  const here = fileURLToPath(import.meta.url);
+  const dir = path.dirname(here);
+  const candidates = [
+    path.join(dir, "..", "maintenance", "rebuild-memory-projection-runner.ts"),
+    path.join(dir, "..", "maintenance", "rebuild-memory-projection-runner.js"),
+    path.join(dir, "maintenance", "rebuild-memory-projection-runner.js"),
+    path.join(dir, "rebuild-memory-projection-runner.js"),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error("projection rebuild runner was not found next to the maintenance bundle");
+}
+
+function runnerExecArgv(runnerPath: string): string[] {
+  const argv: string[] = [];
+  const source = process.execArgv;
+  for (let index = 0; index < source.length; index += 1) {
+    const arg = source[index] ?? "";
+    if (arg === "--inspect" || arg === "--inspect-brk" || arg === "--inspect-port") {
+      if (arg === "--inspect-port") index += 1;
+      continue;
+    }
+    if (arg.startsWith("--inspect=") || arg.startsWith("--inspect-brk=") || arg.startsWith("--inspect-port=")) {
+      continue;
+    }
+    argv.push(arg);
+  }
+  if (runnerPath.endsWith(".ts") && !argv.some((arg) => arg === "tsx" || arg.includes(`${path.sep}tsx`))) {
+    argv.unshift("--import", "tsx");
+  }
+  return argv;
+}
+
+function isRunnerSuccess(message: unknown): message is ProjectionRebuildForkResult & { ok: true } {
+  if (!message || typeof message !== "object") return false;
+  const row = message as Record<string, unknown>;
+  return row.ok === true
+    && typeof row.currentRows === "number"
+    && typeof row.timelineRows === "number"
+    && typeof row.entityMentionRows === "number";
+}
+
+/** Fork the projection rebuild. Arguments are path, namespace, and timestamp only. */
+export async function forkProjectionRebuild(
+  request: ProjectionRebuildForkRequest,
+  options?: {
+    timeoutMs?: number;
+    spawnChild?: () => ChildProcess;
+    /** Scheduler that owns this child. Dispose kills only that owner's child. */
+    owner?: ProjectionRebuildScheduleState;
+    /** Invoked after exit listeners are attached. Tests use this to disconnect. */
+    onChild?: (child: ChildProcess) => void;
+  },
+): Promise<ProjectionRebuildForkResult> {
+  const timeoutMs = Math.min(options?.timeoutMs ?? FORK_TIMEOUT_MS, MAX_SETTIMEOUT_MS);
+  const child = options?.spawnChild
+    ? options.spawnChild()
+    : spawnProjectionRebuildChild(request);
+  rememberProjectionRebuildChild(child, options?.owner);
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (err?: Error, result?: ProjectionRebuildForkResult) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (err) reject(err);
+      else if (result) resolve(result);
+      else reject(new Error("projection rebuild runner returned no result"));
+    };
+    timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      finish(new Error(`projection rebuild runner timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    timer.unref?.();
+    child.on("message", (message: unknown) => {
+      if (isRunnerSuccess(message)) {
+        finish(undefined, message);
+        return;
+      }
+      const error = message && typeof message === "object" && "error" in message
+        ? String((message as { error?: unknown }).error ?? "projection rebuild runner failed")
+        : "projection rebuild runner failed";
+      finish(new Error(error));
+    });
+    child.on("error", (err) => finish(err));
+    child.on("exit", (code) => {
+      if (!settled) {
+        finish(new Error(`projection rebuild runner exited ${code ?? "null"}`));
+      }
+    });
+    options?.onChild?.(child);
+  });
+}
+
+function spawnProjectionRebuildChild(request: ProjectionRebuildForkRequest): ChildProcess {
+  const runnerPath = projectionRebuildRunnerPath();
+  const nowIso = request.now.toISOString();
+  return fork(
+    runnerPath,
+    [PROJECTION_REBUILD_RUNNER_FLAG, request.memoryDir, request.defaultNamespace, nowIso],
+    {
+      execArgv: runnerExecArgv(runnerPath),
+      env: projectionRebuildChildEnv(process.env),
+      stdio: ["ignore", "inherit", "inherit", "ipc"],
+    },
+  );
+}
+
+function storageIsUnlocked(storage: InjectedStorage | undefined): boolean {
+  if (!storage || typeof storage.isSecureStoreUnlocked !== "function") return false;
+  return storage.isSecureStoreUnlocked();
+}
+
 export async function maybeRebuildMemoryProjectionScheduled(opts: {
   config: PluginConfig;
   /** The daemon's live root storage, when available (secure-store unlock). */
   getStorage?: () => InjectedStorage | undefined;
   state: ProjectionRebuildScheduleState;
+  /** Test seam. Production forks {@link forkProjectionRebuild}. */
+  forkRebuild?: (
+    request: ProjectionRebuildForkRequest,
+    options?: { timeoutMs?: number; owner?: ProjectionRebuildScheduleState },
+  ) => Promise<ProjectionRebuildForkResult>;
+  /** Test seam. Production reads `v8.getHeapStatistics()`. */
+  heapStatistics?: () => HeapLimitStatistics;
 }): Promise<void> {
   const { config, state } = opts;
   if (!resolveMemoryLifecycleCapabilities(config).projectionRebuild) return;
@@ -81,17 +328,41 @@ export async function maybeRebuildMemoryProjectionScheduled(opts: {
     return;
   }
 
+  const heapLimit = config.projectionRebuildHeapUsageLimit ?? DEFAULT_PROJECTION_REBUILD_HEAP_USAGE_LIMIT;
+  const heapStats = (opts.heapStatistics ?? (() => v8.getHeapStatistics()))();
+  const pressure = fullCorpusHeapPressure(heapStats, heapLimit);
+  if (pressure.postpone) {
+    state.lastFailureAtMs = Date.now();
+    log.warn(
+      `memory projection scheduled rebuild postponed for ${memoryDir}: `
+      + `heap used ${heapStats.used_heap_size} of limit ${heapStats.heap_size_limit} `
+      + `(ratio ${pressure.ratio.toFixed(3)}) exceeds projectionRebuildHeapUsageLimit ${heapLimit}`,
+    );
+    return;
+  }
+
+  const forkRebuild = opts.forkRebuild ?? forkProjectionRebuild;
+  const unlocked = storageIsUnlocked(rootStorage);
   state.inFlight = true;
   try {
-    const result = await rebuildMemoryProjection({
-      memoryDir,
-      // Reuse the daemon's live storage so secure-store deployments rebuild
-      // through the unlocked instance instead of a fresh locked one.
-      ...(rootStorage ? { storage: rootStorage } : {}),
-      defaultNamespace: config.defaultNamespace,
-      dryRun: false,
-      now: new Date(now),
-    });
+    const result = unlocked
+      ? await rebuildMemoryProjection({
+        memoryDir,
+        // Reuse the daemon's live storage so secure-store deployments rebuild
+        // through the unlocked instance instead of a fresh locked one.
+        ...(rootStorage ? { storage: rootStorage } : {}),
+        defaultNamespace: config.defaultNamespace,
+        dryRun: false,
+        now: new Date(now),
+      })
+      : await forkRebuild({
+        memoryDir,
+        defaultNamespace: config.defaultNamespace || "default",
+        now: new Date(now),
+      }, {
+        timeoutMs: projectionRebuildForkTimeoutMs(intervalMs),
+        owner: state,
+      });
     state.lastRebuildAtMs = Date.now();
     const lag = Number.isFinite(rebuiltAtMs)
       ? `${Math.max(0, Math.round((now - rebuiltAtMs) / 60_000))}m stale`

package/src/projection-rebuild-config.ts

@@ -0,0 +1,82 @@
+/**
+ * Scheduled projection-rebuild knobs (issue #2119, heap guard).
+ *
+ * Extracted from `config.ts` / `types.ts` so those god-file ceilings do not
+ * grow. `PluginConfig` extends the interface and `parseConfig` spreads
+ * {@link parseProjectionRebuildScheduleConfig}.
+ */
+
+import { coerceBooleanLike, coerceNumber } from "./connectors/coerce.js";
+
+/** Knobs for the maintenance-scheduled memory-projection rebuild. */
+export interface ProjectionRebuildScheduleConfig {
+  /**
+   * Enable the maintenance-scheduled rebuild of `state/memory-projection.sqlite`.
+   * The projection is otherwise rebuild-only (manual CLI / tests), so it rots as
+   * the lifecycle ledger grows and timeline/browse consumers silently regress to
+   * full-corpus fallback scans. Default true — mirrors lifecycle-ledger
+   * auto-compaction, which is likewise enabled-by-default to keep a state file
+   * healthy. Set false to disable (operators can still cron the CLI rebuild).
+   */
+  projectionRebuildEnabled: boolean;
+  /**
+   * Minimum interval between scheduled projection rebuilds. A rebuild is skipped
+   * when the projection's `rebuiltAt` meta is younger than this, so a burst of
+   * maintenance requests cannot fan into back-to-back rebuilds. Floored at 60s.
+   * Default 6h (matches memoryLifecycleLedgerCompactMinIntervalMs).
+   */
+  projectionRebuildIntervalMs: number;
+  /**
+   * Postpone a scheduled full-corpus projection rebuild when
+   * `v8.getHeapStatistics().used_heap_size / heap_size_limit` exceeds this
+   * ratio. Finite number in `(0, 1]`. Default `0.6`. `1` disables the guard
+   * (usage cannot exceed the limit). A postponed rebuild uses the failure
+   * backoff and does not start the multi-GB allocation.
+   */
+  projectionRebuildHeapUsageLimit: number;
+}
+
+/** Integer coercion contract shared with `config.ts` (`parseIntegerAtLeast`). */
+type IntegerParser = (value: unknown, fallback: number, min: number, keyName: string) => number;
+
+/** Default heap-usage ratio above which a scheduled full-corpus rebuild waits. */
+export const DEFAULT_PROJECTION_REBUILD_HEAP_USAGE_LIMIT = 0.6;
+
+/**
+ * Parse `projectionRebuildHeapUsageLimit`. Absent values take the default.
+ * A present value must be a finite number in `(0, 1]` (numeric strings
+ * coerced). `0` is rejected: it would postpone every rebuild.
+ */
+export function parseProjectionRebuildHeapUsageLimit(value: unknown): number {
+  if (value === undefined || value === null) return DEFAULT_PROJECTION_REBUILD_HEAP_USAGE_LIMIT;
+  const coerced = coerceNumber(value);
+  if (coerced === undefined || !Number.isFinite(coerced) || coerced <= 0 || coerced > 1) {
+    throw new Error(
+      `projectionRebuildHeapUsageLimit must be a finite number in (0, 1]; got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+/**
+ * Parse the scheduled projection-rebuild knobs. Boolean coercion follows
+ * gotcha #36 (`"false"` is false). The interval uses the shared integer
+ * parser (strings coerced, non-integers and sub-60s values rejected).
+ */
+export function parseProjectionRebuildScheduleConfig(
+  cfg: Record<string, unknown>,
+  parseIntegerAtLeast: IntegerParser,
+): ProjectionRebuildScheduleConfig {
+  return {
+    projectionRebuildEnabled: coerceBooleanLike(cfg.projectionRebuildEnabled) ?? true,
+    projectionRebuildIntervalMs: parseIntegerAtLeast(
+      cfg.projectionRebuildIntervalMs,
+      6 * 60 * 60 * 1000,
+      60_000,
+      "projectionRebuildIntervalMs",
+    ),
+    projectionRebuildHeapUsageLimit: parseProjectionRebuildHeapUsageLimit(
+      cfg.projectionRebuildHeapUsageLimit,
+    ),
+  };
+}

package/src/storage/memory-lifecycle-ledger-access.ts

@@ -46,33 +46,41 @@ export type LedgerSecureReader = (filePath: string) => Promise<string>;
 export type LedgerSecureBufferReader = (filePath: string) => Promise<Buffer>;
 
 /**
- * Parse + canonically sort lifecycle rows from a line source. Permissive
- * validation (any `eventType` string is admitted) — matches the historical
- * `readAllMemoryLifecycleEvents` contract that projection rebuild depends on.
- * Fail-open on malformed rows.
+ * Parse one ledger line. Permissive validation (any `eventType` string is
+ * admitted) — matches the historical `readAllMemoryLifecycleEvents` contract
+ * that projection rebuild depends on. Fail-open on malformed rows.
+ */
+function parseLifecycleLedgerLine(line: string): MemoryLifecycleEvent | null {
+  const row = line.trim();
+  if (!row) return null;
+  try {
+    const parsed = JSON.parse(row) as Partial<MemoryLifecycleEvent>;
+    if (
+      typeof parsed.eventId === "string" &&
+      typeof parsed.memoryId === "string" &&
+      typeof parsed.eventType === "string" &&
+      typeof parsed.timestamp === "string" &&
+      typeof parsed.actor === "string" &&
+      typeof parsed.ruleVersion === "string"
+    ) {
+      return parsed as MemoryLifecycleEvent;
+    }
+  } catch {
+    // Ignore malformed rows (fail-open).
+  }
+  return null;
+}
+
+/**
+ * Parse + canonically sort lifecycle rows from a line source.
  */
 async function collectLifecycleEvents(
   lines: AsyncIterable<string>,
 ): Promise<MemoryLifecycleEvent[]> {
   const out: MemoryLifecycleEvent[] = [];
   for await (const line of lines) {
-    const row = line.trim();
-    if (!row) continue;
-    try {
-      const parsed = JSON.parse(row) as Partial<MemoryLifecycleEvent>;
-      if (
-        typeof parsed.eventId === "string" &&
-        typeof parsed.memoryId === "string" &&
-        typeof parsed.eventType === "string" &&
-        typeof parsed.timestamp === "string" &&
-        typeof parsed.actor === "string" &&
-        typeof parsed.ruleVersion === "string"
-      ) {
-        out.push(parsed as MemoryLifecycleEvent);
-      }
-    } catch {
-      // Ignore malformed rows (fail-open).
-    }
+    const parsed = parseLifecycleLedgerLine(line);
+    if (parsed) out.push(parsed);
   }
   return sortMemoryLifecycleEvents(out);
 }
@@ -116,27 +124,47 @@ async function* linesFromBuffer(
 }
 
 /**
- * Every valid ledger row in canonical order, read through the string-capped
- * secure line source (refuses an encrypted body over the whole-file decrypt
- * limit). General readers use this; compaction uses the uncapped buffer variant.
+ * Yield each valid ledger row in file order. Unlike
+ * {@link readAllLifecycleEventsFromLedger}, this does not accumulate or sort
+ * the ledger first. ENOENT yields nothing; a locked secure store rethrows.
+ * Malformed rows are skipped.
  */
-export async function readAllLifecycleEventsFromLedger(
+export async function* iterateLifecycleEventsFromLedger(
   ledgerPath: string,
   readSecureFile: LedgerSecureReader,
-): Promise<MemoryLifecycleEvent[]> {
+): AsyncGenerator<MemoryLifecycleEvent> {
+  let lines: AsyncGenerator<string>;
   try {
-    return await collectLifecycleEvents(
-      readMaybeEncryptedLines(
-        ledgerPath,
-        () => readSecureFile(ledgerPath),
-        STATE_FILE_MAX_DECRYPT_BYTES,
-      ),
+    lines = readMaybeEncryptedLines(
+      ledgerPath,
+      () => readSecureFile(ledgerPath),
+      STATE_FILE_MAX_DECRYPT_BYTES,
     );
   } catch (err) {
     if (err instanceof SecureStoreLockedError) throw err;
     if (!isErrnoCode(err, "ENOENT")) throw err;
-    return [];
+    return;
   }
+  try {
+    for await (const line of lines) {
+      const parsed = parseLifecycleLedgerLine(line);
+      if (parsed) yield parsed;
+    }
+  } catch (err) {
+    if (err instanceof SecureStoreLockedError) throw err;
+    if (!isErrnoCode(err, "ENOENT")) throw err;
+  }
+}
+
+export async function readAllLifecycleEventsFromLedger(
+  ledgerPath: string,
+  readSecureFile: LedgerSecureReader,
+): Promise<MemoryLifecycleEvent[]> {
+  const out: MemoryLifecycleEvent[] = [];
+  for await (const event of iterateLifecycleEventsFromLedger(ledgerPath, readSecureFile)) {
+    out.push(event);
+  }
+  return sortMemoryLifecycleEvents(out);
 }
 
 /**

package/src/storage/memory-read-store.ts

@@ -69,6 +69,7 @@ export interface MemoryReadStoreDeps {
   readParsedMemoriesFromPaths(
     filePaths: string[],
     batchSize?: number,
+    options?: CorpusReadOptions,
   ): Promise<MemoryFile[]>;
   readStorageSecureFile(filePath: string): Promise<string>;
   readWindowBoundedBatch(
@@ -466,7 +467,9 @@ export class MemoryReadStore {
    * covers any hot→cold demotion that changes cold-tier contents) and
    * expires after COLD_SCAN_CACHE_TTL_MS as a safety net.
    */
-  async readAllColdMemories(): Promise<MemoryFile[]> {
+  async readAllColdMemories(options?: CorpusReadOptions): Promise<MemoryFile[]> {
+    checkCorpusReadAbort(options);
+    const retainRaw = options?.retainRaw !== false;
     const coldRoot = this.deps.resolveTierRootDir("cold");
 
     // Read the on-disk cold-version sentinel BEFORE checking the cache so that
@@ -480,7 +483,7 @@ export class MemoryReadStore {
     // decrypts per this manager's key, so a differently-keyed manager must not
     // read a cold corpus another instance decrypted for the same coldRoot.
     const keyId = this.deps.hotCacheKeyId();
-    const cached = this.deps.storageManagerClass.coldMemoriesCache.get(coldRoot);
+    const cached = retainRaw ? this.deps.storageManagerClass.coldMemoriesCache.get(coldRoot) : undefined;
     if (
       cached &&
       cached.keyId === keyId &&
@@ -518,11 +521,14 @@ export class MemoryReadStore {
     // and ensures that any memory with structuredAttributes is found regardless
     // of which category it was written with.
     await collectPaths(coldRoot);
-    const memories = await this.deps.readParsedMemoriesFromPaths(filePaths, 50);
+    const memories = await this.deps.readParsedMemoriesFromPaths(filePaths, 50, options);
 
     // Store in cache with the sentinel version captured above so that any
     // subsequent cold-version bump (by this or another process) invalidates it.
-    this.deps.storageManagerClass.coldMemoriesCache.set(coldRoot, { memories, loadedAt: Date.now(), coldVersion: currentColdVersion, keyId });
+    // A raw-free read stays out of the cache so it cannot evict the raw copy.
+    if (retainRaw) {
+      this.deps.storageManagerClass.coldMemoriesCache.set(coldRoot, { memories, loadedAt: Date.now(), coldVersion: currentColdVersion, keyId });
+    }
     return memories;
   }