@anuma/sdk 6.43.0 → 6.43.1

package/dist/server/{consolidate-YEGACWLR.mjs → consolidate-WY6BHODK.mjs}

@@ -2,7 +2,7 @@ import {
   callPortalJsonCompletion,
   notifyConsolidationFallback,
   resolvePiiRedactor
-} from "./chunk-4RGGAOAJ.mjs";
+} from "./chunk-WCG5BFI6.mjs";
 import "./chunk-3RPGXXPZ.mjs";
 
 // src/lib/memory/consolidate.ts

package/dist/server/index.cjs

@@ -14378,6 +14378,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;
@@ -15022,18 +15034,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";
-  }
-});
-
 // node_modules/.pnpm/@nozbe+watermelondb@0.28.0/node_modules/@nozbe/watermelondb/decorators/action/index.js
 var require_action = __commonJS({
   "node_modules/.pnpm/@nozbe+watermelondb@0.28.0/node_modules/@nozbe/watermelondb/decorators/action/index.js"(exports2) {
@@ -19836,6 +19836,7 @@ var postApiV1Embeddings = (options) => (options.client ?? client).post({
 
 // 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;
@@ -19933,7 +19934,10 @@ async function embedOne(text12, options, outer) {
     const cached = cache.get(text12);
     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({
@@ -20028,7 +20032,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;
@@ -30374,6 +30381,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;
@@ -31066,6 +31117,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));
 }
@@ -32048,6 +32100,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
     },
@@ -32149,16 +32202,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
         ),
@@ -33312,7 +33369,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();
@@ -33351,42 +33418,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));
@@ -33394,33 +33464,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;
   }
@@ -34025,6 +34102,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;
@@ -34120,7 +34201,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;
@@ -34178,7 +34259,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, {
@@ -34544,7 +34625,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 },
@@ -34555,34 +34636,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)
@@ -34621,7 +34715,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();
@@ -34649,10 +34747,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;
@@ -34661,7 +34766,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) {
@@ -34673,6 +34798,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,
@@ -34716,6 +34849,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;
@@ -34957,6 +35091,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();
@@ -34978,6 +35124,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 },
@@ -34986,6 +35138,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`
       );
@@ -34994,6 +35147,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`
       );
@@ -35006,6 +35160,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;
 }
@@ -35044,6 +35199,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");
@@ -35084,7 +35240,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);
@@ -35115,7 +35282,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
@@ -35270,7 +35446,7 @@ function createLocalMemoryStore(options) {
       search: (query, searchOptions) => searchVaultMemoriesWithSize(
         query,
         vaultCtx,
-        options.embeddingOptions,
+        { ...options.embeddingOptions, taskType: "memory_recall_embed" },
         vaultCache,
         searchOptions
       ),
@@ -36929,9 +37105,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 },
@@ -36985,6 +37165,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 {
@@ -36992,7 +37173,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: (count) => {
+              candidateCount = count;
+            },
             limit: requestLimit,
             minSimilarity,
             useFusion: false,
@@ -37000,13 +37185,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 outcome = "retain" in vaultCtx ? await vaultCtx.factSource.search(query, legacyOptions) : await searchVaultMemoriesWithSize(
             query,
             vaultCtx,
-            embeddingOptions,
+            recallEmbeddingOptions,
             cache,
             legacyOptions
           );
+          const { results: legacy, embeddingsUnavailable, vaultSize } = outcome;
+          const diagnostics = factRecallDiagnostics(
+            legacy.map((m) => m.similarity),
+            Date.now() - start,
+            {
+              vaultSize,
+              minScore: minSimilarity,
+              embeddingsUnavailable,
+              candidateCount,
+              truncated: candidateCount !== void 0 && candidateCount > requestLimit,
+              decryptLast: outcome.decryptLast,
+              vaultRowsDecrypted: outcome.rowsDecrypted,
+              vaultRowsEmbedded: outcome.rowsEmbedded,
+              queryEmbedMs: outcome.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.";
           }
@@ -37028,6 +37238,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,
@@ -37060,6 +37278,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}`;
       }