@remnic/core 9.6.17 → 9.6.19

package/src/temporal-timeline-recall.test.ts

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { buildTemporalTimelineRecallSection, type TemporalTimelineRecallItem } from "./temporal-timeline-recall.js";
+import type { MemoryFile } from "./types.js";
+
+function item(
+  id: string,
+  content: string,
+  eventAt: string,
+  sessionKey?: string,
+): TemporalTimelineRecallItem {
+  const memory: MemoryFile = {
+    path: `/memory/${id}.md`,
+    content,
+    frontmatter: {
+      id,
+      category: "fact",
+      created: "2026-07-01T00:00:00.000Z",
+      updated: "2026-07-01T00:00:00.000Z",
+      source: "test",
+      confidence: 0.9,
+      confidenceTier: "explicit",
+      tags: ["trip"],
+    },
+  };
+  return { memory, eventAt, ...(sessionKey ? { sessionKey } : {}) };
+}
+
+test("timeline selects query-relevant evidence then restores cross-session chronology", () => {
+  const output = buildTemporalTimelineRecallSection({
+    query: "Which trip happened first, Paris or Rome?",
+    maxChars: 4_000,
+    maxItems: 2,
+    items: [
+      item("rome", "Visited Rome in spring.", "2026-05-10T00:00:00.000Z", "session-b"),
+      item("noise", "Changed the database pool size.", "2026-01-01T00:00:00.000Z", "session-c"),
+      item("paris", "Visited Paris in winter.", "2026-03-04T00:00:00.000Z", "session-a"),
+    ],
+  });
+
+  assert.doesNotMatch(output, /database pool/);
+  assert.ok(output.indexOf("Visited Paris") < output.indexOf("Visited Rome"));
+  assert.match(output, /session=session-a/);
+  assert.match(output, /session=session-b/);
+});
+
+test("timeline dedupes replayed memory ids and uses a stable tie-break", () => {
+  const output = buildTemporalTimelineRecallSection({
+    query: "What happened first?",
+    maxChars: 4_000,
+    maxItems: 10,
+    items: [
+      item("b", "Second stable item.", "2026-03-04T00:00:00.000Z"),
+      item("a", "First stable item.", "2026-03-04T00:00:00.000Z"),
+      item("a", "REPLAY_MUST_NOT_SURFACE.", "2026-04-04T00:00:00.000Z"),
+    ],
+  });
+
+  assert.ok(output.indexOf("First stable item") < output.indexOf("Second stable item"));
+  assert.doesNotMatch(output, /REPLAY_MUST_NOT_SURFACE/);
+});
+
+test("timeline respects zero limits and clips within its character budget", () => {
+  const items = [item("a", "A long temporal event body.", "2026-03-04T00:00:00.000Z")];
+  assert.equal(buildTemporalTimelineRecallSection({ query: "when", maxChars: 0, maxItems: 1, items }), "");
+  assert.equal(buildTemporalTimelineRecallSection({ query: "when", maxChars: 100, maxItems: 0, items }), "");
+  const clipped = buildTemporalTimelineRecallSection({ query: "when", maxChars: 40, maxItems: 1, items });
+  assert.ok(clipped.length <= 40);
+});

package/src/temporal-timeline-recall.ts

@@ -0,0 +1,111 @@
+import type { MemoryFile } from "./types.js";
+
+export interface TemporalTimelineRecallItem {
+  memory: MemoryFile;
+  eventAt: string;
+  observedAt?: string;
+  sessionKey?: string;
+  validUntil?: string;
+}
+
+export interface TemporalTimelineRecallOptions {
+  items: readonly TemporalTimelineRecallItem[];
+  query: string;
+  maxChars: number;
+  maxItems: number;
+  title?: string;
+}
+
+const QUERY_STOPWORDS = new Set([
+  "a", "an", "and", "did", "do", "first", "happened", "how", "i", "in",
+  "is", "it", "last", "many", "most", "my", "of", "on", "or", "recent",
+  "recently", "the", "to", "was", "what", "when", "which", "who", "with",
+]);
+
+function queryTerms(query: string): string[] {
+  return [...new Set(
+    query
+      .toLowerCase()
+      .match(/[\p{L}\p{N}][\p{L}\p{N}'_-]*/gu)
+      ?.filter((term) => term.length > 1 && !QUERY_STOPWORDS.has(term)) ?? [],
+  )];
+}
+
+function relevanceScore(item: TemporalTimelineRecallItem, terms: readonly string[]): number {
+  if (terms.length === 0) return 1;
+  const haystack = `${item.memory.content} ${(item.memory.frontmatter.tags ?? []).join(" ")} ${item.memory.frontmatter.entityRef ?? ""}`.toLowerCase();
+  let score = 0;
+  for (const term of terms) {
+    if (haystack.includes(term)) score += 1;
+  }
+  return score;
+}
+
+function compareChronology(
+  left: TemporalTimelineRecallItem,
+  right: TemporalTimelineRecallItem,
+): number {
+  const eventOrder = left.eventAt.localeCompare(right.eventAt);
+  if (eventOrder !== 0) return eventOrder;
+  const observedOrder = (left.observedAt ?? "").localeCompare(right.observedAt ?? "");
+  if (observedOrder !== 0) return observedOrder;
+  return left.memory.frontmatter.id.localeCompare(right.memory.frontmatter.id);
+}
+
+function clip(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  if (maxChars <= 1) return text.slice(0, maxChars);
+  return `${text.slice(0, maxChars - 1).trimEnd()}…`;
+}
+
+/**
+ * Build a query-focused timeline from ingest-indexed memory primitives.
+ * Selection is relevance-first; presentation is always event-time ordered.
+ */
+export function buildTemporalTimelineRecallSection(
+  options: TemporalTimelineRecallOptions,
+): string {
+  const maxChars = Number.isFinite(options.maxChars) ? Math.floor(options.maxChars) : 0;
+  const maxItems = Number.isFinite(options.maxItems) ? Math.floor(options.maxItems) : 0;
+  if (maxChars <= 0 || maxItems <= 0 || options.items.length === 0) return "";
+
+  const terms = queryTerms(options.query);
+  const uniqueById = new Map<string, TemporalTimelineRecallItem>();
+  for (const item of options.items) {
+    const id = item.memory.frontmatter.id;
+    const current = uniqueById.get(id);
+    if (!current || compareChronology(item, current) < 0) uniqueById.set(id, item);
+  }
+
+  const scored = [...uniqueById.values()].map((item) => ({
+    item,
+    score: relevanceScore(item, terms),
+  }));
+  const relevant = scored.some(({ score }) => score > 0)
+    ? scored.filter(({ score }) => score > 0)
+    : scored;
+  const selected = relevant
+    .sort((left, right) => {
+      if (right.score !== left.score) return right.score - left.score;
+      return compareChronology(left.item, right.item);
+    })
+    .slice(0, maxItems)
+    .map(({ item }) => item)
+    .sort(compareChronology);
+
+  const title = options.title ?? "Cross-session temporal timeline";
+  const lines = [
+    `## ${title}`,
+    "Ordered by event time across source sessions; event time is distinct from ingest time.",
+  ];
+  for (const item of selected) {
+    const provenance = [
+      `event=${item.eventAt}`,
+      item.validUntil ? `until<${item.validUntil}` : "",
+      item.observedAt ? `observed=${item.observedAt}` : "",
+      item.sessionKey ? `session=${item.sessionKey}` : "",
+    ].filter(Boolean).join(", ");
+    lines.push(`- [${provenance}] ${item.memory.content.trim()}`);
+  }
+  return clip(lines.join("\n"), maxChars);
+}