agent-working-memory 0.16.1 → 0.18.1

package/src/core/asked-value.ts

@@ -0,0 +1,74 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * "Known subject, attribute not stored" — the near-miss that invites invention.
+ *
+ * The strongest mechanistic account of hallucination (Ferrando et al., ICLR
+ * 2025; Lindsey et al. 2025) is that a model fabricates when it RECOGNISES an
+ * entity but lacks the fact asked about it: recognition switches off the
+ * "can't answer" default. A memory layer cannot reach the model's internals,
+ * but it can stop handing the model exactly that shape of context: three
+ * memories that are plainly about Sam's Denver flight, none of which holds a
+ * departure time, read to the model as "I know this flight", and the time
+ * gets made up. AWM's abstention gate does not fire here, by design: a
+ * near-miss usually has a clear winner.
+ *
+ * So, when the query asks for a KIND of value — a time, a date, an amount, a
+ * count, a status — and no returned memory holds a value of that kind, the
+ * reply says so in one line. It costs the agent one read of the source; the
+ * alternative is a confident wrong number. Detection is deliberately simple
+ * and conservative: it only ever ADDS a line, never changes ranking, and says
+ * nothing when the query names no kind.
+ */
+
+import { valueSlots, type SlotKind } from './conflicts.js';
+
+/** Query phrasings that ask for each kind of value. Lower-case, tested as regexes. */
+const ASKS: Array<[SlotKind, RegExp]> = [
+  ['time',   /\b(what time|time does|time is|what hour|o'?clock|depart(?:s|ure)?|leaves?|arrives?|arrival|starts? at|ends? at|opens? at|closes? at)\b/],
+  ['date',   /\b(what day|what date|which day|which date|due|deadline|by when|expire|expires|renews?|renewal date)\b/],
+  ['money',  /\b(how much|price|prices|cost|costs|fee|fees|rate|rates|charge|charges|amount|invoice total|\$)/],
+  ['number', /\b(how many|count|which port|port number|version|how old|what number|phone|extension|zip|room number|flight number)\b/],
+  ['status', /\b(status|(?:is|are|was|were) (?:\w+ ){0,4}(?:open|closed|paid|unpaid|cancell?ed|confirmed|approved|done|live|down|blocked|overdue|pending)|still (?:open|unpaid|pending|blocked)|did (?:\w+ ){0,3}(?:pay|cancel|confirm|approve|renew|ship|deploy))\b/],
+];
+
+/** "when" asks for a time OR a date; either kind stored answers it. */
+const WHEN = /\b(when)\b/;
+
+/** The kinds of value the query asks for; empty when it names none. */
+export function askedKinds(query: string): Set<SlotKind> {
+  const q = query.toLowerCase();
+  const out = new Set<SlotKind>();
+  for (const [kind, re] of ASKS) if (re.test(q)) out.add(kind);
+  if (WHEN.test(q)) { out.add('time'); out.add('date'); }
+  return out;
+}
+
+/** What this needs from a result. */
+export interface ValueBearing { engram: { content: string } }
+
+/**
+ * The kinds asked for that NO returned memory holds, or an empty array. With
+ * a "when" question, a stored time or date on any result satisfies both.
+ */
+export function missingAskedKinds(query: string, results: ValueBearing[]): SlotKind[] {
+  const asked = askedKinds(query);
+  if (asked.size === 0 || results.length === 0) return [];
+  const held = new Set<SlotKind>();
+  for (const r of results) for (const k of valueSlots(r.engram.content).keys()) held.add(k);
+  const whenAsked = WHEN.test(query.toLowerCase());
+  if (whenAsked && (held.has('time') || held.has('date'))) { asked.delete('time'); asked.delete('date'); }
+  return [...asked].filter(k => !held.has(k));
+}
+
+const LABEL: Record<SlotKind, string> = {
+  time: 'a time', date: 'a date', money: 'an amount', number: 'a number', status: 'a status',
+};
+
+/** One reply line, or empty. */
+export function missingValueNote(query: string, results: ValueBearing[]): string {
+  const missing = missingAskedKinds(query, results);
+  if (missing.length === 0) return '';
+  const what = missing.map(k => LABEL[k]).join(' or ');
+  return `\n⚠ These memories are about the subject, but none of them holds ${what}, which is what the question asks for. Do not state one from memory — read the source.`;
+}

package/src/core/conflicts.ts

@@ -0,0 +1,280 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Conflict surfacing among the memories ONE recall returns.
+ *
+ * AWM keeps contradictions on purpose (edge-case test 7 requires both sides of
+ * a contradiction in the top 5): settling them is the agent's job, with the
+ * source. What it did not do, until 2026-10-19, was SAY that two returned
+ * memories disagree, or which is newer. The MWA evaluation probe showed the
+ * cost: "departs 10:15" and "now departs 8:40" came back as two undated lines,
+ * the stale one first, and nothing on the page told the model it was looking
+ * at two versions of one fact. In the BL-40 assessment "newer facts lose to
+ * older sources" cost four checks.
+ *
+ * This is a detector over the returned set only — never over the store — so it
+ * costs a handful of string comparisons per recall. It is deliberately
+ * conservative and its output is a QUESTION ("possible conflict … confirm
+ * against the source"), not a verdict: a false mark costs the agent one check,
+ * a missed one costs a wrong answer stated with confidence.
+ *
+ * Two memories are flagged when
+ *   1. they are about the same thing — related by embedding cosine, or by word
+ *      overlap when an embedding is missing — and
+ *   2. they carry a value of the same kind (a time, a date, a money amount, a
+ *      bare number, a status word) and those values differ, and
+ *   3. neither supersedes the other and neither is already stale (superseded,
+ *      expired, not yet valid) — those are marked elsewhere.
+ *
+ * Known limit, measured in tests/core/conflicts.test.ts: "template twins" —
+ * two genuinely distinct facts that share a template ("flight out 8:40",
+ * "flight back 10:15") — are flagged. That is the precision cost of (1)+(2)
+ * without a parser, and the reason the mark is phrased as a question.
+ */
+
+import { cosineSimilarity } from './embeddings.js';
+import { validityState } from './validity.js';
+
+export type SlotKind = 'time' | 'date' | 'money' | 'number' | 'status';
+
+/** What this needs from a result — any ActivationResult qualifies. */
+export interface ConflictCandidate {
+  engram: {
+    id: string;
+    concept: string;
+    content: string;
+    embedding?: number[] | null;
+    createdAt?: Date | string | null;
+    supersededBy?: string | null;
+    supersedes?: string | null;
+    validFrom?: string | null;
+    validTo?: string | null;
+  };
+}
+
+export interface ConflictMark {
+  /** The other memory in the pair. */
+  id: string;
+  /** True when THIS memory was written after the other one. */
+  newer: boolean;
+  /** The kind of value the two disagree on. */
+  slot: SlotKind;
+}
+
+const MONTHS = 'jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec';
+const STATUS_WORDS = new Set([
+  'moved', 'cancelled', 'canceled', 'renewed', 'rejected', 'approved', 'closed', 'open', 'opened',
+  'paused', 'resumed', 'delayed', 'postponed', 'confirmed', 'unpaid', 'paid', 'overdue', 'done',
+  'blocked', 'shipped', 'deployed', 'reverted', 'merged', 'unmerged', 'live', 'offline', 'down', 'up',
+]);
+const STOP = new Set([
+  'the', 'and', 'for', 'with', 'that', 'this', 'from', 'per', 'now', 'was', 'were', 'are', 'has',
+  'have', 'had', 'into', 'onto', 'than', 'then', 'not', 'but', 'its', 'his', 'her', 'their', 'our',
+  'according', 'page', 'said', 'says', 'still', 'also', 'any', 'all', 'one', 'two', 'about',
+]);
+
+/** Normalise a clock time to HH:MM (24h). Returns null when it is not one. */
+function clock(h: string, m: string | undefined, ampm: string | undefined): string | null {
+  let hh = Number(h);
+  const mm = m ? Number(m) : 0;
+  if (!Number.isFinite(hh) || hh > 23 || mm > 59) return null;
+  if (ampm) {
+    const p = ampm.toLowerCase();
+    if (hh > 12) return null;
+    if (p === 'pm' && hh < 12) hh += 12;
+    if (p === 'am' && hh === 12) hh = 0;
+  }
+  return `${String(hh).padStart(2, '0')}:${String(mm).padStart(2, '0')}`;
+}
+
+/**
+ * The comparable values in a text, by kind. Text matched by an earlier,
+ * more specific kind is blanked before a later kind runs, so "3:30pm" is one
+ * time rather than a time and the numbers 3 and 30, and "$49" is money, not
+ * a number.
+ */
+export function valueSlots(text: string): Map<SlotKind, Set<string>> {
+  const slots = new Map<SlotKind, Set<string>>();
+  const add = (k: SlotKind, v: string) => {
+    if (!slots.has(k)) slots.set(k, new Set());
+    slots.get(k)!.add(v);
+  };
+  let t = ` ${text} `;
+  const take = (re: RegExp, fn: (m: RegExpExecArray) => void) => {
+    t = t.replace(re, (...args) => {
+      const m = args as unknown as RegExpExecArray;
+      fn(m);
+      return ' ';
+    });
+  };
+
+  // Times: 8:40 AM, 3:30pm, 14:00, 7pm.
+  take(/\b(\d{1,2}):(\d{2})\s*(am|pm)\b/gi, m => { const c = clock(m[1], m[2], m[3]); if (c) add('time', c); });
+  take(/\b(\d{1,2})\s*(am|pm)\b/gi, m => { const c = clock(m[1], undefined, m[2]); if (c) add('time', c); });
+  take(/\b([01]?\d|2[0-3]):([0-5]\d)\b/g, m => { const c = clock(m[1], m[2], undefined); if (c) add('time', c); });
+  // Dates: 2026-01-15, Nov 14, 14 Nov, November 14th.
+  take(/\b(\d{4})-(\d{2})-(\d{2})\b/g, m => add('date', `${m[1]}-${m[2]}-${m[3]}`));
+  take(new RegExp(`\\b(${MONTHS})[a-z]*\\.?\\s+(\\d{1,2})(?:st|nd|rd|th)?\\b`, 'gi'),
+    m => add('date', `${m[1].slice(0, 3).toLowerCase()}-${Number(m[2])}`));
+  take(new RegExp(`\\b(\\d{1,2})(?:st|nd|rd|th)?\\s+(${MONTHS})[a-z]*\\b`, 'gi'),
+    m => add('date', `${m[2].slice(0, 3).toLowerCase()}-${Number(m[1])}`));
+  // A bare month after a preposition ("in October", "by March", "since
+  // November") is a date too — coarser, but "in October the club chose
+  // fantasy" against "in March … a mystery" is exactly the two-versions case
+  // (MWA, 0.18.1). Full names only and a preposition required: an unanchored
+  // match took the modal verb "may" and every passing "March" as a date, and
+  // on the real store that flagged enough false conflicts to show in the
+  // benchmark. Runs after the month-day forms, which have already been
+  // blanked, so "Nov 14" is not also counted as "nov".
+  take(/\b(?:in|by|until|till|from|since|during|before|after|early|late|mid|next|last|this|of|through)\s+(january|february|march|april|may|june|july|august|september|october|november|december)\b/gi,
+    m => add('date', m[1].slice(0, 3).toLowerCase()));
+  // Money: $1.45, $2,400, $49/month.
+  take(/\$\s?(\d[\d,]*(?:\.\d+)?)/g, m => add('money', m[1].replace(/,/g, '')));
+  // Bare numbers (ids, counts, flight numbers): shared ones do no harm, differing ones may.
+  take(/\b\d+(?:\.\d+)?\b/g, m => add('number', m[0]));
+  // Status vocabulary.
+  for (const w of t.toLowerCase().match(/[a-z]+/g) ?? []) {
+    if (STATUS_WORDS.has(w)) add('status', w);
+  }
+  return slots;
+}
+
+/** Content words for the overlap fallback: lower-case, 3+ letters, no stopwords, no digits. */
+function words(c: ConflictCandidate): Set<string> {
+  const out = new Set<string>();
+  for (const w of `${c.engram.concept} ${c.engram.content}`.toLowerCase().match(/[a-z][a-z']{2,}/g) ?? []) {
+    if (!STOP.has(w)) out.add(w);
+  }
+  return out;
+}
+
+function jaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 || b.size === 0) return 0;
+  let inter = 0;
+  for (const w of a) if (b.has(w)) inter++;
+  return inter / (a.size + b.size - inter);
+}
+
+const COSINE_RELATED = 0.80;
+const OVERLAP_RELATED = 0.30;
+
+/** True when the two memories look like they are about the same thing. */
+export function related(a: ConflictCandidate, b: ConflictCandidate): boolean {
+  const ea = a.engram.embedding, eb = b.engram.embedding;
+  if (ea && eb && ea.length === eb.length && ea.length > 0) {
+    if (cosineSimilarity(ea, eb) >= COSINE_RELATED) return true;
+  }
+  return jaccard(words(a), words(b)) >= OVERLAP_RELATED;
+}
+
+/** The first kind of value present in BOTH texts on which they disagree, or null. */
+export function disagreement(a: ConflictCandidate, b: ConflictCandidate): SlotKind | null {
+  const sa = valueSlots(a.engram.content), sb = valueSlots(b.engram.content);
+  for (const kind of ['time', 'date', 'money', 'status', 'number'] as SlotKind[]) {
+    let va = sa.get(kind), vb = sb.get(kind);
+    if (!va || !vb) continue;
+    // Dates come at three grains (2026-01-15, nov-14, nov). When either side
+    // has a month-only value, compare both at month grain: "Nov 14" and
+    // "in November" agree; "in October" and "in March" do not.
+    if (kind === 'date' && ([...va, ...vb].some(v => /^[a-z]{3}$/.test(v)))) {
+      va = new Set([...va].map(monthOf)); vb = new Set([...vb].map(monthOf));
+    }
+    // Disagree when neither set contains the other: a memory that mentions
+    // two times, one of which the other repeats, is an elaboration, not a conflict.
+    const aInB = [...va].every(v => vb.has(v));
+    const bInA = [...vb].every(v => va.has(v));
+    if (!aInB && !bInA) return kind;
+  }
+  return null;
+}
+
+const MONTH_NAMES = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+/** The month token of any date value this file produces. */
+function monthOf(v: string): string {
+  const iso = /^(\d{4})-(\d{2})-\d{2}$/.exec(v);
+  if (iso) return MONTH_NAMES[Number(iso[2]) - 1] ?? v;
+  return v.slice(0, 3);
+}
+
+function createdMs(c: ConflictCandidate): number {
+  const v = c.engram.createdAt;
+  if (!v) return NaN;
+  return v instanceof Date ? v.getTime() : Date.parse(v);
+}
+
+function stale(c: ConflictCandidate, now: number): boolean {
+  return !!c.engram.supersededBy || validityState(c.engram, now) !== 'current';
+}
+
+/**
+ * Pairwise over the returned set. Returns one list of marks per input, in
+ * input order; an empty list means no conflict for that memory.
+ */
+export function detectConflicts(results: ConflictCandidate[], now: number = Date.now()): ConflictMark[][] {
+  const marks: ConflictMark[][] = results.map(() => []);
+  for (let i = 0; i < results.length; i++) {
+    const a = results[i];
+    if (stale(a, now)) continue;
+    for (let j = i + 1; j < results.length; j++) {
+      const b = results[j];
+      if (stale(b, now)) continue;
+      if (a.engram.supersedes === b.engram.id || b.engram.supersedes === a.engram.id) continue;
+      if (!related(a, b)) continue;
+      const slot = disagreement(a, b);
+      if (!slot) continue;
+      const ta = createdMs(a), tb = createdMs(b);
+      const aNewer = Number.isFinite(ta) && Number.isFinite(tb) ? ta > tb : false;
+      const bNewer = Number.isFinite(ta) && Number.isFinite(tb) ? tb > ta : false;
+      marks[i].push({ id: b.engram.id, newer: aNewer, slot });
+      marks[j].push({ id: a.engram.id, newer: bNewer, slot });
+    }
+  }
+  return marks;
+}
+
+/**
+ * Newest first among results that are two versions of one fact — FOR HARNESSES.
+ *
+ * MWA's case: "In October the club chose fantasy / December science fiction /
+ * March a mystery" for "what did the club most recently choose". The
+ * cross-encoder cannot tell them apart, and a sort by its score put the newest
+ * last. AWM itself does NOT apply this (0.18.1): a score-epsilon fallback to the
+ * blend measured -14pp identifier s@1 (rerank2.ts), and applying this helper
+ * inside the engine measured -18pp with s@5 unchanged, because on a real store
+ * the detector also marks related memories that differ in a ticket id or a
+ * date. The marks are a cue to check the source. A harness whose policy is
+ * "newer beats older" (MWA's is) can call this on the returned results with
+ * their `conflictsWith` marks. `marks` is parallel to `results`; the returned
+ * array is new and its marks still describe the same ids.
+ */
+export function newestFirstAmongConflicts<T extends ConflictCandidate>(results: T[], marks: ConflictMark[][]): T[] {
+  const out = results.slice();
+  const m = marks.slice();
+  for (let guard = 0; guard < out.length * out.length; guard++) {
+    let moved = false;
+    for (let j = 1; j < out.length && !moved; j++) {
+      for (let i = 0; i < j; i++) {
+        const mk = m[j].find(x => x.id === out[i].engram.id);
+        if (mk && mk.newer) {
+          const [r] = out.splice(j, 1); const [mm] = m.splice(j, 1);
+          out.splice(i, 0, r); m.splice(i, 0, mm);
+          moved = true;
+          break;
+        }
+      }
+    }
+    if (!moved) break;
+  }
+  return out;
+}
+
+/** The id of the most recently written memory among those carrying a mark, or null. */
+export function newestConflicting(results: ConflictCandidate[], marks: ConflictMark[][]): string | null {
+  let best: string | null = null, bestMs = -Infinity;
+  results.forEach((r, i) => {
+    if (marks[i].length === 0) return;
+    const ms = createdMs(r);
+    if (Number.isFinite(ms) && ms > bestMs) { bestMs = ms; best = r.engram.id; }
+  });
+  return best;
+}

package/src/core/embeddings.ts

@@ -18,7 +18,8 @@
  */
 
 import { pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers';
-import { dispatchEmbed, registerInProcessHandlers } from './ml-worker.js';
+import { dispatchEmbed, registerInferenceConfig, registerInProcessHandlers } from './ml-worker.js';
+import type { Lane } from './model-daemon.js';
 import { noteModelLoad } from './write-telemetry.js';
 import { ensureModelCacheDir } from './model-cache.js';
 
@@ -26,6 +27,23 @@ const MODEL_ID = process.env.AWM_EMBED_MODEL ?? 'Xenova/bge-small-en-v1.5';
 const DIMENSIONS = parseInt(process.env.AWM_EMBED_DIMS ?? '384', 10);
 const POOLING = (process.env.AWM_EMBED_POOLING ?? 'mean') as 'cls' | 'mean';
 
+/**
+ * Texts per forward pass (default 8; 0 = all at once). onnxruntime-node's CPU arena grows
+ * to the largest tensor it has run and never shrinks, and attention is quadratic in the
+ * padded length: a 100-memory /memory/write-batch or a 32-engram consolidation backfill
+ * at 512 tokens set a high-water mark the process then kept for life. Chunking bounds it.
+ * A text's vector does not depend on the others in its batch (padding is masked).
+ * See reranker.ts for the measurement.
+ */
+const EMBED_BATCH = (() => {
+  // An explicit 0 disables chunking; anything else invalid falls back to 8 (see reranker.ts).
+  const v = Number(process.env.AWM_EMBED_BATCH?.trim() || NaN);
+  return Number.isInteger(v) && v >= 0 ? v : 8;
+})();
+
+/** The texts-per-pass setting, for the model daemon's background chunking. */
+export const EMBED_BATCH_SIZE = EMBED_BATCH;
+
 // --- In-process fallback (used by tests and crash recovery) ---
 
 let inProcessInstance: FeatureExtractionPipeline | null = null;
@@ -45,21 +63,27 @@ async function loadInProcess(): Promise<FeatureExtractionPipeline> {
   return inProcessInitPromise;
 }
 
-async function inProcessEmbed(args: { texts: string[]; pooling: 'cls' | 'mean'; dimensions: number }): Promise<number[][]> {
+/** Exported with its batch size as a parameter so tests can compare settings in one process. */
+export async function inProcessEmbed(args: { texts: string[]; pooling: 'cls' | 'mean'; dimensions: number }, batch = EMBED_BATCH): Promise<number[][]> {
   const { texts, pooling, dimensions } = args;
   if (texts.length === 0) return [];
   const embedder = await loadInProcess();
-  const result = await embedder(texts, { pooling, normalize: true });
-  const data = result.data as Float32Array;
   const vectors: number[][] = [];
-  for (let i = 0; i < texts.length; i++) {
-    vectors.push(Array.from(data.slice(i * dimensions, (i + 1) * dimensions)));
+  const size = batch > 0 ? batch : texts.length;
+  for (let b = 0; b < texts.length; b += size) {
+    const chunk = texts.slice(b, b + size);
+    const result = await embedder(chunk, { pooling, normalize: true });
+    const data = result.data as Float32Array;
+    for (let i = 0; i < chunk.length; i++) {
+      vectors.push(Array.from(data.slice(i * dimensions, (i + 1) * dimensions)));
+    }
   }
   return vectors;
 }
 
 // Register the in-process handler with the pool (used in test mode and as fallback)
-registerInProcessHandlers({ embed: inProcessEmbed });
+registerInProcessHandlers({ embed: (args) => inProcessEmbed(args) });
+registerInferenceConfig({ embedModel: MODEL_ID, embedDims: DIMENSIONS, embedPooling: POOLING, embedBatch: EMBED_BATCH });
 
 // --- Public API ---
 
@@ -85,11 +109,12 @@ export async function embed(text: string): Promise<number[]> {
 /**
  * Generate embeddings for multiple texts in a batch.
  * More efficient than calling embed() in a loop — the worker batches the
- * tokenization + forward pass.
+ * tokenization + forward pass. `lane: 'background'` (consolidation backfill) lets the
+ * shared model daemon run interactive requests ahead of it.
  */
-export async function embedBatch(texts: string[]): Promise<number[][]> {
+export async function embedBatch(texts: string[], opts: { lane?: Lane } = {}): Promise<number[][]> {
   if (texts.length === 0) return [];
-  return dispatchEmbed({ texts, pooling: POOLING, dimensions: DIMENSIONS });
+  return dispatchEmbed({ texts, pooling: POOLING, dimensions: DIMENSIONS }, opts.lane);
 }
 
 /** Get the current embedding model ID (for version tracking in stored embeddings) */

package/src/core/format-recall.ts

@@ -1,25 +1,83 @@
-import type { ActivationResult } from '../types/engram.js';
-
-/**
- * Formats one memory_recall result line for the MCP text response.
- *
- * Extracted out of the inline closure in mcp.ts (0.12.1) so the format itself
- * — specifically, that every result carries its engram id — can be unit
- * tested without booting the MCP server (mcp.ts has a top-level `await` and
- * opens the store as a side effect of import, so it cannot be imported by a
- * test directly).
- *
- * The id is placed right after the score, not at the end of the line: result
- * bodies can be long, and a consumer scanning for `[id: ...]` shouldn't have
- * to read past a paragraph of content to find it.
- */
-export function formatRecallResultLine(r: ActivationResult, index: number): string {
-  const body = r.summary ?? r.engram.content;
-  const chain = r.engram.supersededBy
-    ? ` ⚠ SUPERSEDED by ${r.engram.supersededBy} — treat as historical; recall/fetch the successor before relying on this.`
-    : '';
-  const validity = r.engram.validTo
-    ? ` [valid until ${r.engram.validTo}]`
-    : '';
-  return `${index + 1}. **${r.engram.concept}** (${r.score.toFixed(3)}) [id: ${r.engram.id}]${validity}: ${body}${chain}`;
-}
+import type { ActivationResult } from '../types/engram.js';
+import { validityState } from './validity.js';
+
+/**
+ * Formats one memory_recall result line for the MCP text response.
+ *
+ * Extracted out of the inline closure in mcp.ts (0.12.1) so the format itself
+ * — specifically, that every result carries its engram id — can be unit
+ * tested without booting the MCP server (mcp.ts has a top-level `await` and
+ * opens the store as a side effect of import, so it cannot be imported by a
+ * test directly).
+ *
+ * The id is placed right after the score, not at the end of the line: result
+ * bodies can be long, and a consumer scanning for `[id: ...]` shouldn't have
+ * to read past a paragraph of content to find it.
+ */
+/**
+ * True when Phase 5.5 has already trimmed this engram's body.
+ *
+ * The fade marker is written INTO the content (`consolidation.ts` appends
+ * `'… [faded]'` after slicing to FADE_KEEP_CHARS), which means it is only
+ * visible to a reader who reaches the end of the body. Two things hide it
+ * there: `granularity: 'compact'`/`'auto'`, where the displayed body is a
+ * query-aware 200-char window that will rarely include the tail, and the
+ * plain length of a full body. So the marker is detected on the CONTENT and
+ * rendered in the header, next to `[valid until …]`, where a partial answer
+ * cannot be mistaken for a complete one.
+ *
+ * Matched anywhere rather than at the end because merge-on-reinforce
+ * (`AWM_REINFORCE_MERGE_CONTENT`) can append text after a fade, which would
+ * leave the marker mid-body. A false positive labels a full memory partial,
+ * which is the harmless direction.
+ */
+export function isFaded(content: string): boolean {
+  return content.includes('[faded]');
+}
+
+export function formatRecallResultLine(r: ActivationResult, index: number, now: number = Date.now()): string {
+  const body = r.summary ?? r.engram.content;
+  // Fade retains 7.1% of answer-bearing identifiers while leaving findability
+  // intact (docs/eval-gap-2026-10-11.md §8.1) — 37 of 38 faded engrams still
+  // surface by cue. That combination is the worst possible shape: the result
+  // ranks, reads as an answer, and no longer contains one. The label does not
+  // fix the retrieval, it stops the silent part.
+  const faded = isFaded(r.engram.content)
+    // Fade overwrites the content (consolidation.ts Phase 5.5); no tool can bring the
+    // rest back, so the label says what to do instead.
+    ? ' [faded — body trimmed, the rest is gone; confirm against the source or a newer memory]'
+    : '';
+  const chain = r.engram.supersededBy
+    ? ` ⚠ SUPERSEDED by ${r.engram.supersededBy} — treat as historical; recall/fetch the successor before relying on this.`
+    : '';
+  // Temporal validity (D8). Same decision as ranking (activation.ts Phase 8c,
+  // via core/validity.ts): a memory past its valid_to is down-ranked AND says
+  // so here — "[valid until 2026-01-15]" on a line read in March was the label
+  // that let 482 expired memories in the live store pass as current.
+  const vstate = validityState(r.engram, now);
+  const validity = vstate === 'expired'
+    ? ` ⚠ EXPIRED ${r.engram.validTo} — treat as historical; confirm the current state before relying on this.`
+    : vstate === 'not-yet-valid'
+      ? ` [not yet valid — from ${r.engram.validFrom}]`
+      : r.engram.validTo
+        ? ` [valid until ${r.engram.validTo}]`
+        : '';
+  // The written date on every line (2026-10-19). Two versions of a fact used
+  // to arrive with nothing to say which came first; the prime hook printed an
+  // age, this format printed nothing.
+  const written = writtenDate(r.engram.createdAt);
+  const dated = written ? ` [written ${written}]` : '';
+  // Conflict mark (src/core/conflicts.ts): phrased as a question, because the
+  // detector cannot tell a correction from two facts that share a template.
+  const conflicts = (r.conflictsWith ?? []).map(c =>
+    ` ⚠ POSSIBLE CONFLICT with ${c.id} on a ${c.slot} (this one is ${c.newer ? 'newer' : 'older'}; confirm against the source before stating a value)`,
+  ).join('');
+  return `${index + 1}. **${r.engram.concept}** (${r.score.toFixed(3)}) [id: ${r.engram.id}]${dated}${validity}${faded}: ${body}${chain}${conflicts}`;
+}
+
+/** YYYY-MM-DD from a Date or ISO string; empty when absent or unparseable. */
+export function writtenDate(createdAt: Date | string | null | undefined): string {
+  if (!createdAt) return '';
+  const ms = createdAt instanceof Date ? createdAt.getTime() : Date.parse(createdAt);
+  return Number.isFinite(ms) ? new Date(ms).toISOString().slice(0, 10) : '';
+}