agent-working-memory 0.5.4 → 0.5.6

package/src/engine/connections.ts

@@ -1,103 +1,103 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Connection Engine — discovers links between memories.
- *
- * Runs asynchronously. When a new engram is written, the connection
- * engine checks it against existing memories and forms association
- * edges where resonance exceeds a threshold.
- *
- * Connection memories are first-class engrams — they can themselves
- * activate and form higher-order connections, producing emergent
- * associative structure over time.
- */
-
-import type { EngramStore } from '../storage/sqlite.js';
-import type { ActivationEngine } from './activation.js';
-import type { Engram } from '../types/index.js';
-
-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.
-   */
-  enqueue(engramId: string): void {
-    this.queue.push(engramId);
-    if (!this.processing) {
-      this.processQueue();
-    }
-  }
-
-  private async processQueue(): Promise<void> {
-    this.processing = true;
-
-    while (this.queue.length > 0) {
-      const engramId = this.queue.shift()!;
-      const engram = 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
-      }
-    }
-
-    this.processing = false;
-  }
-
-  /**
-   * 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 = 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
-      this.store.upsertAssociation(
-        engram.id,
-        result.engram.id,
-        result.score,
-        'connection'
-      );
-
-      // Bidirectional
-      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.
+ *
+ * Runs asynchronously. When a new engram is written, the connection
+ * engine checks it against existing memories and forms association
+ * edges where resonance exceeds a threshold.
+ *
+ * Connection memories are first-class engrams — they can themselves
+ * activate and form higher-order connections, producing emergent
+ * associative structure over time.
+ */
+
+import type { EngramStore } from '../storage/sqlite.js';
+import type { ActivationEngine } from './activation.js';
+import type { Engram } from '../types/index.js';
+
+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.
+   */
+  enqueue(engramId: string): void {
+    this.queue.push(engramId);
+    if (!this.processing) {
+      this.processQueue();
+    }
+  }
+
+  private async processQueue(): Promise<void> {
+    this.processing = true;
+
+    while (this.queue.length > 0) {
+      const engramId = this.queue.shift()!;
+      const engram = 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
+      }
+    }
+
+    this.processing = false;
+  }
+
+  /**
+   * 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 = 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
+      this.store.upsertAssociation(
+        engram.id,
+        result.engram.id,
+        result.score,
+        'connection'
+      );
+
+      // Bidirectional
+      this.store.upsertAssociation(
+        result.engram.id,
+        engram.id,
+        result.score,
+        'connection'
+      );
+    }
+  }
+}

package/src/engine/consolidation-scheduler.ts

@@ -1,125 +1,125 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Consolidation Scheduler — automatically triggers sleep cycles.
- *
- * Four triggers:
- *   1. Idle — agent inactive >10min → full consolidation
- *   2. Volume — 50+ writes since last consolidation → full consolidation
- *   3. Time — 30min since last consolidation → full consolidation
- *   4. Adaptive — retrieval precision <0.4 → full consolidation
- *
- * Also provides mini-consolidation for restore (fire-and-forget, lightweight).
- * Checks every 30 seconds across all active agents.
- */
-
-import type { EngramStore } from '../storage/sqlite.js';
-import type { ConsolidationEngine } from './consolidation.js';
-
-const TICK_INTERVAL_MS = 30_000;         // Check every 30s
-const IDLE_THRESHOLD_MS = 10 * 60_000;   // 10 minutes
-const VOLUME_THRESHOLD = 50;             // 50 writes
-const TIME_THRESHOLD_MS = 30 * 60_000;   // 30 minutes
-const PRECISION_THRESHOLD = 0.4;         // Below this triggers consolidation
-
-export class ConsolidationScheduler {
-  private timer: ReturnType<typeof setInterval> | null = null;
-  private running = false;
-
-  constructor(
-    private store: EngramStore,
-    private consolidationEngine: ConsolidationEngine,
-  ) {}
-
-  start(): void {
-    if (this.timer) return;
-    this.timer = setInterval(() => this.tick(), TICK_INTERVAL_MS);
-    console.log('ConsolidationScheduler started (30s tick)');
-  }
-
-  stop(): void {
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
-    }
-    console.log('ConsolidationScheduler stopped');
-  }
-
-  /**
-   * Mini-consolidation — lightweight, called from restore path.
-   * Only runs replay + strengthen (phases 1-2), skips heavy phases.
-   */
-  async runMiniConsolidation(agentId: string): Promise<void> {
-    if (this.running) return;
-    this.running = true;
-    try {
-      console.log(`[scheduler] mini-consolidation for ${agentId}`);
-      await this.consolidationEngine.consolidate(agentId);
-      this.store.markConsolidation(agentId, true);
-    } catch (err) {
-      console.error(`[scheduler] mini-consolidation failed for ${agentId}:`, err);
-    } finally {
-      this.running = false;
-    }
-  }
-
-  private tick(): void {
-    if (this.running) return;
-
-    const agents = this.store.getActiveAgents();
-    const now = Date.now();
-
-    for (const agent of agents) {
-      const idleMs = now - agent.lastActivityAt.getTime();
-      const sinceConsolidation = agent.lastConsolidationAt
-        ? now - agent.lastConsolidationAt.getTime()
-        : Infinity;
-
-      let trigger: string | null = null;
-
-      // 1. Idle trigger — agent stopped writing/recalling >10min ago
-      if (idleMs > IDLE_THRESHOLD_MS && sinceConsolidation > IDLE_THRESHOLD_MS) {
-        trigger = `idle (${Math.round(idleMs / 60_000)}min)`;
-      }
-
-      // 2. Volume trigger — many writes accumulated
-      if (!trigger && agent.writeCount >= VOLUME_THRESHOLD) {
-        trigger = `volume (${agent.writeCount} writes)`;
-      }
-
-      // 3. Time trigger — been too long since last consolidation
-      if (!trigger && sinceConsolidation > TIME_THRESHOLD_MS) {
-        trigger = `time (${Math.round(sinceConsolidation / 60_000)}min)`;
-      }
-
-      // 4. Adaptive trigger — precision is low
-      if (!trigger) {
-        try {
-          const precision = this.store.getRetrievalPrecision(agent.agentId, 1);
-          if (precision > 0 && precision < PRECISION_THRESHOLD) {
-            trigger = `adaptive (precision ${(precision * 100).toFixed(0)}%)`;
-          }
-        } catch { /* precision check is non-fatal */ }
-      }
-
-      if (trigger) {
-        this.runFullConsolidation(agent.agentId, trigger);
-        return; // One consolidation per tick to avoid overload
-      }
-    }
-  }
-
-  private async runFullConsolidation(agentId: string, reason: string): Promise<void> {
-    this.running = true;
-    try {
-      console.log(`[scheduler] full consolidation for ${agentId} — trigger: ${reason}`);
-      const result = await this.consolidationEngine.consolidate(agentId);
-      this.store.markConsolidation(agentId, false);
-      console.log(`[scheduler] consolidation done: ${result.edgesStrengthened} strengthened, ${result.memoriesForgotten} forgotten`);
-    } catch (err) {
-      console.error(`[scheduler] consolidation failed for ${agentId}:`, err);
-    } finally {
-      this.running = false;
-    }
-  }
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Consolidation Scheduler — automatically triggers sleep cycles.
+ *
+ * Four triggers:
+ *   1. Idle — agent inactive >10min → full consolidation
+ *   2. Volume — 50+ writes since last consolidation → full consolidation
+ *   3. Time — 30min since last consolidation → full consolidation
+ *   4. Adaptive — retrieval precision <0.4 → full consolidation
+ *
+ * Also provides mini-consolidation for restore (fire-and-forget, lightweight).
+ * Checks every 30 seconds across all active agents.
+ */
+
+import type { EngramStore } from '../storage/sqlite.js';
+import type { ConsolidationEngine } from './consolidation.js';
+
+const TICK_INTERVAL_MS = 30_000;         // Check every 30s
+const IDLE_THRESHOLD_MS = 10 * 60_000;   // 10 minutes
+const VOLUME_THRESHOLD = 50;             // 50 writes
+const TIME_THRESHOLD_MS = 30 * 60_000;   // 30 minutes
+const PRECISION_THRESHOLD = 0.4;         // Below this triggers consolidation
+
+export class ConsolidationScheduler {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private running = false;
+
+  constructor(
+    private store: EngramStore,
+    private consolidationEngine: ConsolidationEngine,
+  ) {}
+
+  start(): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.tick(), TICK_INTERVAL_MS);
+    console.log('ConsolidationScheduler started (30s tick)');
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    console.log('ConsolidationScheduler stopped');
+  }
+
+  /**
+   * Mini-consolidation — lightweight, called from restore path.
+   * Only runs replay + strengthen (phases 1-2), skips heavy phases.
+   */
+  async runMiniConsolidation(agentId: string): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+    try {
+      console.log(`[scheduler] mini-consolidation for ${agentId}`);
+      await this.consolidationEngine.consolidate(agentId);
+      this.store.markConsolidation(agentId, true);
+    } catch (err) {
+      console.error(`[scheduler] mini-consolidation failed for ${agentId}:`, err);
+    } finally {
+      this.running = false;
+    }
+  }
+
+  private tick(): void {
+    if (this.running) return;
+
+    const agents = this.store.getActiveAgents();
+    const now = Date.now();
+
+    for (const agent of agents) {
+      const idleMs = now - agent.lastActivityAt.getTime();
+      const sinceConsolidation = agent.lastConsolidationAt
+        ? now - agent.lastConsolidationAt.getTime()
+        : Infinity;
+
+      let trigger: string | null = null;
+
+      // 1. Idle trigger — agent stopped writing/recalling >10min ago
+      if (idleMs > IDLE_THRESHOLD_MS && sinceConsolidation > IDLE_THRESHOLD_MS) {
+        trigger = `idle (${Math.round(idleMs / 60_000)}min)`;
+      }
+
+      // 2. Volume trigger — many writes accumulated
+      if (!trigger && agent.writeCount >= VOLUME_THRESHOLD) {
+        trigger = `volume (${agent.writeCount} writes)`;
+      }
+
+      // 3. Time trigger — been too long since last consolidation
+      if (!trigger && sinceConsolidation > TIME_THRESHOLD_MS) {
+        trigger = `time (${Math.round(sinceConsolidation / 60_000)}min)`;
+      }
+
+      // 4. Adaptive trigger — precision is low
+      if (!trigger) {
+        try {
+          const precision = this.store.getRetrievalPrecision(agent.agentId, 1);
+          if (precision > 0 && precision < PRECISION_THRESHOLD) {
+            trigger = `adaptive (precision ${(precision * 100).toFixed(0)}%)`;
+          }
+        } catch { /* precision check is non-fatal */ }
+      }
+
+      if (trigger) {
+        this.runFullConsolidation(agent.agentId, trigger);
+        return; // One consolidation per tick to avoid overload
+      }
+    }
+  }
+
+  private async runFullConsolidation(agentId: string, reason: string): Promise<void> {
+    this.running = true;
+    try {
+      console.log(`[scheduler] full consolidation for ${agentId} — trigger: ${reason}`);
+      const result = await this.consolidationEngine.consolidate(agentId);
+      this.store.markConsolidation(agentId, false);
+      console.log(`[scheduler] consolidation done: ${result.edgesStrengthened} strengthened, ${result.memoriesForgotten} forgotten`);
+    } catch (err) {
+      console.error(`[scheduler] consolidation failed for ${agentId}:`, err);
+    } finally {
+      this.running = false;
+    }
+  }
+}

package/src/engine/eval.ts

@@ -1,102 +1,102 @@
-// 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 { EngramStore } from '../storage/sqlite.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.
-   */
-  computeMetrics(agentId: string, windowHours: number = 24): EvalMetrics {
-    const window = windowHours <= 24 ? '24h' : `${Math.round(windowHours / 24)}d`;
-
-    // Retrieval quality
-    const precision = this.store.getRetrievalPrecision(agentId, windowHours);
-
-    // Staging accuracy
-    const stagingMetrics = this.store.getStagingMetrics(agentId);
-    const totalStaged = stagingMetrics.promoted + stagingMetrics.discarded + stagingMetrics.expired;
-    const promotionPrecision = totalStaged > 0 ? stagingMetrics.promoted / totalStaged : 0;
-
-    // Memory health
-    const activeEngrams = this.store.getEngramsByAgent(agentId, 'active');
-    const stagingEngrams = this.store.getEngramsByAgent(agentId, 'staging');
-    const retractedEngrams = this.store.getEngramsByAgent(agentId, undefined, true)
-      .filter(e => e.retracted);
-    const allAssociations = 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 = this.store.getActivationStats(agentId, windowHours);
-
-    // Consolidated count
-    const consolidatedCount = 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 { EngramStore } from '../storage/sqlite.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.
+   */
+  computeMetrics(agentId: string, windowHours: number = 24): EvalMetrics {
+    const window = windowHours <= 24 ? '24h' : `${Math.round(windowHours / 24)}d`;
+
+    // Retrieval quality
+    const precision = this.store.getRetrievalPrecision(agentId, windowHours);
+
+    // Staging accuracy
+    const stagingMetrics = this.store.getStagingMetrics(agentId);
+    const totalStaged = stagingMetrics.promoted + stagingMetrics.discarded + stagingMetrics.expired;
+    const promotionPrecision = totalStaged > 0 ? stagingMetrics.promoted / totalStaged : 0;
+
+    // Memory health
+    const activeEngrams = this.store.getEngramsByAgent(agentId, 'active');
+    const stagingEngrams = this.store.getEngramsByAgent(agentId, 'staging');
+    const retractedEngrams = this.store.getEngramsByAgent(agentId, undefined, true)
+      .filter(e => e.retracted);
+    const allAssociations = 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 = this.store.getActivationStats(agentId, windowHours);
+
+    // Consolidated count
+    const consolidatedCount = 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),
+    };
+  }
+}