@remnic/core 9.54.7 → 9.54.8

package/dist/transfer/capsule-export.js

@@ -1,10 +1,10 @@
 import {
   exportCapsule,
   isValidCapsuleSince
-} from "../chunk-IPLYGWQF.js";
-import "../chunk-J4EB7DNW.js";
+} from "../chunk-KQAFEZQX.js";
 import "../chunk-WEHSQBFR.js";
 import "../chunk-X7Y7WX73.js";
+import "../chunk-J4EB7DNW.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";

package/dist/verified-recall.js

@@ -1,14 +1,14 @@
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-5FD7JMTX.js";
+} from "./chunk-ZUJW327U.js";
 import "./chunk-B7RWBZXW.js";
-import "./chunk-M4YHAODQ.js";
-import "./chunk-MLPTFODV.js";
+import "./chunk-XXRRHING.js";
 import "./chunk-UHVXE24Y.js";
+import "./chunk-MLPTFODV.js";
 import "./chunk-SXIMQLGV.js";
-import "./chunk-TO7ZTWJW.js";
-import "./chunk-QZLDRQ4I.js";
+import "./chunk-KMWYZTIE.js";
+import "./chunk-47J4EDGR.js";
 import "./chunk-XL3TATMJ.js";
 import "./chunk-VANZKHTN.js";
 import "./chunk-CYEPCZN5.js";
@@ -17,10 +17,10 @@ import "./chunk-VYISFWVX.js";
 import "./chunk-W7IGLX4G.js";
 import "./chunk-GWFSVJ4P.js";
 import "./chunk-GUMZC2BO.js";
-import "./chunk-LEPOP46W.js";
+import "./chunk-227UFSEQ.js";
+import "./chunk-ET356KSB.js";
 import "./chunk-72A4L5JJ.js";
 import "./chunk-A7Q43EUZ.js";
-import "./chunk-ET356KSB.js";
 import "./chunk-S2V7RUCL.js";
 import "./chunk-76JJSXK7.js";
 import "./chunk-SCU65EZI.js";
@@ -33,8 +33,8 @@ import "./chunk-AAD2ZS6P.js";
 import "./chunk-K2UGPTYY.js";
 import "./chunk-NSVDUN76.js";
 import "./chunk-BT7NVCML.js";
-import "./chunk-3ONXXHQO.js";
 import "./chunk-YXZG5TVN.js";
+import "./chunk-3ONXXHQO.js";
 import "./chunk-5GINB5LC.js";
 import "./chunk-G7D6GZ5J.js";
 import "./chunk-ZMSZVISA.js";
@@ -43,18 +43,18 @@ import "./chunk-RBOJCG4T.js";
 import "./chunk-GSTIBXBW.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
+import "./chunk-RVO6TCTU.js";
+import "./chunk-URS5GSM7.js";
+import "./chunk-IUM3VSHI.js";
+import "./chunk-ZLQ37WJX.js";
+import "./chunk-XMMESCPD.js";
+import "./chunk-42JKGUFJ.js";
 import "./chunk-UW5NPZJ2.js";
 import "./chunk-QIEUU4UK.js";
 import "./chunk-L2EXJQJP.js";
 import "./chunk-45GF7Y3V.js";
 import "./chunk-RGMVMVMF.js";
 import "./chunk-N7RWREIQ.js";
-import "./chunk-QCECHYZL.js";
-import "./chunk-URS5GSM7.js";
-import "./chunk-ZLQ37WJX.js";
-import "./chunk-IUM3VSHI.js";
-import "./chunk-XMMESCPD.js";
-import "./chunk-42JKGUFJ.js";
 import "./chunk-VOELBUS4.js";
 import "./chunk-ZIKENA2C.js";
 import "./chunk-PQVCH2AE.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.54.7",
+  "version": "9.54.8",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3136,7 +3136,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.54.7"
+    "@remnic/coding-graph": "^9.54.8"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/briefing-window.ts

@@ -0,0 +1,27 @@
+import { log } from "./logger.js";
+import type { MemoryFile } from "./types.js";
+type BriefingMemoryReader = {
+  readMemoriesWindow?: (options: { updatedAfter?: Date }) => Promise<{ memories: MemoryFile[] }>;
+  readAllMemories: () => Promise<MemoryFile[]>;
+};
+import type { ParsedBriefingWindow } from "./briefing.js";
+
+/** Read only the memories needed by a briefing, with compatibility fallback. */
+export async function safeReadMemories(
+  storage: BriefingMemoryReader,
+  window: ParsedBriefingWindow
+): Promise<MemoryFile[]> {
+  try {
+    // A briefing only needs memories inside its lookback window. Avoid parsing
+    // the full corpus on cache misses; keep the full-read fallback for custom
+    // StorageManager-compatible callers that predate readMemoriesWindow().
+    if (typeof storage.readMemoriesWindow === "function") {
+      const result = await storage.readMemoriesWindow({ updatedAfter: window.from });
+      return result.memories;
+    }
+    return await storage.readAllMemories();
+  } catch (err) {
+    log.warn(`briefing: read memories failed: ${err}`);
+    return [];
+  }
+}

package/src/briefing.test.ts

@@ -913,6 +913,35 @@ function makeEmptyStorage(): StorageManager {
     readAllEntityFiles: async () => [],
   } as unknown as StorageManager;
 }
+test("buildBriefing reads only memories updated inside the briefing window", async () => {
+  let readWindowOptions: { updatedAfter?: Date } | undefined;
+  const atWindowStart = makeMemory("2026-04-10T00:00:00.000Z");
+  const atWindowEnd = makeMemory("2026-04-11T00:00:00.000Z");
+  const storage = {
+    readAllMemories: async () => {
+      throw new Error("full corpus read must not be used by briefing");
+    },
+    readMemoriesWindow: async (options: { updatedAfter?: Date }) => {
+      readWindowOptions = options;
+      return {
+        memories: [atWindowStart, atWindowEnd],
+        filePaths: [atWindowStart.path, atWindowEnd.path],
+      };
+    },
+    readAllEntityFiles: async () => [],
+  } as unknown as StorageManager;
+
+  const result = await buildBriefing({
+    storage,
+    window: makeWindow("2026-04-10T00:00:00.000Z", "2026-04-11T00:00:00.000Z"),
+    allowLlm: false,
+    now: new Date("2026-04-11T10:00:00.000Z"),
+  });
+
+  assert.equal(readWindowOptions?.updatedAfter?.toISOString(), "2026-04-10T00:00:00.000Z");
+  assert.equal(result.sections.activeThreads.length, 1);
+});
+
 
 test("buildBriefing excludes support passport records from generated context", async () => {
   const generatedPrompts: unknown[] = [];

package/src/briefing.ts

@@ -23,6 +23,7 @@ import { extractJsonCandidates } from "./json-extract.js";
 import { drainPassiveCorrectionNotifications } from "./correction/passive-correction-notifications.js";
 import { excludeSupportPassportPrivateMemories } from "./support-passport/card-projection.js";
 import { normalizeEntityName, StorageManager } from "./storage.js";
+import { safeReadMemories } from "./briefing-window.js";
 import { readEnvVar, resolveHomeDir } from "./runtime/env.js";
 import type {
   BriefingActiveThread,
@@ -834,7 +835,7 @@ export async function buildBriefing(options: BuildBriefingOptions): Promise<Brie
   const focus = options.focus ?? null;
 
   const [allMemories, allEntities] = await Promise.all([
-    safeReadMemories(options.storage),
+    safeReadMemories(options.storage, window).then(excludeSupportPassportPrivateMemories),
     safeReadEntities(options.storage),
   ]);
 
@@ -977,14 +978,6 @@ function defaultWindow(now: Date): ParsedBriefingWindow {
   return { from: new Date(now.getTime() - DAY_MS), to: now, label: "yesterday" };
 }
 
-async function safeReadMemories(storage: StorageManager): Promise<MemoryFile[]> {
-  try {
-    return excludeSupportPassportPrivateMemories(await storage.readAllMemories());
-  } catch (err) { log.warn(`briefing: readAllMemories failed: ${err}`);
-    return [];
-  }
-}
-
 async function safeReadEntities(storage: StorageManager): Promise<EntityFile[]> {
   try {
     return await storage.readAllEntityFiles();

package/src/maintenance/memory-governance.ts

@@ -829,6 +829,7 @@ export async function runMemoryGovernance(
         maxMemories: options.maxMemories,
         batchSize: options.batchSize,
         updatedAfter,
+        includeMalformedPaths: true,
       })
     : undefined;
   const memories = excludeSupportPassportPrivateMemories(

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

@@ -869,3 +869,4 @@ export class MemoryReadStore {
     }
   }
 }
+export { readWindowedMemories, type WindowedMemoryReadOptions, type WindowedMemoryReadResult } from "./windowed-memory-read.js";

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

@@ -0,0 +1,109 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { getCachedMemories } from "../memory-cache.js";
+import { readRawMemoryDocument } from "./memory-frontmatter-metadata.js";
+import type { MemoryFile } from "../types.js";
+import type { MemoryReadStore } from "./memory-read-store.js";
+
+export interface WindowedMemoryReadOptions {
+  maxMemories?: number;
+  batchSize?: number;
+  updatedAfter?: Date;
+  /** Require candidate paths so malformed files can be reported by governance. */
+  includeMalformedPaths?: boolean;
+}
+
+export interface WindowedMemoryReadResult {
+  memories: MemoryFile[];
+  filePaths: string[];
+}
+
+type WindowedMemoryReadStore = Pick<MemoryReadStore, "readMemoriesWindow">;
+
+type HotMemoryCache = {
+  enabled: boolean;
+  baseDir: string;
+  corpusVersion: number;
+  cacheKeyId: string;
+  ttlMs?: number;
+};
+
+/**
+ * Serve the briefing-only updatedAfter shape from the warm corpus cache, then
+ * delegate all other window reads to MemoryReadStore.
+ */
+export async function readWindowedMemories(
+  store: WindowedMemoryReadStore,
+  options: WindowedMemoryReadOptions,
+  hotCache: HotMemoryCache,
+  rememberMemorySnapshots: (memories: MemoryFile[]) => MemoryFile[]
+): Promise<WindowedMemoryReadResult> {
+  if (
+    options.updatedAfter !== undefined &&
+    (!(options.updatedAfter instanceof Date) || !Number.isFinite(options.updatedAfter.getTime()))
+  ) {
+    throw new TypeError("updatedAfter must be a valid Date");
+  }
+  if (
+    hotCache.enabled &&
+    options.updatedAfter !== undefined &&
+    options.maxMemories === undefined &&
+    options.batchSize === undefined &&
+    options.includeMalformedPaths !== true
+  ) {
+    const cached = getCachedMemories(hotCache.baseDir, hotCache.corpusVersion, hotCache.cacheKeyId, hotCache.ttlMs);
+    if (cached !== null) {
+      const updatedAfterMs = options.updatedAfter.getTime();
+      const selected = (
+        await Promise.all(
+          cached.map(async (memory) => {
+            const timestampMs = await readWindowTimestamp(memory);
+            return timestampMs === null || timestampMs >= updatedAfterMs ? memory : null;
+          })
+        )
+      ).filter((memory): memory is MemoryFile => memory !== null);
+      const memories = orderWindowMemories(selected, hotCache.baseDir);
+      return { memories: rememberMemorySnapshots(memories), filePaths: memories.map((memory) => memory.path) };
+    }
+  }
+  const result = await store.readMemoriesWindow(options);
+  return {
+    ...result,
+    memories: rememberMemorySnapshots(result.memories),
+  };
+}
+
+async function readWindowTimestamp(memory: MemoryFile): Promise<number | null> {
+  const rawDocument = readRawMemoryDocument(memory);
+  const frontmatterBlock = rawDocument?.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+  const rawTimestamp =
+    frontmatterBlock?.match(/^[ \t]*updated:[ \t]*"?([^"\r\n]*)"?/m)?.[1] ||
+    frontmatterBlock?.match(/^[ \t]*created:[ \t]*"?([^"\r\n]*)"?/m)?.[1] ||
+    memory.frontmatter.updated ||
+    memory.frontmatter.created;
+  const timestampMs = typeof rawTimestamp === "string" ? Date.parse(rawTimestamp.trim()) : Number.NaN;
+  if (Number.isFinite(timestampMs)) return timestampMs;
+  try {
+    return (await stat(memory.path)).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function orderWindowMemories(memories: MemoryFile[], baseDir: string): MemoryFile[] {
+  const correctionsRoot = path.join(baseDir, "corrections");
+  const corrections = memories
+    .filter((memory) => memory.path === correctionsRoot || memory.path.startsWith(`${correctionsRoot}${path.sep}`))
+    .sort((left, right) => right.path.localeCompare(left.path));
+  const facts = memories
+    .filter((memory) => memory.path !== correctionsRoot && !memory.path.startsWith(`${correctionsRoot}${path.sep}`))
+    .sort((left, right) => right.path.localeCompare(left.path));
+  const ordered: MemoryFile[] = [];
+  for (let index = 0; index < Math.max(corrections.length, facts.length); index += 1) {
+    const correction = corrections[index];
+    if (correction) ordered.push(correction);
+    const fact = facts[index];
+    if (fact) ordered.push(fact);
+  }
+  return ordered;
+}

package/src/storage.ts

@@ -26,7 +26,7 @@ import { resolveSafeStoragePath } from "./storage-paths.js";
 import { log } from "./logger.js";
 import { createMemorySnapshot } from "./memory-snapshot.js";
 import { assertMemoryFrontmatterId, warnProjectionFallback } from "./storage-guards.js";
-import { MemoryReadStore } from "./storage/memory-read-store.js";
+import { MemoryReadStore, readWindowedMemories, type WindowedMemoryReadOptions, type WindowedMemoryReadResult } from "./storage/memory-read-store.js";
 import { hasSupersessionAudit } from "./storage/supersession-audit.js";
 import { runCommittedInvalidation } from "./storage/committed-invalidation.js";
 import { renderProfileWithLastUpdated } from "./storage/profile-header.js";
@@ -4735,14 +4735,14 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   private async readWindowUpdatedMs(filePath: string): Promise<number | null> {
     try {
       const raw = await readMaybeEncryptedFile(filePath, this._secureStoreKey, this.baseDir);
-      const match = raw.match(/^---\n([\s\S]*?)\n---\n?/);
+      const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
       if (!match) return null;
       const frontmatterBlock = match[1];
       const rawUpdated =
-        frontmatterBlock.match(/^updated:\s*"?([^"\n]*)"?/m)?.[1] ??
-        frontmatterBlock.match(/^created:\s*"?([^"\n]*)"?/m)?.[1] ??
+        frontmatterBlock.match(/^[ \t]*updated:[ \t]*"?([^"\r\n]*)"?/m)?.[1] ||
+        frontmatterBlock.match(/^[ \t]*created:[ \t]*"?([^"\r\n]*)"?/m)?.[1] ||
         null;
-      const updatedMs = rawUpdated ? Date.parse(rawUpdated) : Number.NaN;
+      const updatedMs = rawUpdated ? Date.parse(rawUpdated.trim()) : Number.NaN;
       return Number.isFinite(updatedMs) ? updatedMs : null;
     } catch {
       return null;
@@ -4827,14 +4827,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return { memories, filePaths };
   }
 
-  async readMemoriesWindow(
-    options: {
-      maxMemories?: number;
-      batchSize?: number;
-      updatedAfter?: Date;
-    } = {}
-  ): Promise<{ memories: MemoryFile[]; filePaths: string[] }> {
-    return this.memoryReadStore.readMemoriesWindow(options);
+  async readMemoriesWindow(options: WindowedMemoryReadOptions = {}): Promise<WindowedMemoryReadResult> {
+    return readWindowedMemories(this.memoryReadStore, options, { enabled: this.hotMemoriesCacheEnabled, baseDir: this.baseDir, corpusVersion: this.getMemoryCorpusVersion(), cacheKeyId: this.hotCacheKeyId(), ttlMs: this.hotCacheTtlMs() }, (memories) => this.rememberMemorySnapshots(memories));
   }
 
   private async _readAllMemoriesFromDisk(options?: CorpusReadOptions): Promise<MemoryFile[]> {

package/src/testing/subjects/windowed-memory-read.test.ts

@@ -0,0 +1,146 @@
+import assert from "node:assert/strict";
+import { readFile, rm, utimes, writeFile } from "node:fs/promises";
+
+import { type WindowedMemoryReadResult } from "../../storage/windowed-memory-read.js";
+import { StorageManager } from "../../storage.js";
+import { type LifecycleSubject, type MatrixRow, runLifecycleMatrix } from "../lifecycle-matrix.js";
+import { mkTempMemoryDir } from "../orchestrator-lite.js";
+
+type WindowResult = WindowedMemoryReadResult;
+interface WindowedMemoryState {
+  dir: string;
+  storage: StorageManager;
+  updatedAfter: Date;
+  expectedIds: Set<string>;
+  excludedIds: Set<string>;
+  cold?: WindowResult;
+  warm?: WindowResult;
+  afterWrite?: WindowResult;
+}
+
+const UPDATED_AFTER = new Date("2021-01-01T00:00:00.000Z");
+const INCLUDED = new Date("2021-01-02T00:00:00.000Z");
+const BOUNDARY = UPDATED_AFTER.toISOString();
+const OLD = new Date("2020-12-31T23:59:59.000Z").toISOString();
+
+async function writeFixture(
+  storage: StorageManager,
+  content: string,
+  editFrontmatter: (raw: string) => string,
+): Promise<{ id: string; filePath: string }> {
+  const written = await storage.writeMemory("fact", content);
+  const raw = await readFile(written.memory.path, "utf8");
+  await writeFile(written.memory.path, editFrontmatter(raw), "utf8");
+  return { id: written.id, filePath: written.memory.path };
+}
+
+async function readColdThenWarm(state: WindowedMemoryState): Promise<void> {
+  // The first window read must miss the process cache and exercise the real
+  // path census/filter/parser. Populate the hot corpus cache explicitly, then
+  // repeat the identical request through readWindowedMemories' warm branch.
+  state.cold = await state.storage.readMemoriesWindow({ updatedAfter: state.updatedAfter });
+  await state.storage.readAllMemories();
+  state.warm = await state.storage.readMemoriesWindow({ updatedAfter: state.updatedAfter });
+}
+
+const subject: LifecycleSubject<WindowedMemoryState> = {
+  async setup(row: MatrixRow): Promise<WindowedMemoryState> {
+    const dir = await mkTempMemoryDir(`windowed-read-${row.id}`);
+    try {
+      const storage = new StorageManager(dir, undefined, true);
+      await storage.ensureDirectories();
+      const expectedIds = new Set<string>();
+      const excludedIds = new Set<string>();
+
+      const boundary = await writeFixture(storage, "boundary timestamp", (raw) =>
+        raw.replace(/^updated:.*$/m, `updated: ${BOUNDARY}`),
+      );
+      expectedIds.add(boundary.id);
+
+      const old = await writeFixture(storage, "outside lower boundary", (raw) =>
+        raw.replace(/^updated:.*$/m, `updated: ${OLD}`),
+      );
+      excludedIds.add(old.id);
+
+      const blankUpdated = await writeFixture(storage, "blank updated falls back to created", (raw) =>
+        raw
+          .replace(/^created:.*$/m, `created: ${INCLUDED.toISOString()}`)
+          .replace(/^updated:.*$/m, "updated:"),
+      );
+      expectedIds.add(blankUpdated.id);
+
+      const indented = await writeFixture(storage, "indented keys parse on both paths", (raw) =>
+        raw
+          .replace(/^created:/m, "  created:")
+          .replace(/^updated:/m, "  updated:"),
+      );
+      expectedIds.add(indented.id);
+
+      const mtimeAbsent = await writeFixture(storage, "mtime fallback with absent timestamps", (raw) =>
+        raw.replace(/^created:.*\n/m, "").replace(/^updated:.*\n/m, ""),
+      );
+      await utimes(mtimeAbsent.filePath, INCLUDED, INCLUDED);
+      expectedIds.add(mtimeAbsent.id);
+
+      const mtimeInvalid = await writeFixture(storage, "mtime fallback with invalid timestamps", (raw) =>
+        raw
+          .replace(/^created:.*$/m, "created: not-a-timestamp")
+          .replace(/^updated:.*$/m, "updated: not-a-timestamp"),
+      );
+      await utimes(mtimeInvalid.filePath, INCLUDED, INCLUDED);
+      expectedIds.add(mtimeInvalid.id);
+
+      return { dir, storage, updatedAfter: UPDATED_AFTER, expectedIds, excludedIds };
+    } catch (error) {
+      await rm(dir, { recursive: true, force: true });
+      throw error;
+    }
+  },
+
+  async exercise(state: WindowedMemoryState, row: MatrixRow): Promise<void> {
+    if (row.dimensions.restart) {
+      state.storage = new StorageManager(state.dir, undefined, true);
+      await state.storage.ensureDirectories();
+    }
+    await readColdThenWarm(state);
+
+    if (row.id === "session-end") {
+      await state.storage.writeMemory("fact", "write after the first window read");
+      state.afterWrite = await state.storage.readMemoriesWindow({ updatedAfter: state.updatedAfter });
+    }
+  },
+
+  async invariants(state: WindowedMemoryState, row: MatrixRow): Promise<void> {
+    assert.ok(state.cold, `${row.id}: cold window result must exist`);
+    assert.ok(state.warm, `${row.id}: warm window result must exist`);
+    assert.deepEqual(
+      state.warm!.filePaths,
+      state.cold!.filePaths,
+      `${row.id}: warm and cold path selection/order must match`,
+    );
+    assert.deepEqual(
+      state.warm!.memories.map((memory) => memory.path),
+      state.cold!.memories.map((memory) => memory.path),
+      `${row.id}: warm and cold memory selection/order must match`,
+    );
+
+    const selectedIds = new Set(state.cold!.memories.map((memory) => memory.frontmatter.id));
+    for (const id of state.expectedIds) assert.ok(selectedIds.has(id), `${row.id}: expected fixture ${id} was selected`);
+    for (const id of state.excludedIds) assert.ok(!selectedIds.has(id), `${row.id}: pre-boundary fixture ${id} was excluded`);
+
+    if (row.id === "session-end") {
+      assert.ok(state.afterWrite, "cache invalidation row must perform a read after writing");
+      assert.equal(
+        state.afterWrite!.memories.some((memory) => memory.content.includes("write after the first window read")),
+        true,
+        "a write between reads must invalidate the window cache and expose the new memory",
+      );
+    }
+  },
+
+  async teardown(state: WindowedMemoryState): Promise<void> {
+    await rm(state.dir, { recursive: true, force: true });
+  },
+};
+
+runLifecycleMatrix("windowed-memory-read", subject);