@remnic/core 9.62.0 → 9.62.2

package/src/episodic-context.ts

@@ -0,0 +1,274 @@
+/**
+ * Episodic context planning (issue #2331, harmonic-memory P3).
+ *
+ * Turns the structured `sources` provenance on recalled facts into episode
+ * windows over the LCM archive: resolve each source's turn, group overlapping
+ * turn ranges within a session into merged episodes, and cap the episode
+ * count/span. Pure planning — no archive access — plus an async wrapper that
+ * applies the single documented fallback (quote lookup) through an injected
+ * locator so the planner stays testable without SQLite.
+ *
+ * Window bounds are `[start, end)` throughout (`toTurn` exclusive); the
+ * archive's `getMessages` bounds are inclusive, so the fetch site passes
+ * `toTurn - 1`.
+ */
+
+import type { ProvenanceSource } from "./types.js";
+
+/** One fact contributing to episodic planning, with its final recall rank. */
+export interface EpisodicFactInput {
+  memoryId: string;
+  /** Final recall rank of the fact (0 = best). Lower wins. */
+  rank: number;
+  sources?: ProvenanceSource[];
+}
+
+/** A merged, fetch-ready episode window. */
+export interface EpisodeWindow {
+  sessionKey: string;
+  /** Inclusive first turn. */
+  fromTurn: number;
+  /** EXCLUSIVE end turn (`[start, end)` semantics). */
+  toTurn: number;
+  /** Best (lowest) rank among contributing facts — drives ordering. */
+  factRank: number;
+  /** Sorted, deduplicated contributing memory ids (citation line). */
+  memoryIds: string[];
+}
+
+/** Locates a quote's turn index within a session, or null on a miss. */
+export type QuoteLocator = (
+  quote: string,
+  sessionKey: string,
+) => Promise<number | null>;
+
+const TURN_FIELD_SEPARATOR = String.fromCharCode(1);
+
+/**
+ * Resolve a provenance `turnId` to a numeric LCM turn index, or null.
+ *
+ * Extraction writes `turnId` as the host turn fingerprint
+ * (`buildTurnFingerprint`: `role␁content␁thread␁turnIndex`), so the numeric
+ * LCM turn index is the LAST `␁`-separated field. A bare integer string is
+ * also accepted. Anything else is unresolvable — skip, never guess.
+ */
+export function resolveProvenanceTurnIndex(turnId: unknown): number | null {
+  if (typeof turnId !== "string" || turnId.length === 0) return null;
+  const lastField = turnId.includes(TURN_FIELD_SEPARATOR)
+    ? turnId.split(TURN_FIELD_SEPARATOR).pop()!
+    : turnId;
+  if (!/^\d+$/.test(lastField)) return null;
+  const parsed = Number.parseInt(lastField, 10);
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
+}
+
+interface DraftWindow {
+  sessionKey: string;
+  fromTurn: number;
+  toTurn: number;
+  factRank: number;
+  bestTurn: number;
+  memoryIds: Set<string>;
+}
+
+function windowForTurn(
+  sessionKey: string,
+  turn: number,
+  rank: number,
+  memoryId: string,
+): DraftWindow {
+  const fromTurn = Math.max(0, turn - 1);
+  return {
+    sessionKey,
+    fromTurn,
+    toTurn: turn + 2,
+    factRank: rank,
+    bestTurn: turn,
+    memoryIds: new Set([memoryId]),
+  };
+}
+
+function mergeDrafts(drafts: DraftWindow[], maxTurnsPerEpisode: number): EpisodeWindow[] {
+  const bySession = new Map<string, DraftWindow[]>();
+  for (const draft of drafts) {
+    const list = bySession.get(draft.sessionKey);
+    if (list) list.push(draft);
+    else bySession.set(draft.sessionKey, [draft]);
+  }
+
+  const windows: EpisodeWindow[] = [];
+  for (const [, sessionDrafts] of bySession) {
+    // Sort by fromTurn, then toTurn, so a shuffle cannot change merge results.
+    sessionDrafts.sort(
+      (a, b) => a.fromTurn - b.fromTurn || a.toTurn - b.toTurn,
+    );
+    let current: DraftWindow | null = null;
+    const flush = () => {
+      if (!current) return;
+      windows.push(finalizeWindow(current, maxTurnsPerEpisode));
+      current = null;
+    };
+    for (const draft of sessionDrafts) {
+      if (current && draft.fromTurn <= current.toTurn) {
+        // Overlapping or adjacent ([a,b) + [b,c) share no turn but read as one
+        // continuous episode): merge. Merged bounds stay [start, end).
+        current.toTurn = Math.max(current.toTurn, draft.toTurn);
+        if (draft.factRank < current.factRank) {
+          current.factRank = draft.factRank;
+          current.bestTurn = draft.bestTurn;
+        }
+        for (const id of draft.memoryIds) current.memoryIds.add(id);
+      } else {
+        flush();
+        current = { ...draft, memoryIds: new Set(draft.memoryIds) };
+      }
+    }
+    flush();
+  }
+  return windows;
+}
+
+function finalizeWindow(draft: DraftWindow, maxTurnsPerEpisode: number): EpisodeWindow {
+  let { fromTurn, toTurn } = draft;
+  const span = toTurn - fromTurn;
+  if (maxTurnsPerEpisode > 0 && span > maxTurnsPerEpisode) {
+    // Trim the tail but keep the highest-ranked fact's turn inside: anchor one
+    // turn of leading context on the best turn, clamped to the merged range.
+    fromTurn = Math.min(
+      Math.max(draft.bestTurn - 1, draft.fromTurn),
+      draft.toTurn - maxTurnsPerEpisode,
+    );
+    // maxTurnsPerEpisode === 1 (or a clamp collision) can push the anchor
+    // above the best turn; slide back down so the best turn stays included.
+    if (fromTurn + maxTurnsPerEpisode <= draft.bestTurn) {
+      fromTurn = Math.min(draft.bestTurn, draft.toTurn - maxTurnsPerEpisode);
+    }
+    toTurn = fromTurn + maxTurnsPerEpisode;
+  }
+  return {
+    sessionKey: draft.sessionKey,
+    fromTurn,
+    toTurn,
+    factRank: draft.factRank,
+    memoryIds: [...draft.memoryIds].sort(),
+  };
+}
+
+/** Total, stable ordering: rank asc, sessionKey asc, fromTurn asc, then residual identity. */
+export function compareEpisodeWindows(
+  left: EpisodeWindow,
+  right: EpisodeWindow,
+): number {
+  const leftIds = left.memoryIds.join("\u{0}");
+  const rightIds = right.memoryIds.join("\u{0}");
+  return (
+    left.factRank - right.factRank ||
+    (left.sessionKey < right.sessionKey ? -1 : left.sessionKey > right.sessionKey ? 1 : 0) ||
+    left.fromTurn - right.fromTurn ||
+    left.toTurn - right.toTurn ||
+    (leftIds < rightIds ? -1 : leftIds > rightIds ? 1 : 0)
+  );
+}
+
+/**
+ * Plan episode windows from recalled facts' structured provenance.
+ *
+ * Pure: no archive access. Facts without a structured `sources` array are
+ * skipped (no legacy scalar `source` parsing). Sources whose `turnId` does
+ * not resolve to a number are skipped — the caller decides whether to attempt
+ * the quote fallback for facts that lost every source.
+ *
+ * `maxEpisodes` or `maxTurnsPerEpisode` of 0 disables the section: returns
+ * `[]` before any work (zero semantics, checklist item 33).
+ */
+export function planEpisodeWindows(options: {
+  recalledFacts: ReadonlyArray<EpisodicFactInput>;
+  maxEpisodes: number;
+  maxTurnsPerEpisode: number;
+}): EpisodeWindow[] {
+  if (options.maxEpisodes <= 0 || options.maxTurnsPerEpisode <= 0) return [];
+  const drafts: DraftWindow[] = [];
+  for (const fact of options.recalledFacts) {
+    if (!fact || !Array.isArray(fact.sources)) continue;
+    for (const source of fact.sources) {
+      if (!source || typeof source.sessionKey !== "string" || source.sessionKey.length === 0) {
+        continue;
+      }
+      const turn = resolveProvenanceTurnIndex(source.turnId);
+      if (turn === null) continue;
+      drafts.push(
+        windowForTurn(source.sessionKey, turn, fact.rank, fact.memoryId),
+      );
+    }
+  }
+  if (drafts.length === 0) return [];
+  const windows = mergeDrafts(drafts, options.maxTurnsPerEpisode);
+  return windows.sort(compareEpisodeWindows).slice(0, options.maxEpisodes);
+}
+
+/**
+ * Facts whose sources all failed turn resolution but that carry a quote.
+ * These are the ONLY candidates for the quote-lookup fallback.
+ */
+export function factsNeedingQuoteFallback(
+  recalledFacts: ReadonlyArray<EpisodicFactInput>,
+): EpisodicFactInput[] {
+  return recalledFacts.filter(
+    (fact) =>
+      fact &&
+      Array.isArray(fact.sources) &&
+      fact.sources.length > 0 &&
+      fact.sources.some((source) => typeof source?.quote === "string" && source.quote.length > 0) &&
+      !fact.sources.some((source) => resolveProvenanceTurnIndex(source?.turnId) !== null),
+  );
+}
+
+/**
+ * Plan episode windows, applying the single documented fallback: for a fact
+ * whose turnIds ALL failed resolution but that has a quote, locate the quote
+ * in the archive and window around the located turn. A locator miss means the
+ * fact contributes no episode. Falls back to the pure plan when no locator is
+ * supplied.
+ */
+export async function planEpisodeWindowsWithFallback(options: {
+  recalledFacts: ReadonlyArray<EpisodicFactInput>;
+  maxEpisodes: number;
+  maxTurnsPerEpisode: number;
+  locateQuote?: QuoteLocator;
+}): Promise<EpisodeWindow[]> {
+  const facts = [...options.recalledFacts];
+  const locator = options.locateQuote;
+  if (locator && facts.length > 0) {
+    for (const fact of factsNeedingQuoteFallback(options.recalledFacts)) {
+      for (const source of fact.sources ?? []) {
+        if (typeof source?.quote !== "string" || source.quote.length === 0) continue;
+        if (typeof source.sessionKey !== "string" || source.sessionKey.length === 0) continue;
+        let turn: number | null = null;
+        try {
+          turn = await locator(source.quote, source.sessionKey);
+        } catch {
+          turn = null;
+        }
+        if (turn === null || !Number.isSafeInteger(turn) || turn < 0) continue;
+        facts.push({
+          memoryId: fact.memoryId,
+          rank: fact.rank,
+          sources: [
+            {
+              sessionKey: source.sessionKey,
+              turnId: String(turn),
+              observedAt: source.observedAt,
+              quote: source.quote,
+            },
+          ],
+        });
+        break; // one located quote per fact is enough to window it
+      }
+    }
+  }
+  return planEpisodeWindows({
+    recalledFacts: facts,
+    maxEpisodes: options.maxEpisodes,
+    maxTurnsPerEpisode: options.maxTurnsPerEpisode,
+  });
+}

package/src/harmonic-construction.test.ts

@@ -1,10 +1,11 @@
 import assert from "node:assert/strict";
 import { spawn } from "node:child_process";
-import { appendFile, mkdir, mkdtemp, open, readFile, rm, stat, unlink, utimes, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, mkdtemp, open, readdir, readFile, rm, stat, unlink, utimes, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import {
+  HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY,
   getAbstractionNodeStoreStatus,
   upsertAbstractionNode,
   upsertAbstractionNodes,
@@ -26,12 +27,14 @@ import {
   deriveHarmonicRecords,
   normalizeCueAnchorInputs,
 } from "./harmonic-construction.js";
-import { searchHarmonicRetrieval } from "./harmonic-retrieval.js";
+import { searchHarmonicRetrieval, type HarmonicRetrievalResult } from "./harmonic-retrieval.js";
 import { readJsonFile, withJsonStoreMutationLock } from "./json-store.js";
 import {
   filterHarmonicEntityMentions,
   persistConstructedHarmonicRecords,
 } from "./orchestration/harmonic-construction-persist.js";
+import { compareDeterministicStrings } from "./deterministic-order.js";
+import { stripAttributesSuffix } from "./structured-attributes.js";
 import { Orchestrator } from "./orchestrator.js";
 import { ExtractedFactSchema, ExtractionResultSchema } from "./schemas.js";
 import type { ExtractionResult, MemoryFile } from "./types.js";
@@ -1259,6 +1262,188 @@ test("harmonic anchors stay scoped to projected active sources in a mixed episod
   }
 });
 
+async function persistRecencyFixture(memoryDir: string): Promise<{
+  storageDir: string;
+  persistedIds: string[];
+  contentById: Map<string, string>;
+}> {
+  const config = parseConfig({
+    openaiApiKey: "sk-test",
+    memoryDir,
+    workspaceDir: path.join(memoryDir, "workspace"),
+    qmdEnabled: false,
+    embeddingFallbackEnabled: false,
+    chunkingEnabled: false,
+    harmonicRetrievalEnabled: true,
+    abstractionAnchorsEnabled: false,
+  });
+  const orchestrator = new Orchestrator(config) as unknown as PersistenceHarness;
+  const storage = await orchestrator.getStorage("default");
+  await storage.ensureDirectories();
+  const contents = [
+    "Atlas fact zero of the oldest insertion pair.",
+    "Atlas fact one of the oldest insertion pair.",
+    "Atlas fact two at the middle insertion time.",
+    "Atlas fact three of the newest insertion pair.",
+    "Atlas fact four of the newest insertion pair.",
+  ];
+  const { persistedIds } = await orchestrator.persistExtraction(
+    {
+      facts: contents.map((content) => ({
+        category: "fact",
+        content,
+        confidence: 0.99,
+        tags: ["atlas"],
+        entityRef: "atlas-project",
+        cueAnchors: [],
+      })),
+      entities: [{ name: "atlas-project", type: "company", facts: [] }],
+      profileUpdates: [],
+      questions: [],
+      relationships: [],
+      episodeTitle: "Atlas insertion ordering",
+    },
+    storage,
+    null,
+    { sessionKey: "session:harmonic-recency" }
+  );
+  const expectedContents = new Set(contents);
+  const contentById = new Map<string, string>();
+  const factIds: string[] = [];
+  for (const persistedId of persistedIds) {
+    const memory = await storage.getMemoryById(persistedId);
+    if (!memory) continue;
+    const content = memory.frontmatter.structuredAttributes
+      ? stripAttributesSuffix(memory.content)
+      : memory.content;
+    if (!expectedContents.has(content)) continue;
+    factIds.push(persistedId);
+    contentById.set(persistedId, content);
+  }
+  assert.equal(factIds.length, 5, `expected the five fact memories, got ${persistedIds.length} persisted`);
+  return { storageDir: storage.dir, persistedIds: factIds, contentById };
+}
+
+async function rewriteTopicInsertedAt(
+  storageDir: string,
+  insertedAtById: Record<string, string> | null,
+  recordedAt?: string
+): Promise<void> {
+  const nodesDir = path.join(storageDir, "state", "abstraction-nodes", "nodes");
+  for (const dayEntry of await readdir(nodesDir, { withFileTypes: true })) {
+    if (!dayEntry.isDirectory()) continue;
+    for (const entryName of await readdir(path.join(nodesDir, dayEntry.name))) {
+      if (!entryName.endsWith(".json")) continue;
+      const filePath = path.join(nodesDir, dayEntry.name, entryName);
+      const node = JSON.parse(await readFile(filePath, "utf8")) as Record<string, unknown>;
+      if (node.kind !== "topic") continue;
+      const metadata = { ...(node.metadata as Record<string, string>) };
+      if (insertedAtById === null) {
+        delete metadata[HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY];
+      } else {
+        metadata[HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY] = JSON.stringify(insertedAtById);
+      }
+      await writeFile(
+        filePath,
+        `${JSON.stringify({ ...node, metadata, ...(recordedAt ? { recordedAt } : {}) }, null, 2)}\n`
+      );
+    }
+  }
+}
+
+async function findProjectedTopic(
+  storageDir: string
+): Promise<HarmonicRetrievalResult | undefined> {
+  const results = await searchHarmonicRetrieval({
+    memoryDir: storageDir,
+    query: "atlas",
+    maxResults: 5,
+    anchorsEnabled: false,
+  });
+  return results.find((result) => result.node.kind === "topic");
+}
+
+test("harmonic projection orders sources newest-first with deterministic tiebreak", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-harmonic-recency-"));
+  try {
+    const { storageDir, persistedIds, contentById } = await persistRecencyFixture(memoryDir);
+    const ascendingIds = [...persistedIds].sort(compareDeterministicStrings);
+    const [first, second, third, fourth, fifth] = ascendingIds.map((memoryId) => memoryId);
+    assert.ok(first && second && third && fourth && fifth);
+    const oldest = "2026-01-01T00:00:00.000Z";
+    const middle = "2026-02-01T00:00:00.000Z";
+    const newest = "2026-03-01T00:00:00.000Z";
+    const insertedAtByRank = [oldest, oldest, middle, newest, newest];
+    await rewriteTopicInsertedAt(
+      storageDir,
+      Object.fromEntries(ascendingIds.map((memoryId, index) => [memoryId, insertedAtByRank[index]]))
+    );
+
+    const topic = await findProjectedTopic(storageDir);
+    assert.ok(topic, "topic node must stay retrievable");
+    assert.deepEqual(topic.node.sourceMemoryIds, [fourth, fifth, third, first, second]);
+    assert.equal(topic.node.title, contentById.get(fourth));
+    assert.equal(
+      topic.node.summary,
+      [fourth, fifth, third].map((memoryId) => contentById.get(memoryId)).join("; ")
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("harmonic projection keeps ascending id order for equal or missing insertion timestamps", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-harmonic-recency-equal-"));
+  try {
+    const { storageDir, persistedIds, contentById } = await persistRecencyFixture(memoryDir);
+    const ascendingIds = [...persistedIds].sort(compareDeterministicStrings);
+    const [first, second, third, fourth, fifth] = ascendingIds.map((memoryId) => memoryId);
+    assert.ok(first && second && third && fourth && fifth);
+    const expectedSummary = [first, second, third]
+      .map((memoryId) => contentById.get(memoryId))
+      .join("; ");
+
+    await rewriteTopicInsertedAt(
+      storageDir,
+      Object.fromEntries(ascendingIds.map((memoryId) => [memoryId, "2026-01-01T00:00:00.000Z"]))
+    );
+    let topic = await findProjectedTopic(storageDir);
+    assert.ok(topic);
+    assert.deepEqual(topic.node.sourceMemoryIds, ascendingIds);
+    assert.equal(topic.node.title, contentById.get(first));
+    assert.equal(topic.node.summary, expectedSummary);
+
+    await rewriteTopicInsertedAt(storageDir, null);
+    topic = await findProjectedTopic(storageDir);
+    assert.ok(topic);
+    assert.deepEqual(topic.node.sourceMemoryIds, ascendingIds);
+    assert.equal(topic.node.title, contentById.get(first));
+    assert.equal(topic.node.summary, expectedSummary);
+
+    await rewriteTopicInsertedAt(
+      storageDir,
+      {
+        [first]: "not-a-timestamp",
+        [second]: "2026-01-01T00:00:00.000Z",
+        [third]: "2026-02-01T00:00:00.000Z",
+        [fourth]: "definitely not a date",
+        [fifth]: "2026-03-01T00:00:00.000Z",
+      },
+      "2026-06-01T00:00:00.000Z"
+    );
+    topic = await findProjectedTopic(storageDir);
+    assert.ok(topic);
+    assert.deepEqual(topic.node.sourceMemoryIds, [first, fourth, fifth, third, second]);
+    assert.equal(topic.node.title, contentById.get(first));
+    assert.equal(
+      topic.node.summary,
+      [first, fourth, fifth].map((memoryId) => contentById.get(memoryId)).join("; ")
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
 test("non-default namespace construction ignores the default store override", async () => {
   const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-harmonic-namespace-"));
   try {

package/src/harmonic-retrieval.ts

@@ -13,6 +13,7 @@ import { compareDeterministicStrings } from "./deterministic-order.js";
 import { countRecallTokenOverlap, normalizeRecallTokens } from "./recall-tokenization.js";
 import { stripAttributesSuffix } from "./structured-attributes.js";
 import { isValidityExpiredNow } from "./temporal-validity.js";
+import { isRecord } from "./store-contract.js";
 import type { MemoryFile } from "./types.js";
 
 type SourceMemoryMap = Map<string, MemoryFile>;
@@ -42,6 +43,22 @@ async function readSourceMemories(options: {
   return sourceMemories;
 }
 
+function parseSourceMemoryInsertedAt(node: AbstractionNode): Map<string, string> {
+  const insertedAtById = new Map<string, string>();
+  const insertedAtRaw = node.metadata?.[HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY];
+  if (!insertedAtRaw) return insertedAtById;
+  try {
+    const parsed = JSON.parse(insertedAtRaw) as unknown;
+    if (!isRecord(parsed)) return insertedAtById;
+    for (const [memoryId, value] of Object.entries(parsed)) {
+      if (typeof value === "string") insertedAtById.set(memoryId, value);
+    }
+  } catch {
+    // Malformed insertion metadata leaves ordering on the recordedAt fallback.
+  }
+  return insertedAtById;
+}
+
 function projectSourceBackedNode(
   node: AbstractionNode,
   sourceMemories: SourceMemoryMap,
@@ -62,6 +79,19 @@ function projectSourceBackedNode(
   });
   if (activeSourceMemoryIds.length === 0) return null;
 
+ // Newest-first source order keeps the projected title and summary on the most
+ // recently inserted facts. Equal or missing timestamps fall back to ascending
+ // id order, which matches the stored sourceMemoryIds order.
+ const insertedAtById = parseSourceMemoryInsertedAt(node);
+ const insertedAtMs = (memoryId: string): number => {
+   const parsedMs = Date.parse(insertedAtById.get(memoryId) ?? "");
+   return Number.isFinite(parsedMs) ? parsedMs : Date.parse(node.recordedAt);
+ };
+ activeSourceMemoryIds.sort(
+   (left, right) =>
+     insertedAtMs(right) - insertedAtMs(left) || compareDeterministicStrings(left, right)
+ );
+
   const activeMemories = activeSourceMemoryIds.flatMap((memoryId) => {
     const memory = sourceMemories.get(memoryId);
     return memory ? [memory] : [];
@@ -69,40 +99,32 @@ function projectSourceBackedNode(
   const activeContents = activeMemories.map((memory) =>
     memory.frontmatter.structuredAttributes ? stripAttributesSuffix(memory.content) : memory.content
   );
-  let metadata: Record<string, string> | undefined;
-  const insertedAtRaw = node.metadata?.[HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY];
-  if (insertedAtRaw) {
-    try {
-      const insertedAt = JSON.parse(insertedAtRaw) as Record<string, unknown>;
-      const activeInsertedAt = activeSourceMemoryIds.flatMap((memoryId) => {
-        const value = insertedAt[memoryId];
-        return typeof value === "string" ? [[memoryId, value] as const] : [];
-      });
-      if (activeInsertedAt.length > 0) {
-        metadata = {
-          [HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY]: JSON.stringify(Object.fromEntries(activeInsertedAt)),
-        };
-      }
-    } catch {
-      metadata = undefined;
-    }
+ let metadata: Record<string, string> | undefined;
+ const activeInsertedAt = activeSourceMemoryIds.flatMap((memoryId) => {
+   const value = insertedAtById.get(memoryId);
+   return typeof value === "string" ? [[memoryId, value] as const] : [];
+ });
+ if (activeInsertedAt.length > 0) {
+   metadata = {
+     [HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY]: JSON.stringify(Object.fromEntries(activeInsertedAt)),
+   };
   }
 
-  return {
-    ...node,
-    sourceMemoryIds: activeSourceMemoryIds,
-    title: activeContents[0]?.slice(0, 80) ?? node.title,
-    summary: activeContents.slice(0, 3).join("; ").slice(0, 400),
-    tags: [...new Set(activeMemories.flatMap((memory) => memory.frontmatter.tags))].sort(compareDeterministicStrings),
-    entityRefs: [
-      ...new Set(
-        activeMemories.flatMap((memory) =>
-          typeof memory.frontmatter.entityRef === "string" ? [memory.frontmatter.entityRef] : []
-        )
-      ),
-    ].sort(compareDeterministicStrings),
-    metadata,
-  };
+ return {
+   ...node,
+   sourceMemoryIds: activeSourceMemoryIds,
+   title: activeContents[0]?.slice(0, 80) ?? node.title,
+   summary: activeContents.slice(0, 3).join("; ").slice(0, 400),
+   tags: [...new Set(activeMemories.flatMap((memory) => memory.frontmatter.tags))].sort(compareDeterministicStrings),
+   entityRefs: [
+     ...new Set(
+       activeMemories.flatMap((memory) =>
+         typeof memory.frontmatter.entityRef === "string" ? [memory.frontmatter.entityRef] : []
+       )
+     ),
+   ].sort(compareDeterministicStrings),
+   metadata,
+ };
 }
 
 function anchorMatchesProjectedNode(

package/src/index.ts

@@ -11,6 +11,8 @@
  *
  */
 
+export { collapseWhitespace, displayWidth, graphemeUnits, padEndDisplay, truncateCodePointSafe, truncateGraphemeSafe } from "./whitespace.js";
+
 // ---------------------------------------------------------------------------
 // Plugin entry resolution
 // ---------------------------------------------------------------------------
@@ -1446,10 +1448,7 @@ export {
 
 // Coding-graph engine contract (#1551 PR1), implemented by optional @remnic/coding-graph.
 
-export {
-  CODING_GRAPH_ENGINE_VERSION,
-  TIER_1_LANGUAGES,
-} from "./coding/coding-graph-types.js";
+export { CODING_GRAPH_ENGINE_VERSION, TIER_1_LANGUAGES } from "./coding/coding-graph-types.js";
 
 export type {
   CodingGraphEngine,

package/src/lcm/engine.ts

@@ -1,6 +1,6 @@
 import type Database from "better-sqlite3";
 import { openLcmDatabase, ensureLcmStateDir } from "./schema.js";
-import { LcmArchive, type LcmStructuredRecallMatch } from "./archive.js";
+import { LcmArchive, type LcmMessage, type LcmStructuredRecallMatch } from "./archive.js";
 import { LcmDag } from "./dag.js";
 import { LcmSummarizer, type SummarizeFn } from "./summarizer.js";
 import {
@@ -541,6 +541,23 @@ export class LcmEngine {
     };
   }
 
+  /**
+   * Retrieve raw archived messages for a turn range (inclusive bounds),
+   * read-only and unshaped — no token-budget trimming (issue #2331
+   * episodic-context). Callers own truncation and cleaning.
+   */
+  async getTurnRange(
+    sessionId: string,
+    fromTurn: number,
+    toTurn: number,
+  ): Promise<LcmMessage[]> {
+    if (!this.config.enabled) return [];
+    const normalizedSessionId = normalizeLcmSessionId(sessionId);
+    if (!normalizedSessionId) return [];
+    await this.ensureInitialized();
+    return this.archive!.getMessages(normalizedSessionId, fromTurn, toTurn);
+  }
+
   /** Retrieve raw messages for a turn range (lossless expansion). */
   async expandContext(
     sessionId: string,