@anuma/sdk 7.0.7 → 7.1.0

package/dist/server/index.cjs

@@ -27824,6 +27824,11 @@ function parseTopics(value) {
 }
 
 // src/lib/db/entities/operations.ts
+async function assertCanWrite(ctx) {
+  if (ctx.canWrite && !await ctx.canWrite()) {
+    throw new Error("Memory source is no longer eligible");
+  }
+}
 function entityToStored(e) {
   return {
     uniqueId: e.id,
@@ -27964,6 +27969,7 @@ async function linkMemoryEntitiesOp(ctx, memoryId, entityInputs, options) {
   let skipped = false;
   let entities = [];
   await ctx.database.write(async () => {
+    await assertCanWrite(ctx);
     const {
       entities: byName,
       operations: entityOps,
@@ -28039,6 +28045,7 @@ async function replaceMemoryEntities(ctx, memoryId, entityInputs, options) {
   let skipped = false;
   let entities = [];
   await ctx.database.write(async () => {
+    await assertCanWrite(ctx);
     const vaultRow = await findVaultRowInWrite(ctx, memoryId);
     if (options.guarded && autoLinkBlocked(vaultRow)) {
       skipped = true;
@@ -28099,6 +28106,7 @@ async function unlinkMemoryEntitiesOp(ctx, memoryIds) {
   const links = await ctx.memoryEntityCollection.query(import_watermelondb18.Q.where("memory_id", import_watermelondb18.Q.oneOf(Array.from(memoryIds)))).fetch();
   if (links.length === 0) return;
   await ctx.database.write(async () => {
+    await assertCanWrite(ctx);
     await ctx.database.batch(...links.map((l) => l.prepareDestroyPermanently()));
   });
 }
@@ -28107,6 +28115,7 @@ async function unlinkAllMemoryEntitiesForUserOp(ctx, userId) {
   const links = await ctx.memoryEntityCollection.query(import_watermelondb18.Q.where("user_id", userId)).fetch();
   if (links.length === 0) return;
   await ctx.database.write(async () => {
+    await assertCanWrite(ctx);
     await ctx.database.batch(...links.map((l) => l.prepareDestroyPermanently()));
   });
 }
@@ -28282,6 +28291,11 @@ function visibilityConditions(requested) {
 function isKinded(record) {
   return record.kind !== null && record.kind !== void 0;
 }
+async function assertCanWrite2(ctx) {
+  if (ctx.canWrite && !await ctx.canWrite()) {
+    throw new Error("Memory source is no longer eligible");
+  }
+}
 function assertValidKindLevel(kind, level) {
   const hasKind = kind !== null && kind !== void 0;
   if (hasKind && !MEMORY_KINDS.includes(kind)) {
@@ -28462,8 +28476,7 @@ async function createVaultMemoryOp(ctx, opts) {
     ctx.embeddedWalletSigner
   ) : opts.content;
   const created = await ctx.database.write(async () => {
-    if (ctx.canWrite && !await ctx.canWrite())
-      throw new Error("Memory source is no longer eligible");
+    await assertCanWrite2(ctx);
     return ctx.vaultMemoryCollection.create(
       (record) => populateNewVaultMemory(record, ctx, opts, encryptedContent, encryptedKindValue)
     );
@@ -28482,8 +28495,7 @@ async function createSupersedingMemoryOp(ctx, opts, targetId) {
   ) : opts.content;
   let createdRecord = null;
   await ctx.database.write(async () => {
-    if (ctx.canWrite && !await ctx.canWrite())
-      throw new Error("Memory source is no longer eligible");
+    await assertCanWrite2(ctx);
     let target;
     try {
       target = await ctx.vaultMemoryCollection.find(targetId);
@@ -28575,8 +28587,7 @@ async function createVaultMemoriesBatchOp(ctx, optionsArray) {
     })
   );
   const created = await ctx.database.write(async () => {
-    if (ctx.canWrite && !await ctx.canWrite())
-      throw new Error("Memory source is no longer eligible");
+    await assertCanWrite2(ctx);
     const prepared = optionsArray.map(
       (opts, i) => ctx.vaultMemoryCollection.prepareCreate(
         (record) => populateNewVaultMemory(record, ctx, opts, encryptedContents[i], encryptedKindValues[i])
@@ -28867,8 +28878,7 @@ async function updateVaultMemoryOp(ctx, id, opts) {
     const record = probe;
     const originalUpdatedAt = record.updatedAt.getTime();
     await ctx.database.write(async () => {
-      if (ctx.canWrite && !await ctx.canWrite())
-        throw new Error("Memory source is no longer eligible");
+      await assertCanWrite2(ctx);
       if (record.isDeleted || record.supersededBy || !isOwnedByCtxUser(ctx, record) || opts.freeFormOnly && isKinded(record)) {
         stale = true;
         return;
@@ -28979,6 +28989,7 @@ async function setMemoryEntitiesOp(ctx, memoryId, entities) {
   let stale = false;
   const originalUpdatedAt = record.updatedAt.getTime();
   await ctx.database.write(async (writer) => {
+    await assertCanWrite2(ctx);
     if (record.isDeleted || !isOwnedByCtxUser(ctx, record)) {
       stale = true;
       return;
@@ -29020,6 +29031,7 @@ async function clearMemoryTopicsOverrideOp(ctx, memoryId, options) {
   const originalUpdatedAt = record.updatedAt.getTime();
   let cleared = false;
   await ctx.database.write(async () => {
+    await assertCanWrite2(ctx);
     if (options?.unlessTopicsRecorded && parseTopics(record.topics) !== null) return;
     cleared = true;
     await record.update((r) => {
@@ -29043,6 +29055,7 @@ async function setMemoryVisibilityOp(ctx, id, opts) {
   if (record.isDeleted || !isOwnedByCtxUser(ctx, record)) return null;
   let stale = false;
   await ctx.database.write(async () => {
+    await assertCanWrite2(ctx);
     if (record.isDeleted || !isOwnedByCtxUser(ctx, record)) {
       stale = true;
       return;
@@ -29071,6 +29084,7 @@ async function deleteVaultMemoryOp(ctx, id) {
     if (record.isDeleted || !isOwnedByCtxUser(ctx, record)) return false;
     let stale = false;
     await ctx.database.write(async () => {
+      await assertCanWrite2(ctx);
       if (record.isDeleted || !isOwnedByCtxUser(ctx, record)) {
         stale = true;
         return;
@@ -29108,8 +29122,7 @@ async function supersedeVaultMemoryOp(ctx, id, supersededById) {
     }
     let stale = false;
     await ctx.database.write(async () => {
-      if (ctx.canWrite && !await ctx.canWrite())
-        throw new Error("Memory source is no longer eligible");
+      await assertCanWrite2(ctx);
       if (record.isDeleted || record.supersededBy || !isOwnedByCtxUser(ctx, record)) {
         stale = true;
         return;
@@ -29271,6 +29284,7 @@ async function stampTopicsExtractedAtOp(ctx, memoryIds, extractedAt, version = T
   for (let i = 0; i < uniqueIds.length; i += CHUNK) {
     const chunkIds = uniqueIds.slice(i, i + CHUNK);
     await ctx.database.write(async () => {
+      await assertCanWrite2(ctx);
       const records = [];
       for (const id of chunkIds) {
         try {
@@ -29304,6 +29318,7 @@ async function relinkMemoryTopicsOp(ctx, memoryIds) {
   for (const id of Array.from(new Set(memoryIds))) {
     try {
       await ctx.database.write(async (writer) => {
+        await assertCanWrite2(ctx);
         let record;
         try {
           record = await ctx.vaultMemoryCollection.find(id);
@@ -29334,6 +29349,7 @@ async function backfillMemoryTopicsOp(ctx, memoryIds) {
   for (let i = 0; i < uniqueIds.length; i += CHUNK) {
     const chunkIds = uniqueIds.slice(i, i + CHUNK);
     await ctx.database.write(async () => {
+      await assertCanWrite2(ctx);
       const writes = [];
       for (const id of chunkIds) {
         let record;
@@ -29366,6 +29382,7 @@ async function deleteAllVaultMemoriesForUserOp(ctx, userId) {
   const records = await ctx.vaultMemoryCollection.query(import_watermelondb19.Q.where("user_id", userId), import_watermelondb19.Q.where("is_deleted", false)).fetch();
   if (records.length === 0) return 0;
   await ctx.database.write(async () => {
+    await assertCanWrite2(ctx);
     const prepared = records.map(
       (record) => record.prepareUpdate((r) => {
         r._setRaw("is_deleted", true);
@@ -29420,6 +29437,7 @@ async function archiveVaultMemoryOp(ctx, id, opts) {
     let stale = false;
     const archivedAtValue = opts?.now ?? Date.now();
     await ctx.database.write(async () => {
+      await assertCanWrite2(ctx);
       if (record.isDeleted || !isOwnedByCtxUser(ctx, record) || record.archivedAt !== null) {
         stale = true;
         return;
@@ -29443,6 +29461,7 @@ async function restoreVaultMemoryOp(ctx, id) {
     if (record.isDeleted || !isOwnedByCtxUser(ctx, record)) return false;
     let stale = false;
     await ctx.database.write(async () => {
+      await assertCanWrite2(ctx);
       if (record.isDeleted || !isOwnedByCtxUser(ctx, record)) {
         stale = true;
         return;
@@ -29463,6 +29482,7 @@ async function hardDeleteDecayedOp(ctx, id, opts) {
     const now = opts.now ?? Date.now();
     let stale = false;
     await ctx.database.write(async () => {
+      await assertCanWrite2(ctx);
       const archivedAt = record.archivedAt;
       if (record.isDeleted || !isOwnedByCtxUser(ctx, record) || archivedAt === null || now - archivedAt <= opts.hardDeleteWindowMs) {
         stale = true;
@@ -29502,6 +29522,7 @@ async function updateVaultMemoryEmbeddingOp(ctx, id, embedding, embeddingModel,
     }
     let written = false;
     await ctx.database.write(async () => {
+      await assertCanWrite2(ctx);
       if (record.isDeleted || !isOwnedByCtxUser(ctx, record)) return;
       const originalUpdatedAt = record.updatedAt.getTime();
       if (originalUpdatedAt !== readUpdatedAt || record._getRaw("content") !== readStoredContent)
@@ -33194,6 +33215,13 @@ function restoreCandidates(candidates, redactor, ownNames) {
   ).map((c) => c.candidate);
 }
 async function extractAndRetain(messages, retainCtx, options) {
+  const { memoryStore, signal } = options;
+  if (memoryStore === null) throw new Error("Memory store is not ready");
+  if (memoryStore && options.folderId !== void 0 && options.folderId !== null)
+    throw new Error("Remote memory extraction does not support folders");
+  if (memoryStore && options.extract.piiRedaction && !memoryStore.masksEmbeddingInput)
+    throw new Error("PII-redacted extraction requires a memory store that masks embedding inputs");
+  signal?.throwIfAborted();
   const minConfidence = options.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
   const resolvedConsolidatePii = options.consolidateOptions?.piiRedaction ?? options.extract.piiRedaction;
   const consolidateOptions = options.consolidateOptions !== void 0 ? {
@@ -33227,6 +33255,7 @@ async function extractAndRetain(messages, retainCtx, options) {
     }
   });
   const extractMs = Date.now() - tExtract;
+  signal?.throwIfAborted();
   const filtered = candidates.filter((c) => c.confidence >= minConfidence);
   const log = getLogger();
   const screened = screenCandidatesForInjection(filtered);
@@ -33274,16 +33303,33 @@ async function extractAndRetain(messages, retainCtx, options) {
   const results = [];
   const quarantinedInfo = [];
   let failedWrites = 0;
+  let auditRows;
   const tRetain = Date.now();
   for (const { candidate, isQuarantined, reason, signature } of toRetain) {
     try {
+      signal?.throwIfAborted();
       if (isQuarantined) {
-        const existingId = await findQuarantinedDuplicateOp(
-          retainCtx.vaultCtx,
-          candidate.content,
-          candidate.sourceMessageIds,
-          { scope: options.scope ?? "private", folderId: options.folderId ?? null }
-        ).catch(() => null);
+        let existingId;
+        if (memoryStore) {
+          auditRows ?? (auditRows = memoryStore.list({
+            scopes: [options.scope ?? "private"],
+            includeArchived: true,
+            includeQuarantined: true,
+            includeSuperseded: true
+          }));
+          const sourceKey = [...new Set(candidate.sourceMessageIds)].sort().join("\0");
+          const normalize = (value) => value.normalize("NFKC").trim().replace(/\s+/g, " ").toLowerCase();
+          existingId = (await auditRows).find(
+            (row) => row.trustTier === "quarantined" && row.scope === (options.scope ?? "private") && [...new Set(row.sourceChunkIds ?? [])].sort().join("\0") === sourceKey && normalize(row.content) === normalize(candidate.content)
+          )?.uniqueId ?? null;
+        } else {
+          existingId = await findQuarantinedDuplicateOp(
+            retainCtx.vaultCtx,
+            candidate.content,
+            candidate.sourceMessageIds,
+            { scope: options.scope ?? "private", folderId: options.folderId ?? null }
+          ).catch(() => null);
+        }
         if (existingId) {
           quarantinedInfo.push({
             candidate,
@@ -33294,18 +33340,26 @@ async function extractAndRetain(messages, retainCtx, options) {
           continue;
         }
       }
-      const result = await retain(candidate.content, retainCtx, {
+      const retainOptions = {
         source: "auto-extracted",
         sourceChunkIds: candidate.sourceMessageIds,
         respectTombstones: true,
         ...options.scope !== void 0 && { scope: options.scope },
-        ...options.folderId !== void 0 && { folderId: options.folderId },
         ...consolidateOptions !== void 0 && { consolidateOptions },
         ...candidate.eventTime !== null && { eventTime: candidate.eventTime },
         factType: candidate.type,
         ...isQuarantined && { trustTier: "quarantined", enableAutoMerge: false }
+      };
+      const result = memoryStore ? await memoryStore.retain(candidate.content, {
+        ...retainOptions,
+        canWrite: retainCtx.vaultCtx.canWrite,
+        signal
+      }) : await retain(candidate.content, retainCtx, {
+        ...retainOptions,
+        ...options.folderId !== void 0 && { folderId: options.folderId }
       });
       if (isQuarantined) {
+        auditRows = void 0;
         const info = {
           candidate,
           memoryId: result.memoryId,
@@ -33324,9 +33378,16 @@ async function extractAndRetain(messages, retainCtx, options) {
       }
       succeededCandidates.push(candidate);
       results.push(result);
-      if (result.action !== "suppressed" && options.entityCtx && candidate.entities.length > 0) {
+      if (result.action !== "suppressed" && candidate.entities.length > 0) {
         try {
-          if (!await isMemoryTopicsUserManaged(options.entityCtx, result.memoryId)) {
+          signal?.throwIfAborted();
+          if (memoryStore) {
+            await memoryStore.addTopics(result.memoryId, candidate.entities, {
+              unlessUserManaged: true,
+              canWrite: retainCtx.vaultCtx.canWrite,
+              signal
+            });
+          } else if (options.entityCtx && !await isMemoryTopicsUserManaged(options.entityCtx, result.memoryId)) {
             await linkMemoryEntitiesOp(options.entityCtx, result.memoryId, candidate.entities, {
               unlessTopicsUserManaged: true
             });
@@ -33576,7 +33637,7 @@ function createAutoExtractor(options) {
   };
   const consolidateOptions = options.consolidate ? { ...options.consolidate, ...subPassAuth(options.consolidate.baseUrl) } : void 0;
   const injectionClassifierOptions = options.injectionClassifier ? { ...options.injectionClassifier, ...subPassAuth(options.injectionClassifier.baseUrl) } : void 0;
-  if (options.retainCtx.vaultCtx.entityCtx && !options.entityCtx) {
+  if (!options.memoryStore && options.retainCtx.vaultCtx.entityCtx && !options.entityCtx) {
     getLogger().warn(
       "[memory/extract] retainCtx.vaultCtx.entityCtx is set but extractor was created without `entityCtx` \u2014 W5 graph lane will receive no writes"
     );
@@ -33621,6 +33682,8 @@ function createAutoExtractor(options) {
       try {
         const { candidates, results, failedCount, outcome, failure, funnel, timings, model } = await extractAndRetain(window2, retainCtx, {
           extract,
+          memoryStore: options.memoryStore,
+          signal: options.signal,
           ...options.minConfidence !== void 0 && { minConfidence: options.minConfidence },
           ...options.entityCtx !== void 0 && { entityCtx: options.entityCtx },
           ...options.scope !== void 0 && { scope: options.scope },
@@ -35752,6 +35815,7 @@ function createLocalMemoryStore(options) {
     database,
     entityCollection: database.get("entity"),
     memoryEntityCollection: database.get("memory_entity"),
+    canWrite: options.canWrite,
     ...userId !== void 0 && { userId },
     ...options.allowUnscopedRows !== void 0 && {
       allowUnscopedRows: options.allowUnscopedRows
@@ -35763,10 +35827,21 @@ function createLocalMemoryStore(options) {
     walletAddress: options.walletAddress,
     signMessage: options.signMessage,
     embeddedWalletSigner: options.embeddedWalletSigner,
+    canWrite: options.canWrite,
     ...userId !== void 0 && { userId },
     ...options.singleTenant !== void 0 && { singleTenant: options.singleTenant },
     entityCtx
   };
+  const assertWrite = async (writeOptions) => {
+    writeOptions?.signal?.throwIfAborted();
+    if (writeOptions?.canWrite && !await writeOptions.canWrite()) {
+      throw new Error("Memory source is no longer eligible");
+    }
+    if (options.canWrite && !await options.canWrite()) {
+      throw new Error("Memory source is no longer eligible");
+    }
+    writeOptions?.signal?.throwIfAborted();
+  };
   const vaultCache = options.vaultCache ?? createVaultEmbeddingCache();
   const ownedBy = userId !== void 0 ? [import_watermelondb24.Q.where("user_id", userId)] : [];
   const linksOwnedBy = userId === void 0 ? [] : options.allowUnscopedRows ? [import_watermelondb24.Q.or(import_watermelondb24.Q.where("user_id", userId), import_watermelondb24.Q.where("user_id", null))] : [import_watermelondb24.Q.where("user_id", userId)];
@@ -35878,9 +35953,25 @@ function createLocalMemoryStore(options) {
     archive: (id) => archiveVaultMemoryOp(vaultCtx, id),
     restore: (id) => restoreVaultMemoryOp(vaultCtx, id),
     setTopics: (memoryId, topics) => setMemoryEntitiesOp(vaultCtx, memoryId, topics),
-    addTopics: (memoryId, topics) => database.write(async (writer) => {
+    addTopics: (memoryId, topics, writeOptions) => database.write(async (writer) => {
+      await assertWrite(writeOptions);
       const owned = await vaultCtx.vaultMemoryCollection.query(import_watermelondb24.Q.where("id", memoryId), import_watermelondb24.Q.where("is_deleted", false), ...ownedBy).fetchCount();
-      return owned > 0 ? writer.callWriter(() => linkMemoryEntitiesOp(entityCtx, memoryId, topics)) : [];
+      return owned > 0 ? writer.callWriter(
+        () => linkMemoryEntitiesOp(
+          {
+            ...entityCtx,
+            canWrite: async () => {
+              await assertWrite(writeOptions);
+              return true;
+            }
+          },
+          memoryId,
+          topics,
+          {
+            unlessTopicsUserManaged: writeOptions?.unlessUserManaged
+          }
+        )
+      ) : [];
     }),
     setVisibility: (id, visibility, visibilityOptions) => setMemoryVisibilityOp(vaultCtx, id, { visibility, ...visibilityOptions }),
     recall: (query, recallOptions) => recall(
@@ -35890,7 +35981,17 @@ function createLocalMemoryStore(options) {
     ),
     retain: (content, retainOptions) => retain(
       content,
-      { vaultCtx, embeddingOptions: options.embeddingOptions, vaultCache },
+      {
+        vaultCtx: {
+          ...vaultCtx,
+          canWrite: async () => {
+            await assertWrite(retainOptions);
+            return true;
+          }
+        },
+        embeddingOptions: options.embeddingOptions,
+        vaultCache
+      },
       retainOptions
     ),
     factSource: {
@@ -36742,6 +36843,7 @@ function createDurableAutoExtractor(options) {
   };
   const folderId = options.folderId ?? null;
   let disposed = false;
+  let activeBatch = null;
   let running = false;
   let wakeRequested = false;
   let timer;
@@ -36778,14 +36880,18 @@ function createDurableAutoExtractor(options) {
     }, delay);
   }
   async function extractBatch(messages, conversationId, ids, jobScope, jobFolderId) {
+    if (disposed) throw new Error("Extraction session was disposed");
     let watchdog;
     let cancelled = false;
+    const controller = new AbortController();
+    activeBatch = controller;
     const model = options.modelForScope?.(jobScope) ?? options.extract.model;
     try {
       return await Promise.race([
         new Promise((resolve, reject) => {
           const worker = createAutoExtractor({
             ...options,
+            signal: controller.signal,
             retainCtx: {
               ...options.retainCtx,
               vaultCtx: {
@@ -36814,6 +36920,8 @@ function createDurableAutoExtractor(options) {
       ]);
     } finally {
       cancelled = true;
+      controller.abort();
+      if (activeBatch === controller) activeBatch = null;
       if (watchdog !== void 0) clearTimeout(watchdog);
     }
   }
@@ -36825,6 +36933,7 @@ function createDurableAutoExtractor(options) {
     for (const message of loaded)
       if (message && message.messageId > 0) sequences.set(message.uniqueId, message.messageId);
     await database.write(async () => {
+      if (disposed) return;
       const current = idsOf(job);
       const acknowledged = ids.filter((id) => current.includes(id));
       if (!acknowledged.length) return;
@@ -36997,6 +37106,7 @@ function createDurableAutoExtractor(options) {
               jobScope,
               jobFolderId
             );
+            if (disposed) throw new Error("Extraction session was disposed");
             options.onTurnComplete?.(result);
             return result;
           };
@@ -37033,6 +37143,7 @@ function createDurableAutoExtractor(options) {
           );
           scheduleAfterSuccess = true;
         } catch (error) {
+          if (disposed) break;
           attempts.set(job.id, attempted + 1);
           retry = true;
           reportError(error, conversationId);
@@ -37055,6 +37166,14 @@ function createDurableAutoExtractor(options) {
         schedule(retry ? options.retryDelayMs ?? 3e4 : 0);
     }
   }
+  function dispose() {
+    disposed = true;
+    activeBatch?.abort(options.signal?.reason);
+    if (timer !== void 0) clearTimeout(timer);
+    options.signal?.removeEventListener("abort", dispose);
+  }
+  if (options.signal?.aborted) dispose();
+  else options.signal?.addEventListener("abort", dispose, { once: true });
   schedule(0);
   return {
     processTurn(messages, conversationId) {
@@ -37134,10 +37253,7 @@ function createDurableAutoExtractor(options) {
       return true;
     },
     isProcessing: () => running,
-    dispose() {
-      disposed = true;
-      if (timer !== void 0) clearTimeout(timer);
-    }
+    dispose
   };
 }
 

package/dist/server/index.d.mts

@@ -2779,6 +2779,7 @@ interface EntityOperationsContext {
      * (server / SQLite, where the migration backfill is authoritative).
      */
     allowUnscopedRows?: boolean;
+    canWrite?: () => Promise<boolean>;
 }
 
 /**
@@ -4933,6 +4934,10 @@ type ExtractOutcome = "extracted" | "no-facts" | "empty-after-retry" | "dropped-
  */
 declare function extractAndRetain(messages: AutoExtractMessage[], retainCtx: RetainContext, options: {
     extract: ExtractFactsOptions;
+    /** Route extracted facts through this store instead of the local vault. */
+    memoryStore?: MemoryStore | null;
+    /** Cancel remote writes for this extraction batch. */
+    signal?: AbortSignal;
     minConfidence?: number;
     /** Override scope/folder for all retained facts. */
     scope?: string;
@@ -6180,7 +6185,12 @@ type MemoryRecallOptions = Omit<RecallOptions, "types" | "includeChunks" | "conv
  * and never receives these credentials, callbacks or redactor instances.
  * @public
  */
-type MemoryRetainOptions = Omit<RetainOptions, "folderId">;
+type MemoryRetainOptions = Omit<RetainOptions, "folderId"> & {
+    /** Reject writes when the originating extraction is no longer eligible. */
+    canWrite?: () => Promise<boolean>;
+    /** Abort pending remote requests when the originating extraction is cancelled. */
+    signal?: AbortSignal;
+};
 /**
  * A topic and how many memories link to it.
  * @public
@@ -6309,7 +6319,11 @@ interface MemoryStore {
     /** Replace the memory's topics with a user-chosen set and stop auto-tagging it. */
     setTopics(memoryId: string, topics: readonly EntityInput[]): Promise<StoredVaultMemory | null>;
     /** Add topics alongside the existing ones (auto-tagging stays on). */
-    addTopics(memoryId: string, topics: readonly EntityInput[]): Promise<StoredEntity[]>;
+    addTopics(memoryId: string, topics: readonly EntityInput[], options?: {
+        unlessUserManaged?: boolean;
+        canWrite?: () => Promise<boolean>;
+        signal?: AbortSignal;
+    }): Promise<StoredEntity[]>;
     setVisibility(id: string, visibility: VaultMemoryVisibility, options?: {
         twinOptIn?: boolean;
     }): Promise<StoredVaultMemory | null>;
@@ -9079,6 +9093,10 @@ interface SyncKeyValueStore {
 declare function createPlatformCursorStore(storage: SyncKeyValueStore, keyPrefix?: string): ExtractionCursorStore;
 interface CreateAutoExtractorOptions {
     retainCtx: RetainContext;
+    /** Route retained facts and topics through this store; null disables memory writes. */
+    memoryStore?: MemoryStore | null;
+    /** Cancel remote writes for an extraction batch. */
+    signal?: AbortSignal;
     extract: ExtractFactsOptions;
     /** Confidence floor for retained facts. Default 0.7. */
     minConfidence?: number;
@@ -9686,6 +9704,8 @@ interface LocalMemoryStoreOptions {
     walletAddress?: string;
     signMessage?: SignMessageFn;
     embeddedWalletSigner?: EmbeddedWalletSignerFn;
+    /** Rechecked inside each serialized memory write. */
+    canWrite?: () => Promise<boolean>;
     /**
      * Scope every read/write to this user — for a shared, multi-tenant database
      * whose rows all carry their `user_id`. Rows with no `user_id` are invisible

package/dist/server/index.d.ts

@@ -2779,6 +2779,7 @@ interface EntityOperationsContext {
      * (server / SQLite, where the migration backfill is authoritative).
      */
     allowUnscopedRows?: boolean;
+    canWrite?: () => Promise<boolean>;
 }
 
 /**
@@ -4933,6 +4934,10 @@ type ExtractOutcome = "extracted" | "no-facts" | "empty-after-retry" | "dropped-
  */
 declare function extractAndRetain(messages: AutoExtractMessage[], retainCtx: RetainContext, options: {
     extract: ExtractFactsOptions;
+    /** Route extracted facts through this store instead of the local vault. */
+    memoryStore?: MemoryStore | null;
+    /** Cancel remote writes for this extraction batch. */
+    signal?: AbortSignal;
     minConfidence?: number;
     /** Override scope/folder for all retained facts. */
     scope?: string;
@@ -6180,7 +6185,12 @@ type MemoryRecallOptions = Omit<RecallOptions, "types" | "includeChunks" | "conv
  * and never receives these credentials, callbacks or redactor instances.
  * @public
  */
-type MemoryRetainOptions = Omit<RetainOptions, "folderId">;
+type MemoryRetainOptions = Omit<RetainOptions, "folderId"> & {
+    /** Reject writes when the originating extraction is no longer eligible. */
+    canWrite?: () => Promise<boolean>;
+    /** Abort pending remote requests when the originating extraction is cancelled. */
+    signal?: AbortSignal;
+};
 /**
  * A topic and how many memories link to it.
  * @public
@@ -6309,7 +6319,11 @@ interface MemoryStore {
     /** Replace the memory's topics with a user-chosen set and stop auto-tagging it. */
     setTopics(memoryId: string, topics: readonly EntityInput[]): Promise<StoredVaultMemory | null>;
     /** Add topics alongside the existing ones (auto-tagging stays on). */
-    addTopics(memoryId: string, topics: readonly EntityInput[]): Promise<StoredEntity[]>;
+    addTopics(memoryId: string, topics: readonly EntityInput[], options?: {
+        unlessUserManaged?: boolean;
+        canWrite?: () => Promise<boolean>;
+        signal?: AbortSignal;
+    }): Promise<StoredEntity[]>;
     setVisibility(id: string, visibility: VaultMemoryVisibility, options?: {
         twinOptIn?: boolean;
     }): Promise<StoredVaultMemory | null>;
@@ -9079,6 +9093,10 @@ interface SyncKeyValueStore {
 declare function createPlatformCursorStore(storage: SyncKeyValueStore, keyPrefix?: string): ExtractionCursorStore;
 interface CreateAutoExtractorOptions {
     retainCtx: RetainContext;
+    /** Route retained facts and topics through this store; null disables memory writes. */
+    memoryStore?: MemoryStore | null;
+    /** Cancel remote writes for an extraction batch. */
+    signal?: AbortSignal;
     extract: ExtractFactsOptions;
     /** Confidence floor for retained facts. Default 0.7. */
     minConfidence?: number;
@@ -9686,6 +9704,8 @@ interface LocalMemoryStoreOptions {
     walletAddress?: string;
     signMessage?: SignMessageFn;
     embeddedWalletSigner?: EmbeddedWalletSignerFn;
+    /** Rechecked inside each serialized memory write. */
+    canWrite?: () => Promise<boolean>;
     /**
      * Scope every read/write to this user — for a shared, multi-tenant database
      * whose rows all carry their `user_id`. Rows with no `user_id` are invisible