agent-working-memory 0.7.9 → 0.7.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-working-memory",
-  "version": "0.7.9",
+  "version": "0.7.11",
   "description": "Cognitive memory layer for AI agents — activation-based retrieval, salience filtering, associative connections",
   "type": "module",
   "main": "dist/index.js",

package/src/api/routes.ts

@@ -705,7 +705,7 @@ export function registerRoutes(app: FastifyInstance, deps: MemoryDeps): void {
     const base: Record<string, unknown> = {
       status: 'ok',
       timestamp: new Date().toISOString(),
-      version: '0.7.9',
+      version: '0.7.11',
       coordination: coordEnabled,
     };
     if (coordEnabled) {

package/src/cli.ts

@@ -334,7 +334,7 @@ async function exportMemories() {
   const agents = [...new Set(memories.map((m: any) => m.agent_id))];
 
   const exportData = {
-    version: '0.7.9',
+    version: '0.7.11',
     exported_at: new Date().toISOString(),
     source_db: dbPath,
     agent_filter: agentFilter,

package/src/core/query-expander.ts

@@ -37,12 +37,60 @@ export async function getExpander(): Promise<Text2TextGenerationPipeline> {
   return initPromise;
 }
 
+/**
+ * LRU cache of normalized-query → expanded-query mappings.
+ * Map preserves insertion order — re-set on hit moves entry to the end (most-recent),
+ * delete-first when over capacity drops the least-recent. ~500 entries × ~200 chars
+ * each ≈ 100KB, negligible memory cost.
+ *
+ * Why: phase-breakdown spike (2026-05-08) showed expandQuery at ~164ms per call.
+ * Agent recall patterns repeat — cache hits are common.
+ */
+const expansionCache = new Map<string, string>();
+const EXPANSION_CACHE_LIMIT = 500;
+
+/**
+ * Heuristic: skip expansion when the query is already specific.
+ * Long, multi-token queries don't benefit from synonyms — they're already
+ * narrow enough that flan-t5's general-vocabulary expansion adds noise more
+ * than recall. Exact thresholds are conservative; false-skips would only
+ * affect candidates that BM25 catches anyway.
+ */
+function shouldSkipExpansion(normalized: string): boolean {
+  if (normalized.length === 0) return true;
+  if (normalized.length > 50) return true;
+  // ≥5 distinct meaningful tokens = already specific
+  const tokens = new Set(normalized.split(/\s+/).filter(t => t.length > 2));
+  return tokens.size >= 5;
+}
+
 /**
  * Expand a query with related terms and synonyms.
  * Returns the original query + generated expansion terms.
  * Falls back to the original query on any error.
+ *
+ * Optimization (0.7.11+):
+ * - Skip heuristic for long/specific queries (~30% of typical agent recalls)
+ * - LRU cache for repeated queries (cache hit ≈ 0ms vs 164ms cold)
+ * - Disable both via AWM_DISABLE_EXPANSION_CACHE=1
  */
 export async function expandQuery(originalQuery: string): Promise<string> {
+  const normalized = originalQuery.toLowerCase().trim();
+  const optimizationsEnabled = process.env.AWM_DISABLE_EXPANSION_CACHE !== '1';
+
+  if (optimizationsEnabled) {
+    if (shouldSkipExpansion(normalized)) {
+      return originalQuery;
+    }
+    const cached = expansionCache.get(normalized);
+    if (cached !== undefined) {
+      // Move to end (most-recent) for LRU semantics
+      expansionCache.delete(normalized);
+      expansionCache.set(normalized, cached);
+      return cached;
+    }
+  }
+
   try {
     const expander = await getExpander();
     const prompt = `Expand this search query with synonyms and related terms. Only output the additional terms, not the original query. Query: ${originalQuery}. Additional terms:`;
@@ -55,11 +103,26 @@ export async function expandQuery(originalQuery: string): Promise<string> {
     const expanded = Array.isArray(result) ? (result[0] as any)?.generated_text ?? '' : '';
     const cleanExpanded = expanded.trim();
 
-    if (cleanExpanded && cleanExpanded.length > 2) {
-      return `${originalQuery} ${cleanExpanded}`;
+    const finalQuery = cleanExpanded && cleanExpanded.length > 2
+      ? `${originalQuery} ${cleanExpanded}`
+      : originalQuery;
+
+    // Cache the result (LRU eviction when over capacity)
+    if (optimizationsEnabled) {
+      if (expansionCache.size >= EXPANSION_CACHE_LIMIT) {
+        const oldestKey = expansionCache.keys().next().value;
+        if (oldestKey !== undefined) expansionCache.delete(oldestKey);
+      }
+      expansionCache.set(normalized, finalQuery);
     }
-    return originalQuery;
+
+    return finalQuery;
   } catch {
     return originalQuery;
   }
 }
+
+/** Clear the expansion cache (used by tests + cache invalidation if needed). */
+export function clearExpansionCache(): void {
+  expansionCache.clear();
+}

package/src/engine/activation.ts

@@ -577,7 +577,33 @@ export class ActivationEngine {
     // Widens the pool to find relevant results that keyword matching missed
     const rerankPool = pool.slice(0, Math.max(limit * 3, 30));
 
-    if (useReranker && rerankPool.length > 0) {
+    // Reranker skip heuristic (0.7.10+): if BM25 already has a clear winner with
+    // strong absolute score AND a meaningful gap to the runner-up, the cross-encoder
+    // is unlikely to change the top result. Skipping saves ~300ms of wall-clock per
+    // recall on simple queries (40% of post-0.7.9 floor was reranker).
+    //
+    // Conservative gate (only skip when very confident):
+    //   - top-1 textMatch >= 0.8 (high BM25 + jaccard agreement)
+    //   - top-1 score is at least 1.5× top-2 score (clear separation)
+    //   - rerankPool size <= limit*2 (small pool — reranker has less to do)
+    //
+    // Ambiguous queries (close BM25 scores, weak top-1, large pool) still go through
+    // the reranker. Disable this heuristic via AWM_DISABLE_RERANK_SKIP=1.
+    let rerankSkipped = false;
+    if (useReranker && rerankPool.length >= 2 && process.env.AWM_DISABLE_RERANK_SKIP !== '1') {
+      const top1 = rerankPool[0];
+      const top2 = rerankPool[1];
+      const t1Text = top1.phaseScores.textMatch;
+      const t1Score = top1.score;
+      const t2Score = top2.score;
+      const cleanWinner = t1Text >= 0.8 && t1Score >= 1.5 * Math.max(t2Score, 0.01);
+      const smallPool = rerankPool.length <= Math.max(limit * 2, 20);
+      if (cleanWinner && smallPool) {
+        rerankSkipped = true;
+      }
+    }
+
+    if (useReranker && !rerankSkipped && rerankPool.length > 0) {
       try {
         const passages = rerankPool.map(r =>
           `${r.engram.concept}: ${r.engram.content}`

package/src/index.ts

@@ -177,7 +177,7 @@ async function main() {
 
   // Start server
   await app.listen({ port: PORT, host: '0.0.0.0' });
-  console.log(`AgentWorkingMemory v0.7.9 listening on port ${PORT}`);
+  console.log(`AgentWorkingMemory v0.7.11 listening on port ${PORT}`);
 
   // Graceful shutdown
   const shutdown = async () => {

package/src/mcp.ts

@@ -78,7 +78,7 @@ const INCOGNITO = process.env.AWM_INCOGNITO === '1' || process.env.AWM_INCOGNITO
 
 if (INCOGNITO) {
   console.error('AWM: incognito mode — all memory tools disabled, nothing will be recorded');
-  const server = new McpServer({ name: 'agent-working-memory', version: '0.7.9' });
+  const server = new McpServer({ name: 'agent-working-memory', version: '0.7.11' });
   const transport = new StdioServerTransport();
   server.connect(transport).catch(err => {
     console.error('MCP server failed:', err);
@@ -115,7 +115,7 @@ let coordDb: import('better-sqlite3').Database | null = null;
 
 const server = new McpServer({
   name: 'agent-working-memory',
-  version: '0.7.9',
+  version: '0.7.11',
 });
 
 server.registerResource(

package/src/storage/sqlite.ts

@@ -28,10 +28,33 @@ const DEFAULT_SALIENCE_FEATURES: SalienceFeatures = {
   surprise: 0, decisionMade: false, causalDepth: 0, resolutionEffort: 0, eventType: 'observation',
 };
 
+/**
+ * In-memory slim entry — the minimum data the activation pipeline's pre-filter
+ * pass reads. Lives in EngramStore.slimCache to skip the SQL fetch + Buffer→
+ * Float32Array conversion on every recall. ~22 bytes overhead per entry plus
+ * the embedding (~1.5KB), so ~15MB at 10K engrams.
+ */
+type SlimCacheEntry = {
+  id: string;
+  agentId: string;
+  concept: string;
+  embedding: number[] | null;
+  stage: EngramStage;
+  retracted: boolean;
+};
+
 export class EngramStore {
   private db: Database.Database;
   private walTimer: ReturnType<typeof setInterval> | null = null;
 
+  // Slim cache for the activation pipeline pre-filter. Populated lazily on
+  // first call to getEngramsByAgentSlim(). Mutations to engrams keep this in
+  // sync via private cache* helpers. Disable via AWM_DISABLE_SLIM_CACHE=1
+  // (for A/B testing or if a regression appears).
+  private slimCache: Map<string, SlimCacheEntry> = new Map();
+  private slimCachePopulated: boolean = false;
+  private slimCacheEnabled: boolean = process.env.AWM_DISABLE_SLIM_CACHE !== '1';
+
   constructor(dbPath: string = 'memory.db') {
     this.db = new Database(dbPath);
     this.db.pragma('journal_mode = WAL');
@@ -43,6 +66,62 @@ export class EngramStore {
     this.startWalCheckpointTimer();
   }
 
+  // --- Slim cache management ---
+
+  /** Lazy-populate the slim cache from the engrams table. Called on first slim fetch. */
+  private ensureSlimCachePopulated(): void {
+    if (this.slimCachePopulated || !this.slimCacheEnabled) return;
+    const rows = this.db.prepare(
+      'SELECT id, agent_id, concept, embedding, stage, retracted FROM engrams'
+    ).all() as any[];
+    for (const r of rows) {
+      this.slimCache.set(r.id as string, {
+        id: r.id as string,
+        agentId: r.agent_id as string,
+        concept: r.concept as string,
+        embedding: r.embedding ? Array.from(bufferToFloat32Array(r.embedding)) : null,
+        stage: r.stage as EngramStage,
+        retracted: !!r.retracted,
+      });
+    }
+    this.slimCachePopulated = true;
+  }
+
+  /** Add a new engram to the slim cache. Called from createEngram. */
+  private cacheAdd(entry: SlimCacheEntry): void {
+    if (!this.slimCacheEnabled) return;
+    this.slimCache.set(entry.id, entry);
+  }
+
+  private cacheUpdateStage(id: string, stage: EngramStage): void {
+    if (!this.slimCacheEnabled) return;
+    const e = this.slimCache.get(id);
+    if (e) e.stage = stage;
+  }
+
+  private cacheUpdateEmbedding(id: string, embedding: number[]): void {
+    if (!this.slimCacheEnabled) return;
+    const e = this.slimCache.get(id);
+    if (e) e.embedding = embedding;
+  }
+
+  private cacheRetract(id: string): void {
+    if (!this.slimCacheEnabled) return;
+    const e = this.slimCache.get(id);
+    if (e) e.retracted = true;
+  }
+
+  private cacheRemove(id: string): void {
+    if (!this.slimCacheEnabled) return;
+    this.slimCache.delete(id);
+  }
+
+  /** Reset cache (used by tests + after timeWarp/bulk operations). */
+  resetSlimCache(): void {
+    this.slimCache.clear();
+    this.slimCachePopulated = false;
+  }
+
   /** Expose the raw database handle for the coordination module. */
   getDb(): Database.Database {
     return this.db;
@@ -306,6 +385,18 @@ export class EngramStore {
       input.memoryType ?? 'unclassified',
     );
 
+    // Add to slim cache (skip if not yet populated — first slim fetch will load it)
+    if (this.slimCachePopulated) {
+      this.cacheAdd({
+        id,
+        agentId: input.agentId,
+        concept: input.concept,
+        embedding: input.embedding ?? null,
+        stage: 'active',
+        retracted: false,
+      });
+    }
+
     return this.getEngram(id)!;
   }
 
@@ -344,6 +435,18 @@ export class EngramStore {
     stage?: EngramStage,
     includeRetracted: boolean = false
   ): Array<{ id: string; concept: string; embedding: number[] | null }> {
+    if (this.slimCacheEnabled) {
+      this.ensureSlimCachePopulated();
+      const result: Array<{ id: string; concept: string; embedding: number[] | null }> = [];
+      for (const entry of this.slimCache.values()) {
+        if (entry.agentId !== agentId) continue;
+        if (stage && entry.stage !== stage) continue;
+        if (!includeRetracted && entry.retracted) continue;
+        result.push({ id: entry.id, concept: entry.concept, embedding: entry.embedding });
+      }
+      return result;
+    }
+    // Cache disabled — fall back to direct SQL
     let query = 'SELECT id, concept, embedding FROM engrams WHERE agent_id = ?';
     const params: any[] = [agentId];
 
@@ -371,6 +474,19 @@ export class EngramStore {
     if (agentIds.length === 0) return [];
     if (agentIds.length === 1) return this.getEngramsByAgentSlim(agentIds[0], stage, includeRetracted);
 
+    if (this.slimCacheEnabled) {
+      this.ensureSlimCachePopulated();
+      const agentSet = new Set(agentIds);
+      const result: Array<{ id: string; concept: string; embedding: number[] | null }> = [];
+      for (const entry of this.slimCache.values()) {
+        if (!agentSet.has(entry.agentId)) continue;
+        if (stage && entry.stage !== stage) continue;
+        if (!includeRetracted && entry.retracted) continue;
+        result.push({ id: entry.id, concept: entry.concept, embedding: entry.embedding });
+      }
+      return result;
+    }
+
     const placeholders = agentIds.map(() => '?').join(',');
     let query = `SELECT id, concept, embedding FROM engrams WHERE agent_id IN (${placeholders})`;
     const params: any[] = [...agentIds];
@@ -513,6 +629,7 @@ export class EngramStore {
 
   updateStage(id: string, stage: EngramStage): void {
     this.db.prepare('UPDATE engrams SET stage = ? WHERE id = ?').run(stage, id);
+    this.cacheUpdateStage(id, stage);
   }
 
   updateConfidence(id: string, confidence: number): void {
@@ -528,16 +645,19 @@ export class EngramStore {
     } else {
       this.db.prepare('UPDATE engrams SET embedding = ? WHERE id = ?').run(blob, id);
     }
+    this.cacheUpdateEmbedding(id, embedding);
   }
 
   retractEngram(id: string, retractedBy: string | null): void {
     this.db.prepare(`
       UPDATE engrams SET retracted = 1, retracted_by = ?, retracted_at = ? WHERE id = ?
     `).run(retractedBy, new Date().toISOString(), id);
+    this.cacheRetract(id);
   }
 
   deleteEngram(id: string): void {
     this.db.prepare('DELETE FROM engrams WHERE id = ?').run(id);
+    this.cacheRemove(id);
   }
 
   /**