@anuma/sdk 2.4.2 → 2.6.0

package/dist/react/index.mjs

@@ -8,6 +8,7 @@ import {
   ENTITY_KINDS,
   LRUCache,
   RerankerUnavailableError,
+  TOPICS_EXTRACTION_VERSION,
   backfillMemoryEntityUserIdsOp,
   chunkAndEmbedAllMessages,
   chunkAndEmbedMessage,
@@ -26,6 +27,7 @@ import {
   createMemoryVaultSearchTool,
   createMessageOp,
   createSseClient,
+  createSupersedingMemoryOp,
   createVaultEmbeddingCache,
   createVaultMemoriesBatchOp,
   createVaultMemoryOp,
@@ -116,6 +118,7 @@ import {
   shouldChunkMessage,
   stampTopicsExtractedAtOp,
   stripToolCalls,
+  supersedeVaultMemoryOp,
   updateConversationPinnedOp,
   updateConversationProjectOp,
   updateConversationTitleOp,
@@ -128,7 +131,7 @@ import {
   updateVaultMemoryOp,
   useEncryption,
   vaultMemoryToStored
-} from "./chunk-IYDQBFS2.mjs";
+} from "./chunk-ZXS3KOY4.mjs";
 import {
   PiiRedactor,
   createStreamingDeAnonymizer,
@@ -6669,6 +6672,15 @@ __decorateClass([
 __decorateClass([
   field3("topics_extracted_at")
 ], VaultMemory.prototype, "topicsExtractedAt", 2);
+__decorateClass([
+  field3("superseded_by")
+], VaultMemory.prototype, "supersededBy", 2);
+__decorateClass([
+  field3("superseded_at")
+], VaultMemory.prototype, "supersededAt", 2);
+__decorateClass([
+  field3("topics_extracted_version")
+], VaultMemory.prototype, "topicsExtractedVersion", 2);
 __decorateClass([
   readonly2,
   date3("created_at")
@@ -6696,53 +6708,62 @@ async function retain(content, ctx, options = {}) {
   const enableAutoMerge = options.enableAutoMerge ?? true;
   const threshold = options.autoMergeThreshold ?? DEFAULT_AUTO_MERGE_THRESHOLD;
   const resolvedScope = options.scope ?? DEFAULT_SCOPE;
+  let supersedeTargetId;
+  let supersedeContent;
   if (enableAutoMerge) {
     if (options.consolidateOptions) {
-      const consolidationResult = await tryConsolidate(trimmed, ctx, options);
-      if (consolidationResult) return consolidationResult;
-    }
-    const matches = await searchVaultMemories(
-      trimmed,
-      ctx.vaultCtx,
-      ctx.embeddingOptions,
-      ctx.vaultCache,
-      {
-        limit: 1,
-        minSimilarity: threshold,
-        useFusion: false,
-        scopes: [resolvedScope],
-        ...options.folderId !== void 0 && { folderId: options.folderId }
-      }
-    );
-    if (matches.length > 0) {
-      const targetId = matches[0].uniqueId;
-      const existing = await getVaultMemoryOp(ctx.vaultCtx, targetId);
-      if (existing) {
-        const mergedSourceIds = unionStrings(
-          existing.sourceChunkIds ?? [],
-          options.sourceChunkIds ?? []
-        );
-        const eventTimeUpdate = pickEventTimeUpdate(existing, options.eventTime);
-        const updated = await updateVaultMemoryOp(ctx.vaultCtx, targetId, {
-          content: existing.content,
-          proofCountIncrement: 1,
-          sourceChunkIds: mergedSourceIds,
-          preserveUpdatedAt: true,
-          ...eventTimeUpdate && { eventTime: eventTimeUpdate }
-        });
-        if (updated) {
-          return {
-            action: "merge",
-            memoryId: targetId,
-            targetId,
-            proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1
-          };
+      const outcome = await tryConsolidate(trimmed, ctx, options);
+      if (outcome) {
+        if ("done" in outcome) return outcome.done;
+        supersedeTargetId = outcome.supersede;
+        supersedeContent = outcome.content;
+      }
+    }
+    if (!supersedeTargetId) {
+      const matches = await searchVaultMemories(
+        trimmed,
+        ctx.vaultCtx,
+        ctx.embeddingOptions,
+        ctx.vaultCache,
+        {
+          limit: 1,
+          minSimilarity: threshold,
+          useFusion: false,
+          scopes: [resolvedScope],
+          ...options.folderId !== void 0 && { folderId: options.folderId }
+        }
+      );
+      if (matches.length > 0) {
+        const targetId = matches[0].uniqueId;
+        const existing = await getVaultMemoryOp(ctx.vaultCtx, targetId);
+        if (existing && !existing.supersededBy) {
+          const mergedSourceIds = unionStrings(
+            existing.sourceChunkIds ?? [],
+            options.sourceChunkIds ?? []
+          );
+          const eventTimeUpdate = pickEventTimeUpdate(existing, options.eventTime);
+          const updated = await updateVaultMemoryOp(ctx.vaultCtx, targetId, {
+            content: existing.content,
+            proofCountIncrement: 1,
+            sourceChunkIds: mergedSourceIds,
+            preserveUpdatedAt: true,
+            ...eventTimeUpdate && { eventTime: eventTimeUpdate }
+          });
+          if (updated) {
+            return {
+              action: "merge",
+              memoryId: targetId,
+              targetId,
+              proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1
+            };
+          }
+          await assertMergeTargetGoneOrThrow(ctx, targetId);
         }
-        await assertMergeTargetGoneOrThrow(ctx, targetId);
       }
     }
   }
-  const embedding = await generateEmbedding(trimmed, ctx.embeddingOptions);
+  const contentToWrite = supersedeContent ?? trimmed;
+  const embedding = await generateEmbedding(contentToWrite, ctx.embeddingOptions);
   const embeddingModel = ctx.embeddingOptions.model ?? DEFAULT_API_EMBEDDING_MODEL;
   if (options.respectTombstones) {
     const tombstoneId = await findTombstoneMatch(embedding, embeddingModel, resolvedScope, ctx, {
@@ -6753,8 +6774,8 @@ async function retain(content, ctx, options = {}) {
       return { action: "suppressed", memoryId: tombstoneId, tombstoneId, proofCount: 0 };
     }
   }
-  const created = await createVaultMemoryOp(ctx.vaultCtx, {
-    content: trimmed,
+  const createOpts = {
+    content: contentToWrite,
     scope: resolvedScope,
     ...options.folderId !== void 0 && { folderId: options.folderId },
     embedding: JSON.stringify(embedding),
@@ -6771,7 +6792,24 @@ async function retain(content, ctx, options = {}) {
         kind: options.eventTime.kind
       }
     }
-  });
+  };
+  if (supersedeTargetId) {
+    const { created: created2, retired } = await createSupersedingMemoryOp(
+      ctx.vaultCtx,
+      createOpts,
+      supersedeTargetId
+    );
+    if (created2 && retired) {
+      ctx.vaultCache.set(created2.uniqueId, Float32Array.from(embedding));
+      return {
+        action: "supersede",
+        memoryId: created2.uniqueId,
+        targetId: supersedeTargetId,
+        proofCount: 1
+      };
+    }
+  }
+  const created = await createVaultMemoryOp(ctx.vaultCtx, createOpts);
   ctx.vaultCache.set(created.uniqueId, Float32Array.from(embedding));
   return {
     action: "create",
@@ -6838,12 +6876,17 @@ async function tryConsolidate(trimmed, ctx, options) {
     content: m.content,
     similarity: m.similarity
   }));
-  const { consolidateMemory: doConsolidate } = await import("./consolidate-IJH7LD2T.mjs");
+  const { consolidateMemory: doConsolidate } = await import("./consolidate-3MXZV3G7.mjs");
   const decision = await doConsolidate(trimmed, candidates, consolidateOptions);
   if (decision.action === "create") return null;
+  if (decision.action === "supersede" && decision.targetId && decision.content) {
+    const existing = await getVaultMemoryOp(ctx.vaultCtx, decision.targetId);
+    if (!existing || existing.supersededBy) return null;
+    return { supersede: decision.targetId, content: decision.content };
+  }
   if (decision.action === "noop" && decision.targetId) {
     const existing = await getVaultMemoryOp(ctx.vaultCtx, decision.targetId);
-    if (!existing) return null;
+    if (!existing || existing.supersededBy) return null;
     const mergedSourceIds = unionStrings(
       existing.sourceChunkIds ?? [],
       options.sourceChunkIds ?? []
@@ -6861,15 +6904,17 @@ async function tryConsolidate(trimmed, ctx, options) {
       return null;
     }
     return {
-      action: "merge",
-      memoryId: decision.targetId,
-      targetId: decision.targetId,
-      proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1
+      done: {
+        action: "merge",
+        memoryId: decision.targetId,
+        targetId: decision.targetId,
+        proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1
+      }
     };
   }
   if (decision.action === "update" && decision.targetId && decision.content) {
     const existing = await getVaultMemoryOp(ctx.vaultCtx, decision.targetId);
-    if (!existing) return null;
+    if (!existing || existing.supersededBy) return null;
     const mergedSourceIds = unionStrings(
       existing.sourceChunkIds ?? [],
       options.sourceChunkIds ?? []
@@ -6896,10 +6941,12 @@ async function tryConsolidate(trimmed, ctx, options) {
     }
     ctx.vaultCache.set(decision.targetId, Float32Array.from(newEmbedding));
     return {
-      action: "update",
-      memoryId: decision.targetId,
-      targetId: decision.targetId,
-      proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1
+      done: {
+        action: "update",
+        memoryId: decision.targetId,
+        targetId: decision.targetId,
+        proofCount: updated.proofCount ?? (existing.proofCount ?? 1) + 1
+      }
     };
   }
   return null;
@@ -12187,7 +12234,7 @@ __decorateClass([
 ], VaultFolder.prototype, "context", 2);
 
 // src/lib/db/schema.ts
-var SDK_SCHEMA_VERSION = 36;
+var SDK_SCHEMA_VERSION = 38;
 var sdkSchema = appSchema2({
   version: SDK_SCHEMA_VERSION,
   tables: [
@@ -12312,7 +12359,20 @@ var sdkSchema = appSchema2({
         // Unix ms of the last LLM topic-extraction pass over this memory's
         // content. Null = never extracted standalone (legacy rows with entity
         // links are grandfathered — see getMemoriesNeedingTopicExtractionOp).
-        { name: "topics_extracted_at", type: "number", isOptional: true }
+        { name: "topics_extracted_at", type: "number", isOptional: true },
+        // Write-time supersession (A2). When set, this fact was replaced by a
+        // newer, incompatible-value fact (e.g. "Lives in Portland" superseded by
+        // "Lives in SF"); `superseded_by` points at the newer memory's id and
+        // `superseded_at` is the Unix ms it happened. Superseded rows stay in
+        // the table (history / read-time fallback) but are excluded from recall
+        // and dedup by default. Null = live (not superseded). Indexed so the
+        // recall filter stays cheap.
+        { name: "superseded_by", type: "string", isOptional: true, isIndexed: true },
+        { name: "superseded_at", type: "number", isOptional: true },
+        // The extraction-logic version this memory was last stamped under. Null
+        // (pre-v38) is treated as version 0, so a bump of TOPICS_EXTRACTION_VERSION
+        // re-extracts stale rows. See getMemoriesNeedingTopicExtractionOp.
+        { name: "topics_extracted_version", type: "number", isOptional: true }
       ]
     }),
     // Entity table — canonical names extracted from auto-extraction (W5).
@@ -12923,6 +12983,34 @@ var sdkMigrations = schemaMigrations2({
           columns: [{ name: "topics_extracted_at", type: "number", isOptional: true }]
         })
       ]
+    },
+    // v36 -> v37: write-time supersession columns on memory_vault. Existing rows
+    // keep both NULL (= live / not superseded), so no backfill — legacy
+    // contradictory rows are handled by the read-time supersession fallback.
+    {
+      toVersion: 37,
+      steps: [
+        addColumns2({
+          table: "memory_vault",
+          columns: [
+            { name: "superseded_by", type: "string", isOptional: true, isIndexed: true },
+            { name: "superseded_at", type: "number", isOptional: true }
+          ]
+        })
+      ]
+    },
+    // v37 -> v38: topics_extracted_version on memory_vault. Existing rows keep it
+    // NULL, read as version 0 by getMemoriesNeedingTopicExtractionOp — so the
+    // first sweep after a TOPICS_EXTRACTION_VERSION bump re-extracts them (drained
+    // across sweeps by the worker's limit). See topicExtract.ts.
+    {
+      toVersion: 38,
+      steps: [
+        addColumns2({
+          table: "memory_vault",
+          columns: [{ name: "topics_extracted_version", type: "number", isOptional: true }]
+        })
+      ]
     }
   ]
 });
@@ -22578,6 +22666,7 @@ export {
   VaultMemory as StoredVaultMemoryModel,
   StreamExpiredError,
   THEME_ATTRS,
+  TOPICS_EXTRACTION_VERSION,
   TOPIC_EXTRACTION_BATCH_SIZE,
   TextProcessor,
   UIInteractionProvider,
@@ -22854,6 +22943,7 @@ export {
   storeNotionReturnUrl,
   streamCancelPath,
   streamReplayPath,
+  supersedeVaultMemoryOp,
   updateAttrs,
   updateConversationProjectOp,
   updateMediaMessageIdBatchOp,

package/dist/{expo/recall-HI7VO3VM.mjs → react/recall-PV7L3SN3.mjs}

@@ -1,6 +1,6 @@
 import {
   recall
-} from "./chunk-UOUJUZM4.mjs";
+} from "./chunk-ZXS3KOY4.mjs";
 import "./chunk-DFVCS3QQ.mjs";
 import "./chunk-GYKJOWEO.mjs";
 export {

package/dist/server/{chunk-3MLG7SUH.mjs → chunk-Z6II54I7.mjs}

@@ -16057,6 +16057,7 @@ function isOwnedByCtxUser(ctx, record) {
 function baseVaultConditions(ctx, options) {
   return [
     ...options?.includeDeleted ? [] : [import_watermelondb3.Q.where("is_deleted", false)],
+    ...options?.includeSuperseded ? [] : [import_watermelondb3.Q.where("superseded_by", null)],
     ...ctx.userId !== void 0 ? [import_watermelondb3.Q.where("user_id", ctx.userId)] : [],
     ...options?.since ? [import_watermelondb3.Q.where("updated_at", import_watermelondb3.Q.gt(options.since.getTime()))] : []
   ];
@@ -16097,6 +16098,9 @@ function vaultMemoryToStoredRaw(memory) {
     eventTimeKind: memory.eventTimeKind ?? null,
     topicsUserManaged: memory.topicsUserManaged ?? false,
     topicsExtractedAt: memory.topicsExtractedAt ?? null,
+    topicsExtractedVersion: memory.topicsExtractedVersion ?? null,
+    supersededBy: memory.supersededBy ?? null,
+    supersededAt: memory.supersededAt ?? null,
     createdAt: memory.createdAt,
     updatedAt: memory.updatedAt,
     isDeleted: memory.isDeleted
@@ -16142,6 +16146,59 @@ async function createVaultMemoryOp(ctx, opts) {
   });
   return vaultMemoryToStored(created, ctx.walletAddress, ctx.signMessage, ctx.embeddedWalletSigner);
 }
+async function createSupersedingMemoryOp(ctx, opts, targetId) {
+  if (!targetId) return { created: null, retired: false };
+  const scope = opts.scope ?? "private";
+  const encryptedContent = ctx.walletAddress && ctx.signMessage ? await encryptVaultMemoryContent(
+    opts.content,
+    ctx.walletAddress,
+    ctx.signMessage,
+    ctx.embeddedWalletSigner
+  ) : opts.content;
+  let createdRecord = null;
+  await ctx.database.write(async () => {
+    let target;
+    try {
+      target = await ctx.vaultMemoryCollection.find(targetId);
+    } catch {
+      return;
+    }
+    if (target.isDeleted || target.supersededBy || !isOwnedByCtxUser(ctx, target)) return;
+    createdRecord = await ctx.vaultMemoryCollection.create((record) => {
+      record._setRaw("content", encryptedContent);
+      record._setRaw("scope", scope);
+      record._setRaw("folder_id", opts.folderId ?? null);
+      record._setRaw("user_id", ctx.userId ?? null);
+      record._setRaw("is_deleted", false);
+      if (opts.embedding !== void 0) {
+        record._setRaw("embedding", opts.embedding);
+        record._setRaw("embedding_model", opts.embeddingModel ?? null);
+      }
+      if (opts.sourceChunkIds !== void 0) {
+        record._setRaw("source_chunk_ids", JSON.stringify(opts.sourceChunkIds));
+      }
+      record._setRaw("proof_count", opts.proofCount ?? 1);
+      record._setRaw("source", opts.source ?? "manual");
+      if (opts.eventTime) {
+        record._setRaw("event_time_start", opts.eventTime.start ?? null);
+        record._setRaw("event_time_end", opts.eventTime.end ?? null);
+        record._setRaw("event_time_kind", opts.eventTime.kind ?? null);
+      }
+    });
+    await target.update((r) => {
+      r._setRaw("superseded_by", createdRecord.id);
+      r._setRaw("superseded_at", Date.now());
+    });
+  });
+  if (!createdRecord) return { created: null, retired: false };
+  const created = await vaultMemoryToStored(
+    createdRecord,
+    ctx.walletAddress,
+    ctx.signMessage,
+    ctx.embeddedWalletSigner
+  );
+  return { created, retired: true };
+}
 async function getMemoriesByEventTimeOp(ctx, windowStart, windowEnd) {
   const records = await ctx.vaultMemoryCollection.query(
     ...baseVaultConditions(ctx),
@@ -16281,6 +16338,9 @@ function vaultMemoryRawToStoredRaw(raw) {
     // SQLite stores booleans as 0/1, LokiJS as true/false — coerce both.
     topicsUserManaged: raw.topics_user_managed === true || raw.topics_user_managed === 1,
     topicsExtractedAt: raw.topics_extracted_at ?? null,
+    topicsExtractedVersion: raw.topics_extracted_version ?? null,
+    supersededBy: raw.superseded_by ?? null,
+    supersededAt: raw.superseded_at ?? null,
     createdAt: new Date(raw.created_at),
     updatedAt: new Date(raw.updated_at),
     isDeleted: raw.is_deleted === true || raw.is_deleted === 1
@@ -16322,7 +16382,7 @@ async function getAllVaultMemoryContentsOp(ctx, options) {
 async function updateVaultMemoryOp(ctx, id, opts) {
   try {
     const probe = await ctx.vaultMemoryCollection.find(id);
-    if (probe.isDeleted || !isOwnedByCtxUser(ctx, probe)) return null;
+    if (probe.isDeleted || probe.supersededBy || !isOwnedByCtxUser(ctx, probe)) return null;
     const encryptedContent = ctx.walletAddress && ctx.signMessage ? await encryptVaultMemoryContent(
       opts.content,
       ctx.walletAddress,
@@ -16333,7 +16393,7 @@ async function updateVaultMemoryOp(ctx, id, opts) {
     const record = probe;
     const originalUpdatedAt = record.updatedAt.getTime();
     await ctx.database.write(async () => {
-      if (record.isDeleted || !isOwnedByCtxUser(ctx, record)) {
+      if (record.isDeleted || record.supersededBy || !isOwnedByCtxUser(ctx, record)) {
         stale = true;
         return;
       }
@@ -16411,6 +16471,40 @@ async function deleteVaultMemoryOp(ctx, id) {
     return false;
   }
 }
+async function supersedeVaultMemoryOp(ctx, id, supersededById) {
+  if (id === supersededById) return false;
+  try {
+    const record = await ctx.vaultMemoryCollection.find(id);
+    if (record.isDeleted || record.supersededBy || !isOwnedByCtxUser(ctx, record)) return false;
+    let successor;
+    try {
+      successor = await ctx.vaultMemoryCollection.find(supersededById);
+    } catch {
+      return false;
+    }
+    if (successor.isDeleted || successor.supersededBy || !isOwnedByCtxUser(ctx, successor)) {
+      return false;
+    }
+    let stale = false;
+    await ctx.database.write(async () => {
+      if (record.isDeleted || record.supersededBy || !isOwnedByCtxUser(ctx, record)) {
+        stale = true;
+        return;
+      }
+      if (successor.isDeleted || successor.supersededBy || !isOwnedByCtxUser(ctx, successor)) {
+        stale = true;
+        return;
+      }
+      await record.update((r) => {
+        r._setRaw("superseded_by", supersededById);
+        r._setRaw("superseded_at", Date.now());
+      });
+    });
+    return !stale;
+  } catch {
+    return false;
+  }
+}
 async function getUnfiledVaultMemoriesOp(ctx) {
   const conditions = [
     import_watermelondb3.Q.where("folder_id", null),
@@ -16423,6 +16517,7 @@ async function getUnfiledVaultMemoriesOp(ctx) {
     (record) => vaultMemoryToStored(record, ctx.walletAddress, ctx.signMessage, ctx.embeddedWalletSigner)
   );
 }
+var TOPICS_EXTRACTION_VERSION = 1;
 async function getMemoriesNeedingTopicExtractionOp(ctx, options) {
   const entityCtx = ctx.entityCtx;
   if (!entityCtx) {
@@ -16441,7 +16536,10 @@ async function getMemoriesNeedingTopicExtractionOp(ctx, options) {
   for (const raw of rows) {
     const stamp = raw.topics_extracted_at ?? null;
     if (stamp !== null) {
-      if (raw.updated_at > stamp) stampedPending.push(raw);
+      const version = raw.topics_extracted_version ?? 0;
+      if (raw.updated_at > stamp || version < TOPICS_EXTRACTION_VERSION) {
+        stampedPending.push(raw);
+      }
     } else {
       unstamped.push(raw);
     }
@@ -16471,7 +16569,7 @@ async function getMemoriesNeedingTopicExtractionOp(ctx, options) {
   );
   return { pending, linkedUnstamped };
 }
-async function stampTopicsExtractedAtOp(ctx, memoryIds, extractedAt) {
+async function stampTopicsExtractedAtOp(ctx, memoryIds, extractedAt, version = TOPICS_EXTRACTION_VERSION) {
   if (memoryIds.length === 0) return [];
   const uniqueIds = Array.from(new Set(memoryIds));
   const CHUNK = 500;
@@ -16494,6 +16592,7 @@ async function stampTopicsExtractedAtOp(ctx, memoryIds, extractedAt) {
         prepared.push(
           record.prepareUpdate((r) => {
             r._setRaw("topics_extracted_at", extractedAt);
+            r._setRaw("topics_extracted_version", version);
             r._setRaw("updated_at", originalUpdatedAt);
           })
         );
@@ -19108,7 +19207,7 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
             legacy.map((r) => ({ id: r.uniqueId, content: r.content, score: r.similarity }))
           );
         }
-        const { recall: recall2 } = await import("./recall-MJHGXMHZ.mjs");
+        const { recall: recall2 } = await import("./recall-CQT24XLH.mjs");
         const result = await recall2(
           query,
           { vaultCtx, embeddingOptions, vaultCache: cache },
@@ -19797,13 +19896,16 @@ export {
   replaceMemoryEntitiesGuardedOp,
   vaultMemoryToStored,
   createVaultMemoryOp,
+  createSupersedingMemoryOp,
   createVaultMemoriesBatchOp,
   getVaultMemoryOp,
   getAllVaultMemoriesOp,
   getAllVaultMemoryContentsOp,
   updateVaultMemoryOp,
   deleteVaultMemoryOp,
+  supersedeVaultMemoryOp,
   getUnfiledVaultMemoriesOp,
+  TOPICS_EXTRACTION_VERSION,
   getMemoriesNeedingTopicExtractionOp,
   stampTopicsExtractedAtOp,
   deleteAllVaultMemoriesForUserOp,

package/dist/server/{consolidate-TDT4HRHG.mjs → consolidate-CN2GQV4D.mjs}

@@ -15,10 +15,11 @@ var SYSTEM_PROMPT = `You consolidate a new memory against existing memories from
 
 A "memory" is a self-contained natural-language fact about the user. Multiple memories about the same EXACT FACET (the same dimension of the same subject) should never coexist \u2014 they should be merged into one. Different facets on the same subject (e.g. user's dog's name vs user's dog's age) are SEPARATE memories.
 
-Decide one of three actions:
+Decide one of four actions:
 
 - "create": the new memory describes a distinct fact not covered by any existing memory. Write it as new.
-- "update": the new memory describes the SAME FACET as exactly one existing memory. Either it adds detail, corrects a value, or rephrases the same fact. Return targetId of that existing memory + the consolidated content (richest version of the two).
+- "update": the new memory describes the SAME FACET as exactly one existing memory and is COMPATIBLE with it \u2014 it adds detail, fixes an incomplete value, or rephrases the same still-true fact. Return targetId of that existing memory + the consolidated content (richest version of the two).
+- "supersede": the new memory REPLACES a standing fact whose value has CHANGED and is now INCOMPATIBLE with an existing memory \u2014 the old fact was true before but is false now (a state change). Return targetId of the STALE existing memory to retire + content = the NEW fact. The old memory is kept as history, not overwritten or deleted; do not re-state it.
 - "noop": the new memory is already fully captured by an existing memory \u2014 same facet, no new information. Skip the write.
 
 RULES (carry these strictly):
@@ -26,18 +27,21 @@ RULES (carry these strictly):
 1. ONE OBSERVATION PER DISTINCT FACET. If the new memory is about "user's aunt's twins" and an existing memory is also about "user's aunt's twins", they are the same facet \u2192 update, never create.
 2. MATCH BY FACET, NOT TOPIC. Two memories both mentioning "Zara" is not enough to merge \u2014 only merge if they describe the same property (e.g. both about "user's pending Zara boot exchange"). Two memories about Zara on different topics (e.g. "user shops at Zara" + "user returned a sweater to Zara last week") are separate facets.
 3. NO COMPUTATION. Do not sum counts, decrement quantities, or derive new facts from existing ones. If the new memory says "user spent $200 today" and an existing memory says "user spent $150 yesterday", these are TWO SEPARATE EVENTS \u2014 create.
-4. Events with different occurredAt dates are different memories even if the same activity ("user went to gym Monday" vs "user went to gym Friday" \u2014 separate events).
-5. When in doubt between create and update, choose create. Over-merging loses information; under-merging is recoverable.
+4. EVENTS vs STANDING STATE.
+   - Distinct EVENTS (episodic \u2014 something that happened on a date) are separate memories, even if the same activity: "user went to gym Monday" vs "user went to gym Friday" \u2192 create; keep both.
+   - A STANDING ATTRIBUTE (an ongoing state: where the user lives/works, relationship status, current role) has ONE current value. When the new memory changes that value ("Lives in Portland" \u2192 "Lives in San Francisco"; "Works at Google" \u2192 "Works at Riverbend"; "Engaged" \u2192 "Broke up"), the old value is no longer true \u2192 supersede (retire the old, record the new). Do NOT create (that leaves a stale contradiction) and do NOT update (that erases the history that the old value was once true).
+5. When in doubt between create and update, choose create \u2014 EXCEPT when the new memory directly contradicts the current value of a standing attribute in an existing memory; then choose supersede. Over-merging loses information; a live contradiction is worse than either.
 
 OUTPUT \u2014 strict JSON, no prose:
 {
-  "action": "create" | "update" | "noop",
-  "targetId": "<existing memory id, required for update/noop, omit for create>",
-  "content": "<consolidated content, required for create/update, omit for noop>"
+  "action": "create" | "update" | "supersede" | "noop",
+  "targetId": "<existing memory id \u2014 required for update/supersede/noop, omit for create>",
+  "content": "<content \u2014 required for create/update/supersede, omit for noop>"
 }
 
 For "create": content is the new memory verbatim (or a slight refinement).
 For "update": content is the merged richest-version, \u226480 words.
+For "supersede": content is the NEW fact only (\u226480 words); targetId is the stale memory being retired.
 For "noop": no content (existing memory is already correct).`;
 async function consolidateMemory(newContent, candidates, options) {
   const fallback = {
@@ -112,7 +116,9 @@ function validate(parsed, newContent, validIds) {
   if (typeof parsed !== "object" || parsed === null) return null;
   const obj = parsed;
   const action = obj.action;
-  if (action !== "create" && action !== "update" && action !== "noop") return null;
+  if (action !== "create" && action !== "update" && action !== "noop" && action !== "supersede") {
+    return null;
+  }
   if (action === "create") {
     const c2 = typeof obj.content === "string" ? obj.content.trim() : "";
     return { action: "create", content: c2.length > 0 ? c2 : newContent };
@@ -124,7 +130,7 @@ function validate(parsed, newContent, validIds) {
   }
   const c = typeof obj.content === "string" ? obj.content.trim() : "";
   if (c.length === 0) return null;
-  return { action: "update", targetId, content: c };
+  return { action, targetId, content: c };
 }
 export {
   consolidateMemory