@anuma/sdk 6.17.1 → 6.18.0

package/dist/expo/index.cjs

@@ -19308,6 +19308,26 @@ var MANUAL_FACT_TYPES = [
 function normalizeManualFactType(value) {
   return typeof value === "string" && MANUAL_FACT_TYPES.includes(value) ? value : void 0;
 }
+async function notifyWritten(options, input, outcome) {
+  try {
+    await options?.onWritten?.({ input, outcome });
+  } catch {
+  }
+}
+function describeWriteOutcome(outcome) {
+  switch (outcome.action) {
+    case "create":
+      return `Memory saved successfully (ID: ${outcome.memoryId}).`;
+    case "update":
+    case "supersede":
+      return `Memory saved successfully (ID: ${outcome.memoryId}); it replaces an earlier version of this fact.`;
+    case "merge":
+    case "skip":
+      return `The vault already holds this fact (ID: ${outcome.memoryId}); it was noted as re-observed. Nothing new was created \u2014 do not save it again.`;
+    case "suppressed":
+      return "Not saved: this matches a memory the user previously deleted. Do not re-save it.";
+  }
+}
 function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
   const hasOnSave = !!options?.onSave;
   const folderNames = options?.folderMap ? Array.from(options.folderMap.keys()) : [];
@@ -19400,6 +19420,17 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
           return `Memory updated successfully (ID: ${updated.uniqueId}).`;
         } else {
           const folderId = folderName ? options?.folderMap?.get(folderName) : void 0;
+          if (options?.write) {
+            const input = {
+              content,
+              scope,
+              ...folderId !== void 0 && { folderId },
+              ...factType !== void 0 && { factType }
+            };
+            const outcome = await options.write(input);
+            await notifyWritten(options, input, outcome);
+            return describeWriteOutcome(outcome);
+          }
           const created = await createVaultMemoryOp(vaultCtx, {
             content,
             scope,
@@ -19419,6 +19450,16 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
               }
             );
           }
+          await notifyWritten(
+            options,
+            {
+              content,
+              scope,
+              ...folderId !== void 0 && { folderId },
+              ...factType !== void 0 && { factType }
+            },
+            { memoryId: created.uniqueId, action: "create" }
+          );
           return `Memory saved successfully (ID: ${created.uniqueId}).`;
         }
       } catch (error) {
@@ -20771,12 +20812,6 @@ function useChatStorage(options) {
     },
     [storageCtx, getToken, baseUrl, embeddingModel, maskEmbeddingInput]
   );
-  const createMemoryVaultTool2 = (0, import_react4.useCallback)(
-    (options2) => {
-      return createMemoryVaultTool(vaultCtx, options2);
-    },
-    [vaultCtx]
-  );
   const vaultEmbeddingCache = (0, import_react4.useMemo)(
     () => getVaultEmbeddingCache(database, walletAddress, embeddingModel),
     [database, walletAddress, embeddingModel]
@@ -20788,6 +20823,42 @@ function useChatStorage(options) {
       chunkVectorCacheRef.current.clear();
     });
   }, [vaultEmbeddingCache]);
+  const retainVaultMemory = (0, import_react4.useCallback)(
+    async (input) => {
+      if (!getToken) {
+        throw new Error("getToken is required to retain a vault memory");
+      }
+      return retain(
+        input.content,
+        {
+          vaultCtx,
+          embeddingOptions: {
+            getToken,
+            baseUrl,
+            model: embeddingModel,
+            maskInput: maskEmbeddingInput
+          },
+          vaultCache: vaultEmbeddingCache
+        },
+        {
+          source: "manual",
+          scope: input.scope,
+          ...input.folderId !== void 0 && { folderId: input.folderId },
+          ...input.factType !== void 0 && { factType: input.factType }
+        }
+      );
+    },
+    [vaultCtx, getToken, baseUrl, embeddingModel, maskEmbeddingInput, vaultEmbeddingCache]
+  );
+  const createMemoryVaultTool2 = (0, import_react4.useCallback)(
+    (options2) => {
+      return createMemoryVaultTool(
+        vaultCtx,
+        getToken ? { write: retainVaultMemory, ...options2 } : options2
+      );
+    },
+    [vaultCtx, getToken, retainVaultMemory]
+  );
   const createRecallTool2 = (0, import_react4.useCallback)(
     (toolOptions, callbacks) => {
       if (!getToken) {
@@ -22137,6 +22208,7 @@ function useChatStorage(options) {
     getMessageCount,
     createMemoryEngineTool: createMemoryEngineTool2,
     createMemoryVaultTool: createMemoryVaultTool2,
+    retainVaultMemory,
     createRecallTool: createRecallTool2,
     recall: recallFn,
     getVaultMemories,

package/dist/expo/index.d.mts

@@ -9530,6 +9530,41 @@ declare function decodeChunkVector(vector: number[] | string | null | undefined,
  * Each operation can be intercepted by the host app for confirmation/cancellation.
  */
 
+/**
+ * The 7 FactTypes a manual save may self-classify into (PR5). Mirrors the
+ * extractor's `FactType` union in `memory/autoExtract` — kept as a local const
+ * (not imported) to avoid a memoryVault → memory runtime import cycle. Only used
+ * to validate the optional `type` tool argument; an unrecognized value is
+ * dropped (persisted as null, the untyped/medium-decay bucket).
+ */
+declare const MANUAL_FACT_TYPES: readonly ["identity", "preference", "relationship", "plan", "ongoing_context", "constraint", "other"];
+/** A FactType the save tool's optional `type` argument may carry. */
+type ManualFactType = (typeof MANUAL_FACT_TYPES)[number];
+/**
+ * What a {@link VaultMemoryWriter} reports back. The action set mirrors
+ * `RetainResult.action` in `memory/retain` — restated here rather than imported
+ * for the same reason MANUAL_FACT_TYPES is (memoryVault → memory import cycle).
+ */
+type VaultWriteAction = "create" | "merge" | "update" | "supersede" | "suppressed" | "skip";
+interface VaultWriteOutcome {
+    /** The memory the write landed on: the fresh row, or the existing one it merged into. */
+    memoryId: string;
+    action: VaultWriteAction;
+}
+/** A NEW memory the tool wants written — `id`-addressed updates never come here. */
+interface VaultWriteInput {
+    content: string;
+    scope: string;
+    folderId?: string;
+    factType?: ManualFactType;
+}
+/**
+ * The seam through which the tool writes NEW memories when the host supplies one.
+ * `useChatStorage` (react + expo) passes a `retain()`-backed writer so a
+ * model-initiated save gets the same cosine auto-merge the background extractor
+ * gets, instead of a bare insert that trusts the model to have de-duplicated.
+ */
+type VaultMemoryWriter = (input: VaultWriteInput) => Promise<VaultWriteOutcome>;
 /**
  * Describes a pending vault save operation for UI confirmation.
  */
@@ -9568,6 +9603,35 @@ interface MemoryVaultToolOptions {
      * When provided, the LLM can specify a folderName argument.
      */
     folderMap?: Map<string, string>;
+    /**
+     * Writer for NEW memories. When set, a save without an `id` goes through it
+     * instead of a bare `createVaultMemoryOp`, and the tool phrases its reply from
+     * the reported action (a merge reads as "already known", not "saved").
+     *
+     * The hooks supply a `retain()`-backed writer, which is what makes this tool
+     * stop being a dedup bypass: until then the only thing standing between the
+     * model and a duplicate row was the prompt asking it to pass an `id`. Omit it
+     * (as a bare `createMemoryVaultTool(vaultCtx, …)` caller must — retain needs
+     * embeddings) and the direct insert path is unchanged.
+     *
+     * Updates addressed by `id` never come here: the model has already named the
+     * row, so there is nothing to de-duplicate against.
+     */
+    write?: VaultMemoryWriter;
+    /**
+     * Fires after a NEW memory's write settles, with what was asked and what the
+     * writer did. The host's analytics hook: `onSave` runs BEFORE the write and so
+     * cannot tell a fresh create from a merge into an existing memory — and that
+     * split is the one number that says whether model-initiated saves duplicate
+     * the vault. Fires on both write paths (a `write` seam, or the direct insert
+     * when none is supplied — reported as `create`). Not called for
+     * `id`-addressed updates or cancelled saves. A throwing or rejecting listener
+     * is awaited and swallowed so it can never fail the tool call.
+     */
+    onWritten?: (event: {
+        input: VaultWriteInput;
+        outcome: VaultWriteOutcome;
+    }) => void | Promise<void>;
 }
 /**
  * Creates a memory vault tool for use with chat completions.
@@ -9860,6 +9924,14 @@ interface UseChatStorageResult extends BaseUseChatStorageResult {
     createMemoryEngineTool: (searchOptions?: Partial<MemoryEngineSearchOptions>) => ToolConfig;
     /** Create a memory vault tool pre-configured with hook's vault context and encryption. */
     createMemoryVaultTool: (options?: MemoryVaultToolOptions) => ToolConfig;
+    /**
+     * Write one memory through `retain()` — cosine auto-merge against the vault,
+     * so an explicit "save this" from a host surface (selection → memory, a
+     * manual add) lands as a re-observation of an existing memory instead of a
+     * duplicate row when the vault already holds the fact. The
+     * `memory_vault_save` tool writes through this too. Throws without `getToken`.
+     */
+    retainVaultMemory: (input: VaultWriteInput) => Promise<RetainResult>;
     /**
      * Create the unified recall tool — single chat-completion tool that
      * searches both vault facts and conversation chunks via recall().
@@ -10654,4 +10726,4 @@ declare function refreshNotionAccessToken(params: NotionRefreshTokenParams): Pro
  */
 declare function createNotionTools(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig[];
 
-export { type AutoExtractMessage, type AutoExtractor, type Budget, CHUNKS_DISCARDED_ORIGIN, 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 CreateDecaySweeperOptions, 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_DECAY_POLICY, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FlushResult, type GetConversationsPageOptions, type GetMessagesPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type Logger, LoggerProvider, type LoggerProviderProps, MAX_HOPS, MEDIUM_TTL_MS, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, type MessageRedactionResult, type MessageSkeleton, NEVER_TTL_MS, NODE_BUDGET, NOTION_OAUTH_CONFIG, type NeighborRefiner, type NotionAuthUrlParams, type NotionClientRegistration, type NotionExchangeCodeParams, type NotionOAuthEndpoints, type NotionPKCEChallenge, type NotionRefreshTokenParams, type NotionTokenResponse, type NowSource, type ObservationTrend, type ObservationTrendInput, PAST_EVENT_GRACE_MS, PII_PATTERNS, PROFILE_DOC_VERSION, type PhotoIngestResult, type PhotoMediaRef, type PiiCategory, type PiiMatch, type PiiPattern, PiiRedactor, type PiiRedactorOptions, type PlatformStorage, type PortalLlmAuth, type PortalLlmFailure, type PortalLlmFailureReason, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type PromptPreProcessor, type PromptPreProcessorContext, type PublishedPhotoMemory, type QuantizedEmbedding, type QuarantinedMemoryInfo, QueueManager, type QueueStatus, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankableVaultMemory, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type RedactionResult, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type ResumeStreamWithStorageResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, SDK_SCHEMA_VERSION, SHORT_TTL_MS, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, 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, type SynthesizeProfileOptions, TOOL_RESULT_ORIGIN, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TopicSkipReason, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateVaultFolderOptions, type UpdateVaultMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseCreditsOptions, type UseCreditsResult, type UseModelsOptions, type UseModelsResult, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, type VaultFolderOperationsContext, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultSaveOperation, type VaultSearchResult, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, addConversationMemoriesOp, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildNotionAuthUrl, capHopsForDensity, chatStorageMigrations, chatStorageSchema, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, clearAllEncryptionKeys, clearAllEncryptionState, clearConversationMemoriesOp, clearEncryptionKey, clearLazyTitleCache, clearServerToolsCache, consoleLogger, conversationMemoryToStored, cosineInt8, createAutoExtractor, createChunkVectorCache, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageSourceResolver, createNotionTools, createPlatformCursorStore, createRecallTool, createStockPricePreProcessor, createStreamingDeAnonymizer, createVaultEmbeddingCache, createVaultFolderOp, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decodeChunkVector, decryptConversationTitle, deleteAllVaultMemoriesForUserOp, deleteVaultFolderOp, deleteVaultMemoryOp, dequantizeEmbedding, discoverNotionOAuthEndpoints, eagerEmbedContent, embedAllMessages, embedMessage, encodeChunkVector, ensureDefaultFoldersOp, exchangeNotionCode, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, generateConversationId, generateEmbedding, generateEmbeddings, generateNotionPKCE, getAllVaultFoldersOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getCachedServerTools, getConversationMemoriesOp, getConversationsByProjectLazyOp, getConversationsLazyOp, getConversationsPageOp, getDecayCandidatesRawOp, getLogger, getMemoriesNeedingTopicExtractionOp, getServerTools, getUnfiledVaultMemoriesOp, getVaultFolderMemoryCountOp, getVaultMemoriesByIdsOp, getVaultMemoryOp, getVaultRankingProjectionsOp, hardDeleteDecayedOp, hasEncryptionKey, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isDegradedTopicSkip, isPiiRedactor, isRerankerAvailable, maskScopedEmbeddingCache, moveMemoriesToFolderOp, noopLogger, onKeyAvailable, parseMedia, preEmbedVaultMemories, quantizeEmbedding, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, refreshNotionAccessToken, registerNotionClient, relinkMemoryTopicsOp, requestEncryptionKey, resolvePiiRedactor, restoreVaultMemoryOp, resumeStream, retain, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchVaultMemories, seedEncryptionKeys, setLogger, setMemoryVisibilityOp, shouldChunkMessage, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, supersedeVaultMemoryOp, synthesizeProfile, traverseGraphLane, ttlForType, updateVaultFolderContextOp, updateVaultFolderOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertMessageOp, useChat, useChatStorage, useCredits, useEncryption, useModels, verifyMemoriesForPublish, xhrTransport };
+export { type AutoExtractMessage, type AutoExtractor, type Budget, CHUNKS_DISCARDED_ORIGIN, 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 CreateDecaySweeperOptions, 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_DECAY_POLICY, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FlushResult, type GetConversationsPageOptions, type GetMessagesPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type Logger, LoggerProvider, type LoggerProviderProps, MAX_HOPS, MEDIUM_TTL_MS, type ManualFactType, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, type MessageRedactionResult, type MessageSkeleton, NEVER_TTL_MS, NODE_BUDGET, NOTION_OAUTH_CONFIG, type NeighborRefiner, type NotionAuthUrlParams, type NotionClientRegistration, type NotionExchangeCodeParams, type NotionOAuthEndpoints, type NotionPKCEChallenge, type NotionRefreshTokenParams, type NotionTokenResponse, type NowSource, type ObservationTrend, type ObservationTrendInput, PAST_EVENT_GRACE_MS, PII_PATTERNS, PROFILE_DOC_VERSION, type PhotoIngestResult, type PhotoMediaRef, type PiiCategory, type PiiMatch, type PiiPattern, PiiRedactor, type PiiRedactorOptions, type PlatformStorage, type PortalLlmAuth, type PortalLlmFailure, type PortalLlmFailureReason, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type PromptPreProcessor, type PromptPreProcessorContext, type PublishedPhotoMemory, type QuantizedEmbedding, type QuarantinedMemoryInfo, QueueManager, type QueueStatus, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankableVaultMemory, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type RedactionResult, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type ResumeStreamWithStorageResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, SDK_SCHEMA_VERSION, SHORT_TTL_MS, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, 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, type SynthesizeProfileOptions, TOOL_RESULT_ORIGIN, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TopicSkipReason, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateVaultFolderOptions, type UpdateVaultMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseCreditsOptions, type UseCreditsResult, type UseModelsOptions, type UseModelsResult, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, type VaultFolderOperationsContext, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultMemoryWriter, type VaultSaveOperation, type VaultSearchResult, type VaultWriteAction, type VaultWriteInput, type VaultWriteOutcome, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, addConversationMemoriesOp, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildNotionAuthUrl, capHopsForDensity, chatStorageMigrations, chatStorageSchema, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, clearAllEncryptionKeys, clearAllEncryptionState, clearConversationMemoriesOp, clearEncryptionKey, clearLazyTitleCache, clearServerToolsCache, consoleLogger, conversationMemoryToStored, cosineInt8, createAutoExtractor, createChunkVectorCache, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageSourceResolver, createNotionTools, createPlatformCursorStore, createRecallTool, createStockPricePreProcessor, createStreamingDeAnonymizer, createVaultEmbeddingCache, createVaultFolderOp, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decodeChunkVector, decryptConversationTitle, deleteAllVaultMemoriesForUserOp, deleteVaultFolderOp, deleteVaultMemoryOp, dequantizeEmbedding, discoverNotionOAuthEndpoints, eagerEmbedContent, embedAllMessages, embedMessage, encodeChunkVector, ensureDefaultFoldersOp, exchangeNotionCode, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, generateConversationId, generateEmbedding, generateEmbeddings, generateNotionPKCE, getAllVaultFoldersOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getCachedServerTools, getConversationMemoriesOp, getConversationsByProjectLazyOp, getConversationsLazyOp, getConversationsPageOp, getDecayCandidatesRawOp, getLogger, getMemoriesNeedingTopicExtractionOp, getServerTools, getUnfiledVaultMemoriesOp, getVaultFolderMemoryCountOp, getVaultMemoriesByIdsOp, getVaultMemoryOp, getVaultRankingProjectionsOp, hardDeleteDecayedOp, hasEncryptionKey, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isDegradedTopicSkip, isPiiRedactor, isRerankerAvailable, maskScopedEmbeddingCache, moveMemoriesToFolderOp, noopLogger, onKeyAvailable, parseMedia, preEmbedVaultMemories, quantizeEmbedding, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, refreshNotionAccessToken, registerNotionClient, relinkMemoryTopicsOp, requestEncryptionKey, resolvePiiRedactor, restoreVaultMemoryOp, resumeStream, retain, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchVaultMemories, seedEncryptionKeys, setLogger, setMemoryVisibilityOp, shouldChunkMessage, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, supersedeVaultMemoryOp, synthesizeProfile, traverseGraphLane, ttlForType, updateVaultFolderContextOp, updateVaultFolderOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertMessageOp, useChat, useChatStorage, useCredits, useEncryption, useModels, verifyMemoriesForPublish, xhrTransport };

package/dist/expo/index.d.ts

@@ -9530,6 +9530,41 @@ declare function decodeChunkVector(vector: number[] | string | null | undefined,
  * Each operation can be intercepted by the host app for confirmation/cancellation.
  */
 
+/**
+ * The 7 FactTypes a manual save may self-classify into (PR5). Mirrors the
+ * extractor's `FactType` union in `memory/autoExtract` — kept as a local const
+ * (not imported) to avoid a memoryVault → memory runtime import cycle. Only used
+ * to validate the optional `type` tool argument; an unrecognized value is
+ * dropped (persisted as null, the untyped/medium-decay bucket).
+ */
+declare const MANUAL_FACT_TYPES: readonly ["identity", "preference", "relationship", "plan", "ongoing_context", "constraint", "other"];
+/** A FactType the save tool's optional `type` argument may carry. */
+type ManualFactType = (typeof MANUAL_FACT_TYPES)[number];
+/**
+ * What a {@link VaultMemoryWriter} reports back. The action set mirrors
+ * `RetainResult.action` in `memory/retain` — restated here rather than imported
+ * for the same reason MANUAL_FACT_TYPES is (memoryVault → memory import cycle).
+ */
+type VaultWriteAction = "create" | "merge" | "update" | "supersede" | "suppressed" | "skip";
+interface VaultWriteOutcome {
+    /** The memory the write landed on: the fresh row, or the existing one it merged into. */
+    memoryId: string;
+    action: VaultWriteAction;
+}
+/** A NEW memory the tool wants written — `id`-addressed updates never come here. */
+interface VaultWriteInput {
+    content: string;
+    scope: string;
+    folderId?: string;
+    factType?: ManualFactType;
+}
+/**
+ * The seam through which the tool writes NEW memories when the host supplies one.
+ * `useChatStorage` (react + expo) passes a `retain()`-backed writer so a
+ * model-initiated save gets the same cosine auto-merge the background extractor
+ * gets, instead of a bare insert that trusts the model to have de-duplicated.
+ */
+type VaultMemoryWriter = (input: VaultWriteInput) => Promise<VaultWriteOutcome>;
 /**
  * Describes a pending vault save operation for UI confirmation.
  */
@@ -9568,6 +9603,35 @@ interface MemoryVaultToolOptions {
      * When provided, the LLM can specify a folderName argument.
      */
     folderMap?: Map<string, string>;
+    /**
+     * Writer for NEW memories. When set, a save without an `id` goes through it
+     * instead of a bare `createVaultMemoryOp`, and the tool phrases its reply from
+     * the reported action (a merge reads as "already known", not "saved").
+     *
+     * The hooks supply a `retain()`-backed writer, which is what makes this tool
+     * stop being a dedup bypass: until then the only thing standing between the
+     * model and a duplicate row was the prompt asking it to pass an `id`. Omit it
+     * (as a bare `createMemoryVaultTool(vaultCtx, …)` caller must — retain needs
+     * embeddings) and the direct insert path is unchanged.
+     *
+     * Updates addressed by `id` never come here: the model has already named the
+     * row, so there is nothing to de-duplicate against.
+     */
+    write?: VaultMemoryWriter;
+    /**
+     * Fires after a NEW memory's write settles, with what was asked and what the
+     * writer did. The host's analytics hook: `onSave` runs BEFORE the write and so
+     * cannot tell a fresh create from a merge into an existing memory — and that
+     * split is the one number that says whether model-initiated saves duplicate
+     * the vault. Fires on both write paths (a `write` seam, or the direct insert
+     * when none is supplied — reported as `create`). Not called for
+     * `id`-addressed updates or cancelled saves. A throwing or rejecting listener
+     * is awaited and swallowed so it can never fail the tool call.
+     */
+    onWritten?: (event: {
+        input: VaultWriteInput;
+        outcome: VaultWriteOutcome;
+    }) => void | Promise<void>;
 }
 /**
  * Creates a memory vault tool for use with chat completions.
@@ -9860,6 +9924,14 @@ interface UseChatStorageResult extends BaseUseChatStorageResult {
     createMemoryEngineTool: (searchOptions?: Partial<MemoryEngineSearchOptions>) => ToolConfig;
     /** Create a memory vault tool pre-configured with hook's vault context and encryption. */
     createMemoryVaultTool: (options?: MemoryVaultToolOptions) => ToolConfig;
+    /**
+     * Write one memory through `retain()` — cosine auto-merge against the vault,
+     * so an explicit "save this" from a host surface (selection → memory, a
+     * manual add) lands as a re-observation of an existing memory instead of a
+     * duplicate row when the vault already holds the fact. The
+     * `memory_vault_save` tool writes through this too. Throws without `getToken`.
+     */
+    retainVaultMemory: (input: VaultWriteInput) => Promise<RetainResult>;
     /**
      * Create the unified recall tool — single chat-completion tool that
      * searches both vault facts and conversation chunks via recall().
@@ -10654,4 +10726,4 @@ declare function refreshNotionAccessToken(params: NotionRefreshTokenParams): Pro
  */
 declare function createNotionTools(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig[];
 
-export { type AutoExtractMessage, type AutoExtractor, type Budget, CHUNKS_DISCARDED_ORIGIN, 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 CreateDecaySweeperOptions, 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_DECAY_POLICY, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FlushResult, type GetConversationsPageOptions, type GetMessagesPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type Logger, LoggerProvider, type LoggerProviderProps, MAX_HOPS, MEDIUM_TTL_MS, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, type MessageRedactionResult, type MessageSkeleton, NEVER_TTL_MS, NODE_BUDGET, NOTION_OAUTH_CONFIG, type NeighborRefiner, type NotionAuthUrlParams, type NotionClientRegistration, type NotionExchangeCodeParams, type NotionOAuthEndpoints, type NotionPKCEChallenge, type NotionRefreshTokenParams, type NotionTokenResponse, type NowSource, type ObservationTrend, type ObservationTrendInput, PAST_EVENT_GRACE_MS, PII_PATTERNS, PROFILE_DOC_VERSION, type PhotoIngestResult, type PhotoMediaRef, type PiiCategory, type PiiMatch, type PiiPattern, PiiRedactor, type PiiRedactorOptions, type PlatformStorage, type PortalLlmAuth, type PortalLlmFailure, type PortalLlmFailureReason, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type PromptPreProcessor, type PromptPreProcessorContext, type PublishedPhotoMemory, type QuantizedEmbedding, type QuarantinedMemoryInfo, QueueManager, type QueueStatus, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankableVaultMemory, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type RedactionResult, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type ResumeStreamWithStorageResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, SDK_SCHEMA_VERSION, SHORT_TTL_MS, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, 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, type SynthesizeProfileOptions, TOOL_RESULT_ORIGIN, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TopicSkipReason, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateVaultFolderOptions, type UpdateVaultMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseCreditsOptions, type UseCreditsResult, type UseModelsOptions, type UseModelsResult, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, type VaultFolderOperationsContext, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultSaveOperation, type VaultSearchResult, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, addConversationMemoriesOp, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildNotionAuthUrl, capHopsForDensity, chatStorageMigrations, chatStorageSchema, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, clearAllEncryptionKeys, clearAllEncryptionState, clearConversationMemoriesOp, clearEncryptionKey, clearLazyTitleCache, clearServerToolsCache, consoleLogger, conversationMemoryToStored, cosineInt8, createAutoExtractor, createChunkVectorCache, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageSourceResolver, createNotionTools, createPlatformCursorStore, createRecallTool, createStockPricePreProcessor, createStreamingDeAnonymizer, createVaultEmbeddingCache, createVaultFolderOp, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decodeChunkVector, decryptConversationTitle, deleteAllVaultMemoriesForUserOp, deleteVaultFolderOp, deleteVaultMemoryOp, dequantizeEmbedding, discoverNotionOAuthEndpoints, eagerEmbedContent, embedAllMessages, embedMessage, encodeChunkVector, ensureDefaultFoldersOp, exchangeNotionCode, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, generateConversationId, generateEmbedding, generateEmbeddings, generateNotionPKCE, getAllVaultFoldersOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getCachedServerTools, getConversationMemoriesOp, getConversationsByProjectLazyOp, getConversationsLazyOp, getConversationsPageOp, getDecayCandidatesRawOp, getLogger, getMemoriesNeedingTopicExtractionOp, getServerTools, getUnfiledVaultMemoriesOp, getVaultFolderMemoryCountOp, getVaultMemoriesByIdsOp, getVaultMemoryOp, getVaultRankingProjectionsOp, hardDeleteDecayedOp, hasEncryptionKey, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isDegradedTopicSkip, isPiiRedactor, isRerankerAvailable, maskScopedEmbeddingCache, moveMemoriesToFolderOp, noopLogger, onKeyAvailable, parseMedia, preEmbedVaultMemories, quantizeEmbedding, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, refreshNotionAccessToken, registerNotionClient, relinkMemoryTopicsOp, requestEncryptionKey, resolvePiiRedactor, restoreVaultMemoryOp, resumeStream, retain, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchVaultMemories, seedEncryptionKeys, setLogger, setMemoryVisibilityOp, shouldChunkMessage, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, supersedeVaultMemoryOp, synthesizeProfile, traverseGraphLane, ttlForType, updateVaultFolderContextOp, updateVaultFolderOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertMessageOp, useChat, useChatStorage, useCredits, useEncryption, useModels, verifyMemoriesForPublish, xhrTransport };
+export { type AutoExtractMessage, type AutoExtractor, type Budget, CHUNKS_DISCARDED_ORIGIN, 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 CreateDecaySweeperOptions, 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_DECAY_POLICY, DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP, DEFAULT_MIN_CHUNK_SIZE, DEFAULT_PROFILE_FACETS, DEFAULT_PROFILE_FACT_TYPE_WEIGHTS, DEFAULT_PROFILE_PROOF_ALPHA, DEFAULT_PROFILE_TREND_MULTIPLIERS, DEFAULT_VAULT_CACHE_SIZE, DatabaseManager, type DatabaseManagerLogger, type DatabaseManagerOptions, type DecayCandidateRaw, type DecayClassifier, type DecayInput, type DecayPolicy, type DecaySweepResult, type DecaySweeper, type DecayVerdict, ENTITY_FANOUT, type EmbeddedWalletSignerFn, EncryptionKeyMissingError, type ExtractFactsOptions, type ExtractOutcome, type ExtractedCandidate, type ExtractedEntity, type ExtractionCursorStore, type FactType, type FileMetadata, type FlushResult, type GetConversationsPageOptions, type GetMessagesPageOptions, type GraphTraversalOptions, HARD_DELETE_WINDOW_MS, INFERENCE_ID_HEADER, type InjectionClassifierOptions, type InjectionReason, type LazyStoredConversation, type LlmDecayClassifierOptions, type LlmNeighborRefinerOptions, type Logger, LoggerProvider, type LoggerProviderProps, MAX_HOPS, MEDIUM_TTL_MS, type ManualFactType, type MemoriesNeedingTopicExtraction, type EmbeddingOptions as MemoryEngineEmbeddingOptions, type MemoryEngineResult, type MemoryEngineSearchOptions, type MemoryExtractedEvent, type MemoryKind, type MemoryQuarantinedEvent, type MemoryToVerify, type MemoryVaultSearchOptions, type MemoryVaultToolOptions, type MemoryVerification, type MessageRedactionResult, type MessageSkeleton, NEVER_TTL_MS, NODE_BUDGET, NOTION_OAUTH_CONFIG, type NeighborRefiner, type NotionAuthUrlParams, type NotionClientRegistration, type NotionExchangeCodeParams, type NotionOAuthEndpoints, type NotionPKCEChallenge, type NotionRefreshTokenParams, type NotionTokenResponse, type NowSource, type ObservationTrend, type ObservationTrendInput, PAST_EVENT_GRACE_MS, PII_PATTERNS, PROFILE_DOC_VERSION, type PhotoIngestResult, type PhotoMediaRef, type PiiCategory, type PiiMatch, type PiiPattern, PiiRedactor, type PiiRedactorOptions, type PlatformStorage, type PortalLlmAuth, type PortalLlmFailure, type PortalLlmFailureReason, type ProfileConfigFingerprint, type ProfileDoc, type ProfileFacet, type ProfileFacetKey, type ProfileSalienceInput, type ProfileSection, type PromptPreProcessor, type PromptPreProcessorContext, type PublishedPhotoMemory, type QuantizedEmbedding, type QuarantinedMemoryInfo, QueueManager, type QueueStatus, RECALL_MAX_LIMIT, RECALL_TOOL_NAME, type RankableVaultMemory, type RankedMemory, type RankedProfileCandidate, type RecallContext, type RecallDegradation, type RecallDiagnostics, type RecallOptions, type RecallResult, type RecallToolCallbacks, type RecallToolOptions, type RecencyOptions, type RedactionResult, type ReflectOptions, type ReflectResult, type RequestEncryptionKeyOptions, RerankerUnavailableError, type ResumeStreamOptions, type ResumeStreamResult, type ResumeStreamWithStorageResult, type RetainAction, type RetainContext, type RetainOptions, type RetainResult, type RetainSource, SDK_SCHEMA_VERSION, SHORT_TTL_MS, STREAM_RESUMABLE_HEADER, type ScoreBreakdown, type ScoreProfileSalienceOptions, type ScreenResult, type ScreenedCandidate, 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, type SynthesizeProfileOptions, TOOL_RESULT_ORIGIN, TOPICS_EXTRACTION_VERSION, TOPIC_EXTRACTION_BATCH_SIZE, TREND_RECENT_WINDOW_DAYS, TREND_STALE_WINDOW_DAYS, type TextChunk, type TopicExtractOptions, type TopicExtractionInput, type TopicExtractionRunResult, type TopicSkipReason, type TurnCompleteEvent, type TurnSkippedEvent, type UncheckedReason, type UnverifiableReason, type UpdateVaultFolderOptions, type UpdateVaultMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseCreditsOptions, type UseCreditsResult, type UseModelsOptions, type UseModelsResult, VAULT_SIZE_HOP_CAP, type VaultEmbeddingCache, type VaultFolderOperationsContext, type VaultMemoryOperationsContext, type VaultMemoryVisibility, type VaultMemoryWriter, type VaultSaveOperation, type VaultSearchResult, type VaultWriteAction, type VaultWriteInput, type VaultWriteOutcome, type VerificationSources, type VerifyMemoriesForPublishOptions, WalletPoller, type WeatherClassification, type WeatherPreProcessorOptions, type WebSearchClassification, type WebSearchPreProcessorOptions, addConversationMemoriesOp, archiveVaultMemoryOp, backfillMemoryTopicsOp, buildNotionAuthUrl, capHopsForDensity, chatStorageMigrations, chatStorageSchema, chunkAndEmbedAllMessages, chunkAndEmbedMessage, chunkText, classifyCryptoPrice, classifyCryptoPriceBatch, classifyDecay, classifyInjectionCandidates, classifyObservationTrend, classifyStockPrice, classifyStockPriceBatch, classifyWeather, classifyWeatherBatch, classifyWebSearch, classifyWebSearchBatch, clearAllEncryptionKeys, clearAllEncryptionState, clearConversationMemoriesOp, clearEncryptionKey, clearLazyTitleCache, clearServerToolsCache, consoleLogger, conversationMemoryToStored, cosineInt8, createAutoExtractor, createChunkVectorCache, createCryptoPricePreProcessor, createDecaySweeper, createLlmDecayClassifier, createLlmNeighborRefiner, createMemoryEngineTool, createMemoryVaultSearchTool, createMemoryVaultTool, createMessageSourceResolver, createNotionTools, createPlatformCursorStore, createRecallTool, createStockPricePreProcessor, createStreamingDeAnonymizer, createVaultEmbeddingCache, createVaultFolderOp, createVaultMemoriesBatchOp, createVaultMemoryOp, createWeatherPreProcessor, createWebSearchPreProcessor, decodeChunkVector, decryptConversationTitle, deleteAllVaultMemoriesForUserOp, deleteVaultFolderOp, deleteVaultMemoryOp, dequantizeEmbedding, discoverNotionOAuthEndpoints, eagerEmbedContent, embedAllMessages, embedMessage, encodeChunkVector, ensureDefaultFoldersOp, exchangeNotionCode, extractAndLinkEntitiesForMemoriesOp, extractAndRetain, extractEntitiesForMemories, extractFacts, generateConversationId, generateEmbedding, generateEmbeddings, generateNotionPKCE, getAllVaultFoldersOp, getAllVaultMemoriesOp, getAllVaultMemoryContentsOp, getCachedServerTools, getConversationMemoriesOp, getConversationsByProjectLazyOp, getConversationsLazyOp, getConversationsPageOp, getDecayCandidatesRawOp, getLogger, getMemoriesNeedingTopicExtractionOp, getServerTools, getUnfiledVaultMemoriesOp, getVaultFolderMemoryCountOp, getVaultMemoriesByIdsOp, getVaultMemoryOp, getVaultRankingProjectionsOp, hardDeleteDecayedOp, hasEncryptionKey, ingestPublishedPhotoMemoriesOp, injectionSignatureCatalog, isDegradedTopicSkip, isPiiRedactor, isRerankerAvailable, maskScopedEmbeddingCache, moveMemoriesToFolderOp, noopLogger, onKeyAvailable, parseMedia, preEmbedVaultMemories, quantizeEmbedding, queueManager, rankProfileCandidates, recall, reflect, refreshEncryptionKeyIfMatches, refreshNotionAccessToken, registerNotionClient, relinkMemoryTopicsOp, requestEncryptionKey, resolvePiiRedactor, restoreVaultMemoryOp, resumeStream, retain, scoreProfileSalience, screenCandidatesForInjection, sdkMigrations, sdkModelClasses, sdkSchema, searchVaultMemories, seedEncryptionKeys, setLogger, setMemoryVisibilityOp, shouldChunkMessage, stampTopicsExtractedAtOp, streamCancelPath, streamReplayPath, summarizeObservationTrends, supersedeVaultMemoryOp, synthesizeProfile, traverseGraphLane, ttlForType, updateVaultFolderContextOp, updateVaultFolderOp, updateVaultMemoryEmbeddingOp, updateVaultMemoryOp, upsertMessageOp, useChat, useChatStorage, useCredits, useEncryption, useModels, verifyMemoriesForPublish, xhrTransport };

package/dist/expo/index.mjs

@@ -9517,6 +9517,26 @@ var MANUAL_FACT_TYPES = [
 function normalizeManualFactType(value) {
   return typeof value === "string" && MANUAL_FACT_TYPES.includes(value) ? value : void 0;
 }
+async function notifyWritten(options, input, outcome) {
+  try {
+    await options?.onWritten?.({ input, outcome });
+  } catch {
+  }
+}
+function describeWriteOutcome(outcome) {
+  switch (outcome.action) {
+    case "create":
+      return `Memory saved successfully (ID: ${outcome.memoryId}).`;
+    case "update":
+    case "supersede":
+      return `Memory saved successfully (ID: ${outcome.memoryId}); it replaces an earlier version of this fact.`;
+    case "merge":
+    case "skip":
+      return `The vault already holds this fact (ID: ${outcome.memoryId}); it was noted as re-observed. Nothing new was created \u2014 do not save it again.`;
+    case "suppressed":
+      return "Not saved: this matches a memory the user previously deleted. Do not re-save it.";
+  }
+}
 function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
   const hasOnSave = !!options?.onSave;
   const folderNames = options?.folderMap ? Array.from(options.folderMap.keys()) : [];
@@ -9609,6 +9629,17 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
           return `Memory updated successfully (ID: ${updated.uniqueId}).`;
         } else {
           const folderId = folderName ? options?.folderMap?.get(folderName) : void 0;
+          if (options?.write) {
+            const input = {
+              content,
+              scope,
+              ...folderId !== void 0 && { folderId },
+              ...factType !== void 0 && { factType }
+            };
+            const outcome = await options.write(input);
+            await notifyWritten(options, input, outcome);
+            return describeWriteOutcome(outcome);
+          }
           const created = await createVaultMemoryOp(vaultCtx, {
             content,
             scope,
@@ -9628,6 +9659,16 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
               }
             );
           }
+          await notifyWritten(
+            options,
+            {
+              content,
+              scope,
+              ...folderId !== void 0 && { folderId },
+              ...factType !== void 0 && { factType }
+            },
+            { memoryId: created.uniqueId, action: "create" }
+          );
           return `Memory saved successfully (ID: ${created.uniqueId}).`;
         }
       } catch (error) {
@@ -10970,12 +11011,6 @@ function useChatStorage(options) {
     },
     [storageCtx, getToken, baseUrl, embeddingModel, maskEmbeddingInput]
   );
-  const createMemoryVaultTool2 = useCallback4(
-    (options2) => {
-      return createMemoryVaultTool(vaultCtx, options2);
-    },
-    [vaultCtx]
-  );
   const vaultEmbeddingCache = useMemo(
     () => getVaultEmbeddingCache(database, walletAddress, embeddingModel),
     [database, walletAddress, embeddingModel]
@@ -10987,6 +11022,42 @@ function useChatStorage(options) {
       chunkVectorCacheRef.current.clear();
     });
   }, [vaultEmbeddingCache]);
+  const retainVaultMemory = useCallback4(
+    async (input) => {
+      if (!getToken) {
+        throw new Error("getToken is required to retain a vault memory");
+      }
+      return retain(
+        input.content,
+        {
+          vaultCtx,
+          embeddingOptions: {
+            getToken,
+            baseUrl,
+            model: embeddingModel,
+            maskInput: maskEmbeddingInput
+          },
+          vaultCache: vaultEmbeddingCache
+        },
+        {
+          source: "manual",
+          scope: input.scope,
+          ...input.folderId !== void 0 && { folderId: input.folderId },
+          ...input.factType !== void 0 && { factType: input.factType }
+        }
+      );
+    },
+    [vaultCtx, getToken, baseUrl, embeddingModel, maskEmbeddingInput, vaultEmbeddingCache]
+  );
+  const createMemoryVaultTool2 = useCallback4(
+    (options2) => {
+      return createMemoryVaultTool(
+        vaultCtx,
+        getToken ? { write: retainVaultMemory, ...options2 } : options2
+      );
+    },
+    [vaultCtx, getToken, retainVaultMemory]
+  );
   const createRecallTool2 = useCallback4(
     (toolOptions, callbacks) => {
       if (!getToken) {
@@ -12336,6 +12407,7 @@ function useChatStorage(options) {
     getMessageCount,
     createMemoryEngineTool: createMemoryEngineTool2,
     createMemoryVaultTool: createMemoryVaultTool2,
+    retainVaultMemory,
     createRecallTool: createRecallTool2,
     recall: recallFn,
     getVaultMemories,

package/dist/react/index.cjs

@@ -20606,6 +20606,26 @@ var MANUAL_FACT_TYPES = [
 function normalizeManualFactType(value) {
   return typeof value === "string" && MANUAL_FACT_TYPES.includes(value) ? value : void 0;
 }
+async function notifyWritten(options, input, outcome) {
+  try {
+    await options?.onWritten?.({ input, outcome });
+  } catch {
+  }
+}
+function describeWriteOutcome(outcome) {
+  switch (outcome.action) {
+    case "create":
+      return `Memory saved successfully (ID: ${outcome.memoryId}).`;
+    case "update":
+    case "supersede":
+      return `Memory saved successfully (ID: ${outcome.memoryId}); it replaces an earlier version of this fact.`;
+    case "merge":
+    case "skip":
+      return `The vault already holds this fact (ID: ${outcome.memoryId}); it was noted as re-observed. Nothing new was created \u2014 do not save it again.`;
+    case "suppressed":
+      return "Not saved: this matches a memory the user previously deleted. Do not re-save it.";
+  }
+}
 function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
   const hasOnSave = !!options?.onSave;
   const folderNames = options?.folderMap ? Array.from(options.folderMap.keys()) : [];
@@ -20698,6 +20718,17 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
           return `Memory updated successfully (ID: ${updated.uniqueId}).`;
         } else {
           const folderId = folderName ? options?.folderMap?.get(folderName) : void 0;
+          if (options?.write) {
+            const input = {
+              content,
+              scope,
+              ...folderId !== void 0 && { folderId },
+              ...factType !== void 0 && { factType }
+            };
+            const outcome = await options.write(input);
+            await notifyWritten(options, input, outcome);
+            return describeWriteOutcome(outcome);
+          }
           const created = await createVaultMemoryOp(vaultCtx, {
             content,
             scope,
@@ -20717,6 +20748,16 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
               }
             );
           }
+          await notifyWritten(
+            options,
+            {
+              content,
+              scope,
+              ...folderId !== void 0 && { folderId },
+              ...factType !== void 0 && { factType }
+            },
+            { memoryId: created.uniqueId, action: "create" }
+          );
           return `Memory saved successfully (ID: ${created.uniqueId}).`;
         }
       } catch (error) {
@@ -23318,17 +23359,42 @@ function useChatStorage(options) {
     },
     [storageCtx, getToken, vaultEmbeddingOptions]
   );
+  const retainVaultMemory = (0, import_react5.useCallback)(
+    async (input) => {
+      if (!getToken) {
+        throw new Error("getToken is required to retain a vault memory");
+      }
+      return retain(
+        input.content,
+        {
+          vaultCtx,
+          embeddingOptions: vaultEmbeddingOptions,
+          vaultCache: vaultEmbeddingCache
+        },
+        {
+          source: "manual",
+          scope: input.scope,
+          ...input.folderId !== void 0 && { folderId: input.folderId },
+          ...input.factType !== void 0 && { factType: input.factType }
+        }
+      );
+    },
+    [vaultCtx, getToken, vaultEmbeddingOptions, vaultEmbeddingCache]
+  );
   const createMemoryVaultTool2 = (0, import_react5.useCallback)(
     (options2) => {
       const embOpts = getToken ? vaultEmbeddingOptions : void 0;
       return createMemoryVaultTool(
         vaultCtx,
-        options2,
+        // New memories go through retain() (auto-merge) whenever embeddings are
+        // available; a caller-supplied `write` still wins. Without a token the
+        // tool keeps its direct-insert path — retain cannot embed.
+        embOpts ? { write: retainVaultMemory, ...options2 } : options2,
         embOpts,
         embOpts ? vaultEmbeddingCache : void 0
       );
     },
-    [vaultCtx, getToken, vaultEmbeddingOptions, vaultEmbeddingCache]
+    [vaultCtx, getToken, vaultEmbeddingOptions, vaultEmbeddingCache, retainVaultMemory]
   );
   const getVaultMemories = (0, import_react5.useCallback)(
     (options2) => {
@@ -24624,6 +24690,7 @@ function useChatStorage(options) {
     getAllFiles,
     createMemoryEngineTool: createMemoryEngineTool2,
     createMemoryVaultTool: createMemoryVaultTool2,
+    retainVaultMemory,
     createMemoryVaultSearchTool: createMemoryVaultSearchTool2,
     createRecallTool: createRecallTool2,
     recall: recallFn,