agent-working-memory 0.7.16 → 0.8.5

package/src/coordination/write-mutex.ts

@@ -1,69 +1,69 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Promise-based write mutex for SQLite coordination routes.
- *
- * SQLite only allows one writer at a time. Under burst from 5+ concurrent
- * workers, multiple async handlers can race for the write lock, causing
- * SQLITE_BUSY errors. This mutex serializes write operations (POST, PATCH,
- * PUT, DELETE) through a single-concurrency queue while keeping reads (GET)
- * unguarded for full parallelism.
- *
- * Usage: Register as a Fastify preHandler hook in the coordination module.
- */
-
-/**
- * Creates a simple single-concurrency mutex.
- * acquire() returns a release function — call it when done.
- */
-export function createWriteMutex(): {
-  acquire(): Promise<() => void>;
-  pending: () => number;
-} {
-  let queue: Array<(release: () => void) => void> = [];
-  let locked = false;
-
-  function release(): void {
-    const next = queue.shift();
-    if (next) {
-      // Hand lock directly to next waiter (no unlock/relock gap)
-      next(release);
-    } else {
-      locked = false;
-    }
-  }
-
-  function acquire(): Promise<() => void> {
-    if (!locked) {
-      locked = true;
-      return Promise.resolve(release);
-    }
-    return new Promise<() => void>((resolve) => {
-      queue.push(resolve);
-    });
-  }
-
-  return {
-    acquire,
-    pending: () => queue.length,
-  };
-}
-
-/** HTTP methods that perform writes and need serialization. */
-const WRITE_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
-
-/** Routes that are safe to skip the mutex (read-only despite POST method). */
-const READ_ONLY_ROUTES = new Set(['/next']);
-
-/**
- * Check if a request needs write serialization.
- * GET/HEAD/OPTIONS are always reads. POST /next is a read (checkin is idempotent upsert
- * but low-contention). All other write methods go through the mutex.
- */
-export function needsWriteLock(method: string, url: string): boolean {
-  if (!WRITE_METHODS.has(method)) return false;
-  // Strip query string for route matching
-  const path = url.split('?')[0];
-  if (READ_ONLY_ROUTES.has(path)) return false;
-  return true;
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Promise-based write mutex for SQLite coordination routes.
+ *
+ * SQLite only allows one writer at a time. Under burst from 5+ concurrent
+ * workers, multiple async handlers can race for the write lock, causing
+ * SQLITE_BUSY errors. This mutex serializes write operations (POST, PATCH,
+ * PUT, DELETE) through a single-concurrency queue while keeping reads (GET)
+ * unguarded for full parallelism.
+ *
+ * Usage: Register as a Fastify preHandler hook in the coordination module.
+ */
+
+/**
+ * Creates a simple single-concurrency mutex.
+ * acquire() returns a release function — call it when done.
+ */
+export function createWriteMutex(): {
+  acquire(): Promise<() => void>;
+  pending: () => number;
+} {
+  let queue: Array<(release: () => void) => void> = [];
+  let locked = false;
+
+  function release(): void {
+    const next = queue.shift();
+    if (next) {
+      // Hand lock directly to next waiter (no unlock/relock gap)
+      next(release);
+    } else {
+      locked = false;
+    }
+  }
+
+  function acquire(): Promise<() => void> {
+    if (!locked) {
+      locked = true;
+      return Promise.resolve(release);
+    }
+    return new Promise<() => void>((resolve) => {
+      queue.push(resolve);
+    });
+  }
+
+  return {
+    acquire,
+    pending: () => queue.length,
+  };
+}
+
+/** HTTP methods that perform writes and need serialization. */
+const WRITE_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
+
+/** Routes that are safe to skip the mutex (read-only despite POST method). */
+const READ_ONLY_ROUTES = new Set(['/next']);
+
+/**
+ * Check if a request needs write serialization.
+ * GET/HEAD/OPTIONS are always reads. POST /next is a read (checkin is idempotent upsert
+ * but low-contention). All other write methods go through the mutex.
+ */
+export function needsWriteLock(method: string, url: string): boolean {
+  if (!WRITE_METHODS.has(method)) return false;
+  // Strip query string for route matching
+  const path = url.split('?')[0];
+  if (READ_ONLY_ROUTES.has(path)) return false;
+  return true;
+}

package/src/core/auto-tagger.ts

@@ -1,168 +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
-}
+// 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/decay.ts

@@ -1,63 +1,63 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * ACT-R Base-Level Activation
- *
- * Based on Anderson's ACT-R cognitive architecture (1993).
- * Memories that are accessed more recently and more frequently
- * have higher activation — a well-established model of human memory.
- *
- * Formula: B(M) = ln(n + 1) - d * ln(ageDays / (n + 1))
- *
- * Where:
- *   n = access count
- *   d = decay exponent (default 0.5)
- *   ageDays = age of memory in days
- */
-
-export function baseLevelActivation(
-  accessCount: number,
-  ageDays: number,
-  decayExponent: number = 0.5
-): number {
-  const n = Math.max(accessCount, 0);
-  const age = Math.max(ageDays, 0.001); // Avoid log(0)
-  return Math.log(n + 1) - decayExponent * Math.log(age / (n + 1));
-}
-
-/**
- * Softplus — smooth approximation of ReLU.
- * Used to keep activation scores positive without hard clipping.
- */
-export function softplus(x: number): number {
-  return Math.log(1 + Math.exp(x));
-}
-
-/**
- * Composite activation score combining content match, temporal decay,
- * Hebbian boost, and confidence.
- *
- * Score = contentMatch * softplus(B(M) + scale * hebbianBoost) * confidence
- */
-export function compositeScore(params: {
-  contentMatch: number;
-  accessCount: number;
-  ageDays: number;
-  hebbianBoost: number;
-  confidence: number;
-  decayExponent?: number;
-  hebbianScale?: number;
-}): number {
-  const {
-    contentMatch,
-    accessCount,
-    ageDays,
-    hebbianBoost,
-    confidence,
-    decayExponent = 0.5,
-    hebbianScale = 1.0,
-  } = params;
-
-  const bm = baseLevelActivation(accessCount, ageDays, decayExponent);
-  return contentMatch * softplus(bm + hebbianScale * hebbianBoost) * confidence;
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ACT-R Base-Level Activation
+ *
+ * Based on Anderson's ACT-R cognitive architecture (1993).
+ * Memories that are accessed more recently and more frequently
+ * have higher activation — a well-established model of human memory.
+ *
+ * Formula: B(M) = ln(n + 1) - d * ln(ageDays / (n + 1))
+ *
+ * Where:
+ *   n = access count
+ *   d = decay exponent (default 0.5)
+ *   ageDays = age of memory in days
+ */
+
+export function baseLevelActivation(
+  accessCount: number,
+  ageDays: number,
+  decayExponent: number = 0.5
+): number {
+  const n = Math.max(accessCount, 0);
+  const age = Math.max(ageDays, 0.001); // Avoid log(0)
+  return Math.log(n + 1) - decayExponent * Math.log(age / (n + 1));
+}
+
+/**
+ * Softplus — smooth approximation of ReLU.
+ * Used to keep activation scores positive without hard clipping.
+ */
+export function softplus(x: number): number {
+  return Math.log(1 + Math.exp(x));
+}
+
+/**
+ * Composite activation score combining content match, temporal decay,
+ * Hebbian boost, and confidence.
+ *
+ * Score = contentMatch * softplus(B(M) + scale * hebbianBoost) * confidence
+ */
+export function compositeScore(params: {
+  contentMatch: number;
+  accessCount: number;
+  ageDays: number;
+  hebbianBoost: number;
+  confidence: number;
+  decayExponent?: number;
+  hebbianScale?: number;
+}): number {
+  const {
+    contentMatch,
+    accessCount,
+    ageDays,
+    hebbianBoost,
+    confidence,
+    decayExponent = 0.5,
+    hebbianScale = 1.0,
+  } = params;
+
+  const bm = baseLevelActivation(accessCount, ageDays, decayExponent);
+  return contentMatch * softplus(bm + hebbianScale * hebbianBoost) * confidence;
+}