agent-working-memory 0.15.9 → 0.16.0

package/src/core/rerank-window.ts

@@ -1,158 +1,159 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Passage selection for cross-encoder reranking.
- *
- * THE PROBLEM
- * -----------
- * Reranking truncates each passage to a fixed prefix (historically the first
- * 400 chars). That truncation exists for a real reason: cross-encoders pad to
- * the longest passage in the batch, so one 5,000-char memory in a 40-item pool
- * drags every passage to ~512 tokens and costs 3-4x. The reranker is already
- * ~90% of warm recall latency, so "just send everything" is not available.
- *
- * But a PREFIX is the wrong 400 chars. Measured on the live 29.8k store:
- *   - canonical memories median 1,965 chars, 98.7% exceed 400
- *   - the reranker cannot see 78.8% of each canonical memory's vocabulary
- *   - 99.9% of long canonical memories carry identifiers only past char 400
- * And measured on tests/longmem-eval: moving the answer from char 150 to char
- * 700 takes success@1 from 100% to 0%, with the gold's cross-encoder score
- * collapsing 0.986 -> 0.000 while its BM25 score barely moves. The memory stays
- * retrievable and stops being rankable.
- *
- * THE FIX
- * -------
- * Spend the same character budget on the window that actually contains the
- * query's terms, instead of on whatever happens to be at the top of the memory.
- * Cost is unchanged — same budget, same batch padding, same inference — so this
- * buys ranking quality without buying latency.
- *
- * The concept line is always kept: it is short, it is the memory's title, and
- * it is what a human wrote to summarise the thing.
- */
-
-/** Cheap tokenizer for locating query terms inside a passage. */
-function terms(query: string): string[] {
-  const raw = query.toLowerCase().match(/[a-z0-9_][a-z0-9_.\-]{1,}/g) ?? [];
-  const STOP = new Set([
-    'the', 'and', 'for', 'with', 'that', 'this', 'from', 'what', 'where', 'when',
-    'which', 'does', 'did', 'was', 'were', 'are', 'is', 'be', 'to', 'of', 'in',
-    'on', 'at', 'by', 'it', 'as', 'do', 'how', 'why', 'a', 'an', 'or',
-  ]);
-  return Array.from(new Set(raw.filter(t => t.length >= 3 && !STOP.has(t))));
-}
-
-/**
- * Choose the `budget`-char window of `content` densest in query terms.
- * Returns the head of the content when nothing matches — the old behaviour,
- * which is the right fallback: with no query signal there is no reason to
- * prefer any other part of the memory.
- */
-export function densestWindow(content: string, query: string, budget: number): string {
-  if (content.length <= budget) return content;
-
-  const toks = terms(query);
-  if (toks.length === 0) return content.slice(0, budget);
-
-  const lower = content.toLowerCase();
-  const hits: number[] = [];
-  for (const t of toks) {
-    let from = 0;
-    for (;;) {
-      const i = lower.indexOf(t, from);
-      if (i < 0) break;
-      hits.push(i);
-      from = i + t.length;
-    }
-  }
-  if (hits.length === 0) return content.slice(0, budget);
-  hits.sort((a, b) => a - b);
-
-  // Slide a window anchored slightly before each hit; keep the one covering most.
-  let bestStart = 0;
-  let bestCount = -1;
-  for (let i = 0; i < hits.length; i++) {
-    const start = Math.max(0, hits[i] - Math.floor(budget / 5));
-    let count = 0;
-    for (let j = i; j < hits.length && hits[j] - start < budget; j++) count++;
-    if (count > bestCount) { bestCount = count; bestStart = start; }
-  }
-
-  // Snap to a word boundary so the cross-encoder is not handed a split token.
-  let start = bestStart;
-  if (start > 0) {
-    const sp = content.indexOf(' ', start);
-    if (sp >= 0 && sp - start < 40) start = sp + 1;
-  }
-  const slice = content.slice(start, start + budget);
-  return (start > 0 ? '…' : '') + slice + (start + budget < content.length ? '…' : '');
-}
-
-/**
- * Build the passage handed to the cross-encoder for one candidate.
- *
- * `mode`:
- *  - `'prefix'` (default) — legacy behaviour, the first `budget` chars.
- *  - `'query'`  — the `budget`-char window densest in query terms.
- */
-export function buildRerankPassage(
-  concept: string,
-  content: string,
-  query: string,
-  budget: number,
-  mode: 'prefix' | 'query',
-  tags?: string[],
-): string {
-  const body = mode === 'query'
-    ? densestWindow(content, query, budget)
-    : (content.length > budget ? content.slice(0, budget) : content);
-  // Topical tags, when enabled. The cross-encoder decides final order since
-  // phase 9b, and it cannot see tags at all — measured on the live store, 66.2%
-  // of topical tag terms never appear in the body, so that vocabulary is
-  // invisible to the stage that now decides ranking. Appended (not substituted)
-  // and length-capped so it cannot crowd out the content window.
-  const extra = rerankTagText(tags);
-  return extra ? `${concept}: ${body} ${extra}` : `${concept}: ${body}`;
-}
-
-/** Whether topical tags are appended to the rerank passage. Default OFF. */
-export function rerankTagsEnabled(): boolean {
-  return process.env.AWM_RERANK_TAGS === '1';
-}
-
-/** Character budget for the appended tag text. */
-export function rerankTagBudget(): number {
-  const v = Number(process.env.AWM_RERANK_TAGS_LEN ?? 80);
-  return Number.isFinite(v) && v > 0 ? v : 80;
-}
-
-/**
- * Render topical tags as plain terms for the cross-encoder.
- * Only `topic=` / `proj=` / `project=` carry query vocabulary; date/person/
- * ticket tags are identifiers the body usually already contains, and adding
- * them would spend the budget without adding reachable words.
- */
-export function rerankTagText(tags?: string[]): string {
-  if (!rerankTagsEnabled() || !tags || tags.length === 0) return '';
-  const words = new Set<string>();
-  for (const t of tags) {
-    const m = /^(?:topic|proj|project)=(.+)$/i.exec(t);
-    if (!m) continue;
-    for (const w of m[1].toLowerCase().split(/[-_\s]+/)) {
-      if (w.length > 2) words.add(w);
-    }
-  }
-  if (words.size === 0) return '';
-  return `[${[...words].join(' ').slice(0, rerankTagBudget())}]`;
-}
-
-/** Character budget for a rerank passage. */
-export function rerankTruncation(): number {
-  const v = Number(process.env.AWM_RERANK_TRUNC ?? 400);
-  return Number.isFinite(v) && v > 0 ? v : 400;
-}
-
-/** Passage selection mode. Default `prefix` preserves shipped behaviour. */
-export function rerankWindowMode(): 'prefix' | 'query' {
-  return process.env.AWM_RERANK_WINDOW === 'query' ? 'query' : 'prefix';
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Passage selection for cross-encoder reranking.
+ *
+ * THE PROBLEM
+ * -----------
+ * Reranking truncates each passage to a fixed prefix (historically the first
+ * 400 chars). That truncation exists for a real reason: cross-encoders pad to
+ * the longest passage in the batch, so one 5,000-char memory in a 40-item pool
+ * drags every passage to ~512 tokens and costs 3-4x. The reranker is already
+ * 83% of warm recall latency (measured, `npm run profile:recall`), so "just send
+ * everything" is not available.
+ *
+ * But a PREFIX is the wrong 400 chars. Measured on the live 29.8k store:
+ *   - canonical memories median 1,965 chars, 98.7% exceed 400
+ *   - the reranker cannot see 78.8% of each canonical memory's vocabulary
+ *   - 99.9% of long canonical memories carry identifiers only past char 400
+ * And measured on tests/longmem-eval: moving the answer from char 150 to char
+ * 700 takes success@1 from 100% to 0%, with the gold's cross-encoder score
+ * collapsing 0.986 -> 0.000 while its BM25 score barely moves. The memory stays
+ * retrievable and stops being rankable.
+ *
+ * THE FIX
+ * -------
+ * Spend the same character budget on the window that actually contains the
+ * query's terms, instead of on whatever happens to be at the top of the memory.
+ * Cost is unchanged — same budget, same batch padding, same inference — so this
+ * buys ranking quality without buying latency.
+ *
+ * The concept line is always kept: it is short, it is the memory's title, and
+ * it is what a human wrote to summarise the thing.
+ */
+
+/** Cheap tokenizer for locating query terms inside a passage. */
+function terms(query: string): string[] {
+  const raw = query.toLowerCase().match(/[a-z0-9_][a-z0-9_.\-]{1,}/g) ?? [];
+  const STOP = new Set([
+    'the', 'and', 'for', 'with', 'that', 'this', 'from', 'what', 'where', 'when',
+    'which', 'does', 'did', 'was', 'were', 'are', 'is', 'be', 'to', 'of', 'in',
+    'on', 'at', 'by', 'it', 'as', 'do', 'how', 'why', 'a', 'an', 'or',
+  ]);
+  return Array.from(new Set(raw.filter(t => t.length >= 3 && !STOP.has(t))));
+}
+
+/**
+ * Choose the `budget`-char window of `content` densest in query terms.
+ * Returns the head of the content when nothing matches — the old behavior,
+ * which is the right fallback: with no query signal there is no reason to
+ * prefer any other part of the memory.
+ */
+export function densestWindow(content: string, query: string, budget: number): string {
+  if (content.length <= budget) return content;
+
+  const toks = terms(query);
+  if (toks.length === 0) return content.slice(0, budget);
+
+  const lower = content.toLowerCase();
+  const hits: number[] = [];
+  for (const t of toks) {
+    let from = 0;
+    for (;;) {
+      const i = lower.indexOf(t, from);
+      if (i < 0) break;
+      hits.push(i);
+      from = i + t.length;
+    }
+  }
+  if (hits.length === 0) return content.slice(0, budget);
+  hits.sort((a, b) => a - b);
+
+  // Slide a window anchored slightly before each hit; keep the one covering most.
+  let bestStart = 0;
+  let bestCount = -1;
+  for (let i = 0; i < hits.length; i++) {
+    const start = Math.max(0, hits[i] - Math.floor(budget / 5));
+    let count = 0;
+    for (let j = i; j < hits.length && hits[j] - start < budget; j++) count++;
+    if (count > bestCount) { bestCount = count; bestStart = start; }
+  }
+
+  // Snap to a word boundary so the cross-encoder is not handed a split token.
+  let start = bestStart;
+  if (start > 0) {
+    const sp = content.indexOf(' ', start);
+    if (sp >= 0 && sp - start < 40) start = sp + 1;
+  }
+  const slice = content.slice(start, start + budget);
+  return (start > 0 ? '…' : '') + slice + (start + budget < content.length ? '…' : '');
+}
+
+/**
+ * Build the passage handed to the cross-encoder for one candidate.
+ *
+ * `mode`:
+ *  - `'prefix'` (default) — legacy behavior, the first `budget` chars.
+ *  - `'query'`  — the `budget`-char window densest in query terms.
+ */
+export function buildRerankPassage(
+  concept: string,
+  content: string,
+  query: string,
+  budget: number,
+  mode: 'prefix' | 'query',
+  tags?: string[],
+): string {
+  const body = mode === 'query'
+    ? densestWindow(content, query, budget)
+    : (content.length > budget ? content.slice(0, budget) : content);
+  // Topical tags, when enabled. The cross-encoder decides final order since
+  // phase 9b, and it cannot see tags at all — measured on the live store, 66.2%
+  // of topical tag terms never appear in the body, so that vocabulary is
+  // invisible to the stage that now decides ranking. Appended (not substituted)
+  // and length-capped so it cannot crowd out the content window.
+  const extra = rerankTagText(tags);
+  return extra ? `${concept}: ${body} ${extra}` : `${concept}: ${body}`;
+}
+
+/** Whether topical tags are appended to the rerank passage. Default OFF. */
+export function rerankTagsEnabled(): boolean {
+  return process.env.AWM_RERANK_TAGS === '1';
+}
+
+/** Character budget for the appended tag text. */
+export function rerankTagBudget(): number {
+  const v = Number(process.env.AWM_RERANK_TAGS_LEN ?? 80);
+  return Number.isFinite(v) && v > 0 ? v : 80;
+}
+
+/**
+ * Render topical tags as plain terms for the cross-encoder.
+ * Only `topic=` / `proj=` / `project=` carry query vocabulary; date/person/
+ * ticket tags are identifiers the body usually already contains, and adding
+ * them would spend the budget without adding reachable words.
+ */
+export function rerankTagText(tags?: string[]): string {
+  if (!rerankTagsEnabled() || !tags || tags.length === 0) return '';
+  const words = new Set<string>();
+  for (const t of tags) {
+    const m = /^(?:topic|proj|project)=(.+)$/i.exec(t);
+    if (!m) continue;
+    for (const w of m[1].toLowerCase().split(/[-_\s]+/)) {
+      if (w.length > 2) words.add(w);
+    }
+  }
+  if (words.size === 0) return '';
+  return `[${[...words].join(' ').slice(0, rerankTagBudget())}]`;
+}
+
+/** Character budget for a rerank passage. */
+export function rerankTruncation(): number {
+  const v = Number(process.env.AWM_RERANK_TRUNC ?? 400);
+  return Number.isFinite(v) && v > 0 ? v : 400;
+}
+
+/** Passage selection mode. Default `prefix` preserves shipped behavior. */
+export function rerankWindowMode(): 'prefix' | 'query' {
+  return process.env.AWM_RERANK_WINDOW === 'query' ? 'query' : 'prefix';
+}

package/src/core/reranker.ts

@@ -3,7 +3,8 @@
 /**
  * Cross-Encoder Re-Ranker - scores (query, passage) pairs for relevance.
  *
- * Uses Xenova/ms-marco-MiniLM-L-6-v2 (~22MB ONNX) trained on MS-MARCO
+ * Uses Xenova/ms-marco-MiniLM-L-6-v2 (91MB ONNX at the fp32 default; the 23MB
+ * quantized file is what AWM_RERANKER_DTYPE=q8 loads) trained on MS-MARCO
  * passage ranking. Unlike bi-encoders, cross-encoders see both query and
  * passage together via full attention - much better at judging if a
  * passage actually answers a question.
@@ -24,6 +25,26 @@ import { ensureModelCacheDir } from './model-cache.js';
 const DEFAULT_MODEL = 'Xenova/ms-marco-MiniLM-L-6-v2';
 const MODEL_ID = process.env.AWM_RERANKER_MODEL || DEFAULT_MODEL;
 
+/**
+ * Weight precision for the cross-encoder. fp32 is the shipped default and the
+ * only value any published number was measured at.
+ *
+ * It is exposed because the cross-encoder is 83% of warm recall latency
+ * (measured, `npm run profile:recall`), which makes precision the largest
+ * single latency lever in the system — and an unmeasurable one while it was a
+ * literal. RE-MEASURED 2026-10-09 on the pipeline that ships: 'q8' cuts total
+ * recall latency 26-33% across three suites, for ONE QUERY in 450 — identifier
+ * success@1 unchanged at 93.0%, topic 92.2% -> 92.0%. Correct abstention is
+ * unmoved on all three suites; success@5 is unmoved on both private suites and
+ * moves +0.5pp on the public corpus, inside its 4pp seed-noise floor. It is deterministic (two runs agree
+ * on all 450 queries to 1e-6), and because no model is bundled it SHRINKS the
+ * first-run fetch: the ONNX file it loads is 23MB against fp32's 91MB. 'q4' is dominated: equal
+ * accuracy, only -3% latency, 6.1s cold start against fp32's 1.6s. The default
+ * is untouched because it is a product decision, not because the cost is
+ * unknown; see docs/recall-latency.md.
+ */
+const DTYPE = (process.env.AWM_RERANKER_DTYPE || 'fp32') as 'fp32' | 'fp16' | 'q8' | 'int8' | 'uint8' | 'q4';
+
 // --- In-process fallback ---
 
 let tokenizer: PreTrainedTokenizer | null = null;
@@ -36,8 +57,8 @@ async function ensureLoaded(): Promise<void> {
   initPromise = (async () => {
     ensureModelCacheDir();
     tokenizer = await AutoTokenizer.from_pretrained(MODEL_ID);
-    model = await AutoModelForSequenceClassification.from_pretrained(MODEL_ID, { dtype: 'fp32' });
-    console.error(`Re-ranker model loaded in-process: ${MODEL_ID}`);
+    model = await AutoModelForSequenceClassification.from_pretrained(MODEL_ID, { dtype: DTYPE });
+    console.error(`Re-ranker model loaded in-process: ${MODEL_ID} (${DTYPE})`);
   })();
   return initPromise;
 }

package/src/core/salience.ts

@@ -246,7 +246,7 @@ export function evaluateSalience(
     case 'observation': break;
   }
   // Signal-weakness gate. The novelty score alone (~0.45 for fresh content)
-  // would clear the active threshold (0.4), so any labelled event with no
+  // would clear the active threshold (0.4), so any labeled event with no
   // backing numerical signals lands as 'active' regardless of the label's
   // semantics. That's wrong for friction/causal: those types describe events
   // that *happened to the agent* and benefit from explicit intensity signals.