agent-working-memory 0.8.6 → 0.8.7

package/src/engine/confidence.ts

@@ -1,120 +1,120 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Retrieval confidence — score-distribution-aware signal that complements
- * the per-result `score`. The shape of the result set carries information
- * the raw scores do not:
- *
- *   - Confident recall: top-1 dominates, sharp cliff, non-trivial floor.
- *   - Noisy recall: many similar scores, flat distribution, weak floor.
- *   - "Best of bad bunch": sharp cliff but the cliff sits below a usable
- *     floor — the system found a winner among uninteresting candidates.
- *
- * Research grounding:
- *   - Geifman & El-Yaniv, "Selective Classification for Deep Neural
- *     Networks" (NeurIPS 2017): abstaining improves precision on confused
- *     inputs more than recalibrating thresholds.
- *   - Roitero et al, "Predictive Confidence in Retrieval" (SIGIR 2022):
- *     score-distribution shape predicts retrieval quality better than
- *     top-1 score in isolation.
- *   - Carmel & Yom-Tov, "Estimating Query Difficulty for IR" (Synthesis
- *     Lectures, 2010): post-retrieval predictors — sharpness, depth of
- *     score drop — correlate with TREC topic difficulty.
- *
- * AWM 0.8.5 integration: confidence is computed once per recall after
- * final scoring and attached to every `ActivationResult`. Consumers may
- * use it however they like (display, abstention, paired retrieval).
- * Default behavior of recall is unchanged — confidence is data, not a
- * gate, in PR-1.
- *
- * Configurable via env vars (initial weights tuned to favour sharpness):
- *   AWM_CONF_SHARPNESS_W (default 0.4) — weight of top1/mean(top5) signal
- *   AWM_CONF_CLIFF_W     (default 0.3) — weight of (top1 - top10) / top1
- *   AWM_CONF_FLOOR_W     (default 0.3) — weight of top1 absolute score
- */
-
-export interface RecallConfidence {
-  /** Composite confidence in [0, 1]. Higher = recall result is more trustworthy. */
-  confidence: number;
-  /** top1 / mean(top5), mapped to [0, 1] via (s-1)/(s+1). High = clear winner. */
-  sharpness: number;
-  /** (top1 - top10) / top1 in [0, 1]. High = sharp dropoff after winner. */
-  cliff: number;
-  /** top1 raw score, clamped to [0, 1]. Low = "best of bad bunch" risk. */
-  floor: number;
-}
-
-const SHARPNESS_W = parseFloat(process.env.AWM_CONF_SHARPNESS_W ?? '0.4');
-const CLIFF_W = parseFloat(process.env.AWM_CONF_CLIFF_W ?? '0.3');
-const FLOOR_W = parseFloat(process.env.AWM_CONF_FLOOR_W ?? '0.3');
-
-/**
- * Compute recall confidence from an ordered (descending) array of result scores.
- *
- * Returns a confidence near 0 when:
- *   - Empty result set (no winner)
- *   - Flat distribution (sharpness ~1, cliff ~0)
- *   - Low absolute scores (floor low — "best of bad bunch")
- *
- * Returns a confidence near 1 when:
- *   - top-1 dominates (sharpness >> 1)
- *   - Sharp cliff after top-1 (cliff close to 1)
- *   - top-1 is itself a strong absolute match (floor close to 1)
- *
- * Edge cases:
- *   - 1 result: cliff is 0 (no runner-up). Sharpness defaults to 1 (no peers
- *     to dominate). Confidence anchored entirely by floor.
- *   - 0 results: all zero, confidence = 0.
- */
-export function computeRecallConfidence(scoresDesc: number[]): RecallConfidence {
-  if (scoresDesc.length === 0) {
-    return { confidence: 0, sharpness: 0, cliff: 0, floor: 0 };
-  }
-
-  const top1 = scoresDesc[0];
-
-  // Floor: clamp top1 into [0, 1]. AWM composite scores already lie in this
-  // range under normal use, but be defensive.
-  const floor = Math.max(0, Math.min(1, top1));
-
-  // Sharpness: top1 / mean(top-5). Skip if only 1 result (no peers).
-  let sharpness = 0;
-  if (scoresDesc.length >= 2) {
-    const window = scoresDesc.slice(0, Math.min(5, scoresDesc.length));
-    const mean = window.reduce((s, v) => s + v, 0) / window.length;
-    if (mean > 0) {
-      const ratio = top1 / mean; // typically in [1, K]
-      sharpness = (ratio - 1) / (ratio + 1); // maps [1, ∞) → [0, 1)
-    }
-  }
-
-  // Cliff: how steep is the drop from top-1 to the K-th candidate?
-  // Use top-10 (or last available). If only 1 result, no cliff to measure.
-  let cliff = 0;
-  if (scoresDesc.length >= 2 && top1 > 0) {
-    const tail = scoresDesc[Math.min(9, scoresDesc.length - 1)];
-    cliff = Math.max(0, Math.min(1, (top1 - tail) / top1));
-  }
-
-  // Geometric blend — any near-zero component pulls confidence down.
-  // Add a tiny epsilon so log/zero doesn't collapse the whole signal when
-  // a result is genuinely sharp but the cliff is computed off only 2-3
-  // candidates (cliff small even for confident recalls).
-  const EPS = 0.05;
-  const s = sharpness + EPS;
-  const c = cliff + EPS;
-  const f = floor + EPS;
-
-  // Weighted geometric mean: prod(x_i ^ w_i)
-  const logConf =
-    SHARPNESS_W * Math.log(s)
-    + CLIFF_W * Math.log(c)
-    + FLOOR_W * Math.log(f);
-  const totalW = SHARPNESS_W + CLIFF_W + FLOOR_W;
-  // Subtract epsilon contribution so the floor of confidence is ~0 when all
-  // signals are zero (rather than the value of EPS).
-  const rawConf = Math.exp(logConf / totalW) - EPS;
-  const confidence = Math.max(0, Math.min(1, rawConf));
-
-  return { confidence, sharpness, cliff, floor };
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Retrieval confidence — score-distribution-aware signal that complements
+ * the per-result `score`. The shape of the result set carries information
+ * the raw scores do not:
+ *
+ *   - Confident recall: top-1 dominates, sharp cliff, non-trivial floor.
+ *   - Noisy recall: many similar scores, flat distribution, weak floor.
+ *   - "Best of bad bunch": sharp cliff but the cliff sits below a usable
+ *     floor — the system found a winner among uninteresting candidates.
+ *
+ * Research grounding:
+ *   - Geifman & El-Yaniv, "Selective Classification for Deep Neural
+ *     Networks" (NeurIPS 2017): abstaining improves precision on confused
+ *     inputs more than recalibrating thresholds.
+ *   - Roitero et al, "Predictive Confidence in Retrieval" (SIGIR 2022):
+ *     score-distribution shape predicts retrieval quality better than
+ *     top-1 score in isolation.
+ *   - Carmel & Yom-Tov, "Estimating Query Difficulty for IR" (Synthesis
+ *     Lectures, 2010): post-retrieval predictors — sharpness, depth of
+ *     score drop — correlate with TREC topic difficulty.
+ *
+ * AWM 0.8.5 integration: confidence is computed once per recall after
+ * final scoring and attached to every `ActivationResult`. Consumers may
+ * use it however they like (display, abstention, paired retrieval).
+ * Default behavior of recall is unchanged — confidence is data, not a
+ * gate, in PR-1.
+ *
+ * Configurable via env vars (initial weights tuned to favour sharpness):
+ *   AWM_CONF_SHARPNESS_W (default 0.4) — weight of top1/mean(top5) signal
+ *   AWM_CONF_CLIFF_W     (default 0.3) — weight of (top1 - top10) / top1
+ *   AWM_CONF_FLOOR_W     (default 0.3) — weight of top1 absolute score
+ */
+
+export interface RecallConfidence {
+  /** Composite confidence in [0, 1]. Higher = recall result is more trustworthy. */
+  confidence: number;
+  /** top1 / mean(top5), mapped to [0, 1] via (s-1)/(s+1). High = clear winner. */
+  sharpness: number;
+  /** (top1 - top10) / top1 in [0, 1]. High = sharp dropoff after winner. */
+  cliff: number;
+  /** top1 raw score, clamped to [0, 1]. Low = "best of bad bunch" risk. */
+  floor: number;
+}
+
+const SHARPNESS_W = parseFloat(process.env.AWM_CONF_SHARPNESS_W ?? '0.4');
+const CLIFF_W = parseFloat(process.env.AWM_CONF_CLIFF_W ?? '0.3');
+const FLOOR_W = parseFloat(process.env.AWM_CONF_FLOOR_W ?? '0.3');
+
+/**
+ * Compute recall confidence from an ordered (descending) array of result scores.
+ *
+ * Returns a confidence near 0 when:
+ *   - Empty result set (no winner)
+ *   - Flat distribution (sharpness ~1, cliff ~0)
+ *   - Low absolute scores (floor low — "best of bad bunch")
+ *
+ * Returns a confidence near 1 when:
+ *   - top-1 dominates (sharpness >> 1)
+ *   - Sharp cliff after top-1 (cliff close to 1)
+ *   - top-1 is itself a strong absolute match (floor close to 1)
+ *
+ * Edge cases:
+ *   - 1 result: cliff is 0 (no runner-up). Sharpness defaults to 1 (no peers
+ *     to dominate). Confidence anchored entirely by floor.
+ *   - 0 results: all zero, confidence = 0.
+ */
+export function computeRecallConfidence(scoresDesc: number[]): RecallConfidence {
+  if (scoresDesc.length === 0) {
+    return { confidence: 0, sharpness: 0, cliff: 0, floor: 0 };
+  }
+
+  const top1 = scoresDesc[0];
+
+  // Floor: clamp top1 into [0, 1]. AWM composite scores already lie in this
+  // range under normal use, but be defensive.
+  const floor = Math.max(0, Math.min(1, top1));
+
+  // Sharpness: top1 / mean(top-5). Skip if only 1 result (no peers).
+  let sharpness = 0;
+  if (scoresDesc.length >= 2) {
+    const window = scoresDesc.slice(0, Math.min(5, scoresDesc.length));
+    const mean = window.reduce((s, v) => s + v, 0) / window.length;
+    if (mean > 0) {
+      const ratio = top1 / mean; // typically in [1, K]
+      sharpness = (ratio - 1) / (ratio + 1); // maps [1, ∞) → [0, 1)
+    }
+  }
+
+  // Cliff: how steep is the drop from top-1 to the K-th candidate?
+  // Use top-10 (or last available). If only 1 result, no cliff to measure.
+  let cliff = 0;
+  if (scoresDesc.length >= 2 && top1 > 0) {
+    const tail = scoresDesc[Math.min(9, scoresDesc.length - 1)];
+    cliff = Math.max(0, Math.min(1, (top1 - tail) / top1));
+  }
+
+  // Geometric blend — any near-zero component pulls confidence down.
+  // Add a tiny epsilon so log/zero doesn't collapse the whole signal when
+  // a result is genuinely sharp but the cliff is computed off only 2-3
+  // candidates (cliff small even for confident recalls).
+  const EPS = 0.05;
+  const s = sharpness + EPS;
+  const c = cliff + EPS;
+  const f = floor + EPS;
+
+  // Weighted geometric mean: prod(x_i ^ w_i)
+  const logConf =
+    SHARPNESS_W * Math.log(s)
+    + CLIFF_W * Math.log(c)
+    + FLOOR_W * Math.log(f);
+  const totalW = SHARPNESS_W + CLIFF_W + FLOOR_W;
+  // Subtract epsilon contribution so the floor of confidence is ~0 when all
+  // signals are zero (rather than the value of EPS).
+  const rawConf = Math.exp(logConf / totalW) - EPS;
+  const confidence = Math.max(0, Math.min(1, rawConf));
+
+  return { confidence, sharpness, cliff, floor };
+}

package/src/engine/connections.ts

@@ -1,162 +1,162 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Connection Engine — discovers links between memories.
- *
- * **Lifecycle (v0.8.2):** `enqueue()` just appends to an in-memory queue and
- * returns. The queue is drained by `processQueue()`, which is called from
- * the consolidation cycle. Per-write inline drain was removed because each
- * `findConnections` call runs a full activation cycle (embed + BM25 + vector
- * + rerank) — ~200-500 ms of event-loop blocking per write, queued ahead
- * of subsequent requests under load.
- *
- * Cold-start exception: when the agent has fewer than
- * `AWM_CONNECTION_COLD_START_THRESHOLD` (default 10) active engrams, callers
- * can opt into inline drain via `enqueueAndMaybeFlush()` so the first few
- * writes still produce a useful association graph before the next
- * consolidation cycle fires. Once the pool grows past the threshold, all
- * discovery defers to consolidation regardless.
- *
- * Footprint: when AWM is idle and no consolidation is running, the queue
- * is a plain `string[]` — no timers, no background work, ~24 bytes per
- * queued ID. AWM remains cheap to NOT use.
- */
-
-import type { IEngramStore as EngramStore } from '../storage/store.js';
-import type { ActivationEngine } from './activation.js';
-import type { Engram } from '../types/index.js';
-
-const COLD_START_THRESHOLD = Number(process.env.AWM_CONNECTION_COLD_START_THRESHOLD ?? 10);
-
-export class ConnectionEngine {
-  private store: EngramStore;
-  private engine: ActivationEngine;
-  private threshold: number;
-  private queue: string[] = [];
-  private processing = false;
-
-  constructor(
-    store: EngramStore,
-    engine: ActivationEngine,
-    threshold: number = 0.7
-  ) {
-    this.store = store;
-    this.engine = engine;
-    this.threshold = threshold;
-  }
-
-  /**
-   * Queue a newly written engram for connection discovery.
-   *
-   * Synchronous and non-triggering. The queue is drained later by:
-   *   - `processQueue()` called from the consolidation cycle, or
-   *   - `enqueueAndMaybeFlush()` for cold-start inline drain.
-   */
-  enqueue(engramId: string): void {
-    this.queue.push(engramId);
-  }
-
-  /**
-   * Queue + opportunistic inline drain for cold-start agents.
-   *
-   * If the agent has fewer than `AWM_CONNECTION_COLD_START_THRESHOLD`
-   * active engrams (default 10), drain the queue inline so the first few
-   * writes produce a useful association graph before consolidation runs.
-   * Once the pool grows past the threshold, this falls back to deferred
-   * (consolidation-driven) drain.
-   *
-   * Returns immediately — the inline drain runs as a fire-and-forget
-   * background task so the calling write doesn't block on it.
-   */
-  enqueueAndMaybeFlush(engramId: string, agentId: string): void {
-    this.queue.push(engramId);
-    if (this.processing) return;
-    void this.maybeDrainColdStart(agentId);
-  }
-
-  private async maybeDrainColdStart(agentId: string): Promise<void> {
-    try {
-      const count = await this.store.getActiveCount(agentId);
-      if (count < COLD_START_THRESHOLD) {
-        await this.processQueue();
-      }
-    } catch {
-      // Cold-start drain is best-effort. The next consolidation cycle
-      // will drain whatever stayed queued.
-    }
-  }
-
-  /**
-   * Drain the queue: run connection discovery for every queued engram.
-   *
-   * Called from the consolidation cycle (`ConsolidationEngine.consolidate`)
-   * at the start of each run, and from `enqueueAndMaybeFlush()` for
-   * cold-start agents. Reentrant-safe via the `processing` flag.
-   *
-   * Exposed publicly so callers (consolidation, tests) can explicitly drain.
-   */
-  async processQueue(): Promise<void> {
-    if (this.processing) return; // Reentrancy guard
-    this.processing = true;
-    try {
-      while (this.queue.length > 0) {
-        const engramId = this.queue.shift()!;
-        const engram = await this.store.getEngram(engramId);
-        if (!engram || engram.stage !== 'active') continue;
-
-        try {
-          await this.findConnections(engram);
-        } catch {
-          // Connection discovery is best-effort — don't crash the server
-        }
-      }
-    } finally {
-      this.processing = false;
-    }
-  }
-
-  /** Number of engrams currently queued for connection discovery. */
-  queueSize(): number {
-    return this.queue.length;
-  }
-
-  /**
-   * Find and create connections for a given engram.
-   */
-  private async findConnections(engram: Engram): Promise<void> {
-    const results = await this.engine.activate({
-      agentId: engram.agentId,
-      context: `${engram.concept} ${engram.content}`,
-      limit: 5,
-      minScore: this.threshold,
-      internal: true,
-    });
-
-    // Filter out self and already-connected engrams
-    const existing = await this.store.getAssociationsFor(engram.id);
-    const existingIds = new Set(existing.map(a =>
-      a.fromEngramId === engram.id ? a.toEngramId : a.fromEngramId
-    ));
-
-    for (const result of results) {
-      if (result.engram.id === engram.id) continue;
-      if (existingIds.has(result.engram.id)) continue;
-
-      // Create a connection association
-      await this.store.upsertAssociation(
-        engram.id,
-        result.engram.id,
-        result.score,
-        'connection'
-      );
-
-      // Bidirectional
-      await this.store.upsertAssociation(
-        result.engram.id,
-        engram.id,
-        result.score,
-        'connection'
-      );
-    }
-  }
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Connection Engine — discovers links between memories.
+ *
+ * **Lifecycle (v0.8.2):** `enqueue()` just appends to an in-memory queue and
+ * returns. The queue is drained by `processQueue()`, which is called from
+ * the consolidation cycle. Per-write inline drain was removed because each
+ * `findConnections` call runs a full activation cycle (embed + BM25 + vector
+ * + rerank) — ~200-500 ms of event-loop blocking per write, queued ahead
+ * of subsequent requests under load.
+ *
+ * Cold-start exception: when the agent has fewer than
+ * `AWM_CONNECTION_COLD_START_THRESHOLD` (default 10) active engrams, callers
+ * can opt into inline drain via `enqueueAndMaybeFlush()` so the first few
+ * writes still produce a useful association graph before the next
+ * consolidation cycle fires. Once the pool grows past the threshold, all
+ * discovery defers to consolidation regardless.
+ *
+ * Footprint: when AWM is idle and no consolidation is running, the queue
+ * is a plain `string[]` — no timers, no background work, ~24 bytes per
+ * queued ID. AWM remains cheap to NOT use.
+ */
+
+import type { IEngramStore as EngramStore } from '../storage/store.js';
+import type { ActivationEngine } from './activation.js';
+import type { Engram } from '../types/index.js';
+
+const COLD_START_THRESHOLD = Number(process.env.AWM_CONNECTION_COLD_START_THRESHOLD ?? 10);
+
+export class ConnectionEngine {
+  private store: EngramStore;
+  private engine: ActivationEngine;
+  private threshold: number;
+  private queue: string[] = [];
+  private processing = false;
+
+  constructor(
+    store: EngramStore,
+    engine: ActivationEngine,
+    threshold: number = 0.7
+  ) {
+    this.store = store;
+    this.engine = engine;
+    this.threshold = threshold;
+  }
+
+  /**
+   * Queue a newly written engram for connection discovery.
+   *
+   * Synchronous and non-triggering. The queue is drained later by:
+   *   - `processQueue()` called from the consolidation cycle, or
+   *   - `enqueueAndMaybeFlush()` for cold-start inline drain.
+   */
+  enqueue(engramId: string): void {
+    this.queue.push(engramId);
+  }
+
+  /**
+   * Queue + opportunistic inline drain for cold-start agents.
+   *
+   * If the agent has fewer than `AWM_CONNECTION_COLD_START_THRESHOLD`
+   * active engrams (default 10), drain the queue inline so the first few
+   * writes produce a useful association graph before consolidation runs.
+   * Once the pool grows past the threshold, this falls back to deferred
+   * (consolidation-driven) drain.
+   *
+   * Returns immediately — the inline drain runs as a fire-and-forget
+   * background task so the calling write doesn't block on it.
+   */
+  enqueueAndMaybeFlush(engramId: string, agentId: string): void {
+    this.queue.push(engramId);
+    if (this.processing) return;
+    void this.maybeDrainColdStart(agentId);
+  }
+
+  private async maybeDrainColdStart(agentId: string): Promise<void> {
+    try {
+      const count = await this.store.getActiveCount(agentId);
+      if (count < COLD_START_THRESHOLD) {
+        await this.processQueue();
+      }
+    } catch {
+      // Cold-start drain is best-effort. The next consolidation cycle
+      // will drain whatever stayed queued.
+    }
+  }
+
+  /**
+   * Drain the queue: run connection discovery for every queued engram.
+   *
+   * Called from the consolidation cycle (`ConsolidationEngine.consolidate`)
+   * at the start of each run, and from `enqueueAndMaybeFlush()` for
+   * cold-start agents. Reentrant-safe via the `processing` flag.
+   *
+   * Exposed publicly so callers (consolidation, tests) can explicitly drain.
+   */
+  async processQueue(): Promise<void> {
+    if (this.processing) return; // Reentrancy guard
+    this.processing = true;
+    try {
+      while (this.queue.length > 0) {
+        const engramId = this.queue.shift()!;
+        const engram = await this.store.getEngram(engramId);
+        if (!engram || engram.stage !== 'active') continue;
+
+        try {
+          await this.findConnections(engram);
+        } catch {
+          // Connection discovery is best-effort — don't crash the server
+        }
+      }
+    } finally {
+      this.processing = false;
+    }
+  }
+
+  /** Number of engrams currently queued for connection discovery. */
+  queueSize(): number {
+    return this.queue.length;
+  }
+
+  /**
+   * Find and create connections for a given engram.
+   */
+  private async findConnections(engram: Engram): Promise<void> {
+    const results = await this.engine.activate({
+      agentId: engram.agentId,
+      context: `${engram.concept} ${engram.content}`,
+      limit: 5,
+      minScore: this.threshold,
+      internal: true,
+    });
+
+    // Filter out self and already-connected engrams
+    const existing = await this.store.getAssociationsFor(engram.id);
+    const existingIds = new Set(existing.map(a =>
+      a.fromEngramId === engram.id ? a.toEngramId : a.fromEngramId
+    ));
+
+    for (const result of results) {
+      if (result.engram.id === engram.id) continue;
+      if (existingIds.has(result.engram.id)) continue;
+
+      // Create a connection association
+      await this.store.upsertAssociation(
+        engram.id,
+        result.engram.id,
+        result.score,
+        'connection'
+      );
+
+      // Bidirectional
+      await this.store.upsertAssociation(
+        result.engram.id,
+        engram.id,
+        result.score,
+        'connection'
+      );
+    }
+  }
+}