@remnic/core 9.7.7 → 9.7.9

package/src/memory-corpus-version.ts

@@ -0,0 +1,45 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { deleteInFlightReadsForDir } from "./in-flight-reads.js";
+import { invalidateDerivedAndGlobalForDir } from "./memory-cache.js";
+
+/**
+ * Filename of the memory-corpus version sentinel (issue #1902). MUST stay in
+ * sync with `StorageManager.versionFilePath("memory-corpus")` in storage.ts —
+ * the byte size of this append-only file IS the corpus version, and the
+ * version-keyed hot-memories result cache keys on it.
+ */
+export const MEMORY_CORPUS_VERSION_SENTINEL = ".memory-corpus-version.log";
+
+/**
+ * Out-of-band corpus-version bump (issue #1902) for code paths that write or
+ * modify memory files WITHOUT going through a StorageManager mutation method
+ * — review approval, governance restore, migration. Appends one byte to the
+ * on-disk sentinel so any process's version-keyed hot-memories cache rescans
+ * on its next read (StorageManager.readSharedVersion reads the file size, so
+ * the growth is observed immediately). Fail-open: a bump failure must never
+ * crash the caller — a stale-cache window self-heals on the next real write.
+ */
+export function bumpMemoryCorpusVersionForDir(memoryDir: string): void {
+  try {
+    const stateDir = path.join(memoryDir, "state");
+    mkdirSync(stateDir, { recursive: true });
+    appendFileSync(path.join(stateDir, MEMORY_CORPUS_VERSION_SENTINEL), "x");
+  } catch {
+    /* fail-open: never let a cache-coherence bump crash the primary operation */
+  }
+  // Drop any in-flight readAllMemories scan for this dir (Cursor Medium, #1902):
+  // after the sentinel advances, a concurrent read that missed the version-keyed
+  // hot entry must not attach to a scan that began BEFORE this out-of-band write
+  // and receive a pre-write corpus. Clearing forces a fresh scan of disk truth.
+  deleteInFlightReadsForDir(memoryDir);
+  // Also evict the TTL-keyed derived (episode/rule) and global (QMD search/recall)
+  // caches for this dir (issue #1902, Codex Medium). The sentinel bump self-heals
+  // the version-keyed hot cache, but the QMD caches are TTL-keyed, NOT
+  // corpus-version-keyed — without this, an out-of-band writer (capsule
+  // import/merge, review, spaces, governance restore, page revert, binary
+  // redirect) would leave a warm process serving pre-write recall/search results
+  // for the remainder of the QMD cache TTL. Route the bump through the same
+  // invalidation chokepoint the in-process mutation paths use.
+  invalidateDerivedAndGlobalForDir(memoryDir);
+}

package/src/namespaces/storage.ts

@@ -292,7 +292,26 @@ export class NamespaceStorageRouter {
       }
     }
 
-    const sm = new StorageManager(root, this.config.entitySchemas);
+    // Pass the hot-memories cache gate explicitly (issue #1902, Codex P2): a
+    // per-namespace child root is never registered in the per-dir default map,
+    // so without this it would fall back to the process-wide default and ignore
+    // THIS daemon's hotMemoriesCacheEnabled config. Threading it from config
+    // keeps every namespace storage aligned with its owning orchestrator.
+    const sm = new StorageManager(
+      root,
+      this.config.entitySchemas,
+      this.config.hotMemoriesCacheEnabled,
+    );
+    // Register this child root's gate AND TTL in the per-dir maps (issue #1902,
+    // Codex P2). The constructor override above fixes the child's own gate, but
+    // its TTL is resolved via the per-dir map (hotCacheTtlMs); an unregistered
+    // child root would fall back to the last process-wide TTL and could inherit
+    // another daemon's value. Registering keyed by root keeps both per-dir.
+    StorageManager.setHotMemoriesCacheDefault(
+      root,
+      this.config.hotMemoriesCacheEnabled,
+      this.config.hotMemoriesCacheTtlMs,
+    );
     // Propagate the inline-attribution template so that router-created storages
     // (used by extraction and shared-promotion paths) strip citations consistently,
     // matching the behaviour of the primary this.storage instance in the orchestrator.

package/src/operator-toolkit.ts

@@ -2297,7 +2297,13 @@ export async function runOperatorInventory(options: OperatorInventoryOptions): P
   let rejected = 0;
 
   for (const entry of uniqueRootEntries.values()) {
-    const storage = new StorageManager(entry.rootDir);
+    // Disable the hot-memories cache for these transient, one-shot inventory
+    // reads (issue #1902, Codex Medium). Each namespace root is read exactly once
+    // here; caching gives no benefit and would warm+RETAIN the full corpus under
+    // the process-wide gate/TTL (this path bypasses NamespaceStorageRouter, so
+    // the root is never registered in the per-dir maps). Disabling sidesteps both
+    // the cross-namespace gate/TTL inheritance and the retained-memory footprint.
+    const storage = new StorageManager(entry.rootDir, undefined, false);
     const memories = await storage.readAllMemories();
     const entities = await storage.readAllEntityFiles();
     namespaces.push({

package/src/orchestration/recall-internal.ts

@@ -2032,9 +2032,10 @@ export class RecallInternalCoordinator {
     // Verified recall and semantic rules both need readAllMemories().
     // Instead of a shared preload (which has namespace/dir mismatch issues),
     // each subsystem calls readAllMemories() on its correct storage instance.
-    // The process-level memory cache (keyed by baseDir + memoryStatusVersion)
-    // ensures only one actual disk scan happens — subsequent calls return
-    // from cache in <1ms.
+    // The version-keyed hot-memories cache (keyed by baseDir + the corpus
+    // version sentinel, issue #1902) serves repeat reads within a version epoch
+    // from memory, so these subsystems share one disk scan; a memory write
+    // between recalls bumps the corpus version and forces exactly one rescan.
 
     const verifiedRecallPromise = (async (): Promise<string | null> => {
       const t0 = Date.now();
@@ -2081,6 +2082,7 @@ export class RecallInternalCoordinator {
               query: retrievalQuery,
               maxResults,
               boxRecallDays: this.deps.config.boxRecallDays,
+              hotMemoriesCacheEnabled: this.deps.config.hotMemoriesCacheEnabled,
             }).catch((err) => {
               log.debug(`verified recall directory scan failed: ${err}`);
               return [] as VerifiedEpisodeResult[];
@@ -2169,6 +2171,7 @@ export class RecallInternalCoordinator {
               memoryDir,
               query: retrievalQuery,
               maxResults,
+              hotMemoriesCacheEnabled: this.deps.config.hotMemoriesCacheEnabled,
             }).catch((err) => {
               log.debug(`verified rules directory scan failed: ${err}`);
               return [] as VerifiedSemanticRuleResult[];

package/src/orchestrator.ts

@@ -1334,6 +1334,17 @@ export class Orchestrator {
 
   constructor(config: PluginConfig) {
     this.config = config;
+    // Thread the hot-memories cache escape hatch (issue #1902) to the storage
+    // layer BEFORE any StorageManager is constructed below, so every instance
+    // — including the ephemeral ones recall sub-stages build over the same dir
+    // — honors the operator's setting. Destructured (not `config.<flag>`) so
+    // this single access-layer read stays off the scattered-flag ratchet.
+    const { hotMemoriesCacheEnabled } = config;
+    StorageManager.setHotMemoriesCacheDefault(
+      config.memoryDir,
+      hotMemoriesCacheEnabled,
+      config.hotMemoriesCacheTtlMs,
+    );
     this.profiler = new ProfilingCollector({
       enabled: resolvePipelineProcessingCapabilities(this.config).profiling,
       storageDir: config.profilingStorageDir || path.join(config.memoryDir, "profiling"),
@@ -1490,7 +1501,20 @@ export class Orchestrator {
       tierMigrationStatus: this.tierMigrationStatus,
       getUtilityRuntimeValues: () => this.utilityRuntimeValues,
       getCompounding: () => this.compounding,
-      createColdStorage: (parentDir) => new StorageManager(parentDir),
+      createColdStorage: (parentDir) => {
+        // Register parentDir's gate AND TTL in the per-dir maps (issue #1902,
+        // Codex Medium) before constructing, mirroring the namespace-child fix.
+        // The constructor override only sets this manager's gate; its TTL is
+        // resolved via the per-dir map, so an unregistered cold root would fall
+        // back to the (first-writer) process-wide TTL and could inherit another
+        // orchestrator's value.
+        StorageManager.setHotMemoriesCacheDefault(
+          parentDir,
+          config.hotMemoriesCacheEnabled,
+          config.hotMemoriesCacheTtlMs,
+        );
+        return new StorageManager(parentDir, config.entitySchemas, config.hotMemoriesCacheEnabled);
+      },
     });
     this.compressionGuidelineCoordinator = new CompressionGuidelineCoordinator({
       config,

package/src/page-versioning.ts

@@ -25,7 +25,8 @@ import {
   writeFile,
   unlink,
 } from "node:fs/promises";
-import { ALL_CATEGORY_DIRS } from "./utils/category-dir.js";
+import { ALL_CATEGORY_DIRS, RECALL_FALLBACK_DIRS } from "./utils/category-dir.js";
+import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 
 // ---------------------------------------------------------------------------
 // Public interfaces
@@ -332,6 +333,18 @@ export async function revertToVersion(
 
   // Write the reverted content to the actual page
   await writeFile(pagePath, targetContent, "utf-8");
+  // A revert overwrites a memory file out-of-band (not via a StorageManager
+  // mutation), so bump the corpus sentinel when the reverted page lives under a
+  // recall category dir — forcing a warm hot-memories cache to rescan on its
+  // next read (issue #1902, Codex P1). Non-recall pages (entities/artifacts/
+  // profiles) are not in the corpus scan, so they need no bump.
+  // The hot-memories corpus covers the RECALL corpus, which excludes the
+  // non-memory queue dirs (questions/). Use RECALL_FALLBACK_DIRS — a revert of a
+  // questions/ page must NOT bump the recall corpus sentinel and force a rescan.
+  const revertedTop = relPath(pagePath, resolvedMemoryDir).split(path.sep)[0];
+  if ((RECALL_FALLBACK_DIRS as readonly string[]).includes(revertedTop)) {
+    bumpMemoryCorpusVersionForDir(resolvedMemoryDir);
+  }
   log.debug(`page-versioning: reverted ${pagePath} to version ${versionId}`);
 
   return version;

package/src/provenance-frontmatter.test.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 import { mkdtemp, mkdir, rm, writeFile, readFile } from "node:fs/promises";
 
 import { StorageManager } from "./storage.js";
+import { clearMemoryCache } from "./memory-cache.js";
 import type { ProvenanceSource } from "./types.js";
 
 /**
@@ -64,6 +65,11 @@ async function writeFactFile(
   const factsDir = path.join((storage as unknown as { baseDir: string }).baseDir, "facts", today);
   await mkdir(factsDir, { recursive: true });
   await writeFile(path.join(factsDir, `${id}.md`), `${lines.join("\n")}\n\n${body}\n`, "utf-8");
+  // This is an out-of-band write (bypasses StorageManager.writeMemory), so it
+  // must invalidate the version-keyed hot-memories cache (issue #1902) — drop
+  // every cache layer for this dir via the exported chokepoint so the next
+  // readAllMemories() rescans disk and sees this file (matches the harness seam).
+  clearMemoryCache(storage.dir);
   return id;
 }
 

package/src/review/index.ts

@@ -8,6 +8,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { getCategoryDir, ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
+import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -259,14 +260,21 @@ export function performReview(
   action: ReviewAction,
   options: ReviewActionOptions = {},
 ): ReviewResult {
-  switch (action) {
-    case "approve":
-      return approveItem(memoryDir, itemId, options);
-    case "dismiss":
-      return dismissItem(memoryDir, itemId, options);
-    case "flag":
-      return flagItem(memoryDir, itemId, options);
-  }
+  const result =
+    action === "approve"
+      ? approveItem(memoryDir, itemId, options)
+      : action === "dismiss"
+        ? dismissItem(memoryDir, itemId, options)
+        : flagItem(memoryDir, itemId, options);
+  // Review approval/dismissal/flagging edits, moves, or removes memory files
+  // directly (out-of-band — it does not go through a StorageManager mutation
+  // method), so bump the corpus sentinel to force the version-keyed hot cache
+  // to rescan on its next read (issue #1902). Only bump when a file was
+  // actually modified/moved (updatedPath set) — no-op early returns (item not
+  // found, unparsable frontmatter) must not advance the sentinel or needlessly
+  // clear caches (Cursor Medium).
+  if (result.updatedPath !== undefined) bumpMemoryCorpusVersionForDir(memoryDir);
+  return result;
 }
 
 // ── Actions ──────────────────────────────────────────────────────────────────

package/src/semantic-rule-promotion.ts

@@ -498,7 +498,15 @@ function normalizeRuleWhitespace(value: string): string {
 }
 
 function stripTrailingClausePunctuation(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 canonicalizeRuleContent(value: string): string {

package/src/semantic-rule-verifier.ts

@@ -116,18 +116,31 @@ export async function searchVerifiedSemanticRules(options: {
   query: string;
   maxResults: number;
   minEffectiveConfidence?: number;
+  /** Hot-memories cache gate (issue #1902, Codex P2). Threaded from the caller
+   *  so a named-namespace root (never registered in the per-dir default map)
+   *  honors the owning daemon's config instead of the process-wide default. */
+  hotMemoriesCacheEnabled?: boolean;
 }): Promise<VerifiedSemanticRuleResult[]> {
   const queryTokens = new Set(normalizeRecallTokens(options.query, ["what", "which"]));
   if (queryTokens.size === 0 || options.maxResults <= 0) return [];
 
-  const storage = new StorageManager(options.memoryDir);
-  const version = storage.getMemoryStatusVersion();
-
-  // Use derived rule cache to avoid O(146K) iteration on every call.
-  let cachedRules = getCachedRuleMemories(storage.dir, version);
+  const storage = new StorageManager(options.memoryDir, undefined, options.hotMemoriesCacheEnabled);
+  // Key the derived rule cache on the CORPUS version, not memory-status (Codex
+  // P1, #1902): rule memories are derived from the full corpus, and plain
+  // creates/writeChunk bump only the corpus sentinel. Keying on memory-status
+  // would let a peer process serve a stale rule set that omits newly created
+  // rule memories.
+  const version = storage.getMemoryCorpusVersion();
+
+  // Use derived rule cache to avoid O(146K) iteration on every call — but honor
+  // the hotMemoriesCacheEnabled opt-out (Codex P2): when disabled, never read or
+  // retain the derived cache, always rebuild from a fresh scan.
+  const cacheEnabled = storage.isHotCacheEnabled();
+  const keyId = storage.hotCacheKeyId();
+  let cachedRules = cacheEnabled ? getCachedRuleMemories(storage.dir, version, keyId, storage.hotCacheTtlMs()) : null;
   if (!cachedRules) {
     const allMems = await storage.readAllMemories();
-    cachedRules = setCachedRuleMemories(storage.dir, allMems, version);
+    cachedRules = setCachedRuleMemories(storage.dir, allMems, version, cacheEnabled, keyId);
   }
   const { all: ruleMemories, byId: memoryById } = cachedRules;
   const minEffectiveConfidence = options.minEffectiveConfidence ?? DEFAULT_MIN_EFFECTIVE_CONFIDENCE;

package/src/spaces/index.ts

@@ -13,6 +13,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { readEnvVar, resolveHomeDir } from "../runtime/env.js";
+import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -935,6 +936,15 @@ function copyMemories(
     }
     fs.writeFileSync(targetPath, content);
     merged++;
+    // Bump the target's corpus sentinel per write (out-of-band — not through a
+    // StorageManager mutation), on the CANONICAL root (targetRoot), matching
+    // where files were written and where a StorageManager resolves its
+    // version/cache keys. Per-write (not once after the loop) so a warm
+    // hot-memories cache for the target rescans MID-batch and never serves the
+    // pre-copy corpus while copies are still landing (#1902; a symlinked target
+    // would otherwise diverge, and a once-after bump leaves in-batch reads
+    // stale).
+    bumpMemoryCorpusVersionForDir(targetRoot);
   }
 
   return { merged, conflicts, skipped };

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

@@ -60,6 +60,8 @@ export interface MemoryReadStoreDeps {
   readonly proceduresDir: string;
   readonly questionsDir: string;
   readColdWriteVersion(): number;
+  /** Secure-store key identity for keying decrypted-corpus caches (#1902). */
+  hotCacheKeyId(): string;
   readMemoryByPath(filePath: string): Promise<MemoryFile | null>;
   readParsedMemoriesFromPaths(
     filePaths: string[],
@@ -365,10 +367,15 @@ export class MemoryReadStore {
     // stale data for up to 30s when another process wrote a new cold memory.
     const currentColdVersion = this.deps.readColdWriteVersion();
 
-    // Return cached result if still valid by both TTL and sentinel version.
+    // Return cached result if still valid by TTL, sentinel version, AND the
+    // secure-store key identity (issue #1902). readParsedMemoriesFromPaths
+    // 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);
     if (
       cached &&
+      cached.keyId === keyId &&
       Date.now() - cached.loadedAt < this.deps.storageManagerClass.COLD_SCAN_CACHE_TTL_MS &&
       cached.coldVersion === currentColdVersion
     ) {
@@ -407,7 +414,7 @@ export class MemoryReadStore {
 
     // 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 });
+    this.deps.storageManagerClass.coldMemoriesCache.set(coldRoot, { memories, loadedAt: Date.now(), coldVersion: currentColdVersion, keyId });
     return memories;
   }
 

package/src/storage-contract/cache-coherence.test.ts

@@ -10,6 +10,9 @@
 
 import assert from "node:assert/strict";
 import test from "node:test";
+import { appendFile, mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 
 import { StorageManager } from "../storage.js";
 import { resetStaticCaches } from "./harness.js";
@@ -98,3 +101,242 @@ test("cache-coherence: readAllMemories reflects writes across instances after in
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+type ScanSpy = { _readAllMemoriesFromDisk: () => Promise<unknown> };
+
+function installScanSpy(sm: StorageManager): { scans: () => number } {
+  const spy = sm as unknown as ScanSpy;
+  const orig = spy._readAllMemoriesFromDisk.bind(sm);
+  let count = 0;
+  spy._readAllMemoriesFromDisk = async () => {
+    count += 1;
+    return orig();
+  };
+  return { scans: () => count };
+}
+
+test("hot cache (#1902): a warm readAllMemories() serves without re-scanning disk", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-warm-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "A");
+    await sm.readAllMemories(); // warming scan populates the hot cache
+    const spy = installScanSpy(sm);
+    const warm = await sm.readAllMemories();
+    assert.equal(spy.scans(), 0, "a warm read must not touch disk");
+    assert.ok(warm.some((m) => m.content === "A"));
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): a single-file write patches the cache in place — next read stays warm", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-patch-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "A");
+    await sm.readAllMemories(); // warm
+    const spy = installScanSpy(sm);
+    await sm.writeMemory("fact", "B"); // patch-on-write keeps the entry warm
+    const after = await sm.readAllMemories();
+    assert.equal(spy.scans(), 0, "patch-on-write must keep the cache warm (no rescan)");
+    assert.ok(after.some((m) => m.content === "B"), "the newly written fact is present");
+    assert.ok(after.some((m) => m.content === "A"), "the prior fact survives the patch");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): a peer corpus-version bump forces exactly one rescan (cross-process coherence)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-peer-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "A");
+    await sm.readAllMemories(); // warm
+    const spy = installScanSpy(sm);
+    // Simulate a peer process advancing the on-disk corpus sentinel (its byte
+    // size IS the version). This instance's warm entry is now stale-versioned.
+    await appendFile(path.join(dir, "state", ".memory-corpus-version.log"), "x");
+    const afterPeer = await sm.readAllMemories();
+    assert.equal(spy.scans(), 1, "a peer sentinel bump must force exactly one rescan");
+    assert.ok(afterPeer.some((m) => m.content === "A"));
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): a delete rescans and drops the removed memory", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-del-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    const { id } = await sm.writeMemory("fact", "A");
+    await sm.writeMemory("fact", "B");
+    await sm.readAllMemories(); // warm
+    await sm.invalidateMemory(id); // delete drops the hot layer wholesale
+    const after = await sm.readAllMemories();
+    assert.ok(after.some((m) => m.content === "B"), "surviving memory remains");
+    assert.ok(!after.some((m) => m.content === "A"), "the deleted memory is gone");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902/#1904 compat): a plain fact create does NOT bump memory-status (entity cache stays warm)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-status-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "seed"); // establish the state dir + baseline
+    const before = sm.getMemoryStatusVersion();
+    await sm.writeMemory("fact", "another create");
+    assert.equal(
+      sm.getMemoryStatusVersion(),
+      before,
+      "a plain fact create must not bump memory-status (the entity cache keys on it)",
+    );
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): hotMemoriesCacheEnabled=false forces every read to rescan", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-off-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir, undefined, false); // gate off
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "A");
+    const spy = installScanSpy(sm);
+    await sm.readAllMemories();
+    await sm.readAllMemories();
+    assert.equal(spy.scans(), 2, "with the cache disabled, each sequential read scans disk");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): the gate default is isolated per memory dir (Codex P2)", async () => {
+  const dirOff = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-perdir-off-"));
+  const dirOn = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-perdir-on-"));
+  try {
+    resetStaticCaches();
+    // Register divergent per-dir settings; a later registration must NOT flip
+    // an earlier dir's behavior (the "last orchestrator wins" bug).
+    StorageManager.setHotMemoriesCacheDefault(dirOff, false);
+    StorageManager.setHotMemoriesCacheDefault(dirOn, true);
+    // Constructed WITHOUT a per-instance override, so each resolves its own
+    // dir's registered default.
+    const smOff = new StorageManager(dirOff);
+    const smOn = new StorageManager(dirOn);
+    await smOff.ensureDirectories();
+    await smOff.writeMemory("fact", "A");
+    await smOn.ensureDirectories();
+    await smOn.writeMemory("fact", "B");
+    const spyOff = installScanSpy(smOff);
+    const spyOn = installScanSpy(smOn);
+    await smOff.readAllMemories();
+    await smOff.readAllMemories();
+    await smOn.readAllMemories();
+    await smOn.readAllMemories();
+    assert.equal(spyOff.scans(), 2, "dir registered false rescans on every read");
+    assert.equal(spyOn.scans(), 1, "dir registered true serves the second read from cache");
+  } finally {
+    resetStaticCaches();
+    await rm(dirOff, { recursive: true, force: true });
+    await rm(dirOn, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): flushAccessTracking patches locally + bumps for cross-process coherence", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-access-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    await sm.ensureDirectories();
+    const { id } = await sm.writeMemory("fact", "trackable");
+    // Warm the cache.
+    const warm = await sm.readAllMemories();
+    assert.equal(warm.length, 1);
+    const versionBefore = sm.getMemoryCorpusVersion();
+    const spy = installScanSpy(sm);
+    await sm.flushAccessTracking([
+      { memoryId: id, newCount: 7, lastAccessed: "2026-07-16T00:00:00.000Z" },
+    ]);
+    const after = await sm.readAllMemories();
+    // Local process: patched in place + re-keyed, so no rescan and fresh counts.
+    assert.equal(spy.scans(), 0, "access-tracking flush must not rescan the corpus locally");
+    const m = after.find((x) => x.frontmatter.id === id);
+    assert.equal(m?.frontmatter.accessCount, 7, "hot cache reflects the flushed access count");
+    assert.equal(m?.frontmatter.lastAccessed, "2026-07-16T00:00:00.000Z");
+    // Cross-process: the shared sentinel advanced so peer processes rescan and
+    // never overwrite this process's increment (Codex P2).
+    assert.ok(
+      sm.getMemoryCorpusVersion() > versionBefore,
+      "access-tracking flush advances the corpus sentinel for peer coherence",
+    );
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): ensureDirectories activates a version-0 corpus so reads cache (Cursor Medium)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-zero-"));
+  try {
+    resetStaticCaches();
+    // Simulate an existing corpus with NO sentinel yet: write a fact file
+    // directly to disk (bypassing StorageManager, so nothing bumps the sentinel).
+    await mkdir(path.join(dir, "facts"), { recursive: true });
+    await writeFile(path.join(dir, "facts", "a.md"), "---\nid: fact-a\n---\nA");
+    const sm = new StorageManager(dir);
+    assert.equal(sm.getMemoryCorpusVersion(), 0, "precondition: sentinel starts at 0");
+    // The daemon calls ensureDirectories() at startup (before serving reads); it
+    // seeds a nonzero sentinel so the hot path engages on a read-heavy workload.
+    await sm.ensureDirectories();
+    assert.ok(sm.getMemoryCorpusVersion() > 0, "ensureDirectories activates the sentinel");
+    const spy = installScanSpy(sm);
+    const first = await sm.readAllMemories();
+    assert.equal(first.length, 1);
+    await sm.readAllMemories();
+    assert.equal(spy.scans(), 1, "second read is served from cache — activation worked");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("hot cache (#1902): an empty corpus is served from cache, not rescanned (kilo null-check)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-hot-empty-"));
+  try {
+    resetStaticCaches();
+    const sm = new StorageManager(dir);
+    // ensureDirectories activates the sentinel (version > 0); the corpus is empty.
+    await sm.ensureDirectories();
+    const first = await sm.readAllMemories();
+    assert.equal(first.length, 0, "corpus is empty");
+    const spy = installScanSpy(sm);
+    await sm.readAllMemories();
+    await sm.readAllMemories();
+    // getCachedMemories returns [] (falsy) for an empty corpus; the read guard
+    // must null-check, not truthiness-check, or every read rescans.
+    assert.equal(spy.scans(), 0, "empty corpus is served from cache on repeat reads");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/storage-contract/namespace-routing.test.ts

@@ -18,9 +18,10 @@ import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import test from "node:test";
 
-import { makeStorage, makeNamespaceRouter } from "./harness.js";
+import { makeStorage, makeNamespaceRouter, resetStaticCaches } from "./harness.js";
 import { resolveNamespaceStorageRoot } from "../namespaces/storage.js";
 import { namespaceIdentityToken } from "../namespaces/identity.js";
+import { getCachedMemories } from "../memory-cache.js";
 
 test("namespace-routing: default namespace resolves to the legacy memoryDir root", async () => {
   const { router, memoryDir, config, cleanup } = await makeNamespaceRouter();
@@ -133,3 +134,27 @@ test("namespace-routing: router caches StorageManager per namespace (same instan
     await cleanup();
   }
 });
+
+test("namespace-routing: hotMemoriesCacheEnabled=false propagates to namespace child storages (#1902 Codex P2)", async () => {
+  const { router, config, cleanup } = await makeNamespaceRouter({ hotMemoriesCacheEnabled: false });
+  try {
+    resetStaticCaches();
+    const sm = await router.storageFor("team-alpha");
+    await sm.ensureDirectories();
+    await sm.writeMemory("fact", "A");
+    await sm.readAllMemories();
+    await sm.readAllMemories();
+    const root = await resolveNamespaceStorageRoot(config, "team-alpha");
+    // Gate propagated to the child: with caching disabled the child storage
+    // never populates the module-level hot cache, so getCachedMemories stays
+    // null even after reads. Before the fix the child fell back to the
+    // process-wide default (true) and would have cached the corpus.
+    assert.equal(
+      getCachedMemories(root, sm.getMemoryCorpusVersion()),
+      null,
+      "namespace child honors the disabled gate and never caches the corpus",
+    );
+  } finally {
+    await cleanup();
+  }
+});