agent-working-memory 0.10.0 → 0.12.0

package/src/engine/eval.ts

@@ -1,102 +1,107 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Evaluation Engine — measures whether memory actually helps.
- *
- * Four dimensions (from Codex):
- *   1. Retrieval quality — precision@k, latency
- *   2. Connection quality — edge utility, stability
- *   3. Staging accuracy — promotion precision, discard regret
- *   4. Memory health — contamination tracking, confidence distribution
- *
- * Task impact (with/without memory) is measured externally via TaskTrial records.
- */
-
-import type { IEngramStore as EngramStore } from '../storage/store.js';
-import type { EvalMetrics } from '../types/index.js';
-
-export class EvalEngine {
-  private store: EngramStore;
-
-  constructor(store: EngramStore) {
-    this.store = store;
-  }
-
-  /**
-   * Compute aggregate metrics for an agent over a time window.
-   */
-  async computeMetrics(agentId: string, windowHours: number = 24): Promise<EvalMetrics> {
-    const window = windowHours <= 24 ? '24h' : `${Math.round(windowHours / 24)}d`;
-
-    // Retrieval quality
-    const precision = await this.store.getRetrievalPrecision(agentId, windowHours);
-
-    // Staging accuracy
-    const stagingMetrics = await this.store.getStagingMetrics(agentId);
-    const totalStaged = stagingMetrics.promoted + stagingMetrics.discarded + stagingMetrics.expired;
-    const promotionPrecision = totalStaged > 0 ? stagingMetrics.promoted / totalStaged : 0;
-
-    // Memory health
-    const activeEngrams = await this.store.getEngramsByAgent(agentId, 'active');
-    const stagingEngrams = await this.store.getEngramsByAgent(agentId, 'staging');
-    const retractedEngrams = (await this.store.getEngramsByAgent(agentId, undefined, true))
-      .filter(e => e.retracted);
-    const allAssociations = await this.store.getAllAssociations(agentId);
-
-    const avgConfidence = activeEngrams.length > 0
-      ? activeEngrams.reduce((sum, e) => sum + e.confidence, 0) / activeEngrams.length
-      : 0;
-
-    // Edge utility — % of edges that have been used in activation
-    const usedEdges = allAssociations.filter(a => a.activationCount > 0);
-    const edgeUtility = allAssociations.length > 0
-      ? usedEdges.length / allAssociations.length
-      : 0;
-
-    // Edge survival — average age of edges that are still above minimum weight
-    const livingEdges = allAssociations.filter(a => a.weight > 0.01);
-    const avgSurvival = livingEdges.length > 0
-      ? livingEdges.reduce((sum, a) =>
-          sum + (Date.now() - a.createdAt.getTime()) / (1000 * 60 * 60 * 24), 0
-        ) / livingEdges.length
-      : 0;
-
-    // Activation performance stats
-    const activationStats = await this.store.getActivationStats(agentId, windowHours);
-
-    // Consolidated count
-    const consolidatedCount = await this.store.getConsolidatedCount(agentId);
-
-    return {
-      agentId,
-      timestamp: new Date(),
-      window,
-
-      activationCount: activationStats.count,
-      avgPrecisionAtK: precision,
-      avgLatencyMs: activationStats.avgLatencyMs,
-      p95LatencyMs: activationStats.p95LatencyMs,
-
-      totalEdges: allAssociations.length,
-      edgesUsedInActivation: usedEdges.length,
-      edgeUtilityRate: edgeUtility,
-      avgEdgeSurvivalDays: avgSurvival,
-
-      totalStaged: totalStaged,
-      promotedCount: stagingMetrics.promoted,
-      discardedCount: stagingMetrics.discarded,
-      promotionPrecision,
-      discardRegret: 0, // Requires tracking discarded-then-rediscovered items
-
-      activeEngramCount: activeEngrams.length,
-      stagingEngramCount: stagingEngrams.length,
-      retractedCount: retractedEngrams.length,
-      consolidatedCount,
-      avgConfidence,
-
-      staleUsageCount: 0, // Requires per-activation age/confidence tracking
-      retractionRate: retractedEngrams.length /
-        Math.max(activeEngrams.length + retractedEngrams.length, 1),
-    };
-  }
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Evaluation Engine — measures whether memory actually helps.
+ *
+ * Four dimensions (from Codex):
+ *   1. Retrieval quality — precision@k, latency
+ *   2. Connection quality — edge utility, stability
+ *   3. Staging accuracy — promotion precision, discard regret
+ *   4. Memory health — contamination tracking, confidence distribution
+ *
+ * Task impact (with/without memory) is measured externally via TaskTrial records.
+ */
+
+import type { IEngramStore as EngramStore } from '../storage/store.js';
+import type { EvalMetrics } from '../types/index.js';
+
+export class EvalEngine {
+  private store: EngramStore;
+
+  constructor(store: EngramStore) {
+    this.store = store;
+  }
+
+  /**
+   * Compute aggregate metrics for an agent over a time window.
+   */
+  async computeMetrics(agentId: string, windowHours: number = 24): Promise<EvalMetrics> {
+    const window = windowHours <= 24 ? '24h' : `${Math.round(windowHours / 24)}d`;
+
+    // Retrieval quality
+    const precision = await this.store.getRetrievalPrecision(agentId, windowHours);
+
+    // Staging accuracy
+    const stagingMetrics = await this.store.getStagingMetrics(agentId);
+    const totalStaged = stagingMetrics.promoted + stagingMetrics.discarded + stagingMetrics.expired;
+    const promotionPrecision = totalStaged > 0 ? stagingMetrics.promoted / totalStaged : 0;
+
+    // Memory health
+    const activeEngrams = await this.store.getEngramsByAgent(agentId, 'active');
+    const stagingEngrams = await this.store.getEngramsByAgent(agentId, 'staging');
+    const retractedEngrams = (await this.store.getEngramsByAgent(agentId, undefined, true))
+      .filter(e => e.retracted);
+    const allAssociations = await this.store.getAllAssociations(agentId);
+
+    const avgConfidence = activeEngrams.length > 0
+      ? activeEngrams.reduce((sum, e) => sum + e.confidence, 0) / activeEngrams.length
+      : 0;
+
+    // Edge utility — % of edges that have been used in activation
+    const usedEdges = allAssociations.filter(a => a.activationCount > 0);
+    const edgeUtility = allAssociations.length > 0
+      ? usedEdges.length / allAssociations.length
+      : 0;
+
+    // Edge survival — average age of edges that are still above minimum weight
+    const livingEdges = allAssociations.filter(a => a.weight > 0.01);
+    const avgSurvival = livingEdges.length > 0
+      ? livingEdges.reduce((sum, a) =>
+          sum + (Date.now() - a.createdAt.getTime()) / (1000 * 60 * 60 * 24), 0
+        ) / livingEdges.length
+      : 0;
+
+    // Activation performance stats
+    const activationStats = await this.store.getActivationStats(agentId, windowHours);
+
+    // Consolidated count
+    const consolidatedCount = await this.store.getConsolidatedCount(agentId);
+
+    return {
+      agentId,
+      timestamp: new Date(),
+      window,
+
+      activationCount: activationStats.count,
+      avgPrecisionAtK: precision,
+      avgLatencyMs: activationStats.avgLatencyMs,
+      p95LatencyMs: activationStats.p95LatencyMs,
+
+      totalEdges: allAssociations.length,
+      edgesUsedInActivation: usedEdges.length,
+      edgeUtilityRate: edgeUtility,
+      avgEdgeSurvivalDays: avgSurvival,
+
+      totalStaged: totalStaged,
+      promotedCount: stagingMetrics.promoted,
+      discardedCount: stagingMetrics.discarded,
+      promotionPrecision,
+      // D12 (2026-07-30): discarded writes persist as 'low-salience'-tagged
+      // engrams (confidence 0.25). Regret = the filter demoted something the
+      // agent later actually needed — measured as low-salience engrams that
+      // were subsequently accessed at least once.
+      discardRegret: activeEngrams.filter(e =>
+        e.tags.includes('low-salience') && e.accessCount > 0).length,
+
+      activeEngramCount: activeEngrams.length,
+      stagingEngramCount: stagingEngrams.length,
+      retractedCount: retractedEngrams.length,
+      consolidatedCount,
+      avgConfidence,
+
+      staleUsageCount: 0, // Requires per-activation age/confidence tracking
+      retractionRate: retractedEngrams.length /
+        Math.max(activeEngrams.length + retractedEngrams.length, 1),
+    };
+  }
+}

package/src/engine/eviction.ts

@@ -1,101 +1,101 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Eviction Engine — capacity enforcement and edge pruning.
- *
- * When memory budgets are exceeded:
- *   1. Archive lowest-value active engrams
- *   2. Delete expired staging engrams
- *   3. Prune weakest edges when per-engram cap exceeded
- *   4. Decay unused association weights over time
- */
-
-import type { IEngramStore as EngramStore } from '../storage/store.js';
-import type { AgentConfig } from '../types/agent.js';
-import { decayAssociation } from '../core/hebbian.js';
-
-export class EvictionEngine {
-  private store: EngramStore;
-
-  constructor(store: EngramStore) {
-    this.store = store;
-  }
-
-  /**
-   * Check capacity budgets and evict if needed.
-   * Returns count of evicted engrams.
-   */
-  async enforceCapacity(agentId: string, config: AgentConfig): Promise<{ evicted: number; edgesPruned: number }> {
-    let evicted = 0;
-    let edgesPruned = 0;
-
-    // Active engram budget
-    const activeCount = await this.store.getActiveCount(agentId);
-    if (activeCount > config.maxActiveEngrams) {
-      const excess = activeCount - config.maxActiveEngrams;
-      const candidates = await this.store.getEvictionCandidates(agentId, excess);
-      for (const engram of candidates) {
-        await this.store.updateStage(engram.id, 'archived');
-        evicted++;
-      }
-    }
-
-    // Staging budget
-    const stagingCount = await this.store.getStagingCount(agentId);
-    if (stagingCount > config.maxStagingEngrams) {
-      const expired = await this.store.getExpiredStaging();
-      for (const engram of expired) {
-        await this.store.deleteEngram(engram.id);
-        evicted++;
-      }
-    }
-
-    // Edge pruning — cap per engram
-    const engrams = await this.store.getEngramsByAgent(agentId, 'active');
-    for (const engram of engrams) {
-      const edgeCount = await this.store.countAssociationsFor(engram.id);
-      if (edgeCount > config.maxEdgesPerEngram) {
-        // Remove weakest edges until under cap
-        let toRemove = edgeCount - config.maxEdgesPerEngram;
-        while (toRemove > 0) {
-          const weakest = await this.store.getWeakestAssociation(engram.id);
-          if (weakest) {
-            await this.store.deleteAssociation(weakest.id);
-            edgesPruned++;
-          }
-          toRemove--;
-        }
-      }
-    }
-
-    return { evicted, edgesPruned };
-  }
-
-  /**
-   * Decay all association weights based on time since last activation.
-   * Run periodically (e.g., daily).
-   */
-  async decayEdges(agentId: string, halfLifeDays: number = 7): Promise<number> {
-    const associations = await this.store.getAllAssociations(agentId);
-    let decayed = 0;
-
-    for (const assoc of associations) {
-      const daysSince = (Date.now() - assoc.lastActivated.getTime()) / (1000 * 60 * 60 * 24);
-      if (daysSince < 0.5) continue; // Skip recently activated
-
-      const newWeight = decayAssociation(assoc.weight, daysSince, halfLifeDays);
-      if (newWeight < 0.01) {
-        // Below minimum useful weight — prune
-        await this.store.deleteAssociation(assoc.id);
-        decayed++;
-      } else if (Math.abs(newWeight - assoc.weight) > 0.001) {
-        await this.store.upsertAssociation(
-          assoc.fromEngramId, assoc.toEngramId, newWeight, assoc.type, assoc.confidence
-        );
-        decayed++;
-      }
-    }
-
-    return decayed;
-  }
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Eviction Engine — capacity enforcement and edge pruning.
+ *
+ * When memory budgets are exceeded:
+ *   1. Archive lowest-value active engrams
+ *   2. Delete expired staging engrams
+ *   3. Prune weakest edges when per-engram cap exceeded
+ *   4. Decay unused association weights over time
+ */
+
+import type { IEngramStore as EngramStore } from '../storage/store.js';
+import type { AgentConfig } from '../types/agent.js';
+import { decayAssociation } from '../core/hebbian.js';
+
+export class EvictionEngine {
+  private store: EngramStore;
+
+  constructor(store: EngramStore) {
+    this.store = store;
+  }
+
+  /**
+   * Check capacity budgets and evict if needed.
+   * Returns count of evicted engrams.
+   */
+  async enforceCapacity(agentId: string, config: AgentConfig): Promise<{ evicted: number; edgesPruned: number }> {
+    let evicted = 0;
+    let edgesPruned = 0;
+
+    // Active engram budget
+    const activeCount = await this.store.getActiveCount(agentId);
+    if (activeCount > config.maxActiveEngrams) {
+      const excess = activeCount - config.maxActiveEngrams;
+      const candidates = await this.store.getEvictionCandidates(agentId, excess);
+      for (const engram of candidates) {
+        await this.store.updateStage(engram.id, 'archived');
+        evicted++;
+      }
+    }
+
+    // Staging budget
+    const stagingCount = await this.store.getStagingCount(agentId);
+    if (stagingCount > config.maxStagingEngrams) {
+      const expired = await this.store.getExpiredStaging();
+      for (const engram of expired) {
+        await this.store.deleteEngram(engram.id);
+        evicted++;
+      }
+    }
+
+    // Edge pruning — cap per engram
+    const engrams = await this.store.getEngramsByAgent(agentId, 'active');
+    for (const engram of engrams) {
+      const edgeCount = await this.store.countAssociationsFor(engram.id);
+      if (edgeCount > config.maxEdgesPerEngram) {
+        // Remove weakest edges until under cap
+        let toRemove = edgeCount - config.maxEdgesPerEngram;
+        while (toRemove > 0) {
+          const weakest = await this.store.getWeakestAssociation(engram.id);
+          if (weakest) {
+            await this.store.deleteAssociation(weakest.id);
+            edgesPruned++;
+          }
+          toRemove--;
+        }
+      }
+    }
+
+    return { evicted, edgesPruned };
+  }
+
+  /**
+   * Decay all association weights based on time since last activation.
+   * Run periodically (e.g., daily).
+   */
+  async decayEdges(agentId: string, halfLifeDays: number = 7): Promise<number> {
+    const associations = await this.store.getAllAssociations(agentId);
+    let decayed = 0;
+
+    for (const assoc of associations) {
+      const daysSince = (Date.now() - assoc.lastActivated.getTime()) / (1000 * 60 * 60 * 24);
+      if (daysSince < 0.5) continue; // Skip recently activated
+
+      const newWeight = decayAssociation(assoc.weight, daysSince, halfLifeDays);
+      if (newWeight < 0.01) {
+        // Below minimum useful weight — prune
+        await this.store.deleteAssociation(assoc.id);
+        decayed++;
+      } else if (Math.abs(newWeight - assoc.weight) > 0.001) {
+        await this.store.upsertAssociation(
+          assoc.fromEngramId, assoc.toEngramId, newWeight, assoc.type, assoc.confidence
+        );
+        decayed++;
+      }
+    }
+
+    return decayed;
+  }
+}

package/src/engine/index.ts

@@ -1,8 +1,8 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-export * from './activation.js';
-export * from './staging.js';
-export * from './connections.js';
-export * from './eviction.js';
-export * from './retraction.js';
-export * from './eval.js';
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+export * from './activation.js';
+export * from './staging.js';
+export * from './connections.js';
+export * from './eviction.js';
+export * from './retraction.js';
+export * from './eval.js';