agent-working-memory 0.16.0 → 0.17.0

package/src/core/salience.ts

@@ -16,42 +16,69 @@ import type { IEngramStore as EngramStore } from '../storage/store.js';
 export type SalienceEventType = 'decision' | 'friction' | 'surprise' | 'causal' | 'observation' | 'user_feedback';
 
 /**
- * Auto-detect user-feedback memories: content that begins with a known user's
- * name + a feedback verb. These memories represent direct human decisions and
- * must never be discarded. Examples:
- *   "Robert verbatim: 'LMS programs-first like CRM'"
- *   "Katherine said the CEC cycle resets on promotion"
- *   "Nancy directed Tier 1 has no grace period"
+ * Auto-detect user-feedback memories: content that begins with a configured
+ * stakeholder's name + a feedback verb. These memories represent direct human
+ * decisions and must never be discarded. With AWM_FEEDBACK_NAMES="Ada,Grace":
+ *   "Ada verbatim: 'programs-first, like the CRM'"
+ *   "Grace said the certification cycle resets on promotion"
+ *   "Ada directed that tier 1 has no grace period"
  *
  * Why this exists: the BM25 novelty check collapses near-duplicates regardless
  * of whether the content is a NEW decision or a repeat observation. User
- * feedback often shares terminology with prior memories ("LMS", "ECP",
- * "officials") and gets discarded at salience 0.14 (verified in activity log
- * 2026-05-06T19:08:47). Detecting "Robert said X" → canonical class bypasses
- * the salience filter entirely.
+ * feedback often shares terminology with prior memories (the same handful of
+ * domain nouns recur in every one) and gets discarded at salience 0.14 (verified
+ * in activity log 2026-05-06T19:08:47). Detecting "<name> said X" → canonical
+ * class bypasses the salience filter entirely.
  *
- * Tune via AWM_FEEDBACK_NAMES (comma list). Pattern requires word boundary at
- * start so "Roberta" or "Hannahs" don't match.
+ * Set via AWM_FEEDBACK_NAMES (comma list). A name must be followed by whitespace
+ * and then a verb, so a longer name sharing a configured prefix ("Adaline" for a
+ * configured "Ada") does not match.
  */
-// D4 (2026-07-30): names/verbs are configurable so the library is not coupled
-// to one organization's staff list. AWM_FEEDBACK_NAMES / AWM_FEEDBACK_VERBS
-// take comma-separated lists. The built-in default preserves existing installs;
-// a future 1.0 flips the default to empty with the installer seeding values.
-const DEFAULT_FEEDBACK_NAMES = 'Robert,Katherine,Catherine,Nancy,Brandy,Brandi,Hannah,Marilyn,Kaylee,Pete,Abby,Tom,Wendy,Sita,Nick,Rob,Joan,Jennifer,Cindy,Jason,Alex,Molly';
+// D4 (2026-07-30): names/verbs are configurable so the library is not coupled to one
+// organization's staff list. AWM_FEEDBACK_NAMES / AWM_FEEDBACK_VERBS take comma lists.
+//
+// 2026-10-11: the default is now EMPTY, which disables the detector until an operator
+// configures it. It previously shipped 22 real first names — a deployment's own staff
+// list, published in the npm tarball (`src/` is in package.json `files`) and readable by
+// anyone who installed the package. That is other people's data, and a general-purpose
+// library has no business carrying it. The flip was the decision of record from the start
+// (docs/archive/eval-decisions-2026-07-30.md:37, "installer seeds Robert's current values
+// so behavior is unchanged for him"); D4 shipped only the configurability half and
+// deferred the flip to 1.0. It is brought forward here because the exposure is live.
+//
+// Operators who relied on the built-in list must now set AWM_FEEDBACK_NAMES explicitly —
+// in the MCP server's `env` block, since that is the only place guaranteed to be read
+// (the .env loader in cli.ts/mcp.ts resolves against process.cwd(), which an MCP server
+// does not control). Without it, "<name> said X" no longer auto-promotes to canonical;
+// an explicit memory_class: 'canonical' on the write still does.
+const DEFAULT_FEEDBACK_NAMES = '';
 const DEFAULT_FEEDBACK_VERBS = 'said,verbatim,feedback,asked,wants,prefers,requested,directed,decided,confirmed,clarified,chose,specified,explained';
 function csvToAlternation(env: string | undefined, fallback: string): string {
   return (env ?? fallback).split(',').map(x => x.trim()).filter(Boolean)
     .map(x => x.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
     .join('|');
 }
+const FEEDBACK_NAMES_ALTERNATION = csvToAlternation(process.env.AWM_FEEDBACK_NAMES, DEFAULT_FEEDBACK_NAMES);
 const USER_FEEDBACK_PATTERN = new RegExp(
-  '^(' + csvToAlternation(process.env.AWM_FEEDBACK_NAMES, DEFAULT_FEEDBACK_NAMES) + ')\\s+(' +
+  '^(' + FEEDBACK_NAMES_ALTERNATION + ')\\s+(' +
   csvToAlternation(process.env.AWM_FEEDBACK_VERBS, DEFAULT_FEEDBACK_VERBS) + ')\\b',
   'i',
 );
 
+/** True when at least one feedback name is configured; otherwise the detector is off. */
+export function userFeedbackDetectionEnabled(): boolean {
+  return FEEDBACK_NAMES_ALTERNATION.length > 0;
+}
+
 /** Returns true if the content looks like direct user feedback that should auto-promote to canonical. */
 export function detectUserFeedback(content: string): boolean {
+  // No configured names means the detector is OFF, as a decision rather than as an
+  // accident of the regex. An empty name list compiles to `^()\s+(said|asked|...)`, whose
+  // empty first group matches the empty string — so the pattern degrades to "starts with
+  // whitespace then a feedback verb". That is unreachable today only because the content
+  // is trimmed one line below, which makes correctness depend on the order of two
+  // unrelated statements. Check the configuration instead.
+  if (!userFeedbackDetectionEnabled()) return false;
   if (typeof content !== 'string' || content.length === 0) return false;
   return USER_FEEDBACK_PATTERN.test(content.trim());
 }

package/src/core/write-pipeline.ts

@@ -169,8 +169,16 @@ export async function performWrite(
   input: WriteInput,
 ): Promise<WriteResult> {
   const { store, connectionEngine } = engines;
+  // An explicit `supersedes` argument outranks every novelty signal: the caller has
+  // NAMED the engram this write replaces. Gating reinforcement off it routes the write
+  // to createNewEngram, which is the only path that honors meta.supersedesId (see the
+  // supersession side-effects below). Without this gate the argument was silently
+  // discarded by every branch in the block below — R1 (healthy match reinforced),
+  // R2 (the superseder reinforced instead), R1b (an archived match revived), and R3,
+  // which supersedes `matched.id` rather than the id the caller actually asked for.
   const enableReinforcement = input.enableReinforcement !== false
-    && process.env.AWM_WRITE_PIPELINE !== 'off';
+    && process.env.AWM_WRITE_PIPELINE !== 'off'
+    && !input.supersedes;
 
   // Profiling: AWM_PROFILE_WRITE=1 logs ms-per-phase to stderr (v0.8.2).
   // Off by default; zero cost when unset.
@@ -314,7 +322,22 @@ export async function performWrite(
 
   // -- Default: create new engram (if no reinforce/supersede branch fired) --
   if (!result) {
-    result = await createNewEngram(engines, input, salience, noveltyResult, {
+    // A correction of a near-duplicate has low novelty BY CONSTRUCTION: the replacement
+    // says almost what the engram it replaces said. Left on its own salience it lands at
+    // `discard` (confidence 0.25, tagged `low-salience`, below HEALTHY_CONFIDENCE_FLOOR)
+    // or at `staging` — while the supersession side-effect fires regardless. The old
+    // engram would be retired and its replacement too weak to stand in for it, so the
+    // fact leaves recall altogether: strictly worse than dropping the argument. R3 above
+    // already forces `active` for precisely this reason; an explicit `supersedes` is the
+    // same correction intent, stated by the caller instead of inferred from eventType.
+    const supersedeSalience: SalienceResult = input.supersedes
+      ? {
+          ...salience,
+          disposition: 'active' as const,
+          reasonCodes: [...salience.reasonCodes, 'supersede:override-active'],
+        }
+      : salience;
+    result = await createNewEngram(engines, input, supersedeSalience, noveltyResult, {
       effectiveEventType,
       effectiveMemoryClass,
       supersedesId: input.supersedes,

package/src/engine/consolidation.ts

@@ -541,13 +541,25 @@ export class ConsolidationEngine {
     //
     // Fade applies only to accessed engrams (the never-accessed ones go straight
     // to archive via Phase 6). Heavily-used (accessCount >= FADE_PROTECTED_ACCESS_COUNT),
-    // canonical, structural, and short-content engrams are excluded.
+    // canonical, structural, short-content, and UNFINISHED TASK engrams are excluded.
     let fadeCount = 0;
     for (const engram of engrams) {
       if (fadeCount >= FADE_MAX_PER_CYCLE) break;
       if (engram.accessCount === 0) continue;
       if (engram.accessCount >= FADE_PROTECTED_ACCESS_COUNT) continue;
       if (FADE_PROTECTED_CLASSES.has(engram.memoryClass)) continue;
+      // An unfinished task is a COMMITMENT, not a stale observation, and its body is
+      // where the acceptance criteria, source meeting, file paths and blocking reason
+      // live — the concept is 3-10 words by schema, so fading a task leaves a title
+      // nobody can action. Measured 2026-10-10 on the live store before this guard
+      // existed: 19 task bodies had already been cut to 150 chars, and `blocked` tasks
+      // were hit at 29% (5/17) against 1.2% (3/243) for `open` — ~24x — precisely
+      // BECAUSE a blocked task accrues idle days by definition while it waits on
+      // someone else, which is also when its body matters most. Only 1 of the 19 was
+      // recoverable from any backup. `done` tasks still fade: the work is finished and
+      // the gist suffices. memory_task_add sets salience 0.9 but never memoryClass, so
+      // FADE_PROTECTED_CLASSES above never covers a task.
+      if (engram.taskStatus && engram.taskStatus !== 'done') continue;
       if (engram.retracted) continue;
       if (engram.content.length < FADE_MIN_CONTENT_LEN) continue;
       if (engram.content.endsWith(FADE_MARKER)) continue; // Already faded