@anuma/sdk 6.43.0 → 6.44.0

package/dist/expo/index.cjs

@@ -122,6 +122,18 @@ var init_clientConfig = __esm({
   }
 });
 
+// src/lib/taskType.ts
+function taskTypeHeader(taskType) {
+  return taskType ? { [TASK_TYPE_HEADER]: taskType } : {};
+}
+var TASK_TYPE_HEADER;
+var init_taskType = __esm({
+  "src/lib/taskType.ts"() {
+    "use strict";
+    TASK_TYPE_HEADER = "X-Anuma-Task-Type";
+  }
+});
+
 // src/lib/pii/patterns.ts
 function luhnCheck(digits) {
   let sum = 0;
@@ -766,18 +778,6 @@ var init_internalFlowMarker = __esm({
   }
 });
 
-// src/lib/taskType.ts
-function taskTypeHeader(taskType) {
-  return taskType ? { [TASK_TYPE_HEADER]: taskType } : {};
-}
-var TASK_TYPE_HEADER;
-var init_taskType = __esm({
-  "src/lib/taskType.ts"() {
-    "use strict";
-    TASK_TYPE_HEADER = "X-Anuma-Task-Type";
-  }
-});
-
 // src/lib/memory/portalLlm.ts
 function defaultBaseUrl() {
   return typeof process !== "undefined" && process.env?.ANUMA_PORTAL_BASE_URL || BASE_URL;
@@ -5218,6 +5218,7 @@ var getApiV1Models = (options) => (options?.client ?? client).get({ url: "/api/v
 
 // src/lib/memoryEngine/generate.ts
 init_clientConfig();
+init_taskType();
 var EMBED_MAX_ATTEMPTS = 4;
 var DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS = 15e3;
 var DEFAULT_EMBEDDING_TOKEN_TIMEOUT_MS = 1e4;
@@ -5315,7 +5316,10 @@ async function embedOne(text14, options, outer) {
     const cached = cache.get(text14);
     if (cached) return Array.from(cached);
   }
-  const headers = await resolveAuthHeaders(options, outer);
+  const headers = {
+    ...await resolveAuthHeaders(options, outer),
+    ...taskTypeHeader(options.taskType)
+  };
   const response = await withEmbeddingRetry(
     () => withDeadline(
       (signal) => postApiV1Embeddings({
@@ -5410,7 +5414,10 @@ async function embedMany(texts, options, outer) {
   if (uncachedTexts.length === 0) {
     return results;
   }
-  const headers = await resolveAuthHeaders(options, outer);
+  const headers = {
+    ...await resolveAuthHeaders(options, outer),
+    ...taskTypeHeader(options.taskType)
+  };
   if (outer?.aborted) throw outer.reason;
   const embeddingModel = model ?? DEFAULT_API_EMBEDDING_MODEL;
   let newEmbeddings;
@@ -15149,6 +15156,50 @@ function applyMMR(candidates, k, lambda = 0.5) {
   return selected;
 }
 
+// src/lib/memory/recallTelemetry.ts
+function notifyMemoryCallback(callback, value) {
+  try {
+    callback?.(value);
+  } catch {
+    return;
+  }
+}
+function factRecallDiagnostics(scores, elapsedMs, options = {}) {
+  return {
+    usedBudget: "low",
+    reranked: false,
+    candidateCount: options.candidateCount ?? scores.length,
+    ...options.vaultSize !== void 0 && { vaultSize: options.vaultSize },
+    ...options.decryptLast !== void 0 && { decryptLast: options.decryptLast },
+    ...options.vaultRowsDecrypted !== void 0 && {
+      vaultRowsDecrypted: options.vaultRowsDecrypted
+    },
+    ...options.vaultRowsEmbedded !== void 0 && {
+      vaultRowsEmbedded: options.vaultRowsEmbedded
+    },
+    factCount: scores.length,
+    chunkCount: 0,
+    admittedCount: scores.length,
+    topScore: scores.length ? Math.max(...scores) : -1,
+    lowestAdmittedScore: scores.length ? Math.min(...scores) : -1,
+    minScoreApplied: options.minScore ?? -1,
+    truncated: options.truncated ?? false,
+    graphLaneCount: 0,
+    temporalLaneCount: 0,
+    emptyReason: scores.length ? "" : options.vaultSize === 0 ? "vault-empty" : "no-candidates",
+    timings: {
+      total: elapsedMs,
+      prep: 0,
+      factLane: elapsedMs,
+      rerank: 0,
+      queryEmbed: options.queryEmbedMs ?? 0,
+      chunkLane: 0,
+      fuse: 0
+    },
+    degraded: options.embeddingsUnavailable ? ["embeddings-unavailable"] : []
+  };
+}
+
 // src/lib/memory/recency.ts
 var DAY_MS2 = 1e3 * 60 * 60 * 24;
 var DEFAULT_PER_YEAR_DECAY = 0.2;
@@ -15841,6 +15892,7 @@ function rankVaultMemories(_query, queryEmbedding, items, options) {
     }
     filtered.sort((a, b) => b.similarity - a.similarity);
   }
+  notifyMemoryCallback(options?.onCandidateCount, filtered.length);
   const itemById = new Map(items.map((i) => [i.id, i]));
   return filtered.slice(0, limit).map((r) => resultFromItem(itemById.get(r.uniqueId), r.similarity));
 }
@@ -16823,6 +16875,7 @@ async function rankPreparedVaultCandidates(query, prepared, embeddingOptions, se
   const results = rankVaultMemories(query, queryEmbedding, embeddedItems, {
     limit,
     minSimilarity,
+    onCandidateCount: searchOptions?.onCandidateCount,
     ...searchOptions?.supersessionBoost !== void 0 && {
       supersessionBoost: searchOptions.supersessionBoost
     },
@@ -16924,16 +16977,20 @@ var DEFAULT_SCOPE = "private";
 var DEFAULT_CONSOLIDATE_THRESHOLD = 0.55;
 var DEFAULT_CONSOLIDATE_TOP_K = 20;
 async function retain(content, ctx, options = {}) {
+  const embeddingOptions = {
+    ...ctx.embeddingOptions,
+    taskType: "memory_retain_embed"
+  };
   return retainWithPersistence(
     content,
     {
-      embeddingOptions: ctx.embeddingOptions,
+      embeddingOptions,
       vaultCache: ctx.vaultCache,
       persistence: {
         prepare: (query, searchOptions) => prepareVaultCandidates(
           query,
           ctx.vaultCtx,
-          ctx.embeddingOptions,
+          embeddingOptions,
           ctx.vaultCache,
           searchOptions
         ),
@@ -18087,7 +18144,17 @@ function parseVerdict(parsed) {
 
 // src/lib/memory/decayWorker.ts
 init_logger();
-var EMPTY_RESULT = { archived: 0, deleted: 0, scanned: 0 };
+function emptyResult() {
+  return {
+    archived: 0,
+    deleted: 0,
+    scanned: 0,
+    ruleDriven: { archived: 0, deleted: 0 },
+    classifierDriven: { archived: 0, deleted: 0 },
+    classifierCalls: 0,
+    classifierCapHits: 0
+  };
+}
 var DEFAULT_MAX_CLASSIFIER_CALLS_PER_SWEEP = 20;
 function resolveNow(now) {
   if (typeof now === "function") return now();
@@ -18126,42 +18193,45 @@ function createDecaySweeper(options) {
   let disposed = false;
   async function verdictFor(input, now, sweep) {
     const ruleVerdict = classifyDecay(input, now, policy);
-    if (ruleVerdict !== "keep") return ruleVerdict;
-    if (!classifier || !isBorderline(input)) return ruleVerdict;
+    const rule = { verdict: ruleVerdict, source: "ruleDriven" };
+    if (ruleVerdict !== "keep") return rule;
+    if (!classifier || !isBorderline(input)) return rule;
     if (input.id) {
       const cached = classifierCache.get(input.id);
-      if (cached && cached.activityAt === lastActivityAt(input)) return cached.verdict;
+      if (cached && cached.activityAt === lastActivityAt(input))
+        return { verdict: cached.verdict, source: "classifierDriven" };
     }
     if (sweep.classifierCalls >= maxClassifierCalls) {
+      sweep.classifierCapHits++;
       if (!sweep.ceilingLogged) {
         sweep.ceilingLogged = true;
         getLogger().warn(
           `[memory/decay] classifier per-sweep ceiling (${maxClassifierCalls}) reached; remaining borderline rows use the rule verdict this sweep`
         );
       }
-      return ruleVerdict;
+      return rule;
     }
     sweep.classifierCalls++;
     try {
       const verdict = await classifier.classify(input, ruleVerdict, now);
       if (input.id) classifierCache.set(input.id, { activityAt: lastActivityAt(input), verdict });
-      return verdict;
+      return { verdict, source: "classifierDriven" };
     } catch (err) {
       getLogger().warn(
         `[memory/decay] classifier failed; falling back to rule verdict: ${err instanceof Error ? err.message : String(err)}`
       );
-      return ruleVerdict;
+      return rule;
     }
   }
   async function runSweep() {
-    if (disposed) return { ...EMPTY_RESULT };
+    if (disposed) return emptyResult();
     const now = resolveNow(options.now);
     let candidates;
     try {
       candidates = await getDecayCandidatesRawOp(vaultCtx);
     } catch (err) {
       onError?.(err instanceof Error ? err : new Error(String(err)));
-      return { ...EMPTY_RESULT };
+      return emptyResult();
     }
     if (classifierCache.size > 0) {
       const liveIds = new Set(candidates.map((c) => c.uniqueId));
@@ -18169,33 +18239,40 @@ function createDecaySweeper(options) {
         if (!liveIds.has(id)) classifierCache.delete(id);
       }
     }
-    const sweep = { classifierCalls: 0, ceilingLogged: false };
+    const sweep = { classifierCalls: 0, classifierCapHits: 0, ceilingLogged: false };
     const toArchive = [];
     const toDelete = [];
     for (const c of candidates) {
-      const verdict = await verdictFor(toDecayInput(c), now, sweep);
-      if (verdict === "archive") toArchive.push(c);
-      else if (verdict === "delete") toDelete.push(c);
-    }
-    let archived = 0;
-    let deleted = 0;
+      const { verdict, source } = await verdictFor(toDecayInput(c), now, sweep);
+      if (verdict === "archive") toArchive.push({ candidate: c, source });
+      else if (verdict === "delete") toDelete.push({ candidate: c, source });
+    }
+    const result = emptyResult();
+    result.scanned = candidates.length;
+    result.classifierCalls = sweep.classifierCalls;
+    result.classifierCapHits = sweep.classifierCapHits;
     try {
-      for (const c of toArchive) {
+      for (const { candidate: c, source } of toArchive) {
         const ok = await archiveVaultMemoryOp(vaultCtx, c.uniqueId, {
           now,
           expectedUpdatedAt: c.updatedAt,
           expectedLastObservedAt: c.lastObservedAt ?? null
         });
-        if (ok) archived++;
+        if (ok) {
+          result.archived++;
+          result[source].archived++;
+        }
       }
-      for (const c of toDelete) {
+      for (const { candidate: c, source } of toDelete) {
         const ok = await hardDeleteDecayedOp(vaultCtx, c.uniqueId, { hardDeleteWindowMs, now });
-        if (ok) deleted++;
+        if (ok) {
+          result.deleted++;
+          result[source].deleted++;
+        }
       }
     } catch (err) {
       onError?.(err instanceof Error ? err : new Error(String(err)));
     }
-    const result = { archived, deleted, scanned: candidates.length };
     onSwept?.(result);
     return result;
   }
@@ -18800,6 +18877,10 @@ async function recall(query, ctx, options = {}) {
   const flags = flagsForBudget(usedBudget);
   const normalizedFacets = normalizeSubQueries(options.subQueries);
   const subQueries = normalizedFacets.length >= 2 ? normalizedFacets : void 0;
+  const embeddingOptions = {
+    ...ctx.embeddingOptions,
+    taskType: "memory_recall_embed"
+  };
   const t0 = nowMs2();
   let prepMs = 0;
   let factLaneMs = 0;
@@ -18895,7 +18976,7 @@ async function recall(query, ctx, options = {}) {
   let sharedEmbedMs = 0;
   const [queryEmbedding, entityRanking, temporalRanking] = await Promise.all([
     needsChunkEmbedding ? generateEmbedding(query, {
-      ...ctx.embeddingOptions,
+      ...embeddingOptions,
       totalTimeoutMs: queryEmbedTotalTimeoutMs
     }).finally(() => {
       sharedEmbedMs = nowMs2() - prepStart;
@@ -18953,7 +19034,7 @@ async function recall(query, ctx, options = {}) {
     } = await (ctx.factSource?.search.bind(ctx.factSource) ?? ((searchQuery, searchOptions) => searchVaultMemoriesWithSize(
       searchQuery,
       ctx.vaultCtx,
-      ctx.embeddingOptions,
+      embeddingOptions,
       ctx.vaultCache,
       searchOptions
     )))(query, {
@@ -19319,7 +19400,7 @@ function isDumpQuery(query) {
 async function listRecentFacts(ctx, limit, toolOptions) {
   const store = toolOptions?.memoryStore;
   const vaultCtx = ctx.vaultCtx;
-  if (!vaultCtx && !store) return [];
+  if (!vaultCtx && !store) return { memories: [], truncated: false };
   const read = (ids) => store ? store.list({ memoryIds: ids }) : getVaultMemoriesByIdsOp(vaultCtx, ids);
   const filters = {
     ...toolOptions?.scopes && { scopes: toolOptions.scopes },
@@ -19330,34 +19411,47 @@ async function listRecentFacts(ctx, limit, toolOptions) {
     ...toolOptions?.folderId !== void 0 && { folderId: toolOptions.folderId }
   });
   const readable = [];
+  const readLimit = limit + 1;
+  let batchLimit = limit;
   let start = 0;
-  for (let size = limit; readable.length < limit; size *= 2) {
+  let projected = 0;
+  let exhausted = false;
+  for (let size = readLimit; readable.length < readLimit; size *= 2) {
     const ordered = await project(size);
-    for (let i = start; i < ordered.length && readable.length < limit; i += limit) {
-      const batch = ordered.slice(i, i + limit).map((p) => p.uniqueId);
+    projected = ordered.length;
+    exhausted = !store || ordered.length < size;
+    for (let i = start; i < ordered.length && readable.length < readLimit; ) {
+      const batch = ordered.slice(i, i + batchLimit).map((p) => p.uniqueId);
       const byId = new Map((await read(batch)).map((m) => [m.uniqueId, m]));
+      const previousCount = readable.length;
       for (const id of batch) {
         const m = byId.get(id);
         if (m && !isEncrypted(m.content)) readable.push(m);
-        if (readable.length >= limit) break;
+        if (readable.length >= readLimit) break;
       }
+      batchLimit = readable.length > previousCount ? Math.min(limit, readLimit - readable.length) : limit;
+      i += batch.length;
     }
-    if (!store || ordered.length < size) break;
+    if (exhausted) break;
     start = ordered.length;
   }
-  return readable.map((m) => ({
-    id: m.uniqueId,
-    kind: "fact",
-    content: m.content,
-    score: 0,
-    folderId: m.folderId,
-    eventTimeStart: m.eventTimeStart,
-    eventTimeEnd: m.eventTimeEnd,
-    eventTimeKind: m.eventTimeKind,
-    factType: m.factType,
-    createdAt: m.createdAt,
-    updatedAt: m.updatedAt
-  }));
+  return {
+    memories: readable.slice(0, limit).map((m) => ({
+      id: m.uniqueId,
+      kind: "fact",
+      content: m.content,
+      score: 0,
+      folderId: m.folderId,
+      eventTimeStart: m.eventTimeStart,
+      eventTimeEnd: m.eventTimeEnd,
+      eventTimeKind: m.eventTimeKind,
+      factType: m.factType,
+      createdAt: m.createdAt,
+      updatedAt: m.updatedAt
+    })),
+    ...exhausted && { vaultSize: projected },
+    truncated: readable.length > limit
+  };
 }
 function createRecallTool(ctx, toolOptions, callbacks) {
   if (toolOptions?.memoryStore && toolOptions.folderId !== void 0)
@@ -19396,7 +19490,11 @@ function createRecallTool(ctx, toolOptions, callbacks) {
     },
     executor: async (args) => {
       if (typeof args.query !== "string" || args.query.length === 0) {
-        throw new Error("recall_memory: `query` is required and must be a non-empty string.");
+        const error = new Error(
+          "recall_memory: `query` is required and must be a non-empty string."
+        );
+        notifyMemoryCallback(callbacks?.onError, error);
+        throw error;
       }
       const query = args.query;
       const now = Date.now();
@@ -19424,10 +19522,17 @@ function createRecallTool(ctx, toolOptions, callbacks) {
         RECALL_MAX_MEMORIES_PER_CONVERSATION - conversationMemories
       );
       const effectiveLimit = Math.min(requestLimit, remainingTurnBudget, remainingConvBudget);
+      const truncatedByBudget = effectiveLimit < requestLimit;
+      if (truncatedByBudget) {
+        notifyMemoryCallback(callbacks?.onTruncated, {
+          requestedLimit: requestLimit,
+          effectiveLimit,
+          truncatedByBudget
+        });
+      }
       if (effectiveLimit <= 0) {
         return VOLUME_LIMIT_NOTICE;
       }
-      const truncatedByBudget = effectiveLimit < requestLimit;
       turnMemories += effectiveLimit;
       conversationMemories += effectiveLimit;
       let surfaced = 0;
@@ -19436,7 +19541,27 @@ function createRecallTool(ctx, toolOptions, callbacks) {
         const wantsRecent = args.sort === "recent" && defaultTypes.includes("fact") && (ctx.vaultCtx !== void 0 || toolOptions?.memoryStore !== void 0);
         let result;
         if (wantsRecent) {
-          result = { memories: await listRecentFacts(ctx, effectiveLimit, toolOptions) };
+          const start = Date.now();
+          const recent = await listRecentFacts(ctx, effectiveLimit, toolOptions);
+          result = recent;
+          notifyMemoryCallback(callbacks?.onDiagnostics, {
+            ...factRecallDiagnostics(
+              result.memories.map((m) => m.score),
+              Date.now() - start,
+              {
+                truncated: recent.truncated,
+                ...recent.vaultSize !== void 0 && { vaultSize: recent.vaultSize }
+              }
+            ),
+            truncatedByBudget
+          });
+          if (recent.truncated && !truncatedByBudget) {
+            notifyMemoryCallback(callbacks?.onTruncated, {
+              requestedLimit: requestLimit,
+              effectiveLimit,
+              truncatedByBudget
+            });
+          }
         } else {
           let subQueries;
           if (defaultBudget === "high" && toolOptions?.decomposeOptions) {
@@ -19448,6 +19573,14 @@ function createRecallTool(ctx, toolOptions, callbacks) {
           const recallOpts = {
             onDiagnostics: (d) => {
               recallDegraded = d.degraded;
+              notifyMemoryCallback(callbacks?.onDiagnostics, { ...d, truncatedByBudget });
+              if (d.truncated && !truncatedByBudget) {
+                notifyMemoryCallback(callbacks?.onTruncated, {
+                  requestedLimit: requestLimit,
+                  effectiveLimit,
+                  truncatedByBudget
+                });
+              }
             },
             types: defaultTypes,
             limit: effectiveLimit,
@@ -19491,6 +19624,7 @@ ${TRUNCATION_NOTICE}` : formatted;
         const message = error instanceof Error ? error.message : "Unknown error";
         const wrapped = new Error(`recall_memory: search failed \u2014 ${message}`);
         wrapped.cause = error;
+        notifyMemoryCallback(callbacks?.onError, wrapped);
         throw wrapped;
       } finally {
         const unused = effectiveLimit - surfaced;
@@ -19732,6 +19866,18 @@ When a memory refers to one of these, reuse the EXACT existing name (same spelli
 ` : "";
   for (let i = 0; i < memories.length; i += TOPIC_EXTRACTION_BATCH_SIZE) {
     const batch = memories.slice(i, i + TOPIC_EXTRACTION_BATCH_SIZE);
+    const start = Date.now();
+    let attempts = 0;
+    let failure;
+    const reportBatch = (unansweredCount) => {
+      notifyMemoryCallback(options.onBatch, {
+        memoryIds: batch.map((m) => m.id),
+        attempts,
+        durationMs: Date.now() - start,
+        unansweredCount,
+        ...failure && { failure }
+      });
+    };
     const rows = [];
     for (const m of batch) {
       const content = m.content.slice(0, MAX_CHARS_PER_MEMORY).replace(/\s+/g, " ").trim();
@@ -19753,6 +19899,12 @@ ${listing}
 
 List each memory's named entities.`,
       tag: "memory/topics",
+      onAttempt: (attempt) => {
+        attempts = attempt.attempt;
+      },
+      onFailure: (value) => {
+        failure = value;
+      },
       extra: { max_completion_tokens: MAX_COMPLETION_TOKENS },
       ...options.fetchFn && { fetchFn: options.fetchFn },
       ...options.maxAttempts !== void 0 && { maxAttempts: options.maxAttempts },
@@ -19761,6 +19913,7 @@ List each memory's named entities.`,
       ...options.backoffMs && { backoffMs: options.backoffMs }
     });
     if (parsed === null) {
+      reportBatch(batch.length);
       getLogger().warn(
         `[memory/topics] batch of ${batch.length} failed after retries \u2014 will retry next sweep`
       );
@@ -19769,6 +19922,7 @@ List each memory's named entities.`,
     const validIds = new Set(batch.map((m) => m.id));
     const byId = parseTopicResponse(parsed, validIds);
     if (byId === null) {
+      reportBatch(batch.length);
       getLogger().warn(
         `[memory/topics] batch of ${batch.length} returned an unrecognized shape \u2014 will retry next sweep`
       );
@@ -19781,6 +19935,7 @@ List each memory's named entities.`,
       }
       out.set(m.id, redactor ? restoreEntities(entities, redactor) : entities);
     }
+    reportBatch(batch.filter((m) => !byId.has(m.id)).length);
   }
   return out;
 }
@@ -19819,6 +19974,7 @@ function isDegradedTopicSkip(reason) {
   return DEGRADED_TOPIC_SKIP[reason] === true;
 }
 async function extractAndLinkEntitiesForMemoriesOp(ctx, memoryIds, options) {
+  const start = Date.now();
   const entityCtx = ctx.entityCtx;
   if (!entityCtx) {
     throw new Error("extractAndLinkEntitiesForMemoriesOp requires ctx.entityCtx");
@@ -19859,7 +20015,18 @@ async function extractAndLinkEntitiesForMemoriesOp(ctx, memoryIds, options) {
       skip(id, "unreadable");
     }
   }
-  const entitiesByMemory = await extractEntitiesForMemories(inputs, options);
+  const batches = [];
+  const llmFailures = /* @__PURE__ */ new Map();
+  const entitiesByMemory = await extractEntitiesForMemories(inputs, {
+    ...options,
+    onBatch: (batch) => {
+      batches.push(batch);
+      if (batch.failure) {
+        for (const id of batch.memoryIds) llmFailures.set(id, batch.failure);
+      }
+      notifyMemoryCallback(options.onBatch, batch);
+    }
+  });
   const toStamp = [];
   for (const input of inputs) {
     const entities = entitiesByMemory.get(input.id);
@@ -19890,7 +20057,16 @@ async function extractAndLinkEntitiesForMemoriesOp(ctx, memoryIds, options) {
       entitiesByMemory.delete(id);
     }
   }
-  return { entitiesByMemory, stampedIds, skippedIds, skippedReasons };
+  return {
+    entitiesByMemory,
+    stampedIds,
+    skippedIds,
+    skippedReasons,
+    batchCount: batches.length,
+    durationMs: Date.now() - start,
+    batches,
+    llmFailures
+  };
 }
 
 // src/lib/memory/store/local.ts
@@ -20045,7 +20221,7 @@ function createLocalMemoryStore(options) {
       search: (query, searchOptions) => searchVaultMemoriesWithSize(
         query,
         vaultCtx,
-        options.embeddingOptions,
+        { ...options.embeddingOptions, taskType: "memory_recall_embed" },
         vaultCache,
         searchOptions
       ),
@@ -20709,6 +20885,7 @@ function createRemoteMemoryPipeline(options) {
       const budgetMs = search.queryEmbedTotalTimeoutMs ?? 8e3;
       const embed = (texts) => generateEmbeddings(texts, {
         ...embeddingOptions,
+        taskType: mode === "retain" ? "memory_retain_embed" : "memory_recall_embed",
         totalTimeoutMs: budgetMs
       });
       const embedFacets = async () => {
@@ -20957,7 +21134,7 @@ function createRemoteMemoryPipeline(options) {
       const ranked = await rankPreparedVaultCandidates(
         text14,
         prepared,
-        embeddingOptions,
+        { ...embeddingOptions, taskType: "memory_recall_embed" },
         searchOptions
       );
       return {
@@ -20979,7 +21156,7 @@ function createRemoteMemoryPipeline(options) {
         content,
         {
           persistence: port,
-          embeddingOptions,
+          embeddingOptions: { ...embeddingOptions, taskType: "memory_retain_embed" },
           vaultCache: /* @__PURE__ */ new Map(),
           normalizeEmbedding: storedVector
         },
@@ -21356,6 +21533,7 @@ var MAX_BATCH = 50;
 var MAX_QUERY_IDS = 1e3;
 var MAX_QUERY_TOPICS = 100;
 var MAX_QUERY_FILTER = 20;
+var GRAPH_LANE_ROWS = 256;
 var RemoteMemoryPartialCreateError = class extends Error {
   constructor(created, cause) {
     super(`createMany stored ${created.length} memories before a batch failed`);
@@ -21451,7 +21629,11 @@ function createRemoteMemoryStore(options) {
   const { persistence, embeddingOptions } = options;
   const model = embeddingOptions.model ?? DEFAULT_API_EMBEDDING_MODEL;
   const pollIntervalMs = options.pollIntervalMs ?? 6e4;
-  const pipeline = createRemoteMemoryPipeline(options);
+  const pipeline = createRemoteMemoryPipeline({
+    ...options,
+    graphRanking: options.graphRanking ?? ((query, _traverse, recallOptions) => topicGraphRanking(query, recallOptions)),
+    temporalRanking: options.temporalRanking ?? (() => Promise.resolve([]))
+  });
   const subscribers = /* @__PURE__ */ new Set();
   const seen = /* @__PURE__ */ new Map();
   let timer;
@@ -21483,6 +21665,36 @@ function createRemoteMemoryStore(options) {
   const decrypted = (options2) => persistence.query(options2);
   const metadata2 = (options2) => persistence.queryMetadata(options2);
   const enumerate = (filters, max = Infinity) => pages(decrypted, filters, max);
+  const memoriesByTopics = async (names) => {
+    const wanted = new Set(names.map(normalizeEntityName).filter(Boolean));
+    const out = /* @__PURE__ */ new Map();
+    const pages2 = await Promise.all(
+      chunks2([...wanted], MAX_QUERY_TOPICS).map((topics) => enumerate({ topics }))
+    );
+    for (const { memory } of pages2.flat()) {
+      const matched = [...canonicalTopics(memory)].filter((name) => wanted.has(name));
+      if (matched.length) out.set(memory.memory_id, new Set(matched));
+    }
+    return out;
+  };
+  const topicGraphRanking = async (query, recallOptions = {}) => {
+    const wanted = new Set(extractQueryEntities(query).map(normalizeEntityName).filter(Boolean));
+    if (wanted.size === 0 || recallOptions.memoryIds?.length === 0) return [];
+    const rows = await pages(
+      metadata2,
+      {
+        topics: [...wanted].slice(0, MAX_QUERY_TOPICS),
+        ...recallOptions.scopes && { scopes: recallOptions.scopes },
+        ...recallOptions.factTypes && { fact_types: recallOptions.factTypes },
+        ...recallOptions.memoryIds && { memory_ids: recallOptions.memoryIds }
+      },
+      GRAPH_LANE_ROWS
+    );
+    return rows.map(({ memory }) => ({
+      memoryId: memory.memory_id,
+      matched: [...canonicalTopics(memory)].filter((name) => wanted.has(name)).length
+    })).filter((row) => row.matched > 0).sort((a, b) => b.matched - a.matched).slice(0, NODE_BUDGET).map((row) => row.memoryId);
+  };
   const enumerateIds = async (read, ids, filters) => (await Promise.all(
     chunks2([...new Set(ids)], MAX_QUERY_IDS).map(
       (memory_ids) => pages(read, { ...filters, memory_ids })
@@ -21708,7 +21920,8 @@ function createRemoteMemoryStore(options) {
       };
     },
     extractTopics: async (memoryIds, extractOptions) => {
-      const extractedAt = extractOptions.now ?? Date.now();
+      const start = Date.now();
+      const extractedAt = extractOptions.now ?? start;
       const skippedIds = [];
       const skippedReasons = /* @__PURE__ */ new Map();
       const skip = (id, reason) => {
@@ -21726,7 +21939,18 @@ function createRemoteMemoryStore(options) {
         else if (memory.is_deleted || memory.topics_user_managed) skip(id, "excluded");
         else inputs.push({ id, content: memory.content });
       }
-      const entitiesByMemory = await extractEntitiesForMemories(inputs, extractOptions);
+      const batches = [];
+      const llmFailures = /* @__PURE__ */ new Map();
+      const entitiesByMemory = await extractEntitiesForMemories(inputs, {
+        ...extractOptions,
+        onBatch: (batch) => {
+          batches.push(batch);
+          if (batch.failure) {
+            for (const id of batch.memoryIds) llmFailures.set(id, batch.failure);
+          }
+          notifyMemoryCallback(extractOptions.onBatch, batch);
+        }
+      });
       const answered = /* @__PURE__ */ new Map();
       for (const input of inputs) {
         const entities = entitiesByMemory.get(input.id);
@@ -21775,7 +21999,16 @@ function createRemoteMemoryStore(options) {
         getLogger().warn("[memory/remote-store] Failed to write extracted topics:", error);
         for (const id of answered.keys()) fail(id, "link-failed");
       }
-      return { entitiesByMemory, stampedIds, skippedIds, skippedReasons };
+      return {
+        entitiesByMemory,
+        stampedIds,
+        skippedIds,
+        skippedReasons,
+        batchCount: batches.length,
+        durationMs: Date.now() - start,
+        batches,
+        llmFailures
+      };
     },
     stampTopicsExtracted: async (memoryIds, extractedAt, version = TOPICS_EXTRACTION_VERSION) => {
       const ids = [...new Set(memoryIds)];
@@ -21902,18 +22135,7 @@ function createRemoteMemoryStore(options) {
     listArchived: async () => (await enumerate({ archived_only: true, order: "archived", include_embeddings: true })).map(
       (record2) => stored(record2.memory)
     ),
-    memoriesByTopics: async (names) => {
-      const wanted = new Set(names.map(normalizeEntityName).filter(Boolean));
-      const out = /* @__PURE__ */ new Map();
-      const pages2 = await Promise.all(
-        chunks2([...wanted], MAX_QUERY_TOPICS).map((topics) => enumerate({ topics }))
-      );
-      for (const { memory } of pages2.flat()) {
-        const matched = [...canonicalTopics(memory)].filter((name) => wanted.has(name));
-        if (matched.length) out.set(memory.memory_id, new Set(matched));
-      }
-      return out;
-    },
+    memoriesByTopics,
     topicsByMemories: async (memoryIds) => {
       const out = /* @__PURE__ */ new Map();
       for (const { memory } of await enumerateIds(decrypted, memoryIds, {
@@ -23791,9 +24013,13 @@ function formatVaultHits(hits) {
   return hits.map((h, i) => `[${i + 1}] (id: ${h.id}, similarity: ${h.score.toFixed(2)})
 ${h.content}`).join("\n\n");
 }
-function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOptions) {
+function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOptions, callbacks) {
   const limit = searchOptions?.limit ?? 5;
   const minSimilarity = searchOptions?.minSimilarity ?? 0.1;
+  const recallEmbeddingOptions = {
+    ...embeddingOptions,
+    taskType: "memory_recall_embed"
+  };
   const tuningForward = {
     ...searchOptions?.rerankTopN !== void 0 && { rerankTopN: searchOptions.rerankTopN },
     ...searchOptions?.ceWeight !== void 0 && { ceWeight: searchOptions.ceWeight },
@@ -23847,6 +24073,7 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
       const requestLimit = Number.isFinite(rawLimit) ? Math.min(Math.max(Math.floor(rawLimit), 1), RECALL_MAX_LIMIT) : limit;
       const argFolderId = args.folder_id;
       if (!query || typeof query !== "string") {
+        notifyMemoryCallback(callbacks?.onError, new Error("A search query is required."));
         return "Error: A search query is required.";
       }
       try {
@@ -23854,7 +24081,11 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
         const budget = wantsDecompose ? "high" : searchOptions?.rerank ? "mid" : "low";
         const folderId = searchOptions?.folderId ?? argFolderId;
         if (searchOptions?.useFusion === false) {
+          let candidateCount;
           const legacyOptions = {
+            onCandidateCount: (count2) => {
+              candidateCount = count2;
+            },
             limit: requestLimit,
             minSimilarity,
             useFusion: false,
@@ -23862,13 +24093,38 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
             ...folderId !== void 0 && { folderId },
             ...searchOptions?.scopes && { scopes: searchOptions.scopes }
           };
-          const { results: legacy, embeddingsUnavailable } = "retain" in vaultCtx ? await vaultCtx.factSource.search(query, legacyOptions) : await searchVaultMemoriesWithSize(
+          const start = Date.now();
+          const outcome2 = "retain" in vaultCtx ? await vaultCtx.factSource.search(query, legacyOptions) : await searchVaultMemoriesWithSize(
             query,
             vaultCtx,
-            embeddingOptions,
+            recallEmbeddingOptions,
             cache,
             legacyOptions
           );
+          const { results: legacy, embeddingsUnavailable, vaultSize } = outcome2;
+          const diagnostics = factRecallDiagnostics(
+            legacy.map((m) => m.similarity),
+            Date.now() - start,
+            {
+              vaultSize,
+              minScore: minSimilarity,
+              embeddingsUnavailable,
+              candidateCount,
+              truncated: candidateCount !== void 0 && candidateCount > requestLimit,
+              decryptLast: outcome2.decryptLast,
+              vaultRowsDecrypted: outcome2.rowsDecrypted,
+              vaultRowsEmbedded: outcome2.rowsEmbedded,
+              queryEmbedMs: outcome2.queryEmbedMs
+            }
+          );
+          notifyMemoryCallback(callbacks?.onDiagnostics, diagnostics);
+          if (diagnostics.truncated) {
+            notifyMemoryCallback(callbacks?.onTruncated, {
+              requestedLimit: requestLimit,
+              effectiveLimit: requestLimit,
+              truncatedByBudget: false
+            });
+          }
           if (legacy.length === 0) {
             return embeddingsUnavailable ? EMBEDDINGS_DEGRADED_EMPTY_NO_LEXICAL : "No relevant memories found in the vault.";
           }
@@ -23890,6 +24146,14 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
           {
             onDiagnostics: (d) => {
               recallDegraded = d.degraded;
+              notifyMemoryCallback(callbacks?.onDiagnostics, d);
+              if (d.truncated) {
+                notifyMemoryCallback(callbacks?.onTruncated, {
+                  requestedLimit: requestLimit,
+                  effectiveLimit: requestLimit,
+                  truncatedByBudget: false
+                });
+              }
             },
             types: ["fact"],
             limit: requestLimit,
@@ -23922,6 +24186,10 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
 
 ${formatted}`;
       } catch (error) {
+        notifyMemoryCallback(
+          callbacks?.onError,
+          error instanceof Error ? error : new Error(String(error))
+        );
         const message = error instanceof Error ? error.message : "Unknown error";
         return `Error searching vault: ${message}`;
       }
@@ -25397,6 +25665,15 @@ function useChat(options) {
     detachControllerRef.current = null;
     pendingResumeRef.current = null;
   }, [resumable, fireCancel]);
+  const cancel = (0, import_react4.useCallback)(
+    (handle) => {
+      if (resumable) fireCancel(handle);
+      if (pendingResumeRef.current?.inferenceId === handle.inferenceId) {
+        pendingResumeRef.current = null;
+      }
+    },
+    [resumable, fireCancel]
+  );
   const detach = (0, import_react4.useCallback)(() => {
     if (detachControllerRef.current) {
       detachControllerRef.current.abort();
@@ -25655,6 +25932,7 @@ function useChat(options) {
     isLoading,
     sendMessage,
     stop,
+    cancel,
     detach,
     resumeStream: resumeStream2
   };
@@ -27064,6 +27342,7 @@ function useChatStorage(options) {
     isLoading,
     sendMessage: baseSendMessage,
     stop: baseStop,
+    cancel: baseCancel,
     detach,
     resumeStream: baseResumeStream
   } = useChat({
@@ -27087,6 +27366,9 @@ function useChatStorage(options) {
   });
   const pendingResumeRef = (0, import_react5.useRef)(null);
   const isResumingRef = (0, import_react5.useRef)(false);
+  const activeResumeRef = (0, import_react5.useRef)(null);
+  const retirementRef = (0, import_react5.useRef)(null);
+  const retirementStopRequestedRef = (0, import_react5.useRef)(false);
   const createConversation = (0, import_react5.useCallback)(
     async (opts) => {
       const { result, queued } = await writeOrQueue(
@@ -27286,6 +27568,143 @@ function useChatStorage(options) {
   activeToolSetsRef.current = activeToolSets;
   const getTokenRef = (0, import_react5.useRef)(getToken);
   getTokenRef.current = getToken;
+  const finalizeResumedRow = (0, import_react5.useCallback)(
+    async (ctx, data, wasStopped, responseDuration, viaQueue = false) => {
+      const { content, thinking } = extractAssistantText(data);
+      let parentMessageId = ctx.userMessageUniqueId;
+      let knownIds = ctx.knownToolCallEventIds;
+      if (ctx.convId && (!knownIds || !parentMessageId)) {
+        let storedMessages = null;
+        try {
+          storedMessages = await getMessages(ctx.convId);
+        } catch {
+        }
+        if (storedMessages) {
+          if (!knownIds) {
+            knownIds = /* @__PURE__ */ new Set();
+            for (const msg of storedMessages) {
+              if (msg.uniqueId === ctx.assistantUniqueId) continue;
+              if (msg.toolCallEvents) {
+                for (const evt of msg.toolCallEvents) {
+                  if (evt.id) knownIds.add(evt.id);
+                }
+              }
+            }
+          }
+          if (!parentMessageId) {
+            for (let i = storedMessages.length - 1; i >= 0; i--) {
+              if (storedMessages[i].uniqueId !== ctx.assistantUniqueId) {
+                parentMessageId = storedMessages[i].uniqueId;
+                break;
+              }
+            }
+          }
+        }
+      }
+      const allToolCallEvents = getToolCallEvents(data);
+      const currentTurnToolCallEvents = knownIds ? allToolCallEvents?.filter(
+        (evt) => evt.id !== void 0 && evt.id !== null && !knownIds.has(evt.id)
+      ) : allToolCallEvents;
+      const baseSources = ctx.sources ?? [];
+      const seenSourceUrls = new Set(
+        baseSources.map((s) => s.url).filter((url) => !!url)
+      );
+      const toolEventSources = extractSourcesFromToolCallEvents(currentTurnToolCallEvents);
+      const sources = [
+        ...baseSources,
+        ...toolEventSources.filter((s) => !s.url || !seenSourceUrls.has(s.url))
+      ].filter((source) => !source.url?.includes(MCP_R2_DOMAIN));
+      const rowOpts = {
+        conversationId: ctx.convId,
+        role: "assistant",
+        content,
+        model: data.model || ctx.model || "",
+        imageModel: ctx.imageModel || getImageModel(data),
+        usage: convertUsageToStored(data),
+        responseDuration,
+        sources,
+        thoughtProcess: finalizeThoughtProcess(ctx.thoughtProcess),
+        thinking,
+        wasStopped,
+        parentMessageId,
+        toolCallEvents: currentTurnToolCallEvents && currentTurnToolCallEvents.length > 0 ? currentTurnToolCallEvents : void 0,
+        uniqueId: ctx.assistantUniqueId
+      };
+      if (!viaQueue) return upsertMessageOp(storageCtx, rowOpts);
+      const { result } = await writeOrQueue(
+        "createMessage",
+        rowOpts,
+        () => upsertMessageOp(storageCtx, rowOpts),
+        () => makeSyntheticStoredMessage(rowOpts),
+        ctx.userMessageQueueId ? [ctx.userMessageQueueId] : []
+      );
+      return result;
+    },
+    [storageCtx, getMessages, writeOrQueue]
+  );
+  const retirePendingTurn = (0, import_react5.useCallback)(async () => {
+    const visible = activeResumeRef.current;
+    if (visible && !visible.headless) {
+      baseStop();
+      await visible.settled;
+    }
+    if (retirementRef.current) return retirementRef.current;
+    const active = activeResumeRef.current;
+    if (active && !active.headless) return "Resume already in progress";
+    const pending = pendingResumeRef.current;
+    if (!pending) return null;
+    if (!pending.userMessageUniqueId) {
+      if (active?.context === pending) return null;
+      if (!pending.partialData) {
+        pendingResumeRef.current = null;
+        return null;
+      }
+    }
+    if (active?.context === pending) return "Resume already in progress";
+    pendingResumeRef.current = null;
+    retirementStopRequestedRef.current = false;
+    const retirement = Promise.resolve().then(async () => {
+      try {
+        const data = pending.partialData;
+        if (data && pending.assistantUniqueId) {
+          const { content, thinking } = extractAssistantText(data);
+          if (content || thinking || (getToolCallEvents(data)?.length ?? 0) > 0) {
+            if (walletAddress && signMessage && !hasEncryptionKey(walletAddress)) {
+              try {
+                await requestEncryptionKey(walletAddress, signMessage, embeddedWalletSigner);
+              } catch {
+              }
+            }
+            await finalizeResumedRow(
+              pending,
+              data,
+              true,
+              (Date.now() - pending.startTime) / 1e3,
+              true
+            );
+          }
+        }
+        if (pending.handle) baseCancel(pending.handle);
+        return null;
+      } catch (err) {
+        pendingResumeRef.current = pending;
+        if (retirementStopRequestedRef.current && pending.handle) {
+          baseCancel(pending.handle);
+          pendingResumeRef.current = { ...pending, handle: null };
+        }
+        return err instanceof Error ? err.message : "Failed to store detached message";
+      }
+    });
+    retirementRef.current = retirement;
+    try {
+      return await retirement;
+    } finally {
+      if (retirementRef.current === retirement) {
+        retirementRef.current = null;
+        retirementStopRequestedRef.current = false;
+      }
+    }
+  }, [baseCancel, baseStop, finalizeResumedRow, walletAddress, signMessage, embeddedWalletSigner]);
   const sendMessage = (0, import_react5.useCallback)(
     async (args) => {
       const {
@@ -27337,7 +27756,11 @@ function useChatStorage(options) {
           maskForCall: (text14) => redactor ? redactor.maskText(text14) : text14
         };
       };
-      pendingResumeRef.current = null;
+      const retirementError = await retirePendingTurn();
+      if (retirementError) {
+        if (!skipStorage) return { data: null, error: retirementError };
+        getLogger().warn("[useChatStorage] detached partial not saved:", retirementError);
+      }
       const effectiveAssistantUniqueId = assistantUniqueId ?? (resumable ? `msg_${(0, import_uuid7.v7)()}` : void 0);
       const embedToolText = (text14, mask, masked, token) => {
         const opts = {
@@ -27861,6 +28284,7 @@ function useChatStorage(options) {
           handle: detachedResult.resume ?? null,
           convId,
           userMessageUniqueId: storedUserMessage.uniqueId,
+          userMessageQueueId: userMsgQueueId,
           assistantUniqueId: rowId,
           model,
           imageModel,
@@ -28087,6 +28511,7 @@ function useChatStorage(options) {
       getMessages,
       storageCtx,
       baseSendMessage,
+      retirePendingTurn,
       embedMessageAsync,
       minContentLength,
       walletAddress,
@@ -28101,72 +28526,9 @@ function useChatStorage(options) {
       onPiiRedacted
     ]
   );
-  const finalizeResumedRow = (0, import_react5.useCallback)(
-    async (ctx, data, wasStopped, responseDuration) => {
-      const { content, thinking } = extractAssistantText(data);
-      let parentMessageId = ctx.userMessageUniqueId;
-      let knownIds = ctx.knownToolCallEventIds;
-      if (ctx.convId && (!knownIds || !parentMessageId)) {
-        let storedMessages = null;
-        try {
-          storedMessages = await getMessages(ctx.convId);
-        } catch {
-        }
-        if (storedMessages) {
-          if (!knownIds) {
-            knownIds = /* @__PURE__ */ new Set();
-            for (const msg of storedMessages) {
-              if (msg.toolCallEvents) {
-                for (const evt of msg.toolCallEvents) {
-                  if (evt.id) knownIds.add(evt.id);
-                }
-              }
-            }
-          }
-          if (!parentMessageId) {
-            for (let i = storedMessages.length - 1; i >= 0; i--) {
-              if (storedMessages[i].uniqueId !== ctx.assistantUniqueId) {
-                parentMessageId = storedMessages[i].uniqueId;
-                break;
-              }
-            }
-          }
-        }
-      }
-      const allToolCallEvents = getToolCallEvents(data);
-      const currentTurnToolCallEvents = knownIds ? allToolCallEvents?.filter(
-        (evt) => evt.id !== void 0 && evt.id !== null && !knownIds.has(evt.id)
-      ) : allToolCallEvents;
-      const baseSources = ctx.sources ?? [];
-      const seenSourceUrls = new Set(
-        baseSources.map((s) => s.url).filter((url) => !!url)
-      );
-      const toolEventSources = extractSourcesFromToolCallEvents(currentTurnToolCallEvents);
-      const sources = [
-        ...baseSources,
-        ...toolEventSources.filter((s) => !s.url || !seenSourceUrls.has(s.url))
-      ].filter((source) => !source.url?.includes(MCP_R2_DOMAIN));
-      return upsertMessageOp(storageCtx, {
-        conversationId: ctx.convId,
-        role: "assistant",
-        content,
-        model: data.model || ctx.model || "",
-        imageModel: ctx.imageModel || getImageModel(data),
-        usage: convertUsageToStored(data),
-        responseDuration,
-        sources,
-        thoughtProcess: finalizeThoughtProcess(ctx.thoughtProcess),
-        thinking,
-        wasStopped,
-        parentMessageId,
-        uniqueId: ctx.assistantUniqueId
-      });
-    },
-    [storageCtx, getMessages]
-  );
   const resumeStream2 = (0, import_react5.useCallback)(
     async (handleOverride, opts) => {
-      if (isResumingRef.current) {
+      if (isResumingRef.current || retirementRef.current) {
         return { data: null, error: "Resume already in progress", assistantMessage: null };
       }
       const pending = pendingResumeRef.current;
@@ -28195,6 +28557,7 @@ function useChatStorage(options) {
         if (pendingResumeRef.current === rctx) pendingResumeRef.current = null;
       };
       const safeFinalize = async (data, wasStopped, responseDuration) => {
+        rctx.partialData = data;
         try {
           return { message: await finalizeResumedRow(rctx, data, wasStopped, responseDuration) };
         } catch (writeErr) {
@@ -28204,6 +28567,13 @@ function useChatStorage(options) {
         }
       };
       isResumingRef.current = true;
+      let markSettled = () => {
+      };
+      const settled = new Promise((resolve) => {
+        markSettled = resolve;
+      });
+      const activeResume = { context: rctx, headless: opts?.headless === true, settled };
+      activeResumeRef.current = activeResume;
       try {
         const result = await baseResumeStream(handle, { headless: opts?.headless });
         const responseDuration = (Date.now() - rctx.startTime) / 1e3;
@@ -28280,11 +28650,17 @@ function useChatStorage(options) {
         throw err;
       } finally {
         isResumingRef.current = false;
+        if (activeResumeRef.current === activeResume) activeResumeRef.current = null;
+        markSettled();
       }
     },
     [baseResumeStream, currentConversationId, finalizeResumedRow, embedMessageAsync]
   );
   const stop = (0, import_react5.useCallback)(() => {
+    if (retirementRef.current) {
+      retirementStopRequestedRef.current = true;
+      return;
+    }
     const pending = pendingResumeRef.current;
     if (pending && pending.assistantUniqueId && !isResumingRef.current) {
       const finalize = pending;