agent-working-memory 0.4.2 → 0.5.0

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.
  *
@@ -8,7 +10,7 @@
  *   - Deterministic heuristics first, LLM augmentation optional
  */
 
-import type { SalienceFeatures } from '../types/index.js';
+import type { SalienceFeatures, MemoryClass } from '../types/index.js';
 import type { EngramStore } from '../storage/sqlite.js';
 
 export type SalienceEventType = 'decision' | 'friction' | 'surprise' | 'causal' | 'observation';
@@ -22,6 +24,8 @@ export interface SalienceInput {
   resolutionEffort?: number;
   /** 0 = exact duplicate exists, 1 = completely novel. Computed by caller via BM25 similarity check. */
   novelty?: number;
+  /** Memory class — canonical memories get salience floor of 0.7 and never stage. */
+  memoryClass?: MemoryClass;
 }
 
 export interface SalienceResult {
@@ -90,10 +94,25 @@ export function evaluateSalience(
     case 'observation': break;
   }
 
-  const score = Math.min(surpriseScore + decisionScore + causalScore + effortScore + noveltyScore + typeBonus, 1.0);
+  let score = Math.min(surpriseScore + decisionScore + causalScore + effortScore + noveltyScore + typeBonus, 1.0);
+
+  // Memory class overrides
+  const memoryClass = input.memoryClass ?? 'working';
+
+  if (memoryClass === 'canonical') {
+    // Canonical memories: salience floor of 0.7, never go to staging
+    score = Math.max(score, 0.7);
+    reasonCodes.push('class:canonical');
+  } else if (memoryClass === 'ephemeral') {
+    reasonCodes.push('class:ephemeral');
+  }
 
   let disposition: 'active' | 'staging' | 'discard';
-  if (score >= activeThreshold) {
+  if (memoryClass === 'canonical') {
+    // Canonical always goes active — they represent current truth
+    disposition = 'active';
+    reasonCodes.push('disposition:active');
+  } else if (score >= activeThreshold) {
     disposition = 'active';
     reasonCodes.push('disposition:active');
   } else if (score >= stagingThreshold) {
@@ -118,22 +137,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.
  *
@@ -428,6 +430,14 @@ export class ActivationEngine {
       }
     }
 
+    // Phase 8c: Supersession penalty — superseded memories are deprioritized.
+    // They aren't wrong (that's retraction), just outdated.
+    for (const item of rerankPool) {
+      if (item.engram.supersededBy) {
+        item.score *= 0.15; // Severe down-rank — successor should dominate
+      }
+    }
+
     // Phase 9: Final sort, limit, explain
     const results: ActivationResult[] = rerankPool
       .sort((a, b) => b.score - a.score)

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.
  *
@@ -228,11 +230,11 @@ export class ConsolidationEngine {
     // Nodes with many strong edges get scaled down so relative weights stay meaningful.
     const engramIds = new Set(engrams.map(e => e.id));
     for (const id of engramIds) {
-      const edges = this.store.getAssociationsFor(id);
-      const totalWeight = edges.reduce((sum, a) => sum + a.weight, 0);
+      const outgoing = this.store.getOutgoingAssociations(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) {
           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,14 +1,17 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * MCP Server — Model Context Protocol interface for AgentWorkingMemory.
  *
  * Runs as a stdio-based MCP server that Claude Code connects to directly.
  * Uses the storage and engine layers in-process (no HTTP overhead).
  *
- * Tools exposed (11):
+ * Tools exposed (12):
  *   memory_write       — store a memory (salience filter decides disposition)
  *   memory_recall      — activate memories by context (cognitive retrieval)
  *   memory_feedback    — report whether a recalled memory was useful
  *   memory_retract     — invalidate a wrong memory with optional correction
+ *   memory_supersede   — replace an outdated memory with a current one
  *   memory_stats       — get memory health metrics
  *   memory_checkpoint  — save structured execution state (survives compaction)
  *   memory_restore     — restore state + targeted recall after compaction
@@ -134,6 +137,10 @@ The concept should be a short label (3-8 words). The content should be the full
       .describe('How deep is the causal understanding? 0=surface, 1=root cause'),
     resolution_effort: z.number().min(0).max(1).optional().default(0.3)
       .describe('How much effort to resolve? 0=trivial, 1=significant debugging'),
+    memory_class: z.enum(['canonical', 'working', 'ephemeral']).optional().default('working')
+      .describe('Memory class: canonical (source-of-truth, never stages), working (default), ephemeral (temporary, decays faster)'),
+    supersedes: z.string().optional()
+      .describe('ID of an older memory this one replaces. The old memory is down-ranked, not deleted.'),
   },
   async (params) => {
     // Check novelty — is this new information or a duplicate?
@@ -147,6 +154,7 @@ The concept should be a short label (3-8 words). The content should be the full
       causalDepth: params.causal_depth,
       resolutionEffort: params.resolution_effort,
       novelty,
+      memoryClass: params.memory_class,
     });
 
     if (salience.disposition === 'discard') {
@@ -168,6 +176,8 @@ The concept should be a short label (3-8 words). The content should be the full
       salienceFeatures: salience.features,
       reasonCodes: salience.reasonCodes,
       ttl: salience.disposition === 'staging' ? DEFAULT_AGENT_CONFIG.stagingTtlMs : undefined,
+      memoryClass: params.memory_class,
+      supersedes: params.supersedes,
     });
 
     if (salience.disposition === 'staging') {
@@ -176,6 +186,16 @@ The concept should be a short label (3-8 words). The content should be the full
       connectionEngine.enqueue(engram.id);
     }
 
+    // Handle supersession: mark old memory as superseded
+    if (params.supersedes) {
+      const oldEngram = store.getEngram(params.supersedes);
+      if (oldEngram) {
+        store.supersedeEngram(params.supersedes, engram.id);
+        // Create supersession association
+        store.upsertAssociation(engram.id, oldEngram.id, 0.8, 'causal', 0.9);
+      }
+    }
+
     // Generate embedding asynchronously (don't block response)
     embed(`${params.concept} ${params.content}`).then(vec => {
       store.updateEmbedding(engram.id, vec);
@@ -329,6 +349,50 @@ Use this when you discover a memory contains incorrect information.`,
   }
 );
 
+server.tool(
+  'memory_supersede',
+  `Replace an outdated memory with a newer one. Unlike retraction (which marks memories as wrong), supersession marks the old memory as outdated but historically correct.
+
+Use this when:
+- A status or count has changed (e.g., "5 reviews done" → "7 reviews done")
+- Architecture or infrastructure evolved (e.g., "two-repo model" → "three-repo model")
+- A schedule or plan was updated
+
+The old memory stays in the database (searchable for history) but is heavily down-ranked in recall so the current version dominates.`,
+  {
+    old_engram_id: z.string().describe('ID of the outdated memory'),
+    new_engram_id: z.string().describe('ID of the replacement memory'),
+    reason: z.string().optional().describe('Why the old memory is outdated'),
+  },
+  async (params) => {
+    const oldEngram = store.getEngram(params.old_engram_id);
+    if (!oldEngram) {
+      return { content: [{ type: 'text' as const, text: `Old memory not found: ${params.old_engram_id}` }] };
+    }
+    const newEngram = store.getEngram(params.new_engram_id);
+    if (!newEngram) {
+      return { content: [{ type: 'text' as const, text: `New memory not found: ${params.new_engram_id}` }] };
+    }
+
+    store.supersedeEngram(params.old_engram_id, params.new_engram_id);
+
+    // Create supersession association (new → old)
+    store.upsertAssociation(params.new_engram_id, params.old_engram_id, 0.8, 'causal', 0.9);
+
+    // Reduce old memory's confidence (not to zero — it's historical, not wrong)
+    store.updateConfidence(params.old_engram_id, Math.max(0.2, oldEngram.confidence * 0.4));
+
+    log(AGENT_ID, 'supersede', `"${oldEngram.concept}" → "${newEngram.concept}"${params.reason ? ` (${params.reason})` : ''}`);
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: `Superseded: "${oldEngram.concept}" → "${newEngram.concept}"`,
+      }],
+    };
+  }
+);
+
 server.tool(
   'memory_stats',
   `Get memory health stats — how many memories, confidence levels, association count, and system performance.
@@ -786,6 +850,8 @@ This captures what was accomplished so future sessions can recall it.`,
     summary: z.string().describe('What was accomplished? Include key outcomes, decisions, and any issues.'),
     tags: z.array(z.string()).optional().default([])
       .describe('Tags for the summary memory'),
+    supersedes: z.array(z.string()).optional().default([])
+      .describe('IDs of older memories this task summary replaces (marks them as superseded)'),
   },
   async (params) => {
     // 1. Write summary as a memory
@@ -810,6 +876,18 @@ This captures what was accomplished so future sessions can recall it.`,
 
     connectionEngine.enqueue(engram.id);
 
+    // 2. Handle supersessions — mark old memories as outdated
+    let supersededCount = 0;
+    for (const oldId of params.supersedes) {
+      const oldEngram = store.getEngram(oldId);
+      if (oldEngram) {
+        store.supersedeEngram(oldId, engram.id);
+        store.upsertAssociation(engram.id, oldId, 0.8, 'causal', 0.9);
+        store.updateConfidence(oldId, Math.max(0.2, oldEngram.confidence * 0.4));
+        supersededCount++;
+      }
+    }
+
     // Generate embedding asynchronously
     embed(`Task completed: ${params.summary}`).then(vec => {
       store.updateEmbedding(engram.id, vec);
@@ -830,12 +908,13 @@ This captures what was accomplished so future sessions can recall it.`,
     });
 
     store.updateAutoCheckpointWrite(AGENT_ID, engram.id);
-    log(AGENT_ID, 'task:end', `"${completedTask}" summary=${engram.id} salience=${salience.score.toFixed(2)}`);
+    log(AGENT_ID, 'task:end', `"${completedTask}" summary=${engram.id} salience=${salience.score.toFixed(2)} superseded=${supersededCount}`);
 
+    const supersededNote = supersededCount > 0 ? ` (${supersededCount} old memories superseded)` : '';
     return {
       content: [{
         type: 'text' as const,
-        text: `Completed: "${completedTask}" [${salience.score.toFixed(2)}]`,
+        text: `Completed: "${completedTask}" [${salience.score.toFixed(2)}]${supersededNote}`,
       }],
     };
   }

package/src/storage/index.ts

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