agent-working-memory 0.7.0 → 0.7.2

package/src/core/auto-tagger.ts

@@ -0,0 +1,168 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Auto-Tagger — generates meta-tags for memories at write time.
+ *
+ * Meta-tags serve as categorical signals that boost BM25 recall.
+ * They're indexed in FTS5 alongside concept/content/tags, so queries
+ * that match a category tag get better BM25 scores.
+ *
+ * Three sources of tags:
+ * 1. Content analysis — extract topics, entities, categories from the text
+ * 2. Context propagation — inherit relevant tags from related memories
+ * 3. Type classification — fact/experience/belief/entity markers
+ *
+ * Design: lightweight heuristics, no LLM calls. Tags are additive —
+ * they enrich the existing tag set without replacing user-provided tags.
+ */
+
+/**
+ * Extract meta-tags from memory content using keyword patterns.
+ * Returns tags prefixed with 'cat:' to distinguish from user tags.
+ */
+export function extractMetaTags(concept: string, content: string): string[] {
+  const tags: string[] = [];
+  const text = `${concept} ${content}`.toLowerCase();
+
+  // --- Category tags (broad topic classification) ---
+
+  // People / personal
+  if (/\b(i |my |i'm |i've |we |our |me )\b/.test(text)) {
+    tags.push('cat:personal');
+  }
+
+  // Work / professional
+  if (/\b(work|job|office|meeting|project|team|manager|colleague|career|salary|hired)\b/.test(text)) {
+    tags.push('cat:work');
+  }
+
+  // Technology / computing
+  if (/\b(code|programming|software|database|api|server|deploy|bug|git|typescript|python|react|node)\b/.test(text)) {
+    tags.push('cat:tech');
+  }
+
+  // Health / wellness
+  if (/\b(health|doctor|exercise|yoga|gym|diet|sleep|meditation|therapy|medicine|symptom)\b/.test(text)) {
+    tags.push('cat:health');
+  }
+
+  // Finance / money
+  if (/\b(money|budget|savings|invest|salary|cost|price|payment|bank|credit|expense|coupon|store|bought|purchased)\b/.test(text)) {
+    tags.push('cat:finance');
+  }
+
+  // Home / living
+  if (/\b(home|house|apartment|room|kitchen|bedroom|furniture|garden|repair|renovation|neighbor|moved)\b/.test(text)) {
+    tags.push('cat:home');
+  }
+
+  // Travel / location
+  if (/\b(travel|trip|vacation|flight|hotel|restaurant|city|country|visited|downtown|park)\b/.test(text)) {
+    tags.push('cat:location');
+  }
+
+  // Education / learning
+  if (/\b(school|university|college|degree|course|class|study|learn|graduate|student|teacher|exam)\b/.test(text)) {
+    tags.push('cat:education');
+  }
+
+  // Social / relationships
+  if (/\b(friend|family|partner|spouse|child|parent|sibling|birthday|party|dinner|wedding|date)\b/.test(text)) {
+    tags.push('cat:social');
+  }
+
+  // Hobbies / entertainment
+  if (/\b(music|movie|book|game|sport|hobby|play|concert|theater|playlist|podcast|guitar|tennis|yoga|painting)\b/.test(text)) {
+    tags.push('cat:hobby');
+  }
+
+  // Shopping / consumer
+  if (/\b(bought|purchased|ordered|shop|store|amazon|target|walmart|coupon|sale|discount|delivery)\b/.test(text)) {
+    tags.push('cat:shopping');
+  }
+
+  // Food / cooking
+  if (/\b(cook|recipe|restaurant|meal|food|dinner|lunch|breakfast|coffee|tea|bake|kitchen)\b/.test(text)) {
+    tags.push('cat:food');
+  }
+
+  // Pets / animals
+  if (/\b(pet|dog|cat|animal|vet|shelter|walk|breed)\b/.test(text)) {
+    tags.push('cat:pets');
+  }
+
+  // Time markers
+  if (/\b(yesterday|today|last week|last month|tomorrow|next week|this morning|this evening|monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/.test(text)) {
+    tags.push('cat:temporal');
+  }
+
+  // --- Entity extraction (simple noun phrase patterns) ---
+
+  // Proper nouns (capitalized words that aren't sentence starters)
+  const properNouns = content.match(/(?:^|\.\s+)?([A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)/g);
+  if (properNouns) {
+    const unique = [...new Set(properNouns.map(n => n.trim()).filter(n => n.length > 2 && n.length < 30))];
+    for (const noun of unique.slice(0, 5)) {
+      tags.push(`entity:${noun}`);
+    }
+  }
+
+  // --- Knowledge type tags ---
+
+  // Preference (I like/prefer/enjoy/love/hate)
+  if (/\b(i like|i prefer|i enjoy|i love|i hate|my favorite|i don't like)\b/.test(text)) {
+    tags.push('cat:preference');
+  }
+
+  // Fact (declarative statements about identity/attributes)
+  if (/\b(my name is|i am a|i work at|i live in|i graduated|my birthday|i was born)\b/.test(text)) {
+    tags.push('cat:identity');
+  }
+
+  // Plan / intention
+  if (/\b(i plan to|i'm going to|i want to|i'm thinking of|i'm considering|next week i|planning to)\b/.test(text)) {
+    tags.push('cat:plan');
+  }
+
+  // Experience / event
+  if (/\b(i went|i visited|i attended|i tried|i saw|i heard|i found|i discovered)\b/.test(text)) {
+    tags.push('cat:experience');
+  }
+
+  return tags;
+}
+
+/**
+ * Propagate relevant tags from related memories to a new memory.
+ * Called after connection engine links the new memory to existing ones.
+ *
+ * Strategy: inherit meta-tags from strongly connected neighbors,
+ * but only tags that appear in 2+ neighbors (consensus filtering).
+ */
+export function propagateTagsFromNeighbors(
+  existingTags: string[],
+  neighborTagSets: string[][],
+): string[] {
+  if (neighborTagSets.length === 0) return [];
+
+  // Count meta-tag occurrences across neighbors
+  const tagCounts = new Map<string, number>();
+  for (const tags of neighborTagSets) {
+    for (const tag of tags) {
+      if (tag.startsWith('cat:') || tag.startsWith('entity:')) {
+        tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+      }
+    }
+  }
+
+  // Only propagate tags that appear in 2+ neighbors (consensus)
+  const propagated: string[] = [];
+  const existingSet = new Set(existingTags);
+  for (const [tag, count] of tagCounts) {
+    if (count >= 2 && !existingSet.has(tag)) {
+      propagated.push(tag);
+    }
+  }
+
+  return propagated.slice(0, 5); // Cap to avoid tag bloat
+}

package/src/core/query-expander.ts

@@ -15,7 +15,6 @@
 import { pipeline, type Text2TextGenerationPipeline } from '@huggingface/transformers';
 
 const MODEL_ID = 'Xenova/flan-t5-small';
-
 let instance: Text2TextGenerationPipeline | null = null;
 let initPromise: Promise<Text2TextGenerationPipeline> | null = null;
 

package/src/core/reranker.ts

@@ -23,7 +23,6 @@ import {
 
 const DEFAULT_MODEL = 'Xenova/ms-marco-MiniLM-L-6-v2';
 const MODEL_ID = process.env.AWM_RERANKER_MODEL || DEFAULT_MODEL;
-
 let tokenizer: PreTrainedTokenizer | null = null;
 let model: PreTrainedModel | null = null;
 let initPromise: Promise<void> | null = null;

package/src/engine/consolidation.ts

@@ -99,8 +99,19 @@ export interface ConsolidationResult {
   stagingPromoted: number;
   stagingDiscarded: number;
   engramsProcessed: number;
+  synthesesCreated: number;
 }
 
+const MAX_SYNTHESES_PER_CYCLE = 5;
+const MIN_CLUSTER_SIZE_FOR_SYNTHESIS = 3;
+
+/** Shared stopwords for synthesis keyword extraction */
+const SYNTH_STOPWORDS = new Set(['the', 'is', 'a', 'an', 'and', 'or', 'of', 'to', 'in', 'for',
+  'on', 'with', 'that', 'this', 'it', 'was', 'are', 'be', 'has', 'had', 'but', 'not', 'from',
+  'by', 'as', 'at', 'i', 'you', 'we', 'my', 'your', 'can', 'will', 'do', 'did', 'if', 'user',
+  'assistant', 'would', 'like', 'just', 'also', 'about', 'really', 'think', 'know', 'want',
+  'here', 'there', 'some', 'more', 'very', 'been', 'have', 'what', 'when', 'how', 'they']);
+
 export class ConsolidationEngine {
   private store: EngramStore;
 
@@ -136,6 +147,7 @@ export class ConsolidationEngine {
       stagingPromoted: 0,
       stagingDiscarded: 0,
       engramsProcessed: 0,
+      synthesesCreated: 0,
     };
 
     // --- Phase 1: Replay ---
@@ -208,6 +220,153 @@ export class ConsolidationEngine {
       }
     }
 
+    // --- Phase 2.5: Two types of synthesis ---
+    //
+    // Type A: SESSION SYNTHESIS (perfect recall)
+    //   Groups by shared metadata tags (sid=, proj=, topic=).
+    //   Summarizes what happened in a conversation/project session.
+    //   Helps find specific facts by providing a topical anchor.
+    //
+    // Type B: PATTERN SYNTHESIS (novel recall)
+    //   Uses the existing vector-similarity clusters.
+    //   Finds structural patterns across disparate topics.
+    //   "Debugging X by Y" + "Resolving A by B" → pattern: "conflict → ordering"
+    //   Lower confidence — these are speculative connections, not facts.
+
+    let synthCount = 0;
+
+    // --- Type A: Session synthesis (tag-based grouping) ---
+    // Group engrams by shared session/project tags, NOT vector similarity
+    const tagGroups = new Map<string, Engram[]>();
+    for (const e of engrams) {
+      if (e.tags.includes('synth=true')) continue; // Skip existing syntheses
+      for (const tag of e.tags) {
+        if (tag.startsWith('sid=') || tag.startsWith('proj=') || tag.startsWith('topic=')) {
+          const group = tagGroups.get(tag) ?? [];
+          group.push(e);
+          tagGroups.set(tag, group);
+        }
+      }
+    }
+
+    for (const [tag, group] of tagGroups) {
+      if (group.length < MIN_CLUSTER_SIZE_FOR_SYNTHESIS) continue;
+      if (synthCount >= MAX_SYNTHESES_PER_CYCLE) break;
+
+      // Check if a synthesis for this tag already exists
+      const existing = engrams.find(e =>
+        e.tags.includes('synth=true') && e.tags.includes(tag)
+      );
+      if (existing) continue;
+
+      // Extract key terms from this group
+      const wordCounts = new Map<string, number>();
+      for (const e of group) {
+        const words = e.content.toLowerCase().replace(/[^\w\s]/g, '').split(/\s+/);
+        for (const w of words) {
+          if (w.length > 3 && !SYNTH_STOPWORDS.has(w)) {
+            wordCounts.set(w, (wordCounts.get(w) ?? 0) + 1);
+          }
+        }
+      }
+      const keyTerms = [...wordCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 15)
+        .map(([word]) => word);
+
+      // Extract unique concepts (deduplicated)
+      const concepts = [...new Set(group.map(e => e.concept))];
+
+      const synthContent = [
+        `Session summary (${tag}, ${group.length} turns).`,
+        `Key topics: ${keyTerms.slice(0, 8).join(', ')}.`,
+        `Discussed: ${keyTerms.slice(8).join(', ')}.`,
+      ].join(' ');
+
+      const synthEngram = this.store.createEngram({
+        agentId,
+        concept: `session: ${tag} (${keyTerms.slice(0, 3).join(', ')})`,
+        content: synthContent,
+        tags: [tag, 'synth=true', 'synth-type=session'],
+        salience: 0.6,
+        confidence: 0.55,
+        memoryType: 'semantic',
+      });
+
+      // Set embedding to group centroid
+      const centroid = this.computeCentroid(group);
+      if (centroid.length > 0) {
+        this.store.updateEmbedding(synthEngram.id, centroid);
+      }
+
+      // Link to sources
+      for (const source of group.slice(0, 10)) { // Cap links to prevent explosion
+        this.store.upsertAssociation(synthEngram.id, source.id, 0.4, 'causal');
+      }
+
+      synthCount++;
+      result.synthesesCreated++;
+    }
+
+    // --- Type B: Pattern synthesis (vector-similarity clusters, speculative) ---
+    // Only create these for clusters where members come from DIFFERENT sessions/projects.
+    // This finds cross-domain patterns: "debugging technique A" + "architecture pattern B"
+    for (const cluster of clusters) {
+      if (cluster.length < MIN_CLUSTER_SIZE_FOR_SYNTHESIS) continue;
+      if (synthCount >= MAX_SYNTHESES_PER_CYCLE) break;
+      if (cluster.some(e => e.tags.includes('synth=true'))) continue;
+
+      // Only create pattern synthesis if cluster spans multiple sessions
+      const sessionTags = new Set<string>();
+      for (const e of cluster) {
+        for (const tag of e.tags) {
+          if (tag.startsWith('sid=') || tag.startsWith('proj=')) sessionTags.add(tag);
+        }
+      }
+      if (sessionTags.size < 2) continue; // Same session → skip (Type A handles it)
+
+      const wordCounts = new Map<string, number>();
+      for (const e of cluster) {
+        const words = e.content.toLowerCase().replace(/[^\w\s]/g, '').split(/\s+/);
+        for (const w of words) {
+          if (w.length > 3 && !SYNTH_STOPWORDS.has(w)) {
+            wordCounts.set(w, (wordCounts.get(w) ?? 0) + 1);
+          }
+        }
+      }
+      const keyTerms = [...wordCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([word]) => word);
+
+      const synthContent = [
+        `Pattern across ${sessionTags.size} sessions (${cluster.length} memories).`,
+        `Common themes: ${keyTerms.join(', ')}.`,
+      ].join(' ');
+
+      const synthEngram = this.store.createEngram({
+        agentId,
+        concept: `pattern: ${keyTerms.slice(0, 3).join(', ')}`,
+        content: synthContent,
+        tags: [...sessionTags, 'synth=true', 'synth-type=pattern'],
+        salience: 0.5,       // Lower — speculative
+        confidence: 0.4,     // Lower — these are hypotheses not facts
+        memoryType: 'semantic',
+      });
+
+      const centroid = this.computeCentroid(cluster);
+      if (centroid.length > 0) {
+        this.store.updateEmbedding(synthEngram.id, centroid);
+      }
+
+      for (const source of cluster.slice(0, 8)) {
+        this.store.upsertAssociation(synthEngram.id, source.id, 0.3, 'bridge');
+      }
+
+      synthCount++;
+      result.synthesesCreated++;
+    }
+
     // --- Phase 3: Direct cross-cluster bridging ---
     // Find the closest pair of memories between each cluster pair and bridge them.
     if (clusters.length >= 2) {
@@ -244,21 +403,18 @@ export class ConsolidationEngine {
     // that received positive feedback are more durable — just like how
     // practiced memories are more resistant to forgetting in the brain.
     // Base half-life: 7 days. High-confidence (0.8+) gets up to 30 days.
-    const engramConfMap = new Map(engrams.map(e => [e.id, e.confidence]));
+    const engramMap = new Map(engrams.map(e => [e.id, e]));
     const associations = this.store.getAllAssociations(agentId);
     for (const assoc of associations) {
       const daysSince =
         (Date.now() - assoc.lastActivated.getTime()) / (1000 * 60 * 60 * 24);
-      if (daysSince < 0.5) continue; // Skip recently activated
+      if (daysSince < 0.5) continue;
 
-      // 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 fromEngram = engramMap.get(assoc.fromEngramId);
+      const toEngram = engramMap.get(assoc.toEngramId);
+      const fromConf = fromEngram?.confidence ?? 0.5;
+      const toConf = toEngram?.confidence ?? 0.5;
       const maxConf = Math.max(fromConf, toConf);
-      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(