agent-working-memory 0.13.1 → 0.14.1

package/src/core/rerank2.ts

@@ -0,0 +1,82 @@
+// 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';
+}

package/src/core/retrieval-text.ts

@@ -0,0 +1,82 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Derived retrieval text — the machine-facing view of a memory.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Measured on the live 11,294-engram store: 66.2% of topical tag terms never
+ * appear in the memory body, and 94.3% of tagged memories are missing at least
+ * one of their own topical terms. Tags are indexed by BM25 only — the embedding
+ * is built from `concept + content` (write-pipeline.ts) and so is the
+ * cross-encoder rerank passage (activation.ts). So that vocabulary is invisible
+ * to two of the three retrieval channels, including the one that decides final
+ * ordering since phase 9b.
+ *
+ * The consequence, observed on a real memory: "private plan memory peaked 88%,
+ * scale P1v3 -> P2v3" was NOT in the top 40 candidates for "azure app service
+ * plan capacity increase internal application". Its body contains no "azure",
+ * no "capacity", no "app service plan" — only `topic=azure` as a tag.
+ *
+ * THE SHAPE THAT MATTERS
+ * ----------------------
+ * This builds a DERIVED text used for embedding and reranking. It does NOT
+ * mutate `content`. That distinction is the whole design:
+ *
+ *   - AWM's model slots have always been ADDITIVE — the embedder, expander and
+ *     reranker score or expand, they never rewrite what was stored. Appending
+ *     tag terms into the body would break that invariant, and a normaliser that
+ *     silently edits stored memories is unrecoverable if it is wrong.
+ *   - A derived view is recomputable. If the rule turns out to be bad, re-derive
+ *     and re-embed; the source of truth was never touched.
+ *   - And it can be BACKFILLED over the existing corpus, which body-only fixes
+ *     (write-time guidance, future writes) cannot reach. 7,350 memories are
+ *     already wrong.
+ *
+ * Only `topic=` / `proj=` / `project=` are included. Date, person and ticket
+ * tags are identifiers the body usually already carries, so adding them spends
+ * budget without adding reachable words.
+ */
+
+/** Whether the derived retrieval text includes tag vocabulary. Default OFF. */
+export function retrievalTextEnabled(): boolean {
+  return process.env.AWM_RETRIEVAL_TEXT === '1';
+}
+
+/**
+ * Extract the topical vocabulary a future question is likely to use.
+ * Deduplicated and lowercased; order follows first appearance so the output is
+ * deterministic for a given tag list (important: a non-deterministic embedding
+ * input would make re-embedding produce different vectors for the same memory).
+ */
+export function topicalTerms(tags?: string[]): string[] {
+  if (!tags || tags.length === 0) return [];
+  const out: string[] = [];
+  const seen = 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 && !seen.has(w)) { seen.add(w); out.push(w); }
+    }
+  }
+  return out;
+}
+
+/**
+ * Build the text used for EMBEDDING a memory.
+ *
+ * When disabled this returns exactly `concept + ' ' + content`, byte-identical
+ * to the historical input — so leaving the flag off cannot change a single
+ * stored vector.
+ */
+export function buildRetrievalText(concept: string, content: string, tags?: string[]): string {
+  const base = `${concept} ${content}`;
+  if (!retrievalTextEnabled()) return base;
+  const terms = topicalTerms(tags);
+  if (terms.length === 0) return base;
+  // Appended at the END. The embedding model truncates beyond its context
+  // window, and the head of the content is what anchors the topic — putting tag
+  // terms first would displace the memory's actual subject in the vector.
+  return `${base} ${terms.join(' ')}`;
+}

package/src/core/temporal-query.ts

@@ -0,0 +1,193 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Temporal expressions in a recall query.
+ *
+ * THE PROBLEM
+ * -----------
+ * Nothing in the pipeline parsed dates out of query text, and `ActivationQuery`
+ * had no date parameter. So "azure app plan from last Thursday or Friday" spent
+ * "last", "Thursday" and "Friday" as ordinary BM25 tokens — diluting the subject
+ * terms and matching `date=` tags right across the corpus.
+ *
+ * Measured on the real store (101 probes, tests/realstore-eval):
+ *   subject only ............ 59.4% success@1   <- control
+ *   + "from last Friday" .... 56.4%  (-3.0pp)
+ *   + "on 2026-05-01" ....... 51.5%  (-7.9pp)
+ *   ORACLE, week-filtered ... 96.0%  (+36.6pp)
+ *
+ * So the most selective thing the user said was a PENALTY, and a working
+ * temporal filter is worth more than anything else measured on this store.
+ *
+ * DESIGN NOTES
+ * ------------
+ * - `asOf` is required for relative phrases. Using the wall clock would make a
+ *   fixture non-reproducible: "last week" would silently mean something new on
+ *   every run. Callers pass the query time explicitly.
+ * - Matching is deliberately CONSERVATIVE. A greedy matcher that fired on
+ *   ordinary words would reshape every recall in the store, so each pattern is
+ *   anchored on an unambiguous cue ("last", "yesterday", an ISO date, a month
+ *   name). When nothing matches, this returns `null` and callers must treat
+ *   that as a strict no-op.
+ * - The window is a PREFERENCE for callers, never a filter. People misremember
+ *   dates — "last Thursday or Friday" is itself an admission of uncertainty —
+ *   so a memory outside the window must stay reachable on subject strength.
+ */
+
+export interface TemporalMatch {
+  /** Inclusive window start (UTC ms). */
+  from: number;
+  /** Exclusive window end (UTC ms). */
+  to: number;
+  /** The literal phrases matched, for logging and for stripping. */
+  matched: string[];
+  /** The query with temporal phrases removed, for the lexical channel. */
+  stripped: string;
+  /** How the window was derived — useful when explaining a recall. */
+  kind: 'relative-day' | 'relative-week' | 'relative-month' | 'recent' | 'absolute-date' | 'absolute-month';
+}
+
+const DAY = 86400000;
+const WEEKDAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+const MONTHS = ['january', 'february', 'march', 'april', 'may', 'june',
+  'july', 'august', 'september', 'october', 'november', 'december'];
+
+const utcDay = (ms: number) => Math.floor(ms / DAY) * DAY;
+
+/**
+ * Parse a temporal expression out of `query`, anchored at `asOf`.
+ * Returns `null` when nothing matches — callers MUST treat that as a no-op.
+ *
+ * Windows are padded generously rather than tightly: the goal is to prefer a
+ * neighbourhood, not to pin an exact day the user probably misremembers.
+ */
+export function parseTemporal(query: string, asOf: Date | number): TemporalMatch | null {
+  const anchorMs = typeof asOf === 'number' ? asOf : asOf.getTime();
+  if (!Number.isFinite(anchorMs)) return null;
+  const q = query.toLowerCase();
+  const today = utcDay(anchorMs);
+  const matched: string[] = [];
+
+  const build = (from: number, to: number, kind: TemporalMatch['kind']): TemporalMatch => ({
+    from, to, matched,
+    stripped: stripPhrases(query, matched),
+    kind,
+  });
+
+  // ── absolute ISO date — ONLY with an explicit temporal cue ──
+  // A BARE date must not trigger this. Memories routinely carry a date as part
+  // of their SUBJECT ("Hive close-out 2026-04-24 PASS", "FIXED 2026-08-21 event
+  // River Glen"), where the date IS the fact, not a "when" filter. Treating
+  // those as temporal strips a strongly discriminative term and makes recall
+  // worse: measured, a bare-date rule fired on 98 of 1,316 (7.4%) real
+  // identifier queries and cost success@1 75.8% -> 75.0%. Same reason the month
+  // rule below requires an "in"/"during" cue.
+  const iso = q.match(/\b(on|from|since|before|after|around|during|dated)\s+(\d{4})-(\d{2})-(\d{2})\b/);
+  if (iso) {
+    matched.push(iso[0]);
+    const d = Date.UTC(+iso[2], +iso[3] - 1, +iso[4]);
+    // +/- 3 days: a remembered date is often a day or two off.
+    return build(d - 3 * DAY, d + 4 * DAY, 'absolute-date');
+  }
+
+  // ── "yesterday" / "today" ──
+  if (/\byesterday\b/.test(q)) {
+    matched.push('yesterday');
+    return build(today - DAY, today, 'relative-day');
+  }
+  if (/\btoday\b/.test(q)) {
+    matched.push('today');
+    return build(today, today + DAY, 'relative-day');
+  }
+
+  // ── "last <weekday>" / "on <weekday>" ──
+  const wd = q.match(/\b(?:last|this|on)\s+(sunday|monday|tuesday|wednesday|thursday|friday|saturday)\b/);
+  if (wd) {
+    matched.push(wd[0]);
+    // A second weekday ("Thursday or Friday") widens rather than confuses.
+    const second = q.match(/\bor\s+(sunday|monday|tuesday|wednesday|thursday|friday|saturday)\b/);
+    if (second) matched.push(second[0]);
+    const targets = [WEEKDAYS.indexOf(wd[1])];
+    if (second) targets.push(WEEKDAYS.indexOf(second[1]));
+    const anchorDow = new Date(today).getUTCDay();
+    const days = targets.map(t => {
+      let back = (anchorDow - t + 7) % 7;
+      if (back === 0) back = 7;                 // "last Friday" on a Friday means the previous one
+      return today - back * DAY;
+    });
+    // +/- 1 day of slack around the named day(s).
+    return build(Math.min(...days) - DAY, Math.max(...days) + 2 * DAY, 'relative-day');
+  }
+
+  // ── "last week" / "this week" / "past week" ──
+  if (/\b(?:last|this|past)\s+week\b/.test(q)) {
+    matched.push((q.match(/\b(?:last|this|past)\s+week\b/) as RegExpMatchArray)[0]);
+    return build(today - 14 * DAY, today + DAY, 'relative-week');
+  }
+
+  // ── "last month" / "this month" / "past month" ──
+  if (/\b(?:last|this|past)\s+month\b/.test(q)) {
+    matched.push((q.match(/\b(?:last|this|past)\s+month\b/) as RegExpMatchArray)[0]);
+    return build(today - 45 * DAY, today + DAY, 'relative-month');
+  }
+
+  // ── "last N days/weeks/months" ──
+  const lastN = q.match(/\b(?:last|past)\s+(\d{1,3})\s+(day|week|month)s?\b/);
+  if (lastN) {
+    matched.push(lastN[0]);
+    const n = +lastN[1];
+    const mult = lastN[2] === 'day' ? DAY : lastN[2] === 'week' ? 7 * DAY : 30 * DAY;
+    return build(today - n * mult, today + DAY, 'relative-week');
+  }
+
+  // ── "recently" / "recent" / "the other day" / "a few days ago" ──
+  if (/\b(?:recently|the other day|a few days ago|just now)\b/.test(q)) {
+    matched.push((q.match(/\b(?:recently|the other day|a few days ago|just now)\b/) as RegExpMatchArray)[0]);
+    return build(today - 14 * DAY, today + DAY, 'recent');
+  }
+
+  // ── "in <Month> [Year]" — requires the "in"/"during" cue so a project named
+  //    "May" or a sentence containing "march" cannot trigger it accidentally.
+  const mon = q.match(/\b(?:in|during|back in)\s+(january|february|march|april|may|june|july|august|september|october|november|december)\b(?:\s+(\d{4}))?/);
+  if (mon) {
+    matched.push(mon[0]);
+    const mIdx = MONTHS.indexOf(mon[1]);
+    const anchorYear = new Date(today).getUTCFullYear();
+    const year = mon[2] ? +mon[2] : anchorYear;
+    const from = Date.UTC(year, mIdx, 1);
+    const to = Date.UTC(mIdx === 11 ? year + 1 : year, (mIdx + 1) % 12, 1);
+    return build(from, to, 'absolute-month');
+  }
+
+  return null;
+}
+
+/** Remove matched temporal phrases (and now-dangling connectives) from a query. */
+function stripPhrases(query: string, phrases: string[]): string {
+  let out = query;
+  // Longest first, so "on 2026-05-01" is removed before the bare date.
+  for (const p of [...phrases].sort((a, b) => b.length - a.length)) {
+    out = out.replace(new RegExp(escapeRe(p), 'gi'), ' ');
+  }
+  return out
+    .replace(/\b(?:from|on|in|during|back in|since)\s*$/i, ' ')
+    .replace(/\s+(?:from|on|in|during)\s+(?=\s|$)/gi, ' ')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Whether temporal handling is enabled. Default OFF. */
+export function temporalEnabled(): boolean {
+  return process.env.AWM_TEMPORAL === '1';
+}
+
+/**
+ * Boost applied to a candidate whose creation time falls inside the window.
+ * A PREFERENCE, not a filter — see the design note above.
+ */
+export function temporalBoost(): number {
+  const v = Number(process.env.AWM_TEMPORAL_BOOST ?? 0.35);
+  return Number.isFinite(v) && v >= 0 ? v : 0.35;
+}

package/src/core/token-budget.ts

@@ -0,0 +1,160 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Token budgeting for memory_recall (0.13.3).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `limit: N` is a COUNT, which is token-blind: a 5-result recall can cost 400
+ * tokens or 4,000 depending on how long the memories happen to be. AWM's own
+ * benchmark shows the problem — in real sessions AWM retrieval averaged 4,514
+ * tokens per call against 2,106 for plain file retrieval. AWM wins 9.8:1 in
+ * AGGREGATE (it needs far fewer calls) but loses 2.1:1 PER CALL. Per-call cost
+ * is the exposed flank, and a caller had no way to bound it.
+ *
+ * `max_tokens` lets the caller say "I have 800 tokens of context to spare"
+ * instead of guessing at a result count.
+ *
+ * PACKING STRATEGY
+ * ----------------
+ * This is a 0/1 knapsack (maximise score within a token budget), so we use the
+ * standard greedy density heuristic — order by score-per-token — with one
+ * deliberate exception: the top-scored result is always admitted first if it
+ * fits at all. Density packing alone can drop the single most relevant memory
+ * purely for being long, which is exactly the answer the caller wanted.
+ *
+ * Selection is by density; OUTPUT is restored to score order, because a reader
+ * scanning results expects the best one first.
+ *
+ * ESTIMATOR
+ * ---------
+ * Deliberately dependency-free: no tokenizer, no model load, no async. It
+ * takes max(words x 1.3, chars / 4) — the two standard English/code
+ * approximations — and takes the larger so the estimate errs toward
+ * OVER-counting. Over-counting keeps us inside the budget; under-counting
+ * would silently blow it, which is the failure that matters.
+ */
+
+import type { ActivationResult } from '../types/engram.js';
+
+/** Rough token count. Over-estimates by design — see the note above. */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  const chars = text.length;
+  const words = text.split(/\s+/).filter(Boolean).length;
+  return Math.max(Math.ceil(words * 1.3), Math.ceil(chars / 4));
+}
+
+export interface PackedRecall {
+  /** Formatted lines that fit the budget, in score order. */
+  lines: string[];
+  /** How many results were kept. */
+  kept: number;
+  /** How many results were available before budgeting. */
+  total: number;
+  /** Estimated tokens of the kept lines. */
+  tokens: number;
+  /** Estimated tokens of everything dropped (0 when nothing was dropped). */
+  withheldTokens: number;
+}
+
+/**
+ * Select and format results to fit `maxTokens`.
+ *
+ * When `maxTokens` is undefined the behaviour is unchanged from pre-0.13.3 —
+ * everything is returned — but the accounting fields are still populated, so
+ * callers get per-call token visibility without opting into budgeting.
+ */
+export function packRecallByBudget(
+  results: ActivationResult[],
+  format: (r: ActivationResult, index: number) => string,
+  maxTokens?: number,
+  /**
+   * Tokens the caller will spend on the SAME reply outside the result lines —
+   * the accounting footer, and any peer-decisions suffix. Reserved up front so
+   * the budget bounds the whole reply rather than just the part this function
+   * happens to build.
+   *
+   * Found by the end-to-end eval, not by the unit tests: budgets of 600/250/80
+   * came back as 601/256/95 because the footer spent tokens it never counted.
+   */
+  reservedTokens = 0,
+): PackedRecall {
+  const total = results.length;
+  if (total === 0) return { lines: [], kept: 0, total: 0, tokens: 0, withheldTokens: 0 };
+  const effectiveBudget = maxTokens === undefined ? undefined
+    : Math.max(0, maxTokens - reservedTokens);
+
+  // Format once against the ORIGINAL index so displayed numbering matches the
+  // caller's mental model of "result 1 is the best match".
+  const measured = results.map((r, i) => {
+    const line = format(r, i);
+    return { line, tokens: estimateTokens(line), score: r.score, order: i };
+  });
+
+  const allTokens = measured.reduce((n, m) => n + m.tokens, 0);
+
+  // NOTE the asymmetry, which a unit test caught: `maxTokens` being absent or
+  // nonsense (<= 0) means "no budget — return everything", but an
+  // *effectiveBudget* of 0 means the reserve ate the entire budget, which must
+  // admit NOTHING. Collapsing those two cases returned the full result set on
+  // the tightest budgets — the exact opposite of what was asked for.
+  const unbudgeted = maxTokens === undefined || maxTokens <= 0;
+  if (unbudgeted || allTokens <= effectiveBudget!) {
+    return {
+      lines: measured.map(m => m.line),
+      kept: total,
+      total,
+      tokens: allTokens,
+      withheldTokens: 0,
+    };
+  }
+
+  const chosen: typeof measured = [];
+  let spent = 0;
+
+  // 1. Top-scored result gets first refusal, so a long best-match is never
+  //    dropped in favour of several short weak ones.
+  const top = measured[0];
+  if (top.tokens <= effectiveBudget!) {
+    chosen.push(top);
+    spent += top.tokens;
+  }
+
+  // 2. Everything else by value density (score per token), greedily.
+  const rest = measured
+    .filter(m => m !== top)
+    .sort((a, b) => (b.score / Math.max(b.tokens, 1)) - (a.score / Math.max(a.tokens, 1)));
+
+  for (const m of rest) {
+    if (spent + m.tokens > effectiveBudget!) continue;   // skip, don't stop: a later
+    chosen.push(m);                                // shorter result may still fit
+    spent += m.tokens;
+  }
+
+  // 3. Restore score order for display.
+  chosen.sort((a, b) => a.order - b.order);
+
+  return {
+    lines: chosen.map(m => m.line),
+    kept: chosen.length,
+    total,
+    tokens: spent,
+    withheldTokens: allTokens - spent,
+  };
+}
+
+/**
+ * One-line accounting footer. Costs ~15-25 tokens to report, which is a good
+ * trade against a recall that can run to thousands — and it is what makes the
+ * per-call cost visible to both the human and the harness. Without this,
+ * AWM's token behaviour is only observable in an offline benchmark.
+ */
+export function formatTokenFooter(p: PackedRecall, maxTokens?: number): string {
+  if (p.total === 0) return '';
+  const parts = [`~${p.tokens} tok`];
+  parts.push(p.kept === p.total ? `${p.total} results` : `${p.kept}/${p.total} results`);
+  if (maxTokens !== undefined && maxTokens > 0) parts.push(`budget ${maxTokens}`);
+  if (p.withheldTokens > 0) parts.push(`~${p.withheldTokens} tok withheld`);
+  return `\n\n[awm: ${parts.join(' · ')}]`;
+}