@anuma/sdk 2.4.1 → 2.5.0

package/dist/expo/index.d.ts

@@ -4316,6 +4316,9 @@ declare class VaultMemory extends Model {
     /** Unix ms of the last LLM topic-extraction pass. Null = never extracted
      *  standalone (linked legacy rows are grandfathered as extracted). */
     topicsExtractedAt: number | null;
+    /** A2 supersession: newer memory id that replaced this one, or null if live. */
+    supersededBy: string | null;
+    supersededAt: number | null;
     createdAt: Date;
     updatedAt: Date;
     isDeleted: boolean;
@@ -4423,6 +4426,13 @@ interface StoredVaultMemory {
      * Null = never extracted standalone; rows that already carry entity links
      * are grandfathered as extracted (see getMemoriesNeedingTopicExtractionOp). */
     topicsExtractedAt: number | null;
+    /** Write-time supersession (A2): id of the newer memory that replaced this
+     * one (incompatible-value update, e.g. "Lives in Portland" → "Lives in SF").
+     * Null = live. Superseded rows are excluded from recall/dedup by default but
+     * kept for history + the read-time fallback. */
+    supersededBy: string | null;
+    /** Unix ms when this memory was superseded. Null when live. */
+    supersededAt: number | null;
     createdAt: Date;
     updatedAt: Date;
     isDeleted: boolean;
@@ -4531,12 +4541,30 @@ declare function getAllVaultMemoriesOp(ctx: VaultMemoryOperationsContext, option
      * render "forgotten" nodes; ordinary consumers should leave this off.
      */
     includeDeleted?: boolean;
+    /**
+     * Include A2-superseded memories (each carries `supersededBy`). Default
+     * `false` — superseded rows are excluded, as they are from recall/dedup.
+     * Used by a "memory history" view to render retired facts.
+     */
+    includeSuperseded?: boolean;
 }): Promise<StoredVaultMemory[]>;
 declare function getAllVaultMemoryContentsOp(ctx: VaultMemoryOperationsContext, options?: {
     since?: Date;
 }): Promise<string[]>;
 declare function updateVaultMemoryOp(ctx: VaultMemoryOperationsContext, id: string, opts: UpdateVaultMemoryOptions): Promise<StoredVaultMemory | null>;
 declare function deleteVaultMemoryOp(ctx: VaultMemoryOperationsContext, id: string): Promise<boolean>;
+/**
+ * Mark a memory as superseded by a newer one (A2 write-time supersession).
+ * The row stays in the table (history + read-time fallback) but is excluded
+ * from recall/dedup by default via `superseded_by`. Idempotent-ish: no-op if
+ * the row is missing, not owned, deleted, or already superseded. Does NOT
+ * preserve `updated_at` — superseded rows are hidden from recall, so their
+ * recency is irrelevant.
+ *
+ * @param id - the memory being retired (e.g. "Lives in Portland")
+ * @param supersededById - the newer memory that replaced it (e.g. "Lives in SF")
+ */
+declare function supersedeVaultMemoryOp(ctx: VaultMemoryOperationsContext, id: string, supersededById: string): Promise<boolean>;
 /**
  * Get all non-deleted, unfiled vault memories (folder_id is null).
  */
@@ -5183,7 +5211,7 @@ interface RecallDiagnostics {
     /** Soft-degradation signals that fired this call (empty when clean). */
     degraded: RecallDegradation[];
 }
-type RetainAction = "create" | "merge" | "update" | "skip" | "suppressed";
+type RetainAction = "create" | "merge" | "update" | "skip" | "suppressed" | "supersede";
 type RetainSource = "manual" | "auto-extracted" | "capsule";
 /** Why the consolidator fell back to "create" instead of a real decision. */
 type ConsolidationFallbackReason = "llm_error" | "invalid_response";
@@ -5249,7 +5277,8 @@ interface RetainOptions {
 interface RetainResult {
     action: RetainAction;
     memoryId: string;
-    /** When action is 'merge' or 'update', the prior memory's id. */
+    /** When action is 'merge' or 'update', the prior memory's id. When action is
+     * 'supersede', the stale memory that was retired (`memoryId` is the new one). */
     targetId?: string;
     /**
      * When action is 'suppressed', the id of the soft-deleted memory that blocked
@@ -5471,9 +5500,12 @@ declare function extractFacts(messages: AutoExtractMessage[], options: ExtractFa
 type ExtractOutcome = "extracted" | "no-facts" | "empty-after-retry" | "dropped-after-redaction";
 /**
  * Stage 2 — for each extracted candidate, call retain() with auto-merge
- * enabled. The resolver path (decide create/merge/update via a second LLM
- * call against the existing vault) is deferred — the auto-merge inside
- * retain() handles dedup at the cosine-similarity level for hackathon.
+ * enabled. When `consolidateOptions` are wired, retain()'s consolidation pass
+ * is the "resolver": a second LLM call against the top-K existing vault
+ * memories that decides create/update/noop/supersede — including retiring a
+ * stale value on a state change (the supersession the extraction prompt above
+ * promises). Without consolidation, retain() still dedups at the cosine-merge
+ * level, and the read-time supersession heuristic remains the fallback.
  *
  * Returns the candidates that survived validation along with the retain
  * result for each (which captures whether the fact was created, merged,
@@ -6733,8 +6765,12 @@ declare function useChatStorage(options: UseChatStorageOptions): UseChatStorageR
  *   LLM topic-extraction pass, so the background topic worker re-extracts only
  *   memories edited since (updated_at > topics_extracted_at) instead of
  *   re-running the whole vault
+ * - v37: Added superseded_by + superseded_at columns to memory_vault for
+ *   write-time supersession — a changed fact retires the stale one (points at
+ *   the newer memory) instead of both surviving; superseded rows are excluded
+ *   from recall/dedup by default
  */
-declare const SDK_SCHEMA_VERSION = 36;
+declare const SDK_SCHEMA_VERSION = 37;
 /**
  * Combined WatermelonDB schema for all SDK storage modules.
  *
@@ -6814,6 +6850,7 @@ declare const sdkSchema: Readonly<{
  * - v32 → v33: Added `embedding_model` column to memory_vault (null grandfathered as current-model-compatible)
  * - v34 → v35: Added `conversation_memory` table (conversation ↔ recalled memory ids)
  * - v35 → v36: Added `topics_extracted_at` column to memory_vault (watermark for the background topic-extraction worker; null + existing links grandfathered as extracted)
+ * - v36 → v37: Added `superseded_by` + `superseded_at` columns to memory_vault (write-time supersession; null = live, excluded from recall/dedup when set)
  */
 declare const sdkMigrations: Readonly<{
     validated: true;
@@ -7335,4 +7372,4 @@ declare function refreshNotionAccessToken(params: NotionRefreshTokenParams): Pro
  */
 declare function createNotionTools(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig[];
 
-export { type AutoExtractMessage, type AutoExtractor, type Budget, type CachedChunkVectors, type CachedServerTools, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type ChunkVectorCache, type ChunkingOptions, type ConsolidationFallbackReason, type ConversationMemoryInput, ConversationMemory as ConversationMemoryModel, type ConversationMemoryOperationsContext, type CreateAutoExtractorOptions, type CreateConversationOptions, type CreateMessageOptions, type CreateVaultFolderOptions, type CreateVaultMemoryOptions, type CryptoPriceClassification, type CryptoPricePreProcessorOptions, DEFAULT_CACHE_EXPIRATION_MS, DEFAULT_CHUNK_CACHE_SIZE, DEFAULT_CHUNK_OVERLAP, DEFAULT_CHUNK_SIZE, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type EmbeddedWalletSignerFn, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FlushResult, type GetMessagesPageOptions, INFERENCE_ID_HEADER, type LazyStoredConversation, type Logger, LoggerProvider, type LoggerProviderProps, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MessageRedactionResult, type MessageSkeleton, NOTION_OAUTH_CONFIG, type NotionAuthUrlParams, type NotionClientRegistration, type NotionExchangeCodeParams, type NotionOAuthEndpoints, type NotionPKCEChallenge, type NotionRefreshTokenParams, type NotionTokenResponse, PII_PATTERNS, type PiiCategory, type PiiMatch, type PiiPattern, PiiRedactor, type PiiRedactorOptions, type PlatformStorage, type PortalLlmAuth, type PromptPreProcessor, type PromptPreProcessorContext, type QuantizedEmbedding, QueueManager, type QueueStatus, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankedMemory, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type RedactionResult, type ReflectOptions, type ReflectResult, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type ResumeStreamWithStorageResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, SDK_SCHEMA_VERSION, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageDetachedResult, type SendMessageWithStorageResult, type ServerToolsOptions, type ServerToolsResponse, type SignMessageFn, type StockPriceClassification, type StockPricePreProcessorOptions, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredConversationMemory, type StoredMessage, type StoredMessageWithSimilarity, type StoredVaultFolder, VaultFolder as StoredVaultFolderModel, type StoredVaultMemory, VaultMemory as StoredVaultMemoryModel, StreamExpiredError, type StreamMetaEvent, type StreamResumeHandle, TOPIC_EXTRACTION_BATCH_SIZE, type TextChunk, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TurnCompleteEvent, type TurnSkippedEvent, type UpdateVaultFolderOptions, type UpdateVaultMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseCreditsOptions, type UseCreditsResult, type UseModelsOptions, type UseModelsResult, type VaultEmbeddingCache, type VaultFolderOperationsContext, type VaultMemoryOperationsContext, type VaultSaveOperation, type VaultSearchResult, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, addConversationMemoriesOp, buildNotionAuthUrl, chatStorageMigrations, chatStorageSchema, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, clearAllEncryptionKeys, clearAllEncryptionState, clearConversationMemoriesOp, clearEncryptionKey, clearLazyTitleCache, clearServerToolsCache, consoleLogger, conversationMemoryToStored, cosineInt8, createAutoExtractor, createChunkVectorCache, createCryptoPricePreProcessor, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createNotionTools, createPlatformCursorStore, createRecallTool, createStockPricePreProcessor, createStreamingDeAnonymizer, createVaultEmbeddingCache, createVaultFolderOp, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decryptConversationTitle, deleteAllVaultMemoriesForUserOp, deleteVaultFolderOp, deleteVaultMemoryOp, dequantizeEmbedding, discoverNotionOAuthEndpoints, eagerEmbedContent, embedAllMessages, embedMessage, ensureDefaultFoldersOp, exchangeNotionCode, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, generateConversationId, generateEmbedding, generateEmbeddings, generateNotionPKCE, getAllVaultFoldersOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getCachedServerTools, getConversationMemoriesOp, getConversationsByProjectLazyOp, getConversationsLazyOp, getLogger, getMemoriesNeedingTopicExtractionOp, getServerTools, getUnfiledVaultMemoriesOp, getVaultFolderMemoryCountOp, getVaultMemoryOp, hasEncryptionKey, isPiiRedactor, isRerankerAvailable, moveMemoriesToFolderOp, noopLogger, onKeyAvailable, preEmbedVaultMemories, quantizeEmbedding, queueManager, recall, reflect, refreshNotionAccessToken, registerNotionClient, requestEncryptionKey, resolvePiiRedactor, resumeStream, retain, sdkMigrations, sdkModelClasses, sdkSchema, searchVaultMemories, setLogger, shouldChunkMessage, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, updateVaultFolderContextOp, updateVaultFolderOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertMessageOp, useChat, useChatStorage, useCredits, useEncryption, useModels, xhrTransport };
+export { type AutoExtractMessage, type AutoExtractor, type Budget, type CachedChunkVectors, type CachedServerTools, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type ChunkVectorCache, type ChunkingOptions, type ConsolidationFallbackReason, type ConversationMemoryInput, ConversationMemory as ConversationMemoryModel, type ConversationMemoryOperationsContext, type CreateAutoExtractorOptions, type CreateConversationOptions, type CreateMessageOptions, type CreateVaultFolderOptions, type CreateVaultMemoryOptions, type CryptoPriceClassification, type CryptoPricePreProcessorOptions, DEFAULT_CACHE_EXPIRATION_MS, DEFAULT_CHUNK_CACHE_SIZE, DEFAULT_CHUNK_OVERLAP, DEFAULT_CHUNK_SIZE, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type EmbeddedWalletSignerFn, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FlushResult, type GetMessagesPageOptions, INFERENCE_ID_HEADER, type LazyStoredConversation, type Logger, LoggerProvider, type LoggerProviderProps, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MessageRedactionResult, type MessageSkeleton, NOTION_OAUTH_CONFIG, type NotionAuthUrlParams, type NotionClientRegistration, type NotionExchangeCodeParams, type NotionOAuthEndpoints, type NotionPKCEChallenge, type NotionRefreshTokenParams, type NotionTokenResponse, PII_PATTERNS, type PiiCategory, type PiiMatch, type PiiPattern, PiiRedactor, type PiiRedactorOptions, type PlatformStorage, type PortalLlmAuth, type PromptPreProcessor, type PromptPreProcessorContext, type QuantizedEmbedding, QueueManager, type QueueStatus, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankedMemory, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type RedactionResult, type ReflectOptions, type ReflectResult, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type ResumeStreamWithStorageResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, SDK_SCHEMA_VERSION, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageDetachedResult, type SendMessageWithStorageResult, type ServerToolsOptions, type ServerToolsResponse, type SignMessageFn, type StockPriceClassification, type StockPricePreProcessorOptions, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredConversationMemory, type StoredMessage, type StoredMessageWithSimilarity, type StoredVaultFolder, VaultFolder as StoredVaultFolderModel, type StoredVaultMemory, VaultMemory as StoredVaultMemoryModel, StreamExpiredError, type StreamMetaEvent, type StreamResumeHandle, TOPIC_EXTRACTION_BATCH_SIZE, type TextChunk, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TurnCompleteEvent, type TurnSkippedEvent, type UpdateVaultFolderOptions, type UpdateVaultMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseCreditsOptions, type UseCreditsResult, type UseModelsOptions, type UseModelsResult, type VaultEmbeddingCache, type VaultFolderOperationsContext, type VaultMemoryOperationsContext, type VaultSaveOperation, type VaultSearchResult, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, addConversationMemoriesOp, buildNotionAuthUrl, chatStorageMigrations, chatStorageSchema, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, clearAllEncryptionKeys, clearAllEncryptionState, clearConversationMemoriesOp, clearEncryptionKey, clearLazyTitleCache, clearServerToolsCache, consoleLogger, conversationMemoryToStored, cosineInt8, createAutoExtractor, createChunkVectorCache, createCryptoPricePreProcessor, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createNotionTools, createPlatformCursorStore, createRecallTool, createStockPricePreProcessor, createStreamingDeAnonymizer, createVaultEmbeddingCache, createVaultFolderOp, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decryptConversationTitle, deleteAllVaultMemoriesForUserOp, deleteVaultFolderOp, deleteVaultMemoryOp, dequantizeEmbedding, discoverNotionOAuthEndpoints, eagerEmbedContent, embedAllMessages, embedMessage, ensureDefaultFoldersOp, exchangeNotionCode, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, generateConversationId, generateEmbedding, generateEmbeddings, generateNotionPKCE, getAllVaultFoldersOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getCachedServerTools, getConversationMemoriesOp, getConversationsByProjectLazyOp, getConversationsLazyOp, getLogger, getMemoriesNeedingTopicExtractionOp, getServerTools, getUnfiledVaultMemoriesOp, getVaultFolderMemoryCountOp, getVaultMemoryOp, hasEncryptionKey, isPiiRedactor, isRerankerAvailable, moveMemoriesToFolderOp, noopLogger, onKeyAvailable, preEmbedVaultMemories, quantizeEmbedding, queueManager, recall, reflect, refreshNotionAccessToken, registerNotionClient, requestEncryptionKey, resolvePiiRedactor, resumeStream, retain, sdkMigrations, sdkModelClasses, sdkSchema, searchVaultMemories, setLogger, shouldChunkMessage, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, supersedeVaultMemoryOp, updateVaultFolderContextOp, updateVaultFolderOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertMessageOp, useChat, useChatStorage, useCredits, useEncryption, useModels, xhrTransport };

package/dist/expo/index.mjs

@@ -21,6 +21,7 @@ import {
   createMemoryVaultSearchTool,
   createMessageOp,
   createSseClient,
+  createSupersedingMemoryOp,
   createVaultEmbeddingCache,
   createVaultMemoriesBatchOp,
   createVaultMemoryOp,
@@ -77,6 +78,7 @@ import {
   shouldChunkMessage,
   stampTopicsExtractedAtOp,
   stripToolCalls,
+  supersedeVaultMemoryOp,
   updateConversationPinnedOp,
   updateConversationTitleOp,
   updateMessageEmbeddingOp,
@@ -86,7 +88,7 @@ import {
   upsertMessageOp,
   useEncryption,
   vaultMemoryToStored
-} from "./chunk-UOUJUZM4.mjs";
+} from "./chunk-A26RBLTJ.mjs";
 import {
   PII_PATTERNS,
   PiiRedactor,
@@ -5508,6 +5510,12 @@ __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([
   readonly2,
   date3("created_at")
@@ -5874,53 +5882,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, {
@@ -5931,8 +5948,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),
@@ -5949,7 +5966,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",
@@ -6016,12 +6050,17 @@ async function tryConsolidate(trimmed, ctx, options) {
     content: m.content,
     similarity: m.similarity
   }));
-  const { consolidateMemory: doConsolidate } = await import("./consolidate-HEMQGOUD.mjs");
+  const { consolidateMemory: doConsolidate } = await import("./consolidate-3QQPUWD6.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 ?? []
@@ -6039,15 +6078,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 ?? []
@@ -6074,10 +6115,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;
@@ -9530,7 +9573,7 @@ __decorateClass([
 ], VaultFolder.prototype, "context", 2);
 
 // src/lib/db/schema.ts
-var SDK_SCHEMA_VERSION = 36;
+var SDK_SCHEMA_VERSION = 37;
 var sdkSchema = appSchema2({
   version: SDK_SCHEMA_VERSION,
   tables: [
@@ -9655,7 +9698,16 @@ 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 }
       ]
     }),
     // Entity table — canonical names extracted from auto-extraction (W5).
@@ -10266,6 +10318,21 @@ 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 }
+          ]
+        })
+      ]
     }
   ]
 });
@@ -11726,6 +11793,7 @@ export {
   stampTopicsExtractedAtOp,
   streamCancelPath,
   streamReplayPath,
+  supersedeVaultMemoryOp,
   updateVaultFolderContextOp,
   updateVaultFolderOp,
   updateVaultMemoryEmbeddingOp,

package/dist/{react/recall-G3CS444F.mjs → expo/recall-JC5GF5CX.mjs}

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

package/dist/react/{chunk-IYDQBFS2.mjs → chunk-V5GC3ES7.mjs}

@@ -2027,6 +2027,7 @@ function isOwnedByCtxUser(ctx, record) {
 function baseVaultConditions(ctx, options) {
   return [
     ...options?.includeDeleted ? [] : [Q3.where("is_deleted", false)],
+    ...options?.includeSuperseded ? [] : [Q3.where("superseded_by", null)],
     ...ctx.userId !== void 0 ? [Q3.where("user_id", ctx.userId)] : [],
     ...options?.since ? [Q3.where("updated_at", Q3.gt(options.since.getTime()))] : []
   ];
@@ -2067,6 +2068,8 @@ function vaultMemoryToStoredRaw(memory) {
     eventTimeKind: memory.eventTimeKind ?? null,
     topicsUserManaged: memory.topicsUserManaged ?? false,
     topicsExtractedAt: memory.topicsExtractedAt ?? null,
+    supersededBy: memory.supersededBy ?? null,
+    supersededAt: memory.supersededAt ?? null,
     createdAt: memory.createdAt,
     updatedAt: memory.updatedAt,
     isDeleted: memory.isDeleted
@@ -2112,6 +2115,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),
@@ -2251,6 +2307,8 @@ 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,
+    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
@@ -2292,7 +2350,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,
@@ -2303,7 +2361,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;
       }
@@ -2435,6 +2493,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 = [
     Q3.where("folder_id", null),
@@ -5282,7 +5374,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-G3CS444F.mjs");
+        const { recall: recall2 } = await import("./recall-IRTSMKYI.mjs");
         const result = await recall2(
           query,
           { vaultCtx, embeddingOptions, vaultCache: cache },
@@ -6008,6 +6100,7 @@ export {
   getMemoriesByEntityNamesOp,
   vaultMemoryToStored,
   createVaultMemoryOp,
+  createSupersedingMemoryOp,
   createVaultMemoriesBatchOp,
   getVaultMemoryOp,
   getAllVaultMemoriesOp,
@@ -6016,6 +6109,7 @@ export {
   setMemoryEntitiesOp,
   clearMemoryTopicsOverrideOp,
   deleteVaultMemoryOp,
+  supersedeVaultMemoryOp,
   getUnfiledVaultMemoriesOp,
   getMemoriesNeedingTopicExtractionOp,
   stampTopicsExtractedAtOp,