agent-working-memory 0.4.2 → 0.4.3

package/src/core/decay.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * ACT-R Base-Level Activation
  *

package/src/core/embeddings.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Embedding Engine — local vector embeddings via transformers.js
  *

package/src/core/hebbian.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Hebbian Learning — "neurons that fire together wire together"
  *

package/src/core/index.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 export * from './decay.js';
 export * from './hebbian.js';
 export * from './salience.js';

package/src/core/logger.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Simple file logger for AWM activity.
  *

package/src/core/query-expander.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Query Expander — rewrites queries with synonyms and related terms.
  *

package/src/core/reranker.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Cross-Encoder Re-Ranker — scores (query, passage) pairs for relevance.
  *

package/src/core/salience.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Salience Filter — decides what's worth remembering.
  *
@@ -118,22 +120,24 @@ export function evaluateSalience(
  * The check is cheap (~1ms) because BM25 is synchronous SQLite FTS5.
  */
 export function computeNovelty(store: EngramStore, agentId: string, concept: string, content: string): number {
-  // Search using concept + first 100 chars of content (enough to detect duplicates, fast)
-  const searchText = `${concept} ${content.slice(0, 100)}`;
-
   try {
+    // Search using concept + first 100 chars of content (enough to detect duplicates, fast)
+    const contentStr = typeof content === 'string' ? content : '';
+    const conceptStr = typeof concept === 'string' ? concept : '';
+    const searchText = `${conceptStr} ${contentStr.slice(0, 100)}`;
+
     const results = store.searchBM25WithRank(agentId, searchText, 3);
     if (results.length === 0) return 1.0; // Nothing similar — fully novel
 
-    // BM25 scores are unbounded. Normalize the top score relative to a "strong match" threshold.
-    // A BM25 score > 15 typically indicates very high overlap. > 25 is near-duplicate.
+    // searchBM25WithRank normalizes scores to 0..1 via |rank|/(1+|rank|).
+    // Higher score = stronger match = less novel.
     const topScore = results[0].bm25Score;
 
-    if (topScore > 25) return 0.1;  // Near-duplicate
-    if (topScore > 15) return 0.3;  // High overlap
-    if (topScore > 8)  return 0.5;  // Moderate overlap
-    if (topScore > 3)  return 0.7;  // Some overlap
-    return 0.9;                      // Minimal overlap — mostly novel
+    if (topScore > 0.95) return 0.1;  // Near-duplicate
+    if (topScore > 0.85) return 0.3;  // High overlap
+    if (topScore > 0.70) return 0.5;  // Moderate overlap
+    if (topScore > 0.50) return 0.7;  // Some overlap
+    return 0.9;                        // Minimal overlap — mostly novel
   } catch {
     // If BM25 search fails (e.g., FTS not ready), assume novel
     return 0.8;

package/src/engine/activation.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Activation Pipeline — the core retrieval engine.
  *

package/src/engine/connections.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Connection Engine — discovers links between memories.
  *

package/src/engine/consolidation-scheduler.ts

@@ -1,123 +1,125 @@
-/**
- * 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}`);
-      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 runFullConsolidation(agentId: string, reason: string): void {
-    this.running = true;
-    try {
-      console.log(`[scheduler] full consolidation for ${agentId} — trigger: ${reason}`);
-      const result = 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}`);
+      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 runFullConsolidation(agentId: string, reason: string): void {
+    this.running = true;
+    try {
+      console.log(`[scheduler] full consolidation for ${agentId} — trigger: ${reason}`);
+      const result = 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/consolidation.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Sleep Cycle — offline memory consolidation.
  *
@@ -226,13 +228,19 @@ export class ConsolidationEngine {
     // --- Phase 5: Synaptic homeostasis ---
     // Normalize total outgoing edge weight per node to prevent hub explosion.
     // Nodes with many strong edges get scaled down so relative weights stay meaningful.
+    // Track processed edge IDs to avoid rescaling the same edge from both endpoints.
     const engramIds = new Set(engrams.map(e => e.id));
+    const processedEdgeIds = new Set<string>();
     for (const id of engramIds) {
-      const edges = this.store.getAssociationsFor(id);
-      const totalWeight = edges.reduce((sum, a) => sum + a.weight, 0);
+      // Only outgoing edges — filter to edges originating from this node
+      const allEdges = this.store.getAssociationsFor(id);
+      const outgoing = allEdges.filter(e => e.fromEngramId === id);
+      const totalWeight = outgoing.reduce((sum, a) => sum + a.weight, 0);
       if (totalWeight > HOMEOSTASIS_TARGET) {
         const scale = HOMEOSTASIS_TARGET / totalWeight;
-        for (const edge of edges) {
+        for (const edge of outgoing) {
+          if (processedEdgeIds.has(edge.id)) continue;
+          processedEdgeIds.add(edge.id);
           const newWeight = edge.weight * scale;
           if (newWeight < PRUNE_THRESHOLD) {
             this.store.deleteAssociation(edge.id);

package/src/engine/eval.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Evaluation Engine — measures whether memory actually helps.
  *

package/src/engine/eviction.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Eviction Engine — capacity enforcement and edge pruning.
  *

package/src/engine/index.ts

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

package/src/engine/retraction.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Retraction Engine — negative memory / invalidation.
  *

package/src/engine/staging.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Staging Buffer — weak signal handler.
  *

package/src/hooks/sidecar.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Hook Sidecar — lightweight HTTP server that runs alongside the MCP process.
  *

package/src/index.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import Fastify from 'fastify';

package/src/mcp.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * MCP Server — Model Context Protocol interface for AgentWorkingMemory.
  *

package/src/storage/index.ts

@@ -1 +1,3 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 export * from './sqlite.js';

package/src/storage/sqlite.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * SQLite storage layer — persistence for engrams, associations, and eval events.
  *
@@ -14,6 +16,14 @@ import type {
   ConsciousState, AutoCheckpoint, CheckpointRow,
 } from '../types/index.js';
 
+/** Safely convert a Node Buffer to Float32Array, respecting byteOffset/byteLength. */
+function bufferToFloat32Array(buf: Buffer | ArrayBuffer): Float32Array {
+  if (buf instanceof ArrayBuffer) return new Float32Array(buf);
+  // Node Buffer may share an underlying ArrayBuffer — slice to the exact region
+  const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  return new Float32Array(ab);
+}
+
 const DEFAULT_SALIENCE_FEATURES: SalienceFeatures = {
   surprise: 0, decisionMade: false, causalDepth: 0, resolutionEffort: 0, eventType: 'observation',
 };
@@ -641,7 +651,7 @@ export class EngramStore {
       concept: row.concept,
       content: row.content,
       embedding: row.embedding
-        ? Array.from(new Float32Array(row.embedding.buffer ?? row.embedding))
+        ? Array.from(bufferToFloat32Array(row.embedding))
         : null,
       confidence: row.confidence,
       salience: row.salience,
@@ -751,7 +761,7 @@ export class EngramStore {
       agentId: row.agent_id,
       label: row.label,
       embedding: row.embedding
-        ? Array.from(new Float32Array(row.embedding.buffer ?? row.embedding))
+        ? Array.from(bufferToFloat32Array(row.embedding))
         : null,
       engramCount: row.engram_count,
       startTime: new Date(row.start_time),

package/src/types/agent.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Agent — a consciousness boundary.
  * Each agent has its own isolated memory space with capacity budgets.

package/src/types/checkpoint.ts

@@ -1,44 +1,46 @@
-/**
- * Checkpoint types — conscious state preservation across compaction.
- *
- * ConsciousState: explicit structured snapshot (saved by agent)
- * AutoCheckpoint: implicit lightweight tracking (updated on every write/recall)
- */
-
-export interface ConsciousState {
-  currentTask: string;
-  decisions: string[];
-  activeFiles: string[];
-  nextSteps: string[];
-  relatedMemoryIds: string[];
-  notes: string;
-  episodeId: string | null;
-}
-
-export interface AutoCheckpoint {
-  lastWriteId: string | null;
-  lastRecallContext: string | null;
-  lastRecallIds: string[];
-  lastActivityAt: Date;
-  writeCountSinceConsolidation: number;
-  recallCountSinceConsolidation: number;
-}
-
-export interface CheckpointRow {
-  agentId: string;
-  auto: AutoCheckpoint;
-  executionState: ConsciousState | null;
-  checkpointAt: Date | null;
-  lastConsolidationAt: Date | null;
-  lastMiniConsolidationAt: Date | null;
-  updatedAt: Date;
-}
-
-export interface RestoreResult {
-  executionState: ConsciousState | null;
-  checkpointAt: Date | null;
-  recalledMemories: Array<{ id: string; concept: string; content: string; score: number }>;
-  lastWrite: { id: string; concept: string; content: string } | null;
-  idleMs: number;
-  miniConsolidationTriggered: boolean;
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Checkpoint types — conscious state preservation across compaction.
+ *
+ * ConsciousState: explicit structured snapshot (saved by agent)
+ * AutoCheckpoint: implicit lightweight tracking (updated on every write/recall)
+ */
+
+export interface ConsciousState {
+  currentTask: string;
+  decisions: string[];
+  activeFiles: string[];
+  nextSteps: string[];
+  relatedMemoryIds: string[];
+  notes: string;
+  episodeId: string | null;
+}
+
+export interface AutoCheckpoint {
+  lastWriteId: string | null;
+  lastRecallContext: string | null;
+  lastRecallIds: string[];
+  lastActivityAt: Date;
+  writeCountSinceConsolidation: number;
+  recallCountSinceConsolidation: number;
+}
+
+export interface CheckpointRow {
+  agentId: string;
+  auto: AutoCheckpoint;
+  executionState: ConsciousState | null;
+  checkpointAt: Date | null;
+  lastConsolidationAt: Date | null;
+  lastMiniConsolidationAt: Date | null;
+  updatedAt: Date;
+}
+
+export interface RestoreResult {
+  executionState: ConsciousState | null;
+  checkpointAt: Date | null;
+  recalledMemories: Array<{ id: string; concept: string; content: string; score: number }>;
+  lastWrite: { id: string; concept: string; content: string } | null;
+  idleMs: number;
+  miniConsolidationTriggered: boolean;
+}

package/src/types/engram.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Engram — the fundamental unit of agent memory.
  *

package/src/types/eval.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Evaluation types — measuring whether memory actually helps.
  *

package/src/types/index.ts

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 export * from './engram.js';
 export * from './agent.js';
 export * from './eval.js';