@anuma/sdk 6.43.0 → 6.44.0

package/dist/react/index.cjs

@@ -122,6 +122,18 @@ var init_logger = __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;
@@ -7132,6 +7132,7 @@ var DEFAULT_API_EMBEDDING_MODEL = "qwen/qwen3-embedding-8b";
 
 // 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;
@@ -7229,7 +7230,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({
@@ -7324,7 +7328,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;
@@ -18522,6 +18529,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;
@@ -19214,6 +19265,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));
 }
@@ -20196,6 +20248,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
     },
@@ -20297,16 +20350,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
         ),
@@ -21460,7 +21517,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();
@@ -21499,42 +21566,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));
@@ -21542,33 +21612,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;
   }
@@ -22173,6 +22250,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;
@@ -22268,7 +22349,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;
@@ -22326,7 +22407,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, {
@@ -22692,7 +22773,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 },
@@ -22703,34 +22784,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)
@@ -22769,7 +22863,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();
@@ -22797,10 +22895,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;
@@ -22809,7 +22914,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) {
@@ -22821,6 +22946,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,
@@ -22864,6 +22997,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;
@@ -23105,6 +23239,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();
@@ -23126,6 +23272,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 },
@@ -23134,6 +23286,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`
       );
@@ -23142,6 +23295,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`
       );
@@ -23154,6 +23308,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;
 }
@@ -23192,6 +23347,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");
@@ -23232,7 +23388,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);
@@ -23263,7 +23430,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
@@ -23418,7 +23594,7 @@ function createLocalMemoryStore(options) {
       search: (query, searchOptions) => searchVaultMemoriesWithSize(
         query,
         vaultCtx,
-        options.embeddingOptions,
+        { ...options.embeddingOptions, taskType: "memory_recall_embed" },
         vaultCache,
         searchOptions
       ),
@@ -24082,6 +24258,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 () => {
@@ -24330,7 +24507,7 @@ function createRemoteMemoryPipeline(options) {
       const ranked = await rankPreparedVaultCandidates(
         text14,
         prepared,
-        embeddingOptions,
+        { ...embeddingOptions, taskType: "memory_recall_embed" },
         searchOptions
       );
       return {
@@ -24352,7 +24529,7 @@ function createRemoteMemoryPipeline(options) {
         content,
         {
           persistence: port,
-          embeddingOptions,
+          embeddingOptions: { ...embeddingOptions, taskType: "memory_retain_embed" },
           vaultCache: /* @__PURE__ */ new Map(),
           normalizeEmbedding: storedVector
         },
@@ -24729,6 +24906,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`);
@@ -24824,7 +25002,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;
@@ -24856,6 +25038,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 })
@@ -25081,7 +25293,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) => {
@@ -25099,7 +25312,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);
@@ -25148,7 +25372,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)];
@@ -25275,18 +25508,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, {
@@ -27164,9 +27386,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 },
@@ -27220,6 +27446,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 {
@@ -27227,7 +27454,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,
@@ -27235,13 +27466,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.";
           }
@@ -27263,6 +27519,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,
@@ -27295,6 +27559,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}`;
       }