@remnic/core 9.7.7 → 9.7.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.7.7",
+  "version": "9.7.9",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -1090,6 +1090,16 @@
       "remnic-source": "./src/importance.ts",
       "import": "./dist/importance.js"
     },
+    "./in-flight-reads": {
+      "types": "./dist/in-flight-reads.d.ts",
+      "remnic-source": "./src/in-flight-reads.ts",
+      "import": "./dist/in-flight-reads.js"
+    },
+    "./in-flight-reads.js": {
+      "types": "./dist/in-flight-reads.d.ts",
+      "remnic-source": "./src/in-flight-reads.ts",
+      "import": "./dist/in-flight-reads.js"
+    },
     "./index": {
       "types": "./dist/index.d.ts",
       "remnic-source": "./src/index.ts",
@@ -3000,7 +3010,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.7.7"
+    "@remnic/coding-graph": "^9.7.9"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/binary-lifecycle/pipeline.ts

@@ -18,6 +18,21 @@ import type {
 import type { BinaryStorageBackend } from "./backend.js";
 import { readManifest, writeManifest } from "./manifest.js";
 import { scanForBinaries } from "./scanner.js";
+import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
+import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
+
+/**
+ * True when `mdPath` is an active recall-corpus memory file under `memoryDir`
+ * (a top-level RECALL_FALLBACK_DIRS category), so a redirect rewrite of it must
+ * bump the corpus sentinel to self-heal a warm hot-memories cache (#1902).
+ * entities/, artifacts/, and other non-recall paths need no bump.
+ */
+function isRecallCorpusMarkdown(mdPath: string, memoryDir: string): boolean {
+  const rel = path.relative(memoryDir, mdPath);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return false;
+  const top = rel.split(path.sep)[0];
+  return (RECALL_FALLBACK_DIRS as readonly string[]).includes(top);
+}
 
 /** Minimal logger interface so we don't depend on the full logger module. */
 interface PipelineLogger {
@@ -305,6 +320,13 @@ async function stageRedirect(
     for (const update of updates) {
       try {
         await writeMarkdownFile(update.mdPath, update.content);
+        // The redirect rewrote an on-disk memory file out-of-band (not through a
+        // StorageManager mutation). Bump the corpus sentinel per write so a warm
+        // hot-memories cache rescans — mid-batch too, never serving pre-redirect
+        // content (#1902). Only recall-corpus files affect that cache.
+        if (isRecallCorpusMarkdown(update.mdPath, memoryDir)) {
+          bumpMemoryCorpusVersionForDir(memoryDir);
+        }
       } catch (err) {
         writeFailCount++;
         const msg = `redirect write failed for ${update.mdPath}: ${err instanceof Error ? err.message : String(err)}`;

package/src/cli.ts

@@ -10,6 +10,7 @@ import { resolveNamespaceCapabilities,
   resolveIdentityContinuityCapabilities,
   resolveSecurityCapabilities, resolveEvalCapabilities, resolveConsolidationCapabilities, resolveRecallAuxiliaryCapabilities } from "./capabilities.js";
 import { ThreadingManager } from "./threading.js";
+import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 import { utcDayRange } from "./transcript.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
 import { registerResearchStatusCommands } from "./cli/research-status-commands.js";
@@ -7495,6 +7496,11 @@ export function registerCli(
             try {
               await unlink(filePath);
               deleted += 1;
+              // Per-delete corpus bump (Cursor Medium, #1902): dedupe removes
+              // active memory files directly (bypassing StorageManager), so bump
+              // each delete to keep a same-process or peer readAllMemories from
+              // recalling a duplicate that was already removed mid-batch.
+              bumpMemoryCorpusVersionForDir(memoryDir);
             } catch (err) {
               console.log(`  failed to delete ${filePath}: ${String(err)}`);
             }
@@ -7556,6 +7562,8 @@ export function registerCli(
             try {
               await unlink(filePath);
               deleted += 1;
+              // Per-delete corpus bump (Cursor Medium, #1902) — see dedupe-exact.
+              bumpMemoryCorpusVersionForDir(memoryDir);
             } catch (err) {
               console.log(`  failed to delete ${filePath}: ${String(err)}`);
             }

package/src/compounding/engine.ts

@@ -321,7 +321,15 @@ function normalizePromotionWhitespace(value: string): string {
 }
 
 function stripTrailingPromotionPunctuation(value: string): string {
-  return value.replace(/[,:;]+$/g, "").trim();
+  // Linear trailing-punctuation strip (no `/[,:;]+$/` — CodeQL flags that as a
+  // polynomial-backtracking ReDoS on long runs of ',;:'). Walk back once, O(n).
+  let end = value.length;
+  while (end > 0) {
+    const ch = value[end - 1];
+    if (ch === "," || ch === ":" || ch === ";") end--;
+    else break;
+  }
+  return value.slice(0, end).trim();
 }
 
 function extractExplicitIfThenRule(value: string): string | null {

package/src/config.ts

@@ -2106,6 +2106,20 @@ export function parseConfig(
     // opt out with recallMemoryWorthFilterEnabled=false.
     recallMemoryWorthFilterEnabled:
       coerceBool(cfg.recallMemoryWorthFilterEnabled) ?? true,
+    // Hot-memories result cache (issue #1902). Default on: readAllMemories()
+    // serves from the version-keyed in-process corpus cache. coerceBool
+    // handles "false"/"0" string forms; set false to force disk scans.
+    hotMemoriesCacheEnabled: coerceBool(cfg.hotMemoriesCacheEnabled) ?? true,
+    // External-edit safety net (issue #1902): the version sentinel gives
+    // immediate coherence for cooperating writers, but direct user/git/editor
+    // writes to memory files (which the project supports) don't bump it. Bound
+    // the hot cache's staleness with a TTL so such edits self-heal. Default 60s;
+    // 0 disables the TTL (version invalidation only — max perf for pure-daemon
+    // deployments with no external edits). coerceNumber handles string forms.
+    hotMemoriesCacheTtlMs: (() => {
+      const n = coerceNumber(cfg.hotMemoriesCacheTtlMs);
+      return n !== undefined && n >= 0 ? n : 60_000;
+    })(),
     recallMemoryWorthHalfLifeMs: (() => {
       const n = coerceNumber(cfg.recallMemoryWorthHalfLifeMs);
       return n !== undefined && n >= 0 ? n : 0;

package/src/consolidation-undo.ts

@@ -25,6 +25,7 @@ import { mkdir, writeFile, access, realpath, lstat } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import type { StorageManager } from "./storage.js";
 import type { VersioningConfig } from "./page-versioning.js";
+import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 import { getVersion } from "./page-versioning.js";
 
 /**
@@ -646,6 +647,13 @@ export async function runConsolidationUndo(options: {
         // write fails with EEXIST instead of silently overwriting the new
         // file (PR #637 round-11 review, codex P1).
         await writeFile(p.sourcePath, p.content, { encoding: "utf-8", flag: "wx" });
+        // Restore writes an active memory file back out-of-band (direct wx write,
+        // not a StorageManager mutation). Bump the corpus sentinel per successful
+        // restore so a warm hot-memories cache rescans — a later restore failure
+        // returns before archiveMemory() runs, so without this the already-written
+        // restores would stay invisible to recall until an unrelated mutation or
+        // restart (esp. with hotMemoriesCacheTtlMs: 0). Issue #1902, Codex Medium.
+        bumpMemoryCorpusVersionForDir(memoryDir);
         result.restores.push({
           entry: p.entry,
           sourcePath: p.sourcePath,

package/src/curation/index.ts

@@ -9,6 +9,7 @@ import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { getCategoryDir, ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
+import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -202,6 +203,10 @@ export async function curate(options: CurateOptions): Promise<CurateResult> {
     }
   }
 
+  // Per-statement corpus bumps happen in writeStatement (below) so a
+  // same-process readAllMemories mid-batch never serves a stale/partial corpus
+  // (Cursor Medium, #1902); no after-loop bump needed here.
+
   return {
     statements,
     filesProcessed,
@@ -471,6 +476,10 @@ function writeStatement(stmt: CuratedStatement, memoryDir: string): string {
   const body = `${frontmatter}\n\n${stmt.content}\n`;
 
   fs.writeFileSync(filePath, body);
+  // Bump the corpus sentinel per write (out-of-band create) so a concurrent
+  // same-process readAllMemories rescans and sees this statement immediately,
+  // never a stale/partial corpus mid-batch (Cursor Medium, #1902).
+  bumpMemoryCorpusVersionForDir(memoryDir);
   return filePath;
 }
 

package/src/in-flight-reads.ts

@@ -0,0 +1,63 @@
+import type { MemoryFile } from "./types.js";
+
+/**
+ * In-flight readAllMemories() dedup registry (issue #1902).
+ *
+ * NOT a cache layer — it holds transient per-(directory, secure-store key) scan
+ * promises so temporally-overlapping reads collapse onto ONE disk scan; the slot
+ * is deleted when the promise settles. It lives in its own module (not
+ * memory-cache.ts) so it is not swept by the ALL_CACHE_LAYERS invalidation
+ * contract, yet remains importable by both StorageManager and the out-of-band
+ * corpus-bump helper (memory-corpus-version.ts).
+ *
+ * Keyed by baseDir AND secure-store key identity (Codex P1 / Cursor Medium):
+ * an unlocked manager's decrypted scan must NOT be handed to a locked or
+ * differently-keyed manager for the same dir — that would bypass the keyId
+ * isolation getCachedMemories enforces. Locked/plaintext stores use keyId "".
+ */
+const inFlightReadsByKey = new Map<string, Promise<MemoryFile[]>>();
+
+const DIR_SEP = "\u0000";
+
+function composeKey(baseDir: string, keyId: string): string {
+  return `${baseDir}${DIR_SEP}${keyId}`;
+}
+
+export function getInFlightRead(baseDir: string, keyId = ""): Promise<MemoryFile[]> | undefined {
+  return inFlightReadsByKey.get(composeKey(baseDir, keyId));
+}
+
+export function setInFlightRead(baseDir: string, keyId: string, read: Promise<MemoryFile[]>): void {
+  inFlightReadsByKey.set(composeKey(baseDir, keyId), read);
+}
+
+/**
+ * Delete the in-flight slot for one (baseDir, keyId). When `expected` is given,
+ * only deletes if the slot still holds that exact promise (owner-only clear).
+ */
+export function deleteInFlightRead(
+  baseDir: string,
+  keyId = "",
+  expected?: Promise<MemoryFile[]>,
+): void {
+  const key = composeKey(baseDir, keyId);
+  if (expected === undefined || inFlightReadsByKey.get(key) === expected) {
+    inFlightReadsByKey.delete(key);
+  }
+}
+
+/**
+ * Drop EVERY in-flight slot for `baseDir` across all secure-store identities.
+ * Used by mutations / invalidation / out-of-band corpus bumps: after the corpus
+ * changes, no reader of any key identity may attach to a pre-mutation scan.
+ */
+export function deleteInFlightReadsForDir(baseDir: string): void {
+  const prefix = `${baseDir}${DIR_SEP}`;
+  for (const key of inFlightReadsByKey.keys()) {
+    if (key.startsWith(prefix)) inFlightReadsByKey.delete(key);
+  }
+}
+
+export function clearInFlightReads(): void {
+  inFlightReadsByKey.clear();
+}

package/src/maintenance/memory-governance.ts

@@ -4,6 +4,7 @@ import { StorageManager } from "../storage.js";
 import { decideLifecycleTransition } from "../lifecycle.js";
 import type { MemoryFile, MemoryStatus } from "../types.js";
 import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
+import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 import { assertPathInsideRoot } from "../utils/path-containment.js";
 
 export type MemoryGovernanceMode = "shadow" | "apply";
@@ -1015,6 +1016,11 @@ export async function restoreMemoryGovernanceRun(
     await mkdir(path.dirname(entry.originalPath), { recursive: true });
     await writeFile(entry.originalPath, entry.beforeRaw, "utf-8");
     restoredActions += 1;
+    // Restore writes/removes memory files directly (out-of-band — not through a
+    // StorageManager mutation). Bump the corpus sentinel PER entry so a
+    // same-process or peer readAllMemories rescans mid-batch and never serves a
+    // partially-restored corpus (Cursor Medium, #1902).
+    bumpMemoryCorpusVersionForDir(options.memoryDir);
   }
 
   return {

package/src/memory-cache-hot.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Issue #1902 — unit tests for the hot-memories result cache layer.
+ *
+ * These pin the low-level cache contract that StorageManager.readAllMemories()
+ * relies on: version-keyed round-trip, the version-0 and version-mismatch null
+ * guards, in-place patch-on-write / patch-on-delete, and the two invalidation
+ * shapes (wholesale drop vs derived/global-only keep).
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  clearMemoryCache,
+  getCachedMemories,
+  invalidateAllForDir,
+  invalidateDerivedAndGlobalForDir,
+  setCachedMemories,
+  updateCacheOnDelete,
+  updateCacheOnWrite,
+} from "./memory-cache.js";
+import type { MemoryFile } from "./types.js";
+
+function mem(p: string, content = "x"): MemoryFile {
+  return {
+    path: p,
+    frontmatter: { id: p, category: "fact" },
+    content,
+  } as unknown as MemoryFile;
+}
+
+test("hot cache: round-trips at a matching version", () => {
+  const dir = "/tmp/remnic-hot-unit-a";
+  clearMemoryCache();
+  setCachedMemories(dir, [mem("a.md"), mem("b.md")], 3);
+  const got = getCachedMemories(dir, 3);
+  assert.ok(got, "expected a cache hit at the matching version");
+  assert.deepEqual(got!.map((m) => m.path).sort(), ["a.md", "b.md"]);
+  clearMemoryCache();
+});
+
+test("hot cache: version 0 always misses (fresh/test dirs)", () => {
+  const dir = "/tmp/remnic-hot-unit-b";
+  clearMemoryCache();
+  setCachedMemories(dir, [mem("a.md")], 0);
+  assert.equal(getCachedMemories(dir, 0), null, "version 0 must never serve a cache hit");
+  clearMemoryCache();
+});
+
+test("hot cache: version mismatch misses (never serves stale)", () => {
+  const dir = "/tmp/remnic-hot-unit-c";
+  clearMemoryCache();
+  setCachedMemories(dir, [mem("a.md")], 5);
+  assert.ok(getCachedMemories(dir, 5), "same version hits");
+  assert.equal(getCachedMemories(dir, 6), null, "a bumped version must miss");
+  clearMemoryCache();
+});
+
+test("hot cache: updateCacheOnWrite / updateCacheOnDelete mutate the entry in place", () => {
+  const dir = "/tmp/remnic-hot-unit-d";
+  clearMemoryCache();
+  setCachedMemories(dir, [mem("a.md")], 2);
+  updateCacheOnWrite(dir, mem("b.md", "new"));
+  const afterWrite = getCachedMemories(dir, 2);
+  assert.deepEqual(afterWrite!.map((m) => m.path).sort(), ["a.md", "b.md"], "write adds in place");
+  updateCacheOnWrite(dir, mem("a.md", "updated"));
+  assert.equal(
+    getCachedMemories(dir, 2)!.find((m) => m.path === "a.md")!.content,
+    "updated",
+    "write to an existing path replaces in place",
+  );
+  updateCacheOnDelete(dir, "a.md");
+  assert.deepEqual(getCachedMemories(dir, 2)!.map((m) => m.path), ["b.md"], "delete removes in place");
+  clearMemoryCache();
+});
+
+test("hot cache: wholesale invalidateAllForDir drops the hot layer; invalidateDerivedAndGlobalForDir keeps it", () => {
+  const dir = "/tmp/remnic-hot-unit-e";
+  clearMemoryCache();
+  setCachedMemories(dir, [mem("a.md")], 4);
+  invalidateDerivedAndGlobalForDir(dir);
+  assert.ok(
+    getCachedMemories(dir, 4),
+    "invalidateDerivedAndGlobalForDir must NOT drop the hot layer (patch-on-write keeps it warm)",
+  );
+  invalidateAllForDir(dir);
+  assert.equal(getCachedMemories(dir, 4), null, "invalidateAllForDir must drop the hot layer");
+  clearMemoryCache();
+});
+
+test("hot cache: keyId scopes entries — a mismatched secure-store key misses (#1902 Codex P1)", () => {
+  const dir = "/tmp/remnic-hot-unit-keyid";
+  clearMemoryCache();
+  // A keyed (unlocked encrypted) manager warms the cache with decrypted content.
+  setCachedMemories(dir, [mem("secret.md", "decrypted")], 5, "secure-store:key:1");
+  // A locked/unkeyed manager for the SAME dir must NOT read the decrypted entry.
+  assert.equal(
+    getCachedMemories(dir, 5, ""),
+    null,
+    "a manager without the matching key must miss the decrypted cache entry",
+  );
+  // A different key id also misses.
+  assert.equal(getCachedMemories(dir, 5, "secure-store:key:2"), null, "a different key id misses");
+  // The matching key id hits.
+  const got = getCachedMemories(dir, 5, "secure-store:key:1");
+  assert.ok(got, "the matching key id serves the cached corpus");
+  assert.deepEqual(got!.map((m) => m.path), ["secret.md"]);
+  clearMemoryCache();
+});
+
+test("hot cache: TTL expires an entry so external edits self-heal (#1902 Codex P1)", (t) => {
+  const dir = "/tmp/remnic-hot-unit-ttl";
+  clearMemoryCache();
+  // Deterministic time control (no real timers): the entry's loadedAt is stamped
+  // from the mocked clock at set time; advancing it past the TTL forces a miss.
+  t.mock.timers.enable({ apis: ["Date"] });
+  try {
+    setCachedMemories(dir, [mem("a.md")], 9, "");
+    // ttl=0 disables the TTL: always a hit at the matching version.
+    assert.ok(getCachedMemories(dir, 9, "", 0), "ttl=0 disables expiry");
+    // Fresh entry within a generous TTL still hits.
+    assert.ok(getCachedMemories(dir, 9, "", 60_000), "fresh entry within TTL hits");
+    // Advance past the TTL: the entry is now a miss, forcing a rescan that would
+    // pick up any external filesystem edit that bypassed the version sentinel.
+    t.mock.timers.tick(120_000);
+    assert.equal(getCachedMemories(dir, 9, "", 60_000), null, "entry older than ttl is a miss");
+  } finally {
+    t.mock.timers.reset();
+    clearMemoryCache();
+  }
+});

package/src/memory-cache.ts

@@ -5,49 +5,107 @@ interface CacheEntry {
   memories: Map<string, MemoryFile>; // keyed by file path
   version: number;
   loadedAt: number;
+  // Secure-store key identity that decrypted these memories (issue #1902, Codex
+  // P1). "" for plaintext/locked stores. A manager only reads an entry whose
+  // keyId matches its own, so a locked/unkeyed instance never sees content
+  // another instance decrypted under a key for the same baseDir.
+  keyId: string;
+  // Effective TTL (ms) this entry was stored under (issue #1902, Codex Medium),
+  // so the opportunistic sweep can evict abandoned corpora that are never
+  // revisited. 0 = no TTL (never swept by age).
+  ttlMs: number;
 }
 
 // Module-level singleton — shared across all StorageManager instances and sessions
 const hotCacheByDir = new Map<string, CacheEntry>();
 const archiveCacheByDir = new Map<string, CacheEntry>();
 
-export function getCachedMemories(baseDir: string, currentVersion: number): MemoryFile[] | null {
+/**
+ * Evict every hot entry whose own TTL has elapsed (issue #1902, Codex Medium).
+ * Called opportunistically on each set so a long-running process that reads many
+ * namespace/temporary roots and never revisits some of them still releases their
+ * (potentially hundreds-of-MB) corpora within the TTL, instead of holding them
+ * resident until an explicit global clear. O(entries) over a small map.
+ */
+function sweepExpiredHotEntries(now: number): void {
+  for (const [dir, entry] of hotCacheByDir) {
+    if (entry.ttlMs > 0 && now - entry.loadedAt > entry.ttlMs) hotCacheByDir.delete(dir);
+  }
+}
+
+export function getCachedMemories(
+  baseDir: string,
+  currentVersion: number,
+  keyId = "",
+  ttlMs = 0,
+): MemoryFile[] | null {
   // Don't serve from cache when version tracking is unavailable (version=0).
   // This ensures tests and fresh installs without a version file always read disk.
   if (currentVersion === 0) return null;
   const entry = hotCacheByDir.get(baseDir);
-  if (!entry || entry.version !== currentVersion) return null;
+  if (!entry || entry.version !== currentVersion || entry.keyId !== keyId) return null;
+  // TTL safety net (issue #1902): bound staleness from external filesystem edits
+  // that bypass the version sentinel. ttlMs <= 0 disables the check. On expiry
+  // evict the entry (not just return null) so a revisited-but-stale dir releases
+  // its resident corpus instead of lingering until an explicit clear.
+  if (ttlMs > 0 && Date.now() - entry.loadedAt > ttlMs) {
+    hotCacheByDir.delete(baseDir);
+    return null;
+  }
   return [...entry.memories.values()];
 }
 
-export function setCachedMemories(baseDir: string, memories: MemoryFile[], version: number): void {
+export function setCachedMemories(
+  baseDir: string,
+  memories: MemoryFile[],
+  version: number,
+  keyId = "",
+  ttlMs = 0,
+): void {
   const map = new Map<string, MemoryFile>();
   for (const m of memories) map.set(m.path, m);
-  hotCacheByDir.set(baseDir, { memories: map, version, loadedAt: Date.now() });
+  const now = Date.now();
+  hotCacheByDir.set(baseDir, { memories: map, version, loadedAt: now, keyId, ttlMs });
+  // Release abandoned corpora that expired but were never revisited (Codex Medium).
+  sweepExpiredHotEntries(now);
 }
 
-export function updateCacheOnWrite(baseDir: string, memory: MemoryFile): void {
+export function updateCacheOnWrite(baseDir: string, memory: MemoryFile, keyId = ""): void {
   const entry = hotCacheByDir.get(baseDir);
-  if (entry) entry.memories.set(memory.path, memory);
+  // Only mutate an entry that belongs to THIS key identity (issue #1902, Codex
+  // Medium). A concurrent differently-keyed manager may have replaced the
+  // single hotCacheByDir slot during an awaited parse; inserting our decrypted
+  // MemoryFile into its entry would leak plaintext across the key boundary.
+  if (entry && entry.keyId === keyId) entry.memories.set(memory.path, memory);
 }
 
-export function updateCacheOnDelete(baseDir: string, filePath: string): void {
+export function updateCacheOnDelete(baseDir: string, filePath: string, keyId = ""): void {
   const entry = hotCacheByDir.get(baseDir);
-  if (entry) entry.memories.delete(filePath);
+  if (entry && entry.keyId === keyId) entry.memories.delete(filePath);
 }
-
 // Archive cache — same pattern, separate store
-export function getCachedArchivedMemories(baseDir: string, currentVersion: number): MemoryFile[] | null {
+export function getCachedArchivedMemories(
+  baseDir: string,
+  currentVersion: number,
+  keyId = "",
+): MemoryFile[] | null {
   if (currentVersion === 0) return null;
   const entry = archiveCacheByDir.get(baseDir);
-  if (!entry || entry.version !== currentVersion) return null;
+  if (!entry || entry.version !== currentVersion || entry.keyId !== keyId) return null;
   return [...entry.memories.values()];
 }
 
-export function setCachedArchivedMemories(baseDir: string, memories: MemoryFile[], version: number): void {
+export function setCachedArchivedMemories(
+  baseDir: string,
+  memories: MemoryFile[],
+  version: number,
+  keyId = "",
+): void {
   const map = new Map<string, MemoryFile>();
   for (const m of memories) map.set(m.path, m);
-  archiveCacheByDir.set(baseDir, { memories: map, version, loadedAt: Date.now() });
+  // ttlMs: 0 — the archive cache has no age TTL; it is version-keyed and cleared
+  // via invalidation. The field satisfies the shared CacheEntry shape (#1902).
+  archiveCacheByDir.set(baseDir, { memories: map, version, loadedAt: Date.now(), keyId, ttlMs: 0 });
 }
 
 // Entity cache — same pattern as memory cache, but keyed by schema-aware parse inputs.
@@ -108,41 +166,77 @@ export function invalidateCachedEntities(baseDir: string): void {
 interface DerivedCacheEntry<T> {
   data: T;
   sourceVersion: number; // matches the hot cache version it was derived from
+  keyId: string; // secure-store key identity of the corpus it was derived from (#1902)
+  loadedAt: number; // build time — bounds staleness from external edits via ttlMs (#1902)
 }
 
 const episodeMapByDir = new Map<string, DerivedCacheEntry<Map<string, MemoryFile>>>();
 const ruleMemoriesByDir = new Map<string, DerivedCacheEntry<{ all: MemoryFile[]; byId: Map<string, MemoryFile> }>>();
 
-/** Get a pre-filtered Map of episode memories (keyed by ID). Derived from hot cache. */
-export function getCachedEpisodeMap(baseDir: string, currentVersion: number): Map<string, MemoryFile> | null {
+export function getCachedEpisodeMap(
+  baseDir: string,
+  currentVersion: number,
+  keyId = "",
+  ttlMs = 0,
+): Map<string, MemoryFile> | null {
   if (currentVersion === 0) return null;
   const entry = episodeMapByDir.get(baseDir);
-  if (!entry || entry.sourceVersion !== currentVersion) return null;
+  if (!entry || entry.sourceVersion !== currentVersion || entry.keyId !== keyId) return null;
+  // TTL safety net (issue #1902): the version sentinel doesn't move on a direct
+  // external edit, so bound how long a derived view is served before a rebuild
+  // (which re-reads via readAllMemories, itself TTL-bounded). ttlMs <= 0 disables.
+  if (ttlMs > 0 && Date.now() - entry.loadedAt > ttlMs) {
+    episodeMapByDir.delete(baseDir);
+    return null;
+  }
   return entry.data;
 }
 
 /** Build and cache the episode memory map from the full memory list. */
-export function setCachedEpisodeMap(baseDir: string, memories: MemoryFile[], version: number): Map<string, MemoryFile> {
+export function setCachedEpisodeMap(
+  baseDir: string,
+  memories: MemoryFile[],
+  version: number,
+  cache = true,
+  keyId = "",
+): Map<string, MemoryFile> {
   const map = new Map<string, MemoryFile>();
   for (const m of memories) {
     if (m.frontmatter.status === "archived" || m.frontmatter.status === "forgotten") continue;
     if (m.frontmatter.memoryKind !== "episode") continue;
     map.set(m.frontmatter.id, m);
   }
-  episodeMapByDir.set(baseDir, { data: map, sourceVersion: version });
+  if (cache) episodeMapByDir.set(baseDir, { data: map, sourceVersion: version, keyId, loadedAt: Date.now() });
   return map;
 }
 
 /** Get pre-filtered rule memories. Derived from hot cache. */
-export function getCachedRuleMemories(baseDir: string, currentVersion: number): { all: MemoryFile[]; byId: Map<string, MemoryFile> } | null {
+export function getCachedRuleMemories(
+  baseDir: string,
+  currentVersion: number,
+  keyId = "",
+  ttlMs = 0,
+): { all: MemoryFile[]; byId: Map<string, MemoryFile> } | null {
   if (currentVersion === 0) return null;
   const entry = ruleMemoriesByDir.get(baseDir);
-  if (!entry || entry.sourceVersion !== currentVersion) return null;
+  if (!entry || entry.sourceVersion !== currentVersion || entry.keyId !== keyId) return null;
+  // TTL safety net (issue #1902): bound staleness from direct external edits
+  // that don't move the version sentinel. ttlMs <= 0 disables.
+  if (ttlMs > 0 && Date.now() - entry.loadedAt > ttlMs) {
+    ruleMemoriesByDir.delete(baseDir);
+    return null;
+  }
   return entry.data;
 }
 
 /** Build and cache the rule memories from the full memory list. */
-export function setCachedRuleMemories(baseDir: string, memories: MemoryFile[], version: number): { all: MemoryFile[]; byId: Map<string, MemoryFile> } {
+export function setCachedRuleMemories(
+  baseDir: string,
+  memories: MemoryFile[],
+  version: number,
+  cache = true,
+  keyId = "",
+): { all: MemoryFile[]; byId: Map<string, MemoryFile> } {
   const byId = new Map<string, MemoryFile>();
   const all: MemoryFile[] = [];
   for (const m of memories) {
@@ -156,7 +250,7 @@ export function setCachedRuleMemories(baseDir: string, memories: MemoryFile[], v
     }
   }
   const result = { all, byId };
-  ruleMemoriesByDir.set(baseDir, { data: result, sourceVersion: version });
+  if (cache) ruleMemoriesByDir.set(baseDir, { data: result, sourceVersion: version, keyId, loadedAt: Date.now() });
   return result;
 }
 
@@ -295,6 +389,36 @@ export function invalidateAllForDir(baseDir: string): void {
   }
 }
 
+/**
+ * Invalidate every cache layer for `baseDir` EXCEPT the hot-memories layer
+ * (issue #1902). Single-file write paths use this instead of
+ * `invalidateAllForDir` because they patch the hot-memories entry in place
+ * (via `updateCacheOnWrite`/`updateCacheOnDelete`) and re-key it to the bumped
+ * version — so dropping it here would defeat the whole warm-cache fast path.
+ * The derived episode/rule views and the global QMD caches are cheap to
+ * rebuild and are not patched, so they are still evicted here. Every other
+ * layer remains reachable for the wholesale `invalidateAllForDir` /
+ * `clearMemoryCache` chokepoint used by bulk/ambiguous mutations.
+ */
+export function invalidateDerivedAndGlobalForDir(baseDir: string): void {
+  // Preserve the layers a single-file write intentionally keeps warm (issue
+  // #1902, Codex Medium): hot-memories is patched + re-keyed in place; the
+  // entities layer is keyed on memory-status, which plain create/content writes
+  // deliberately do NOT bump (so entity retrieval stays warm); and the
+  // archive-memories layer is version-keyed on the archive tier, untouched by a
+  // hot-tier write. Evict ONLY the derived (episode/rule) and global (QMD) views.
+  for (const layer of ALL_CACHE_LAYERS) {
+    if (
+      layer.name === "hot-memories" ||
+      layer.name === "entities" ||
+      layer.name === "archive-memories"
+    ) {
+      continue;
+    }
+    layer.invalidateForDir(baseDir);
+  }
+}
+
 export function clearMemoryCache(baseDir?: string): void {
   if (baseDir) {
     invalidateAllForDir(baseDir);