agent-working-memory 0.3.0

package/src/engine/eval.ts

@@ -0,0 +1,100 @@
+/**
+ * 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),
+    };
+  }
+}

package/src/engine/eviction.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 { EngramStore } from '../storage/sqlite.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.
+   */
+  enforceCapacity(agentId: string, config: AgentConfig): { evicted: number; edgesPruned: number } {
+    let evicted = 0;
+    let edgesPruned = 0;
+
+    // Active engram budget
+    const activeCount = this.store.getActiveCount(agentId);
+    if (activeCount > config.maxActiveEngrams) {
+      const excess = activeCount - config.maxActiveEngrams;
+      const candidates = this.store.getEvictionCandidates(agentId, excess);
+      for (const engram of candidates) {
+        this.store.updateStage(engram.id, 'archived');
+        evicted++;
+      }
+    }
+
+    // Staging budget
+    const stagingCount = this.store.getStagingCount(agentId);
+    if (stagingCount > config.maxStagingEngrams) {
+      const expired = this.store.getExpiredStaging();
+      for (const engram of expired) {
+        this.store.deleteEngram(engram.id);
+        evicted++;
+      }
+    }
+
+    // Edge pruning — cap per engram
+    const engrams = this.store.getEngramsByAgent(agentId, 'active');
+    for (const engram of engrams) {
+      const edgeCount = 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 = this.store.getWeakestAssociation(engram.id);
+          if (weakest) {
+            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).
+   */
+  decayEdges(agentId: string, halfLifeDays: number = 7): number {
+    const associations = 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
+        this.store.deleteAssociation(assoc.id);
+        decayed++;
+      } else if (Math.abs(newWeight - assoc.weight) > 0.001) {
+        this.store.upsertAssociation(
+          assoc.fromEngramId, assoc.toEngramId, newWeight, assoc.type, assoc.confidence
+        );
+        decayed++;
+      }
+    }
+
+    return decayed;
+  }
+}

package/src/engine/index.ts

@@ -0,0 +1,6 @@
+export * from './activation.js';
+export * from './staging.js';
+export * from './connections.js';
+export * from './eviction.js';
+export * from './retraction.js';
+export * from './eval.js';

package/src/engine/retraction.ts

@@ -0,0 +1,98 @@
+/**
+ * Retraction Engine — negative memory / invalidation.
+ *
+ * Codex critique: "You need explicit anti-salience for wrong info.
+ * Otherwise wrong memories persist and compound mistakes."
+ *
+ * When an agent discovers a memory is wrong:
+ *   1. The original engram is marked retracted (not deleted — audit trail)
+ *   2. An invalidation association is created
+ *   3. Optionally, a counter-engram with correct info is created
+ *   4. Confidence of associated engrams is reduced (contamination check)
+ */
+
+import type { EngramStore } from '../storage/sqlite.js';
+import type { Retraction } from '../types/index.js';
+
+export class RetractionEngine {
+  private store: EngramStore;
+
+  constructor(store: EngramStore) {
+    this.store = store;
+  }
+
+  /**
+   * Retract a memory — mark it invalid and optionally create a correction.
+   */
+  retract(retraction: Retraction): { retractedId: string; correctionId: string | null; associatesAffected: number } {
+    const target = this.store.getEngram(retraction.targetEngramId);
+    if (!target) {
+      throw new Error(`Engram ${retraction.targetEngramId} not found`);
+    }
+
+    // Mark the original as retracted
+    this.store.retractEngram(target.id, null);
+
+    let correctionId: string | null = null;
+
+    // Create counter-engram if correction content provided
+    if (retraction.counterContent) {
+      const correction = this.store.createEngram({
+        agentId: retraction.agentId,
+        concept: `correction:${target.concept}`,
+        content: retraction.counterContent,
+        tags: [...target.tags, 'correction', 'retraction'],
+        salience: Math.max(target.salience, 0.6), // Corrections are at least moderately salient
+        confidence: 0.7,
+        reasonCodes: ['retraction_correction', `invalidates:${target.id}`],
+      });
+
+      correctionId = correction.id;
+
+      // Create invalidation link
+      this.store.upsertAssociation(
+        correction.id, target.id, 1.0, 'invalidation', 1.0
+      );
+
+      // Update retracted_by to point to correction
+      this.store.retractEngram(target.id, correction.id);
+    }
+
+    // Reduce confidence of closely associated engrams (contamination spread)
+    const associatesAffected = this.propagateConfidenceReduction(target.id, 0.1, 1);
+
+    return { retractedId: target.id, correctionId, associatesAffected };
+  }
+
+  /**
+   * Reduce confidence of engrams associated with a retracted engram.
+   * Shallow propagation (depth 1) to avoid over-penalizing.
+   */
+  private propagateConfidenceReduction(
+    engramId: string,
+    penalty: number,
+    maxDepth: number,
+    currentDepth: number = 0
+  ): number {
+    if (currentDepth >= maxDepth) return 0;
+
+    let affected = 0;
+    const associations = this.store.getAssociationsFor(engramId);
+    for (const assoc of associations) {
+      if (assoc.type === 'invalidation') continue; // Don't penalize corrections
+
+      const neighborId = assoc.fromEngramId === engramId
+        ? assoc.toEngramId
+        : assoc.fromEngramId;
+      const neighbor = this.store.getEngram(neighborId);
+      if (!neighbor || neighbor.retracted) continue;
+
+      // Scale penalty by association weight
+      const scaledPenalty = penalty * assoc.weight;
+      const newConfidence = Math.max(0.1, neighbor.confidence - scaledPenalty);
+      this.store.updateConfidence(neighborId, newConfidence);
+      affected++;
+    }
+    return affected;
+  }
+}

package/src/engine/staging.ts

@@ -0,0 +1,72 @@
+/**
+ * Staging Buffer — weak signal handler.
+ *
+ * Observations that don't meet the salience threshold for active memory
+ * go to staging. The staging buffer periodically:
+ *   1. Checks staged engrams against active memory for resonance
+ *   2. Promotes resonant engrams to active
+ *   3. Discards expired engrams that never resonated
+ *
+ * Modeled on hippocampal consolidation — provisional encoding
+ * that only persists if reactivated.
+ */
+
+import type { EngramStore } from '../storage/sqlite.js';
+import type { ActivationEngine } from './activation.js';
+
+export class StagingBuffer {
+  private store: EngramStore;
+  private engine: ActivationEngine;
+  private checkInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(store: EngramStore, engine: ActivationEngine) {
+    this.store = store;
+    this.engine = engine;
+  }
+
+  /**
+   * Start the periodic staging check.
+   */
+  start(intervalMs: number = 60_000): void {
+    this.checkInterval = setInterval(() => this.sweep(), intervalMs);
+  }
+
+  stop(): void {
+    if (this.checkInterval) {
+      clearInterval(this.checkInterval);
+      this.checkInterval = null;
+    }
+  }
+
+  /**
+   * Sweep staged engrams: promote or discard.
+   */
+  async sweep(): Promise<{ promoted: string[]; discarded: string[] }> {
+    const promoted: string[] = [];
+    const discarded: string[] = [];
+
+    const expired = this.store.getExpiredStaging();
+    for (const engram of expired) {
+      // Check if this engram resonates with active memory
+      const results = await this.engine.activate({
+        agentId: engram.agentId,
+        context: `${engram.concept} ${engram.content}`,
+        limit: 3,
+        minScore: 0.3,
+        internal: true,
+      });
+
+      if (results.length > 0) {
+        // Resonance found — promote to active
+        this.store.updateStage(engram.id, 'active');
+        promoted.push(engram.id);
+      } else {
+        // No resonance — discard
+        this.store.deleteEngram(engram.id);
+        discarded.push(engram.id);
+      }
+    }
+
+    return { promoted, discarded };
+  }
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import Fastify from 'fastify';
+
+// Load .env file if present (no external dependency)
+try {
+  const envPath = resolve(process.cwd(), '.env');
+  const envContent = readFileSync(envPath, 'utf-8');
+  for (const line of envContent.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    const val = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '');
+    if (!process.env[key]) process.env[key] = val; // Don't override existing env
+  }
+} catch { /* No .env file — that's fine */ }
+import { EngramStore } from './storage/sqlite.js';
+import { ActivationEngine } from './engine/activation.js';
+import { ConnectionEngine } from './engine/connections.js';
+import { StagingBuffer } from './engine/staging.js';
+import { EvictionEngine } from './engine/eviction.js';
+import { RetractionEngine } from './engine/retraction.js';
+import { EvalEngine } from './engine/eval.js';
+import { ConsolidationEngine } from './engine/consolidation.js';
+import { ConsolidationScheduler } from './engine/consolidation-scheduler.js';
+import { registerRoutes } from './api/routes.js';
+import { DEFAULT_AGENT_CONFIG } from './types/agent.js';
+import { getEmbedder } from './core/embeddings.js';
+import { getReranker } from './core/reranker.js';
+import { getExpander } from './core/query-expander.js';
+
+const PORT = parseInt(process.env.AWM_PORT ?? '8400', 10);
+const DB_PATH = process.env.AWM_DB_PATH ?? 'memory.db';
+const API_KEY = process.env.AWM_API_KEY ?? null;
+
+async function main() {
+  // Storage
+  const store = new EngramStore(DB_PATH);
+
+  // Engines
+  const activationEngine = new ActivationEngine(store);
+  const connectionEngine = new ConnectionEngine(store, activationEngine);
+  const stagingBuffer = new StagingBuffer(store, activationEngine);
+  const evictionEngine = new EvictionEngine(store);
+  const retractionEngine = new RetractionEngine(store);
+  const evalEngine = new EvalEngine(store);
+  const consolidationEngine = new ConsolidationEngine(store);
+  const consolidationScheduler = new ConsolidationScheduler(store, consolidationEngine);
+
+  // API
+  const app = Fastify({ logger: true });
+
+  // Bearer token auth — only enforced when AWM_API_KEY is set
+  if (API_KEY) {
+    app.addHook('onRequest', async (req, reply) => {
+      if (req.url === '/health') return; // Health check is always public
+      const bearer = req.headers.authorization;
+      const xApiKey = req.headers['x-api-key'] as string | undefined;
+      if (bearer === `Bearer ${API_KEY}` || xApiKey === API_KEY) return;
+      reply.code(401).send({ error: 'Unauthorized' });
+    });
+    console.log('API key auth enabled (AWM_API_KEY set)');
+  }
+
+  registerRoutes(app, {
+    store, activationEngine, connectionEngine,
+    evictionEngine, retractionEngine, evalEngine,
+    consolidationEngine, consolidationScheduler,
+  });
+
+  // Background tasks
+  stagingBuffer.start(DEFAULT_AGENT_CONFIG.stagingTtlMs);
+  consolidationScheduler.start();
+
+  // Pre-load ML models (downloads on first run: embeddings ~22MB, reranker ~22MB, expander ~80MB)
+  getEmbedder().catch(err => console.warn('Embedding model unavailable:', err.message));
+  getReranker().catch(err => console.warn('Reranker model unavailable:', err.message));
+  getExpander().catch(err => console.warn('Query expander model unavailable:', err.message));
+
+  // Start server
+  await app.listen({ port: PORT, host: '0.0.0.0' });
+  console.log(`AgentWorkingMemory v0.3.0 listening on port ${PORT}`);
+
+  // Graceful shutdown
+  const shutdown = () => {
+    consolidationScheduler.stop();
+    stagingBuffer.stop();
+    store.close();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch(err => {
+  console.error('Failed to start:', err);
+  process.exit(1);
+});