agent-working-memory 0.17.0 → 0.18.1

package/src/core/rerank2.ts

@@ -1,82 +1,143 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Second-stage reordering — "rerank the rerank".
- *
- * THE PROBLEM
- * -----------
- * Phase 7 blends the cross-encoder's judgement with the composite score:
- *
- *     score = compositeWeight * composite + rerankWeight * rerankerScore
- *
- * with `rerankWeight` capped at 0.7, so `composite` always keeps at least 30%
- * of the vote on final ordering. Composite carries decay, Hebbian and salience
- * terms — useful for deciding WHICH candidates deserve consideration, but a
- * poor judge of which one actually answers the question.
- *
- * Measured on LoCoMo (616 answerable probes, tests/rerank2-eval): the blend
- * disagrees with the cross-encoder about which item deserves rank 1 on **38.6%**
- * of queries. Where that disagreement is decidable — one of the two is the gold
- * evidence — the **cross-encoder is right 77% of the time** (61 vs 18).
- *
- * THE FIX
- * -------
- * Re-sort only the final returned window by `rerankerScore` alone. Simulated
- * gain: **+8.0pp success@1** (39.1% -> 47.1%), fixing 61 queries and breaking
- * 12, with every category improving.
- *
- * WHY THIS IS SAFE
- * ----------------
- * Applied AFTER the channel-agreement gate, AFTER computeRecallConfidence, and
- * AFTER the requireConfidence check. Those read rerankerScore maxima/margins and
- * the score distribution. Reordering a window afterwards changes neither its
- * membership nor any score, so **adversarial abstention is provably
- * unaffected**. Retuning `rerankWeight` inside phase 7 would NOT have that
- * property — it shifts `item.score`, hence which items clear `minScore`, which
- * is exactly what cost adversarial 73.4->71.0 when the pool was last widened.
- *
- * Margin-guarded variants were simulated and are strictly worse: gating on a
- * >0.15 reranker margin cuts breakage 12->1 but also cuts fixes 61->17.
- */
-
-/** Minimal shape this needs — anything carrying a cross-encoder score. */
-export interface RerankScored {
-  phaseScores: { rerankerScore: number };
-}
-
-/**
- * Re-sort the first `k` entries of `ranked` by descending `rerankerScore`,
- * leaving the tail untouched. Returns a new array; never mutates the input.
- *
- * Returns `ranked` unchanged when reordering would be unsound:
- *  - `k <= 1`, or fewer than 2 entries to order
- *  - any entry in the window has `rerankerScore <= 0`, which means the
- *    cross-encoder did not score it (skipped, failed, or timed out). Sorting
- *    on a zero would scramble an otherwise sound composite ordering — the
- *    reranker is wrapped in try/catch and a 10s timeout upstream, so this is a
- *    real path, not a theoretical one.
- */
-export function reorderByReranker<T extends RerankScored>(ranked: T[], k: number): T[] {
-  if (k <= 1 || ranked.length <= 1) return ranked;
-
-  const window = Math.min(k, ranked.length);
-  if (window <= 1) return ranked;
-
-  const head = ranked.slice(0, window);
-  for (const r of head) {
-    if (!(r.phaseScores.rerankerScore > 0)) return ranked;  // also catches NaN
-  }
-
-  const sorted = head.slice().sort((a, b) => b.phaseScores.rerankerScore - a.phaseScores.rerankerScore);
-  return sorted.concat(ranked.slice(window));
-}
-
-/** Window size for the second stage. */
-export function rerank2WindowSize(): number {
-  return Number(process.env.AWM_RERANK2_K ?? 10);
-}
-
-/** Whether the second stage is enabled. Default OFF pending the tracer verdict. */
-export function rerank2Enabled(): boolean {
-  return process.env.AWM_RERANK2 === '1';
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Second-stage reordering — "rerank the rerank".
+ *
+ * THE PROBLEM
+ * -----------
+ * Phase 7 blends the cross-encoder's judgement with the composite score:
+ *
+ *     score = compositeWeight * composite + rerankWeight * rerankerScore
+ *
+ * with `rerankWeight` capped at 0.7, so `composite` always keeps at least 30%
+ * of the vote on final ordering. Composite carries decay, Hebbian and salience
+ * terms — useful for deciding WHICH candidates deserve consideration, but a
+ * poor judge of which one actually answers the question.
+ *
+ * Measured on LoCoMo (616 answerable probes, tests/rerank2-eval): the blend
+ * disagrees with the cross-encoder about which item deserves rank 1 on **38.6%**
+ * of queries. Where that disagreement is decidable — one of the two is the gold
+ * evidence — the **cross-encoder is right 77% of the time** (61 vs 18).
+ *
+ * THE FIX
+ * -------
+ * Re-sort only the final returned window by `rerankerScore` alone. Simulated
+ * gain: **+8.0pp success@1** (39.1% -> 47.1%), fixing 61 queries and breaking
+ * 12, with every category improving.
+ *
+ * WHY THIS IS SAFE
+ * ----------------
+ * Applied AFTER the channel-agreement gate, AFTER computeRecallConfidence, and
+ * AFTER the requireConfidence check. Those read rerankerScore maxima/margins and
+ * the score distribution. Reordering a window afterwards changes neither its
+ * membership nor any score, so **adversarial abstention is provably
+ * unaffected**. Retuning `rerankWeight` inside phase 7 would NOT have that
+ * property — it shifts `item.score`, hence which items clear `minScore`, which
+ * is exactly what cost adversarial 73.4->71.0 when the pool was last widened.
+ *
+ * Margin-guarded variants were simulated and are strictly worse: gating on a
+ * >0.15 reranker margin cuts breakage 12->1 but also cuts fixes 61->17.
+ */
+
+/** Minimal shape this needs — anything carrying a cross-encoder score, and
+ *  optionally the stale penalty Phase 8c applied to it (see below). */
+export interface RerankScored {
+  phaseScores: { rerankerScore: number; stalePenalty?: number };
+  /** The Phase 7 blended score (composite + reranker). Carries decay, so recency. */
+  score?: number;
+}
+
+/**
+ * NEAR-TIES (0.18.1, found by MWA when it moved to rerank2-on defaults)
+ * -----------------------------------------------------------------------
+ * The cross-encoder judges relevance to the query and nothing else. Three
+ * same-topic facts written in October, December and March ("the book club
+ * chose a fantasy novel / science fiction / a mystery") score within a few
+ * hundredths of each other for "what did the book club most recently
+ * choose", and a sort by reranker score alone put the newest LAST. The blend
+ * carries decay, so it knows which is newest; replacing it outright threw
+ * that away exactly where the cross-encoder has nothing to say.
+ *
+ * The first fix tried was a score epsilon: within `AWM_RERANK2_TIE_EPS` the
+ * blended score decides. MEASURED at 0.03 on the private snapshot (2026-10-19):
+ * identifier s@1 93.0% -> 78.7%, topic 92.2% -> 84.4%. The cross-encoder's
+ * scores saturate near 1.0 for the top candidates, so hundredths separate most
+ * top-2 pairs and are informative there; the blend loses to it 77% of the time
+ * on disagreements. So the epsilon DEFAULTS TO 0 (off) and exists only for
+ * experiments. The recency rule lives where it belongs instead: among results
+ * the conflict detector marks as two versions of one fact, the newest goes
+ * first (conflicts.ts `newestFirstAmongConflicts`, applied in activation.ts).
+ * That cannot touch a suite whose golds are single facts.
+ */
+export function rerank2TieEpsilon(): number {
+  const v = Number(process.env.AWM_RERANK2_TIE_EPS ?? 0);
+  return Number.isFinite(v) && v >= 0 ? v : 0;
+}
+
+/**
+ * THE STALE-SUPPRESSION HOLE (found 2026-10-19, MWA evaluation probe)
+ * --------------------------------------------------------------------
+ * Phase 8c multiplies a superseded (or, since 2026-10-19, expired) memory's
+ * `score` by 0.15 so its successor dominates. This stage sorted the window by
+ * raw `rerankerScore`, which never carried that penalty — so with
+ * `AWM_RERANK2=1` (what `awm setup` writes into every Claude Code install) a
+ * superseded memory came back at rank 1 ABOVE its replacement whenever the
+ * cross-encoder liked its wording better. The supersession test ran with the
+ * reranker off, so nothing caught it. `tests/core/rerank2.test.ts` now pins the
+ * corrected behaviour: the sort key is `rerankerScore × stalePenalty`, the same
+ * factor Phase 8c used, so stale rows sort below current ones here exactly as
+ * they do in the blend. The soundness guards below are unchanged.
+ */
+export function rerankSortKey(r: RerankScored): number {
+  return r.phaseScores.rerankerScore * (r.phaseScores.stalePenalty ?? 1);
+}
+
+/**
+ * Re-sort the first `k` entries of `ranked` by descending `rerankerScore`,
+ * leaving the tail untouched. Returns a new array; never mutates the input.
+ *
+ * Returns `ranked` unchanged when reordering would be unsound:
+ *  - `k <= 1`, or fewer than 2 entries to order
+ *  - any entry in the window has `rerankerScore <= 0`, which means the
+ *    cross-encoder did not score it (skipped, failed, or timed out). Sorting
+ *    on a zero would scramble an otherwise sound composite ordering — the
+ *    reranker is wrapped in try/catch and a 10s timeout upstream, so this is a
+ *    real path, not a theoretical one.
+ */
+export function reorderByReranker<T extends RerankScored>(ranked: T[], k: number): T[] {
+  if (k <= 1 || ranked.length <= 1) return ranked;
+
+  const window = Math.min(k, ranked.length);
+  if (window <= 1) return ranked;
+
+  const head = ranked.slice(0, window);
+  for (const r of head) {
+    if (!(r.phaseScores.rerankerScore > 0)) return ranked;  // also catches NaN
+  }
+
+  const eps = rerank2TieEpsilon();
+  const sorted = head.slice().sort((a, b) => {
+    const d = rerankSortKey(b) - rerankSortKey(a);
+    if (eps > 0 && Math.abs(d) < eps) return (b.score ?? 0) - (a.score ?? 0);  // experiment only; see above
+    return d;
+  });
+  return sorted.concat(ranked.slice(window));
+}
+
+/** Window size for the second stage. */
+export function rerank2WindowSize(): number {
+  return Number(process.env.AWM_RERANK2_K ?? 10);
+}
+
+/**
+ * Whether the second stage is enabled. Default ON since 2026-10-19; set
+ * `AWM_RERANK2=0` to disable. It was opt-in (`=1`) from 2026-08-24, injected
+ * into every config `awm setup` wrote — and a config that did not carry the
+ * three strings ran degraded for 47 days without anyone noticing, because
+ * degraded recall looks exactly like working recall. The measured-good
+ * configuration is now what the code does when nothing is set; the env var
+ * is the escape hatch, like the other diagnostics knobs.
+ */
+export function rerank2Enabled(): boolean {
+  return process.env.AWM_RERANK2 !== '0';
+}

package/src/core/reranker.ts

@@ -19,7 +19,7 @@ import {
   type PreTrainedTokenizer,
   type PreTrainedModel,
 } from '@huggingface/transformers';
-import { dispatchRerank, registerInProcessHandlers } from './ml-worker.js';
+import { dispatchRerank, registerInferenceConfig, registerInProcessHandlers } from './ml-worker.js';
 import { ensureModelCacheDir } from './model-cache.js';
 
 const DEFAULT_MODEL = 'Xenova/ms-marco-MiniLM-L-6-v2';
@@ -67,11 +67,60 @@ function sigmoid(x: number): number {
   return 1 / (1 + Math.exp(-x));
 }
 
-async function inProcessRerank(args: { query: string; passages: string[] }): Promise<Array<{ index: number; score: number }>> {
-  const { query, passages } = args;
-  if (passages.length === 0) return [];
-  await ensureLoaded();
+/**
+ * Input-shape caps for the cross-encoder. They exist for MEMORY, and one of them also
+ * fixes RANKING.
+ *
+ * onnxruntime-node keeps a CPU memory arena per model that grows to the largest tensor
+ * it has ever run and never shrinks. A cross-encoder's attention tensor is
+ * batch x heads x seq x seq floats, so its size is quadratic in the padded pair length.
+ * Measured 2026-10-16 on AWM 0.17.0: six Claude Code sessions held 13.2 GB, JS heap flat
+ * at ~85 MB, and one process reranking 24 long pairs kept ~1.75 GB after going idle.
+ * The shapes come from the prime hook, which recalls with the WHOLE user prompt (pastes
+ * included), and from recall's 24-40 passage pool: 40 pairs at 512 tokens make one
+ * attention tensor of 40 x 12 x 512 x 512 x 4 B = ~500 MB.
+ *
+ * - AWM_RERANK_BATCH (default 8): passages are scored in chunks. A pair's score depends
+ *   only on that pair (padding is masked), so this changes memory, not order.
+ * - AWM_RERANK_QUERY_TOKENS (default 128): a longer query keeps its first and last
+ *   halves. transformers.js truncates a too-long pair by cutting tokens off the END,
+ *   which is the passage: before this cap, a ~510-token query left the passage no tokens
+ *   at all, and every memory was scored against the query alone. Passages are already
+ *   capped at ~400 chars (rerank-window.ts), so a 128-token query typically keeps a
+ *   pair under ~260 tokens (more for CJK text or a raised AWM_RERANK_TRUNC).
+ *
+ * An explicit 0 disables a cap. Anything else that is not a non-negative integer (empty,
+ * 'off', -1) falls back to the default, as AWM_RERANK_TRUNC does: a typo must not quietly
+ * bring back the unbounded shape.
+ */
+function shapeCap(name: string, fallback: number): number {
+  const v = Number(process.env[name]?.trim() || NaN);
+  return Number.isInteger(v) && v >= 0 ? v : fallback;
+}
+const RERANK_BATCH = shapeCap('AWM_RERANK_BATCH', 8);
+const RERANK_QUERY_TOKENS = shapeCap('AWM_RERANK_QUERY_TOKENS', 128);
 
+/**
+ * The query the cross-encoder sees: unchanged when it fits the cap, else its first and
+ * last halves. Both ends, because a pasted prompt puts the question either before the
+ * paste or after it. Special tokens typed into a long query ([SEP], [UNK]) are dropped by
+ * the decode; a query under the cap passes through untouched.
+ */
+export function capRerankQuery(tok: PreTrainedTokenizer, query: string, maxTokens = RERANK_QUERY_TOKENS): string {
+  if (maxTokens <= 0) return query;
+  const ids = tok.encode(query, { add_special_tokens: false });
+  if (ids.length <= maxTokens) return query;
+  const head = Math.ceil(maxTokens / 2);
+  const tail = maxTokens - head;
+  const decode = (part: number[]) => tok.decode(part, { skip_special_tokens: true, clean_up_tokenization_spaces: true });
+  // A tail that starts mid-word decodes with a leading '##' continuation marker, which
+  // would re-encode as two stray '#' tokens.
+  return tail > 0
+    ? `${decode(ids.slice(0, head))} ${decode(ids.slice(ids.length - tail)).replace(/^##/, '')}`
+    : decode(ids.slice(0, head));
+}
+
+async function scoreChunk(query: string, passages: string[], offset: number): Promise<Array<{ index: number; score: number }>> {
   // Batch path
   try {
     const queries = passages.map(() => query);
@@ -94,9 +143,8 @@ async function inProcessRerank(args: { query: string; passages: string[] }): Pro
     const results: Array<{ index: number; score: number }> = [];
     for (let i = 0; i < passages.length; i++) {
       const rawLogit = Number(data[i] ?? 0);
-      results.push({ index: i, score: sigmoid(rawLogit) });
+      results.push({ index: offset + i, score: sigmoid(rawLogit) });
     }
-    results.sort((a, b) => b.score - a.score);
     return results;
   } catch {
     // Per-passage fallback (the original 0.7.13 path)
@@ -113,18 +161,37 @@ async function inProcessRerank(args: { query: string; passages: string[] }): Pro
         const output = await model!(inputs);
         const logits = output.logits ?? output.last_hidden_state;
         const rawLogit = logits.data[0] as number;
-        results.push({ index: i, score: sigmoid(rawLogit) });
+        results.push({ index: offset + i, score: sigmoid(rawLogit) });
       } catch {
-        results.push({ index: i, score: 0 });
+        results.push({ index: offset + i, score: 0 });
       }
     }
-    results.sort((a, b) => b.score - a.score);
     return results;
   }
 }
 
+/** Exported with its caps as parameters so tests can compare settings in one process. */
+export async function inProcessRerank(
+  args: { query: string; passages: string[] },
+  caps: { batch?: number; queryTokens?: number } = {},
+): Promise<Array<{ index: number; score: number }>> {
+  const { passages } = args;
+  if (passages.length === 0) return [];
+  await ensureLoaded();
+  const query = capRerankQuery(tokenizer!, args.query, caps.queryTokens ?? RERANK_QUERY_TOKENS);
+  const batch = caps.batch ?? RERANK_BATCH;
+  const size = batch > 0 ? batch : passages.length;
+  const results: Array<{ index: number; score: number }> = [];
+  for (let b = 0; b < passages.length; b += size) {
+    results.push(...await scoreChunk(query, passages.slice(b, b + size), b));
+  }
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}
+
 // Register the in-process handler with the pool
-registerInProcessHandlers({ rerank: inProcessRerank });
+registerInProcessHandlers({ rerank: (args) => inProcessRerank(args) });
+registerInferenceConfig({ rerankModel: MODEL_ID, rerankDtype: DTYPE, rerankBatch: RERANK_BATCH, rerankQueryTokens: RERANK_QUERY_TOKENS });
 
 // --- Public API ---
 

package/src/core/trust.ts

@@ -0,0 +1,65 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Trust tiers on writes and memories, and the one rule the write pipeline
+ * applies with them: a merge or a replacement must never RAISE the trust of
+ * text, and must never retire a more-trusted memory on the word of a
+ * less-trusted write.
+ *
+ * Found by MWA BL-17 (2026-10-14/15), five isolated-review rounds with
+ * probes: the pipeline merged a write into an existing memory on concept
+ * equality and the merged engram KEPT THE OLD ENGRAM'S TAGS — so a poisoned
+ * skill merged into a clean one came back trust=medium and primeable; a
+ * planted untrusted decoy under the same concept let a poisoned near-copy
+ * merge into the trusted fact; an archived trusted fact was revived with
+ * poisoned text merged in; and an R3 "correction" (eventType surprise) from
+ * untrusted text retired a trusted memory. MWA works around all of it in its
+ * own wrapper. Any other client writing mixed-trust content was exposed.
+ *
+ * AWM has no trust model of its own, and this does not add one. It reads the
+ * tag MWA's memory spine already writes (`trust=<tier>`) and refuses the
+ * dangerous direction. The write is still stored — as its own engram, with
+ * its own tags — so nothing is lost and the conflict mark can say the two
+ * disagree. Untagged writes and memories are unaffected: the rule only fires
+ * when the write is EXPLICITLY untrusted, or when both sides carry a tier and
+ * the write's is lower.
+ */
+
+/** Ordered tiers; higher is more trusted. */
+const TIERS: Record<string, number> = {
+  untrusted: 0, none: 0, quarantine: 0,
+  low: 1,
+  medium: 2, med: 2,
+  high: 3, trusted: 3, verified: 3, owner: 3,
+};
+
+/** The tier a `trust=<tier>` tag declares, or null when there is none. */
+export function trustTier(tags: readonly string[] | null | undefined): number | null {
+  if (!tags) return null;
+  let found: number | null = null;
+  for (const t of tags) {
+    const m = /^trust=([a-z]+)$/i.exec(t.trim());
+    if (!m) continue;
+    const v = TIERS[m[1].toLowerCase()];
+    if (v === undefined) continue;
+    // Several tags: the lowest wins — a memory is as trusted as its least trusted label.
+    found = found === null ? v : Math.min(found, v);
+  }
+  return found;
+}
+
+/**
+ * True when `writeTags` must not merge into, supersede or revive a memory
+ * carrying `targetTags`.
+ */
+export function mergeBlockedByTrust(
+  writeTags: readonly string[] | null | undefined,
+  targetTags: readonly string[] | null | undefined,
+): boolean {
+  const w = trustTier(writeTags);
+  if (w === null) return false;                  // untagged write: no rule
+  const t = trustTier(targetTags);
+  if (w === 0) return t === null || t > 0;       // explicitly untrusted: only into untrusted
+  if (t === null) return false;                  // tagged write, untagged target: no rule
+  return w < t;
+}

package/src/core/validity.ts

@@ -0,0 +1,47 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Temporal validity (D8) — the one place that decides whether a memory's
+ * `valid_from` / `valid_to` window holds at a given moment.
+ *
+ * Until 2026-10-19 nothing read these fields except the two recall formatters,
+ * which printed `[valid until …]` on expired memories exactly as on current
+ * ones. The live store was serving 482 memories past their `valid_to` as
+ * current (97 active, 385 archived). The guidance given to agents ("use
+ * `valid_to` … so the memory expires") promised behaviour the code did not have.
+ *
+ * Ranking (activation.ts Phase 8c), the MCP recall format and the prime hook
+ * all go through here so they cannot disagree about what "expired" means.
+ */
+
+export type ValidityState = 'current' | 'expired' | 'not-yet-valid';
+
+/** The fields this needs — any engram-shaped object qualifies. */
+export interface TemporallyBounded {
+  validFrom?: string | null;
+  validTo?: string | null;
+}
+
+/**
+ * A date-only `valid_to` ("2026-01-15") means "through that day", so it is
+ * compared against the END of that day in UTC. A full datetime is taken as
+ * written. An unparseable value is ignored: a bad bound must not hide a memory.
+ */
+function boundMs(value: string, endOfDay: boolean): number {
+  const t = Date.parse(value);
+  if (!Number.isFinite(t)) return NaN;
+  const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(value.trim());
+  return dateOnly && endOfDay ? t + 86_400_000 - 1 : t;
+}
+
+export function validityState(e: TemporallyBounded, now: number = Date.now()): ValidityState {
+  if (e.validTo) {
+    const until = boundMs(e.validTo, true);
+    if (Number.isFinite(until) && now > until) return 'expired';
+  }
+  if (e.validFrom) {
+    const from = boundMs(e.validFrom, false);
+    if (Number.isFinite(from) && now < from) return 'not-yet-valid';
+  }
+  return 'current';
+}