agent-working-memory 0.5.2 → 0.5.4

package/src/core/embeddings.ts

@@ -3,16 +3,20 @@
 /**
  * Embedding Engine — local vector embeddings via transformers.js
  *
- * Default: gte-small (384 dimensions, ~34MB int8, MTEB 61.4) for semantic similarity.
+ * Default: bge-small-en-v1.5 (384 dimensions, ~90MB, MTEB retrieval-optimized).
+ * Better short-text similarity than MiniLM for agent memory concepts.
  * Configurable via AWM_EMBED_MODEL env var.
  * Model is downloaded once on first use and cached locally.
  *
  * Singleton pattern — call getEmbedder() to get the shared instance.
+ *
+ * NOTE: Changing the model invalidates existing embeddings.
+ * Set AWM_EMBED_MODEL=Xenova/all-MiniLM-L6-v2 for backward compatibility.
  */
 
 import { pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers';
 
-const MODEL_ID = process.env.AWM_EMBED_MODEL ?? 'Xenova/all-MiniLM-L6-v2';
+const MODEL_ID = process.env.AWM_EMBED_MODEL ?? 'Xenova/bge-small-en-v1.5';
 const DIMENSIONS = parseInt(process.env.AWM_EMBED_DIMS ?? '384', 10);
 const POOLING = (process.env.AWM_EMBED_POOLING ?? 'mean') as 'cls' | 'mean';
 

package/src/core/salience.ts

@@ -166,3 +166,54 @@ export function computeNovelty(store: EngramStore, agentId: string, concept: str
     return 0.8;
   }
 }
+
+/**
+ * Result from novelty computation with match info for reinforcement.
+ */
+export interface NoveltyResult {
+  novelty: number;
+  matchedEngramId: string | null;
+  matchScore: number;
+}
+
+/**
+ * Compute novelty score AND return the best matching engram (for reinforcement-on-duplicate).
+ * Uses BM25 (synchronous, fast) to find the closest existing memory.
+ * Optionally checks workspace-scoped memories too (cross-agent dedup).
+ */
+export function computeNoveltyWithMatch(
+  store: EngramStore, agentId: string, concept: string, content: string,
+  workspace?: string | null
+): NoveltyResult {
+  try {
+    const contentStr = typeof content === 'string' ? content : '';
+    const conceptStr = typeof concept === 'string' ? concept : '';
+    const searchText = `${conceptStr} ${contentStr.slice(0, 100)}`;
+
+    // Agent-scoped search (limit:3 to avoid single shallow match suppressing novelty)
+    const results = store.searchBM25WithRank(agentId, searchText, 3);
+
+    // Workspace search — only if the store supports it (v0.5.4+)
+    let wsResults: { engram: { id: string }; bm25Score: number }[] = [];
+    if (workspace && typeof (store as any).searchBM25WithRankWorkspace === 'function') {
+      wsResults = (store as any).searchBM25WithRankWorkspace(agentId, searchText, 3, workspace);
+    }
+
+    const allResults = [...results, ...wsResults];
+    if (allResults.length === 0) return { novelty: 1.0, matchedEngramId: null, matchScore: 0 };
+
+    allResults.sort((a, b) => b.bm25Score - a.bm25Score);
+    const top = allResults[0];
+    const topScore = top.bm25Score;
+
+    // Concept penalty for exact duplicates
+    const conceptLower = conceptStr.toLowerCase().trim();
+    const exactMatch = allResults.some(r => (r.engram as any)?.concept?.toLowerCase().trim() === conceptLower);
+    const conceptPenalty = exactMatch ? 0.4 : 0;
+
+    const novelty = Math.max(0.1, Math.min(0.95, 1.0 - topScore - conceptPenalty));
+    return { novelty, matchedEngramId: top.engram.id, matchScore: topScore };
+  } catch {
+    return { novelty: 0.8, matchedEngramId: null, matchScore: 0 };
+  }
+}

package/src/engine/activation.ts

@@ -86,8 +86,27 @@ export class ActivationEngine {
     const useExpansion = query.useExpansion ?? true;
     const abstentionThreshold = query.abstentionThreshold ?? 0;
 
+    // Phase -1: Coref expansion — if query has pronouns, append recent entity names
+    // Helps conversational recall where "she/he/they/it" refers to a named entity.
+    let queryContext = query.context;
+    const pronounPattern = /\b(she|he|they|her|his|him|their|it|that|this|there)\b/i;
+    if (pronounPattern.test(queryContext)) {
+      // Pull recent entity names from the agent's most-accessed memories
+      try {
+        const recentEntities = this.store.getEngramsByAgent(query.agentId, 'active')
+          .sort((a, b) => b.accessCount - a.accessCount)
+          .slice(0, 10)
+          .flatMap(e => e.tags.filter(t => t.length >= 3 && !/^(session-|low-|D\d)/.test(t)))
+          .filter((v, i, a) => a.indexOf(v) === i)
+          .slice(0, 5);
+        if (recentEntities.length > 0) {
+          queryContext = `${queryContext} ${recentEntities.join(' ')}`;
+        }
+      } catch { /* non-fatal */ }
+    }
+
     // Phase 0: Query expansion — add related terms to improve BM25 recall
-    let searchContext = query.context;
+    let searchContext = queryContext;
     if (useExpansion) {
       try {
         searchContext = await expandQuery(query.context);
@@ -96,18 +115,35 @@ export class ActivationEngine {
       }
     }
 
-    // Phase 1: Embed original query for vector similarity (original, not expanded)
+    // Phase 1: Embed query for vector similarity (uses coref-expanded context)
     let queryEmbedding: number[] | null = null;
     try {
-      queryEmbedding = await embed(query.context);
+      queryEmbedding = await embed(queryContext);
     } catch {
       // Embedding unavailable — fall back to text-only matching
     }
 
-    // Phase 2: Parallel retrieval — BM25 with rank scores + all active engrams
-    // Use expanded query for BM25 (more terms = better keyword recall)
-    const bm25Ranked = this.store.searchBM25WithRank(query.agentId, searchContext, limit * 3);
-    const bm25ScoreMap = new Map(bm25Ranked.map(r => [r.engram.id, r.bm25Score]));
+    // Phase 2: Parallel retrieval — dual BM25 + all active engrams
+    // Two-pass BM25: (1) keyword-stripped query for precision, (2) expanded query for recall.
+    const keywordQuery = Array.from(tokenize(query.context)).join(' ');
+    const bm25Keyword = keywordQuery.length > 2
+      ? this.store.searchBM25WithRank(query.agentId, keywordQuery, limit * 3)
+      : [];
+    const bm25Expanded = this.store.searchBM25WithRank(query.agentId, searchContext, limit * 3);
+
+    // Merge: take the best BM25 score per engram from either pass
+    const bm25ScoreMap = new Map<string, number>();
+    const bm25EngramMap = new Map<string, any>();
+    for (const r of [...bm25Keyword, ...bm25Expanded]) {
+      const existing = bm25ScoreMap.get(r.engram.id) ?? 0;
+      if (r.bm25Score > existing) {
+        bm25ScoreMap.set(r.engram.id, r.bm25Score);
+        bm25EngramMap.set(r.engram.id, r.engram);
+      }
+    }
+    const bm25Ranked = Array.from(bm25EngramMap.entries()).map(([id, engram]) => ({
+      engram, bm25Score: bm25ScoreMap.get(id) ?? 0,
+    }));
 
     const allActive = this.store.getEngramsByAgent(
       query.agentId,
@@ -190,10 +226,12 @@ export class ActivationEngine {
 
       // --- Temporal signals ---
 
-      // ACT-R decay — confidence-modulated
-      // High-confidence memories (confirmed useful via feedback) decay slower.
-      // Default exponent: 0.5. At confidence 0.8+: 0.3 (much slower decay).
-      const decayExponent = 0.5 - 0.2 * Math.max(0, (engram.confidence - 0.5) / 0.5);
+      // ACT-R decay — confidence + replay modulated (synaptic tagging)
+      // High-confidence memories decay slower. Heavily-accessed memories also resist decay.
+      // Default exponent: 0.5. High confidence (0.8+): 0.3. High access (10+): further -0.05.
+      const confMod = 0.2 * Math.max(0, (engram.confidence - 0.5) / 0.5);
+      const replayMod = Math.min(0.1, 0.05 * Math.log1p(engram.accessCount));
+      const decayExponent = Math.max(0.2, 0.5 - confMod - replayMod);
       const decayScore = baseLevelActivation(engram.accessCount, ageDays, decayExponent);
 
       // Hebbian boost from associations — capped to prevent popular memories
@@ -401,20 +439,52 @@ export class ActivationEngine {
       }
     }
 
-    // Phase 8a: Semantic drift penalty — if no candidate has meaningful vector match
-    // (none exceeded 1 stddev above mean), the query is likely off-topic.
-    if (queryEmbedding && rerankPool.length > 0) {
-      const maxVectorSim = Math.max(...rerankPool.map(r => r.phaseScores.vectorMatch));
-      if (maxVectorSim < 0.05) {
-        // Query is semantically distant from everything — apply drift penalty
+    // Phase 8: Multi-channel OOD detection + agreement gate
+    // Requires at least 2 of 3 retrieval channels to agree the query is in-domain.
+    if (rerankPool.length >= 3) {
+      const topBM25 = Math.max(...rerankPool.map(r => bm25ScoreMap.get(r.engram.id) ?? 0));
+      const topVector = queryEmbedding
+        ? Math.max(...rerankPool.map(r => r.phaseScores.vectorMatch))
+        : 0;
+      const topReranker = Math.max(...rerankPool.map(r => r.phaseScores.rerankerScore));
+
+      const bm25Ok = topBM25 > 0.3;
+      const vectorOk = topVector > 0.05;
+      const rerankerOk = topReranker > 0.25;
+      const channelsAgreeing = (bm25Ok ? 1 : 0) + (vectorOk ? 1 : 0) + (rerankerOk ? 1 : 0);
+
+      const rerankerScores = rerankPool
+        .map(r => r.phaseScores.rerankerScore)
+        .sort((a, b) => b - a);
+      const margin = rerankerScores.length >= 2
+        ? rerankerScores[0] - rerankerScores[1]
+        : rerankerScores[0];
+
+      const maxRawCosine = queryEmbedding && simValues.length > 0
+        ? Math.max(...simValues)
+        : 1.0;
+
+      // Stricter gate when caller explicitly requests abstention (e.g., noise filter queries)
+      const requiredChannels = abstentionThreshold > 0 ? 3 : 2;
+
+      // Hard abstention: fewer than required channels agree AND semantic drift is high
+      if (channelsAgreeing < requiredChannels && maxRawCosine < (simMean + simStdDev * 1.5)) {
+        return [];
+      }
+
+      // Soft penalty: only 1 channel agrees or margin is thin
+      if (channelsAgreeing < 2 || margin < 0.05) {
+        // If caller explicitly requested abstention, honor it when agreement is weak
+        if (abstentionThreshold > 0) {
+          return [];
+        }
         for (const item of rerankPool) {
-          item.score *= 0.5;
+          item.score *= 0.4;
         }
       }
     }
 
-    // Phase 8b: Entropy gating — if top-5 reranker scores are flat (low variance),
-    // the reranker can't distinguish relevant from irrelevant. Abstain.
+    // Legacy abstention gate (when explicitly requested)
     if (abstentionThreshold > 0 && rerankPool.length >= 3) {
       const topRerankerScores = rerankPool
         .map(r => r.phaseScores.rerankerScore)
@@ -424,7 +494,6 @@ export class ActivationEngine {
       const meanScore = topRerankerScores.reduce((s, v) => s + v, 0) / topRerankerScores.length;
       const variance = topRerankerScores.reduce((s, v) => s + (v - meanScore) ** 2, 0) / topRerankerScores.length;
 
-      // Abstain if: top score below threshold OR scores are flat (low discrimination)
       if (maxScore < abstentionThreshold || (maxScore < 0.5 && variance < 0.01)) {
         return [];
       }

package/src/engine/consolidation-scheduler.ts

@@ -54,7 +54,7 @@ export class ConsolidationScheduler {
     this.running = true;
     try {
       console.log(`[scheduler] mini-consolidation for ${agentId}`);
-      this.consolidationEngine.consolidate(agentId);
+      await this.consolidationEngine.consolidate(agentId);
       this.store.markConsolidation(agentId, true);
     } catch (err) {
       console.error(`[scheduler] mini-consolidation failed for ${agentId}:`, err);
@@ -109,11 +109,11 @@ export class ConsolidationScheduler {
     }
   }
 
-  private runFullConsolidation(agentId: string, reason: string): void {
+  private async runFullConsolidation(agentId: string, reason: string): Promise<void> {
     this.running = true;
     try {
       console.log(`[scheduler] full consolidation for ${agentId} — trigger: ${reason}`);
-      const result = this.consolidationEngine.consolidate(agentId);
+      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) {

package/src/engine/consolidation.ts

@@ -25,9 +25,13 @@ import { strengthenAssociation, decayAssociation } from '../core/hebbian.js';
 import type { Engram } from '../types/index.js';
 import type { EngramStore } from '../storage/sqlite.js';
 
-/** Cosine similarity threshold for considering two memories related */
+/** Cosine similarity for initial candidate detection (single-link entry gate) */
 const SIMILARITY_THRESHOLD = 0.65;
 
+/** Minimum pairwise cosine for cluster diameter enforcement.
+ * Prevents chaining: a candidate must be this similar to ALL cluster members. */
+const MIN_PAIRWISE_COS = 0.50;
+
 /** Lower threshold for cross-cluster bridge edges */
 const BRIDGE_THRESHOLD = 0.25;
 
@@ -70,6 +74,12 @@ const REDUNDANCY_THRESHOLD = 0.85;
 /** Max redundant memories to prune per cycle (gradual, not sudden) */
 const MAX_REDUNDANCY_PRUNE_PER_CYCLE = 10;
 
+/** Max confidence drift per consolidation cycle (prevents runaway) */
+const CONFIDENCE_DRIFT_CAP = 0.03;
+
+/** Days without recall before confidence starts drifting down */
+const CONFIDENCE_NEGLECT_DAYS = 30;
+
 export interface ConsolidationResult {
   clustersFound: number;
   edgesStrengthened: number;
@@ -81,6 +91,7 @@ export interface ConsolidationResult {
   memoriesForgotten: number;
   memoriesArchived: number;
   redundancyPruned: number;
+  confidenceAdjusted: number;
   stagingPromoted: number;
   stagingDiscarded: number;
   engramsProcessed: number;
@@ -102,9 +113,10 @@ export class ConsolidationEngine {
    * Phase 4: Decay — weaken unused edges, prune dead ones
    * Phase 5: Homeostasis — normalize outgoing edge weights per node
    * Phase 6: Forget — archive/delete memories never retrieved (age-gated)
+   * Phase 6.7: Confidence drift — adjust confidence based on structural signals
    * Phase 7: Sweep — check staging buffer for resonance
    */
-  consolidate(agentId: string): ConsolidationResult {
+  async consolidate(agentId: string): Promise<ConsolidationResult> {
     const result: ConsolidationResult = {
       clustersFound: 0,
       edgesStrengthened: 0,
@@ -116,15 +128,29 @@ export class ConsolidationEngine {
       memoriesForgotten: 0,
       memoriesArchived: 0,
       redundancyPruned: 0,
+      confidenceAdjusted: 0,
       stagingPromoted: 0,
       stagingDiscarded: 0,
       engramsProcessed: 0,
     };
 
     // --- Phase 1: Replay ---
-    // Get all active engrams with embeddings
-    const engrams = this.store.getEngramsByAgent(agentId, 'active')
-      .filter(e => e.embedding && e.embedding.length > 0);
+    // Get all active engrams, backfill missing embeddings
+    const allActive = this.store.getEngramsByAgent(agentId, 'active');
+    const needsEmbedding = allActive.filter(e => !e.embedding || e.embedding.length === 0);
+    if (needsEmbedding.length > 0) {
+      try {
+        const { embed } = await import('../core/embeddings.js');
+        for (const e of needsEmbedding) {
+          try {
+            const vec = await embed(`${e.concept} ${e.content}`);
+            this.store.updateEmbedding(e.id, vec);
+            e.embedding = vec;
+          } catch { /* non-fatal */ }
+        }
+      } catch { /* embeddings module unavailable */ }
+    }
+    const engrams = allActive.filter(e => e.embedding && e.embedding.length > 0);
 
     result.engramsProcessed = engrams.length;
     if (engrams.length < 2) return result;
@@ -169,30 +195,32 @@ export class ConsolidationEngine {
       }
     }
 
-    // --- Phase 3: Cross-cluster bridge edges ---
-    // For each pair of clusters, compute centroid similarity. If moderate
-    // similarity exists but no direct edge, create a low-weight bridge.
-    // This is what enables cross-topic retrieval to improve over time.
+    // --- Phase 3: Direct cross-cluster bridging ---
+    // Find the closest pair of memories between each cluster pair and bridge them.
     if (clusters.length >= 2) {
+      const MIN_BRIDGE_SIM = 0.15;
       let bridges = 0;
-      const centroids = clusters.map(cluster => this.computeCentroid(cluster));
-
       for (let i = 0; i < clusters.length && bridges < MAX_BRIDGE_EDGES_PER_CYCLE; i++) {
         for (let j = i + 1; j < clusters.length && bridges < MAX_BRIDGE_EDGES_PER_CYCLE; j++) {
-          const sim = cosineSimilarity(centroids[i], centroids[j]);
-          if (sim < BRIDGE_THRESHOLD || sim >= SIMILARITY_THRESHOLD) continue;
-
-          // Find the best representative from each cluster (highest accessCount)
-          const repA = clusters[i].reduce((best, e) => e.accessCount > best.accessCount ? e : best);
-          const repB = clusters[j].reduce((best, e) => e.accessCount > best.accessCount ? e : best);
-
-          const existing = this.store.getAssociation(repA.id, repB.id);
-          if (!existing) {
-            // Bridge weight proportional to inter-cluster similarity
-            const bridgeWeight = 0.15 + 0.15 * ((sim - BRIDGE_THRESHOLD) / (SIMILARITY_THRESHOLD - BRIDGE_THRESHOLD));
-            this.store.upsertAssociation(repA.id, repB.id, bridgeWeight, 'bridge');
-            bridges++;
-            result.bridgesCreated++;
+          let bestSim = -1;
+          let bestA: Engram | null = null;
+          let bestB: Engram | null = null;
+          for (const a of clusters[i]) {
+            if (!a.embedding) continue;
+            for (const b of clusters[j]) {
+              if (!b.embedding) continue;
+              const s = cosineSimilarity(a.embedding, b.embedding);
+              if (s > bestSim) { bestSim = s; bestA = a; bestB = b; }
+            }
+          }
+          if (bestA && bestB && bestSim > MIN_BRIDGE_SIM) {
+            const existing = this.store.getAssociation(bestA.id, bestB.id);
+            if (!existing) {
+              this.store.upsertAssociation(bestA.id, bestB.id, bestSim, 'bridge');
+              this.store.upsertAssociation(bestB.id, bestA.id, bestSim, 'bridge');
+              bridges++;
+              result.bridgesCreated++;
+            }
           }
         }
       }
@@ -210,13 +238,20 @@ export class ConsolidationEngine {
         (Date.now() - assoc.lastActivated.getTime()) / (1000 * 60 * 60 * 24);
       if (daysSince < 0.5) continue; // Skip recently activated
 
-      // Confidence-modulated half-life: higher confidence = slower decay (capped at 3x)
-      // Base: 7 days. Conf 0.5 → 7 days. Conf 0.8 → ~15 days. Conf 1.0 → 21 days (3x).
-      // Cap prevents any edge from becoming immortal.
+      // Confidence + access-count modulated half-life (synaptic tagging for edges)
+      // Base: 7 days. High confidence (0.8+): up to 21 days.
+      // High access count: further extends half-life (log-scaled, capped at 2x boost).
       const fromConf = engramConfMap.get(assoc.fromEngramId) ?? 0.5;
       const toConf = engramConfMap.get(assoc.toEngramId) ?? 0.5;
       const maxConf = Math.max(fromConf, toConf);
-      const halfLifeDays = Math.min(7 * (1 + 2 * Math.max(0, (maxConf - 0.5) / 0.5)), 21);
+      const fromEngram = engrams.find(e => e.id === assoc.fromEngramId);
+      const toEngram = engrams.find(e => e.id === assoc.toEngramId);
+      const maxAccess = Math.max(fromEngram?.accessCount ?? 0, toEngram?.accessCount ?? 0);
+      const accessBoost = Math.min(2.0, 1.0 + 0.5 * Math.log1p(maxAccess));
+      const halfLifeDays = Math.min(
+        7 * (1 + 2 * Math.max(0, (maxConf - 0.5) / 0.5)) * accessBoost,
+        42 // Hard cap: 6 weeks max
+      );
 
       const newWeight = decayAssociation(assoc.weight, daysSince, halfLifeDays);
       if (newWeight < PRUNE_THRESHOLD) {
@@ -378,6 +413,57 @@ export class ConsolidationEngine {
     }
     result.redundancyPruned = redundancyCount;
 
+    // --- Phase 6.7: Confidence drift ---
+    // Adjust confidence based on structural signals that emerge from the graph.
+    // This makes confidence evolve over time without explicit feedback calls.
+    //
+    // Three signals:
+    //   1. Well-clustered memories (appeared in 1+ clusters) get a small boost
+    //      — they're integrated into the knowledge graph, likely valuable.
+    //   2. Isolated memories (0 edges after consolidation) get a small penalty
+    //      — nothing connects to them, possibly noise.
+    //   3. Neglected memories (not recalled in 30+ days) drift toward 0.3
+    //      — if the system never needs them, they're probably not important.
+    //
+    // All adjustments are capped at ±0.03 per cycle to prevent runaway.
+    // Confidence is floored at 0.15 (never reaches 0 — retraction handles that).
+    // Confidence is capped at 0.85 (only explicit feedback can push above).
+    const clusteredIds = new Set<string>();
+    for (const cluster of clusters) {
+      for (const e of cluster) clusteredIds.add(e.id);
+    }
+
+    for (const engram of engrams) {
+      let drift = 0;
+      const edgeCount = this.store.countAssociationsFor(engram.id);
+      const daysSinceAccess = (Date.now() - engram.lastAccessed.getTime()) / (1000 * 60 * 60 * 24);
+
+      // Signal 1: Cluster membership → small boost
+      if (clusteredIds.has(engram.id)) {
+        drift += 0.01;
+      }
+
+      // Signal 2: Zero edges → small penalty
+      if (edgeCount === 0) {
+        drift -= 0.02;
+      }
+
+      // Signal 3: Long neglect → drift toward 0.3
+      if (daysSinceAccess > CONFIDENCE_NEGLECT_DAYS && engram.confidence > 0.3) {
+        drift -= 0.01;
+      }
+
+      // Apply with cap
+      if (Math.abs(drift) > 0.001) {
+        drift = Math.max(-CONFIDENCE_DRIFT_CAP, Math.min(CONFIDENCE_DRIFT_CAP, drift));
+        const newConf = Math.max(0.15, Math.min(0.85, engram.confidence + drift));
+        if (Math.abs(newConf - engram.confidence) > 0.001) {
+          this.store.updateConfidence(engram.id, newConf);
+          result.confidenceAdjusted++;
+        }
+      }
+    }
+
     // --- Phase 7: Sweep staging ---
     const staging = this.store.getEngramsByAgent(agentId, 'staging')
       .filter(e => e.embedding && e.embedding.length > 0);
@@ -394,8 +480,9 @@ export class ConsolidationEngine {
       }
 
       if (maxSim >= 0.6) {
-        // Resonates — promote to active
+        // Resonates — promote to active with low confidence (barely made it)
         this.store.updateStage(staged.id, 'active');
+        this.store.updateConfidence(staged.id, 0.40);
         result.stagingPromoted++;
       } else if (ageMs > 24 * 60 * 60 * 1000) {
         // Over 24h and no resonance — discard
@@ -413,34 +500,66 @@ export class ConsolidationEngine {
    * Greedy agglomerative — each memory belongs to at most one cluster.
    * Clusters of size 2+ are returned (pairs count — they link).
    */
+  /**
+   * Diameter-enforced greedy clustering.
+   * Single-link entry (cosine ≥ SIMILARITY_THRESHOLD to any member)
+   * + complete-link diameter (cosine ≥ MIN_PAIRWISE_COS to ALL members).
+   * Prevents chaining where physics→biophysics→cooking = 1 cluster.
+   */
   private findClusters(engrams: Engram[]): Engram[][] {
-    const assigned = new Set<string>();
+    const n = engrams.length;
+    if (n < 2) return [];
+
+    // Precompute pairwise cosine matrix
+    const sim: number[][] = Array.from({ length: n }, () => Array(n).fill(0));
+    for (let i = 0; i < n; i++) {
+      sim[i][i] = 1;
+      for (let j = i + 1; j < n; j++) {
+        if (!engrams[i].embedding || !engrams[j].embedding) continue;
+        const c = cosineSimilarity(engrams[i].embedding!, engrams[j].embedding!);
+        sim[i][j] = c;
+        sim[j][i] = c;
+      }
+    }
+
+    const unassigned = new Set<number>(Array.from({ length: n }, (_, i) => i));
     const clusters: Engram[][] = [];
 
-    // Seed clusters from most-accessed memories (strongest traces)
-    const sorted = [...engrams].sort((a, b) => b.accessCount - a.accessCount);
+    const sortedIdxs = Array.from({ length: n }, (_, i) => i)
+      .sort((a, b) => engrams[b].accessCount - engrams[a].accessCount);
+
+    for (const seedIdx of sortedIdxs) {
+      if (!unassigned.has(seedIdx)) continue;
+      unassigned.delete(seedIdx);
 
-    for (const seed of sorted) {
-      if (assigned.has(seed.id)) continue;
+      const clusterIdxs: number[] = [seedIdx];
+      let added = true;
 
-      const cluster: Engram[] = [seed];
-      assigned.add(seed.id);
+      while (added) {
+        added = false;
+        for (const candIdx of Array.from(unassigned)) {
+          let links = false;
+          for (const m of clusterIdxs) {
+            if (sim[candIdx][m] >= SIMILARITY_THRESHOLD) { links = true; break; }
+          }
+          if (!links) continue;
 
-      for (const candidate of sorted) {
-        if (assigned.has(candidate.id)) continue;
-        if (!seed.embedding || !candidate.embedding) continue;
+          let passesAll = true;
+          for (const m of clusterIdxs) {
+            if (sim[candIdx][m] < MIN_PAIRWISE_COS) { passesAll = false; break; }
+          }
+          if (!passesAll) continue;
 
-        const sim = cosineSimilarity(seed.embedding, candidate.embedding);
-        if (sim >= SIMILARITY_THRESHOLD) {
-          cluster.push(candidate);
-          assigned.add(candidate.id);
+          clusterIdxs.push(candIdx);
+          unassigned.delete(candIdx);
+          added = true;
         }
       }
 
-      if (cluster.length >= 2) {
-        clusters.push(cluster);
+      if (clusterIdxs.length >= 2) {
+        clusters.push(clusterIdxs.map(i => engrams[i]));
       } else {
-        for (const e of cluster) assigned.delete(e.id);
+        unassigned.add(seedIdx);
       }
     }
 

package/src/index.ts

@@ -1,7 +1,7 @@
 // Copyright 2026 Robert Winter / Complete Ideas
 // SPDX-License-Identifier: Apache-2.0
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { readFileSync, copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname, basename } from 'node:path';
 import Fastify from 'fastify';
 
 // Load .env file if present (no external dependency)
@@ -32,12 +32,31 @@ 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';
+import { initLogger } from './core/logger.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() {
+  // Auto-backup: copy DB to backups/ on startup (cheap insurance)
+  if (existsSync(DB_PATH)) {
+    const dbDir = dirname(resolve(DB_PATH));
+    const backupDir = resolve(dbDir, 'backups');
+    mkdirSync(backupDir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const backupPath = resolve(backupDir, `${basename(DB_PATH, '.db')}-${ts}.db`);
+    try {
+      copyFileSync(resolve(DB_PATH), backupPath);
+      console.log(`Backup: ${backupPath}`);
+    } catch (err) {
+      console.log(`Backup skipped: ${(err as Error).message}`);
+    }
+  }
+
+  // Logger — write activity to awm.log alongside the DB
+  initLogger(DB_PATH);
+
   // Storage
   const store = new EngramStore(DB_PATH);
 
@@ -54,8 +73,8 @@ async function main() {
   // API
   const app = Fastify({ logger: true });
 
-  // Bearer token auth — only enforced when AWM_API_KEY is set
-  if (API_KEY) {
+  // Bearer token auth — only enforced when AWM_API_KEY is explicitly set and non-empty
+  if (API_KEY && API_KEY !== 'NONE' && API_KEY.length > 1) {
     app.addHook('onRequest', async (req, reply) => {
       if (req.url === '/health') return; // Health check is always public
       const bearer = req.headers.authorization;
@@ -83,7 +102,7 @@ async function main() {
 
   // Start server
   await app.listen({ port: PORT, host: '0.0.0.0' });
-  console.log(`AgentWorkingMemory v0.3.0 listening on port ${PORT}`);
+  console.log(`AgentWorkingMemory v0.5.4 listening on port ${PORT}`);
 
   // Graceful shutdown
   const shutdown = () => {