@anuma/sdk 4.2.1 → 5.0.0

package/dist/server/index.cjs

@@ -20612,11 +20612,11 @@ async function decomposeQuery(query, options) {
       userMessage: `Classify the following memory query and decompose if composite. Respond with JSON only \u2014 do not answer the question, do not ask for clarification.
 
 Query: ${trimmed}`,
-      // Decompose runs on the recall hot path — tighter than the
+      // Decompose runs ahead of recall in the tool layer — tighter than the
       // portalLlm default (consolidate/extract can wait longer).
       timeoutMs: 2e4,
       // No internal retry: a failure degrades to the safe `{specific,[query]}`
-      // fallback below, so retrying would only add latency on the hot path.
+      // fallback below. The agent/tool loop is the retry surface (719/B4).
       maxAttempts: 1,
       tag: "memory/decompose",
       ...options.fetchFn && { fetchFn: options.fetchFn }
@@ -20628,12 +20628,28 @@ Query: ${trimmed}`,
   if (parsed === null) return fallback;
   return validate(parsed, trimmed) ?? fallback;
 }
+function normalizeSubQueries(raw) {
+  if (!raw || raw.length === 0) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const s of raw) {
+    if (typeof s !== "string") continue;
+    const t = s.trim();
+    if (t.length === 0) continue;
+    const key = t.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(t);
+    if (out.length >= MAX_SUB_QUERIES) break;
+  }
+  return out;
+}
 function validate(parsed, originalQuery) {
   if (typeof parsed !== "object" || parsed === null) return null;
   const obj = parsed;
   const mode = obj.mode === "composite" ? "composite" : "specific";
   if (!Array.isArray(obj.subQueries)) return null;
-  const subQueries = obj.subQueries.filter((s) => typeof s === "string").map((s) => s.trim()).filter((s) => s.length > 0).slice(0, MAX_SUB_QUERIES);
+  const subQueries = normalizeSubQueries(obj.subQueries);
   if (subQueries.length === 0) return null;
   if (mode === "specific") {
     return { mode: "specific", subQueries: [originalQuery] };
@@ -21212,12 +21228,12 @@ __export(recall_exports, {
 function flagsForBudget(budget) {
   switch (budget) {
     case "high":
-      return { rerank: true, decompose: true, traverse: true };
+      return { rerank: true, traverse: true };
     case "mid":
-      return { rerank: true, decompose: false, traverse: false };
+      return { rerank: true, traverse: false };
     case "low":
     default:
-      return { rerank: false, decompose: false, traverse: false };
+      return { rerank: false, traverse: false };
   }
 }
 function dedupeBy(items, ...keys) {
@@ -21236,10 +21252,10 @@ function dedupeBy(items, ...keys) {
 async function recall(query, ctx, options = {}) {
   const types = options.types ?? ["fact"];
   const limit = options.limit ?? DEFAULT_LIMIT;
-  const requestedBudget = options.budget ?? DEFAULT_BUDGET;
-  const flags = flagsForBudget(requestedBudget);
-  const decomposeAvailable = flags.decompose && !!options.decomposeOptions;
-  const usedBudget = requestedBudget === "high" && !decomposeAvailable ? "mid" : requestedBudget;
+  const usedBudget = options.budget ?? DEFAULT_BUDGET;
+  const flags = flagsForBudget(usedBudget);
+  const normalizedFacets = normalizeSubQueries(options.subQueries);
+  const subQueries = normalizedFacets.length >= 2 ? normalizedFacets : void 0;
   const t0 = nowMs();
   let prepMs = 0;
   let factLaneMs = 0;
@@ -21260,7 +21276,9 @@ async function recall(query, ctx, options = {}) {
     if (flags.rerank && factResults.length > 0 && hadV2Head && !didRerank) {
       degraded.push("rerank-unavailable");
     }
-    if (flags.decompose && !decomposeAvailable) degraded.push("decompose-unavailable");
+    if (usedBudget === "high" && options.decomposeOptions && !subQueries && !options.graphRefine) {
+      degraded.push("decompose-moved");
+    }
     if (embeddingsUnavailable) degraded.push("embeddings-unavailable");
     const diagnostics = {
       usedBudget,
@@ -21373,10 +21391,8 @@ async function recall(query, ctx, options = {}) {
         },
         ...options.rrfK !== void 0 && { rrfK: options.rrfK },
         ...options.decryptLast !== void 0 && { decryptLast: options.decryptLast },
-        ...decomposeAvailable && {
-          decompose: "llm",
-          decomposeOptions: options.decomposeOptions
-        },
+        // 719/B4 — composite facets arrive pre-built; no LLM call here.
+        ...subQueries && { subQueries },
         ...options.scopes && { scopes: options.scopes },
         ...options.folderId !== void 0 && { folderId: options.folderId },
         ...options.factTypes?.length && { factTypes: options.factTypes },
@@ -21613,6 +21629,7 @@ var init_recall = __esm({
     init_logger();
     init_constants();
     init_embeddings();
+    init_decomposeQuery();
     init_searchTool();
     init_graphTraversal();
     init_observationTrend();
@@ -22558,52 +22575,51 @@ async function rankPreparedVaultCandidates(query, prepared, embeddingOptions, se
     ...searchOptions?.rrfK !== void 0 && { rrfK: searchOptions.rrfK },
     ...searchOptions?.factTypeWeights && { factTypeWeights: searchOptions.factTypeWeights }
   };
-  if (useFusion && !embeddingsUnavailable && searchOptions?.decompose === "llm" && searchOptions.decomposeOptions) {
-    const decomp = await decomposeQuery(query, searchOptions.decomposeOptions);
-    if (decomp.mode === "composite") {
-      let subEmbeddings;
-      try {
-        subEmbeddings = await generateEmbeddings(decomp.subQueries, embeddingOptions);
-      } catch (err) {
-        getLogger().warn(
-          "memoryVault: sub-query embedding failed \u2014 falling back to single-query ranking: " + (err instanceof Error ? err.message : String(err))
-        );
-        subEmbeddings = [];
-      }
-      const subEmbeddingsUsable = decomp.subQueries.length > 0 && subEmbeddings.length === decomp.subQueries.length && subEmbeddings.every((v) => v.length > 0 && v.length === queryEmbedding.length);
-      if (subEmbeddings.length > 0 && !subEmbeddingsUsable) {
-        getLogger().warn(
-          `memoryVault: sub-query embedding returned ${subEmbeddings.length} vectors (dims ${subEmbeddings.map((v) => v.length).join(",")}) for ${decomp.subQueries.length} sub-queries against a ${queryEmbedding.length}-dim query \u2014 falling back to single-query ranking`
-        );
-      }
-      if (subEmbeddingsUsable) {
-        const subQueries = decomp.subQueries.map((sq, i) => ({
-          query: sq,
-          embedding: subEmbeddings[i]
-        }));
-        const v2HeadStats = { hadResults: false };
-        const composite = await rankComposite(query, queryEmbedding, subQueries, embeddedItems, {
-          limit,
-          minSimilarity,
-          rerank: !!searchOptions.rerank,
-          ...searchOptions.rerankTopN !== void 0 && {
-            rerankTopN: searchOptions.rerankTopN
-          },
-          ...searchOptions.ceWeight !== void 0 && { ceWeight: searchOptions.ceWeight },
-          ...searchOptions.mmr !== void 0 && { mmr: searchOptions.mmr },
-          ...tuning,
-          ...searchOptions.entityRanking && { entityRanking: searchOptions.entityRanking },
-          ...searchOptions.temporalRanking && { temporalRanking: searchOptions.temporalRanking },
-          rerankStats,
-          v2HeadStats
-        });
-        return stampTimestamps({
-          results: composite,
-          vaultSize,
-          reranked: rerankStats.applied,
-          hadV2Head: v2HeadStats.hadResults
-        });
-      }
+  const normalizedFacets = normalizeSubQueries(searchOptions?.subQueries);
+  const facetQueries = normalizedFacets.length >= 2 ? normalizedFacets : void 0;
+  if (useFusion && !embeddingsUnavailable && facetQueries) {
+    let subEmbeddings;
+    try {
+      subEmbeddings = await generateEmbeddings(facetQueries, embeddingOptions);
+    } catch (err) {
+      getLogger().warn(
+        "memoryVault: sub-query embedding failed \u2014 falling back to single-query ranking: " + (err instanceof Error ? err.message : String(err))
+      );
+      subEmbeddings = [];
+    }
+    const subEmbeddingsUsable = facetQueries.length > 0 && subEmbeddings.length === facetQueries.length && subEmbeddings.every((v) => v.length > 0 && v.length === queryEmbedding.length);
+    if (subEmbeddings.length > 0 && !subEmbeddingsUsable) {
+      getLogger().warn(
+        `memoryVault: sub-query embedding returned ${subEmbeddings.length} vectors (dims ${subEmbeddings.map((v) => v.length).join(",")}) for ${facetQueries.length} sub-queries against a ${queryEmbedding.length}-dim query \u2014 falling back to single-query ranking`
+      );
+    }
+    if (subEmbeddingsUsable) {
+      const subQueries = facetQueries.map((sq, i) => ({
+        query: sq,
+        embedding: subEmbeddings[i]
+      }));
+      const v2HeadStats = { hadResults: false };
+      const composite = await rankComposite(query, queryEmbedding, subQueries, embeddedItems, {
+        limit,
+        minSimilarity,
+        rerank: !!searchOptions?.rerank,
+        ...searchOptions?.rerankTopN !== void 0 && {
+          rerankTopN: searchOptions.rerankTopN
+        },
+        ...searchOptions?.ceWeight !== void 0 && { ceWeight: searchOptions.ceWeight },
+        ...searchOptions?.mmr !== void 0 && { mmr: searchOptions.mmr },
+        ...tuning,
+        ...searchOptions?.entityRanking && { entityRanking: searchOptions.entityRanking },
+        ...searchOptions?.temporalRanking && { temporalRanking: searchOptions.temporalRanking },
+        rerankStats,
+        v2HeadStats
+      });
+      return stampTimestamps({
+        results: composite,
+        vaultSize,
+        reranked: rerankStats.applied,
+        hadV2Head: v2HeadStats.hadResults
+      });
     }
   }
   if (useFusion && searchOptions?.rerank) {
@@ -22663,6 +22679,12 @@ async function searchVaultMemoriesWithSize(query, vaultCtx, embeddingOptions, ca
       rankedOnCosine: false
     };
   }
+  if (searchOptions?.decompose === "llm" && normalizeSubQueries(searchOptions.subQueries).length < 2 && !warnedProgrammaticDecomposeIgnored) {
+    warnedProgrammaticDecomposeIgnored = true;
+    getLogger().warn(
+      'memoryVault: decompose:"llm" is ignored by searchVaultMemories \u2014 pass subQueries or use createMemoryVaultSearchTool / createRecallTool (719/B4)'
+    );
+  }
   const prepared = await prepareVaultCandidates(
     query,
     vaultCtx,
@@ -22767,7 +22789,8 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
         return "Error: A search query is required.";
       }
       try {
-        const budget = searchOptions?.decompose === "llm" && searchOptions.decomposeOptions ? "high" : searchOptions?.rerank ? "mid" : "low";
+        const wantsDecompose = searchOptions?.decompose === "llm" && !!searchOptions.decomposeOptions;
+        const budget = wantsDecompose ? "high" : searchOptions?.rerank ? "mid" : "low";
         const folderId = searchOptions?.folderId ?? argFolderId;
         if (searchOptions?.useFusion === false) {
           const { results: legacy, embeddingsUnavailable } = await searchVaultMemoriesWithSize(
@@ -22791,6 +22814,13 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
             legacy.map((r) => ({ id: r.uniqueId, content: r.content, score: r.similarity }))
           );
         }
+        let subQueries;
+        if (wantsDecompose && searchOptions?.decomposeOptions) {
+          const decomp = await decomposeQuery(query, searchOptions.decomposeOptions);
+          if (decomp.mode === "composite" && decomp.subQueries.length >= 2) {
+            subQueries = decomp.subQueries;
+          }
+        }
         const { recall: recall2 } = await Promise.resolve().then(() => (init_recall(), recall_exports));
         let recallDegraded = [];
         const result = await recall2(
@@ -22807,9 +22837,7 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
             ...tuningForward,
             ...folderId !== void 0 && { folderId },
             ...searchOptions?.scopes && { scopes: searchOptions.scopes },
-            ...searchOptions?.decompose === "llm" && searchOptions.decomposeOptions && {
-              decomposeOptions: searchOptions.decomposeOptions
-            }
+            ...subQueries && { subQueries }
           }
         );
         if (result.vaultSize === 0) {
@@ -22839,7 +22867,7 @@ ${formatted}`;
     }
   };
 }
-var SUPERSESSION_SIMILARITY_THRESHOLD, SUPERSESSION_MIN_AGE_GAP_MS, SUPERSESSION_BOOST_FACTOR, SUPERSESSION_MAX_WINDOW, EMBEDDINGS_DEGRADED_EMPTY_NO_LEXICAL;
+var warnedProgrammaticDecomposeIgnored, SUPERSESSION_SIMILARITY_THRESHOLD, SUPERSESSION_MIN_AGE_GAP_MS, SUPERSESSION_BOOST_FACTOR, SUPERSESSION_MAX_WINDOW, EMBEDDINGS_DEGRADED_EMPTY_NO_LEXICAL;
 var init_searchTool = __esm({
   "src/lib/memoryVault/searchTool.ts"() {
     "use strict";
@@ -22857,6 +22885,7 @@ var init_searchTool = __esm({
     init_bm25();
     init_decomposeQuery();
     init_lruCache();
+    warnedProgrammaticDecomposeIgnored = false;
     SUPERSESSION_SIMILARITY_THRESHOLD = 0.7;
     SUPERSESSION_MIN_AGE_GAP_MS = 30 * 24 * 60 * 60 * 1e3;
     SUPERSESSION_BOOST_FACTOR = 0.8;
@@ -29733,6 +29762,7 @@ function rankProfileCandidates(inputs, now = Date.now(), options = {}) {
 init_recall();
 
 // src/lib/memory/recallTool.ts
+init_decomposeQuery();
 init_recall();
 init_recallConstants();
 var DEFAULT_LIMIT2 = 8;
@@ -29830,7 +29860,7 @@ function createRecallTool(ctx, toolOptions, callbacks) {
     type: "function",
     function: {
       name: RECALL_TOOL_NAME,
-      description: "Search the user's memory across stored facts/preferences and past conversation excerpts. Returns a unified ranked list \u2014 facts carry an `id` you can reference; conversation excerpts carry a date and role. Use this whenever the user's question may relate to anything previously discussed or saved (preferences, prior decisions, past topics). Phrase the query naturally.",
+      description: `Search the user's memory across stored facts/preferences and past conversation excerpts. Returns a unified ranked list \u2014 facts carry an \`id\` you can reference; conversation excerpts carry a date and role. Use this whenever the user's question may relate to anything previously discussed or saved (preferences, prior decisions, past topics). Phrase the query naturally. For multi-faceted / overview questions ("tell me about the user", "what's my tech stack"), prefer several targeted searches \u2014 one facet each (e.g. name, work, hobbies) \u2014 over a single broad query; fuse the results yourself.`,
       arguments: {
         type: "object",
         properties: {
@@ -29885,6 +29915,13 @@ function createRecallTool(ctx, toolOptions, callbacks) {
       let surfaced = 0;
       try {
         let recallDegraded = [];
+        let subQueries;
+        if (defaultBudget === "high" && toolOptions?.decomposeOptions) {
+          const decomp = await decomposeQuery(query, toolOptions.decomposeOptions);
+          if (decomp.mode === "composite" && decomp.subQueries.length >= 2) {
+            subQueries = decomp.subQueries;
+          }
+        }
         const recallOpts = {
           onDiagnostics: (d) => {
             recallDegraded = d.degraded;
@@ -29898,10 +29935,12 @@ function createRecallTool(ctx, toolOptions, callbacks) {
           ...toolOptions?.excludeConversationId && {
             excludeConversationId: toolOptions.excludeConversationId
           },
-          ...toolOptions?.decomposeOptions && {
-            decomposeOptions: toolOptions.decomposeOptions
-          },
-          ...toolOptions?.now !== void 0 && { now: toolOptions.now }
+          // Do NOT forward decomposeOptions into recall() — rewrite already
+          // ran above, and forwarding would falsely trip `decompose-moved`
+          // on every specific-mode high-budget call. graphRefine auth can
+          // be threaded later when the tool opts into that path.
+          ...toolOptions?.now !== void 0 && { now: toolOptions.now },
+          ...subQueries && { subQueries }
         };
         const result = await recall(query, ctx, recallOpts);
         if (callbacks?.onChunksRetrieved) {

package/dist/server/index.d.mts

@@ -4945,15 +4945,26 @@ interface MemoryVaultSearchOptions {
     /** RRF smoothing constant for lane fusion. Default 60. */
     rrfK?: number;
     /**
-     * LLM-based query decomposition for composite/abstract queries. When set,
-     * each query is classified + (if composite) decomposed into 3–5 facet
-     * sub-queries via gpt-5-mini, then ranked via {@link rankComposite}.
-     * Requires `decomposeOptions` (auth) when set to "llm".
+     * Pre-decomposed facet queries for the composite ranker (719/B4). When
+     * ≥2 are supplied (and embeddings are available), runs {@link rankComposite}
+     * over them — no LLM call inside the search path. Callers that want LLM
+     * rewrite (e.g. `createRecallTool`) call `decomposeQuery` first and pass
+     * the facets here.
+     */
+    subQueries?: string[];
+    /**
+     * @deprecated 719/B4 — ignored by {@link searchVaultMemories} /
+     * {@link searchVaultMemoriesWithSize}. Pass {@link MemoryVaultSearchOptions.subQueries}
+     * (or use `createRecallTool`). The legacy {@link createMemoryVaultSearchTool}
+     * executor still honors `decompose: "llm"` + `decomposeOptions` for eval
+     * parity, then forwards facets into the LLM-free search path.
      */
     decompose?: "off" | "llm";
-    /** Auth + endpoint for the decomposition LLM call. Required when
-     * decompose="llm". Auth is the dual pattern — one of `apiKey` /
-     * `getToken`; see {@link PortalLlmAuth}. */
+    /**
+     * @deprecated 719/B4 — see `decompose`. Ignored on the programmatic search
+     * path; tool-layer rewrite still reads this from the search-tool options.
+     * Prefer `RecallToolOptions.decomposeOptions` with `createRecallTool`.
+     */
     decomposeOptions?: PortalLlmAuth & {
         baseUrl?: string;
         model?: string;
@@ -5118,9 +5129,11 @@ type MemoryKind = "fact" | "chunk";
  * Budget controls retrieval depth/cost. Higher budgets enable more
  * candidate sources and the cross-encoder reranker.
  *
- * - `low`: cosine + BM25 fusion only. No reranker. Mobile default.
- * - `mid`: + recency boost. Demo default.
- * - `high`: + cross-encoder rerank stage. Demo `budget: high` path.
+ * - `low`: cosine + BM25 + recency. No reranker. Mobile default.
+ * - `mid`: + cross-encoder rerank.
+ * - `high`: + multi-hop graph traversal. LLM-free — query decomposition
+ *   (when wanted) lives in the tool/agent layer ({@link createRecallTool}),
+ *   not inside `recall()` itself (719/B4).
  */
 type Budget = "low" | "mid" | "high";
 interface ScoreBreakdown {
@@ -5220,10 +5233,28 @@ interface RecallOptions {
     /** Drop results below this score. Default: 0.1 for facts, 0.5 for chunks (mirrors today's defaults). */
     minScore?: number;
     /**
-     * Auth + endpoint for the LLM-based query decomposition pass. Without
-     * these, decompose is skipped even at `budget: 'high'`. Mirrors the
-     * shape used by `searchVaultMemories`. Auth is the dual pattern — one
-     * of `apiKey` / `getToken` is required; see {@link PortalLlmAuth}.
+     * Pre-decomposed facet queries for the composite ranker. When ≥2 are
+     * supplied, the vault lane runs `rankComposite` over them (no LLM call
+     * inside `recall()` — 719/B4). Callers that still want LLM rewrite
+     * (e.g. {@link createRecallTool} at `budget: 'high'`) call
+     * `decomposeQuery` themselves and pass the result here. A single entry
+     * (or omitting this) keeps the single-query path.
+     */
+    subQueries?: string[];
+    /**
+     * Auth + endpoint for optional LLM helpers that reuse portal auth —
+     * currently {@link RecallOptions.graphRefine} neighbor selection.
+     * Query decomposition is **not** driven by this field inside `recall()`
+     * (719/B4); {@link createRecallTool} reads the same shape from
+     * `RecallToolOptions.decomposeOptions` for tool-layer rewrite.
+     *
+     * Callers that still pass `{ budget: 'high', decomposeOptions }` without
+     * {@link RecallOptions.subQueries} keep compiling but no longer rewrite —
+     * `recall()` emits `decompose-moved` on {@link RecallDiagnostics.degraded}
+     * so upgrades without a changelog read still leave a telemetry breadcrumb.
+     *
+     * Auth is the dual pattern — one of `apiKey` / `getToken` is required;
+     * see {@link PortalLlmAuth}.
      */
     decomposeOptions?: PortalLlmAuth & {
         baseUrl?: string;
@@ -5327,9 +5358,22 @@ type RecallDegradation =
 /** Rerank was requested (budget mid/high) but the cross-encoder didn't run
  *  this call — unavailable (e.g. React Native) or a transient failure. */
 "rerank-unavailable"
-/** `budget: 'high'` requested but no `decomposeOptions`, so query
- *  decomposition was skipped and the budget downgraded to mid. */
+/**
+ * @deprecated 719/B4 moved query decomposition out of `recall()`. Budget
+ * `high` no longer requires `decomposeOptions` and this signal is never
+ * emitted. Prefer `"decompose-moved"` for the upgrade breadcrumb. Kept in
+ * the union so existing telemetry consumers stay typed.
+ */
  | "decompose-unavailable"
+/**
+ * `budget: 'high'` with `decomposeOptions` set but no usable
+ * {@link RecallOptions.subQueries}. Pre-B4 this call shape triggered LLM
+ * rewrite inside `recall()`; post-B4 it stays on the single-query high
+ * path (rerank + graph) and callers must pass facets (or use
+ * {@link createRecallTool}). Surfaced so silent quality regressions show
+ * up in diagnostics instead of looking healthier than before.
+ */
+ | "decompose-moved"
 /** There was no usable cosine lane, so results were ranked on BM25 (lexical)
  *  alone: either the query embedding failed (or came back empty), or no
  *  candidate had a vector to score against it because the row (re)embed failed.
@@ -8103,9 +8147,14 @@ declare function rankProfileCandidates(inputs: readonly ProfileSalienceInput[],
  * Unified Recall API — single retrieval surface above vault + engine.
  *
  * Budget maps to pipeline depth (mirrors Hindsight's tiered defaults):
- * - `low`  → V2 cosine + BM25 + recency (no rerank, no decompose)
+ * - `low`  → V2 cosine + BM25 + recency (no rerank)
  * - `mid`  → V2 + cross-encoder rerank
- * - `high` → V2 + rerank + LLM query decomposition for composite queries
+ * - `high` → V2 + rerank + multi-hop graph traversal
+ *
+ * LLM-free by design (719/B4): query decomposition for composite asks
+ * lives in the tool/agent layer (`createRecallTool`), which may pass
+ * pre-built `subQueries` into this API. `recall()` itself never pays an
+ * LLM RTT.
  *
  * Fact + chunk lanes are fused with RRF (k=60). The previous naive
  * "sort the union by raw score" path is gone — score scales differ
@@ -8160,7 +8209,8 @@ interface RecallToolOptions {
     folderId?: string | null;
     /** Exclude one conversation from chunk results (typically the active one). */
     excludeConversationId?: string;
-    /** LLM-decompose options; only used at budget="high". Auth follows the
+    /** LLM-decompose options; only used at budget="high". Runs in THIS tool
+     * executor (719/B4) — `recall()` itself is LLM-free. Auth follows the
      * dual pattern: apiKey (server/CLI) or getToken (browser identity
      * tokens) — at least one required. */
     decomposeOptions?: PortalLlmAuth & {

package/dist/server/index.d.ts

@@ -4945,15 +4945,26 @@ interface MemoryVaultSearchOptions {
     /** RRF smoothing constant for lane fusion. Default 60. */
     rrfK?: number;
     /**
-     * LLM-based query decomposition for composite/abstract queries. When set,
-     * each query is classified + (if composite) decomposed into 3–5 facet
-     * sub-queries via gpt-5-mini, then ranked via {@link rankComposite}.
-     * Requires `decomposeOptions` (auth) when set to "llm".
+     * Pre-decomposed facet queries for the composite ranker (719/B4). When
+     * ≥2 are supplied (and embeddings are available), runs {@link rankComposite}
+     * over them — no LLM call inside the search path. Callers that want LLM
+     * rewrite (e.g. `createRecallTool`) call `decomposeQuery` first and pass
+     * the facets here.
+     */
+    subQueries?: string[];
+    /**
+     * @deprecated 719/B4 — ignored by {@link searchVaultMemories} /
+     * {@link searchVaultMemoriesWithSize}. Pass {@link MemoryVaultSearchOptions.subQueries}
+     * (or use `createRecallTool`). The legacy {@link createMemoryVaultSearchTool}
+     * executor still honors `decompose: "llm"` + `decomposeOptions` for eval
+     * parity, then forwards facets into the LLM-free search path.
      */
     decompose?: "off" | "llm";
-    /** Auth + endpoint for the decomposition LLM call. Required when
-     * decompose="llm". Auth is the dual pattern — one of `apiKey` /
-     * `getToken`; see {@link PortalLlmAuth}. */
+    /**
+     * @deprecated 719/B4 — see `decompose`. Ignored on the programmatic search
+     * path; tool-layer rewrite still reads this from the search-tool options.
+     * Prefer `RecallToolOptions.decomposeOptions` with `createRecallTool`.
+     */
     decomposeOptions?: PortalLlmAuth & {
         baseUrl?: string;
         model?: string;
@@ -5118,9 +5129,11 @@ type MemoryKind = "fact" | "chunk";
  * Budget controls retrieval depth/cost. Higher budgets enable more
  * candidate sources and the cross-encoder reranker.
  *
- * - `low`: cosine + BM25 fusion only. No reranker. Mobile default.
- * - `mid`: + recency boost. Demo default.
- * - `high`: + cross-encoder rerank stage. Demo `budget: high` path.
+ * - `low`: cosine + BM25 + recency. No reranker. Mobile default.
+ * - `mid`: + cross-encoder rerank.
+ * - `high`: + multi-hop graph traversal. LLM-free — query decomposition
+ *   (when wanted) lives in the tool/agent layer ({@link createRecallTool}),
+ *   not inside `recall()` itself (719/B4).
  */
 type Budget = "low" | "mid" | "high";
 interface ScoreBreakdown {
@@ -5220,10 +5233,28 @@ interface RecallOptions {
     /** Drop results below this score. Default: 0.1 for facts, 0.5 for chunks (mirrors today's defaults). */
     minScore?: number;
     /**
-     * Auth + endpoint for the LLM-based query decomposition pass. Without
-     * these, decompose is skipped even at `budget: 'high'`. Mirrors the
-     * shape used by `searchVaultMemories`. Auth is the dual pattern — one
-     * of `apiKey` / `getToken` is required; see {@link PortalLlmAuth}.
+     * Pre-decomposed facet queries for the composite ranker. When ≥2 are
+     * supplied, the vault lane runs `rankComposite` over them (no LLM call
+     * inside `recall()` — 719/B4). Callers that still want LLM rewrite
+     * (e.g. {@link createRecallTool} at `budget: 'high'`) call
+     * `decomposeQuery` themselves and pass the result here. A single entry
+     * (or omitting this) keeps the single-query path.
+     */
+    subQueries?: string[];
+    /**
+     * Auth + endpoint for optional LLM helpers that reuse portal auth —
+     * currently {@link RecallOptions.graphRefine} neighbor selection.
+     * Query decomposition is **not** driven by this field inside `recall()`
+     * (719/B4); {@link createRecallTool} reads the same shape from
+     * `RecallToolOptions.decomposeOptions` for tool-layer rewrite.
+     *
+     * Callers that still pass `{ budget: 'high', decomposeOptions }` without
+     * {@link RecallOptions.subQueries} keep compiling but no longer rewrite —
+     * `recall()` emits `decompose-moved` on {@link RecallDiagnostics.degraded}
+     * so upgrades without a changelog read still leave a telemetry breadcrumb.
+     *
+     * Auth is the dual pattern — one of `apiKey` / `getToken` is required;
+     * see {@link PortalLlmAuth}.
      */
     decomposeOptions?: PortalLlmAuth & {
         baseUrl?: string;
@@ -5327,9 +5358,22 @@ type RecallDegradation =
 /** Rerank was requested (budget mid/high) but the cross-encoder didn't run
  *  this call — unavailable (e.g. React Native) or a transient failure. */
 "rerank-unavailable"
-/** `budget: 'high'` requested but no `decomposeOptions`, so query
- *  decomposition was skipped and the budget downgraded to mid. */
+/**
+ * @deprecated 719/B4 moved query decomposition out of `recall()`. Budget
+ * `high` no longer requires `decomposeOptions` and this signal is never
+ * emitted. Prefer `"decompose-moved"` for the upgrade breadcrumb. Kept in
+ * the union so existing telemetry consumers stay typed.
+ */
  | "decompose-unavailable"
+/**
+ * `budget: 'high'` with `decomposeOptions` set but no usable
+ * {@link RecallOptions.subQueries}. Pre-B4 this call shape triggered LLM
+ * rewrite inside `recall()`; post-B4 it stays on the single-query high
+ * path (rerank + graph) and callers must pass facets (or use
+ * {@link createRecallTool}). Surfaced so silent quality regressions show
+ * up in diagnostics instead of looking healthier than before.
+ */
+ | "decompose-moved"
 /** There was no usable cosine lane, so results were ranked on BM25 (lexical)
  *  alone: either the query embedding failed (or came back empty), or no
  *  candidate had a vector to score against it because the row (re)embed failed.
@@ -8103,9 +8147,14 @@ declare function rankProfileCandidates(inputs: readonly ProfileSalienceInput[],
  * Unified Recall API — single retrieval surface above vault + engine.
  *
  * Budget maps to pipeline depth (mirrors Hindsight's tiered defaults):
- * - `low`  → V2 cosine + BM25 + recency (no rerank, no decompose)
+ * - `low`  → V2 cosine + BM25 + recency (no rerank)
  * - `mid`  → V2 + cross-encoder rerank
- * - `high` → V2 + rerank + LLM query decomposition for composite queries
+ * - `high` → V2 + rerank + multi-hop graph traversal
+ *
+ * LLM-free by design (719/B4): query decomposition for composite asks
+ * lives in the tool/agent layer (`createRecallTool`), which may pass
+ * pre-built `subQueries` into this API. `recall()` itself never pays an
+ * LLM RTT.
  *
  * Fact + chunk lanes are fused with RRF (k=60). The previous naive
  * "sort the union by raw score" path is gone — score scales differ
@@ -8160,7 +8209,8 @@ interface RecallToolOptions {
     folderId?: string | null;
     /** Exclude one conversation from chunk results (typically the active one). */
     excludeConversationId?: string;
-    /** LLM-decompose options; only used at budget="high". Auth follows the
+    /** LLM-decompose options; only used at budget="high". Runs in THIS tool
+     * executor (719/B4) — `recall()` itself is LLM-free. Auth follows the
      * dual pattern: apiKey (server/CLI) or getToken (browser identity
      * tokens) — at least one required. */
     decomposeOptions?: PortalLlmAuth & {

package/dist/server/index.mjs

@@ -43,6 +43,7 @@ import {
   createVaultEmbeddingCache,
   createVaultMemoriesBatchOp,
   createVaultMemoryOp,
+  decomposeQuery,
   decryptData,
   decryptDataBatch,
   decryptDataBytes,
@@ -136,7 +137,7 @@ import {
   updateVaultMemoryOp,
   upsertMessageOp,
   vaultMemoryToStored
-} from "./chunk-UQDYBQVF.mjs";
+} from "./chunk-FKVYUOSD.mjs";
 import {
   createStreamingDeAnonymizer,
   notifyConsolidationFallback,
@@ -6586,7 +6587,7 @@ function createRecallTool(ctx, toolOptions, callbacks) {
     type: "function",
     function: {
       name: RECALL_TOOL_NAME,
-      description: "Search the user's memory across stored facts/preferences and past conversation excerpts. Returns a unified ranked list \u2014 facts carry an `id` you can reference; conversation excerpts carry a date and role. Use this whenever the user's question may relate to anything previously discussed or saved (preferences, prior decisions, past topics). Phrase the query naturally.",
+      description: `Search the user's memory across stored facts/preferences and past conversation excerpts. Returns a unified ranked list \u2014 facts carry an \`id\` you can reference; conversation excerpts carry a date and role. Use this whenever the user's question may relate to anything previously discussed or saved (preferences, prior decisions, past topics). Phrase the query naturally. For multi-faceted / overview questions ("tell me about the user", "what's my tech stack"), prefer several targeted searches \u2014 one facet each (e.g. name, work, hobbies) \u2014 over a single broad query; fuse the results yourself.`,
       arguments: {
         type: "object",
         properties: {
@@ -6641,6 +6642,13 @@ function createRecallTool(ctx, toolOptions, callbacks) {
       let surfaced = 0;
       try {
         let recallDegraded = [];
+        let subQueries;
+        if (defaultBudget === "high" && toolOptions?.decomposeOptions) {
+          const decomp = await decomposeQuery(query, toolOptions.decomposeOptions);
+          if (decomp.mode === "composite" && decomp.subQueries.length >= 2) {
+            subQueries = decomp.subQueries;
+          }
+        }
         const recallOpts = {
           onDiagnostics: (d) => {
             recallDegraded = d.degraded;
@@ -6654,10 +6662,12 @@ function createRecallTool(ctx, toolOptions, callbacks) {
           ...toolOptions?.excludeConversationId && {
             excludeConversationId: toolOptions.excludeConversationId
           },
-          ...toolOptions?.decomposeOptions && {
-            decomposeOptions: toolOptions.decomposeOptions
-          },
-          ...toolOptions?.now !== void 0 && { now: toolOptions.now }
+          // Do NOT forward decomposeOptions into recall() — rewrite already
+          // ran above, and forwarding would falsely trip `decompose-moved`
+          // on every specific-mode high-budget call. graphRefine auth can
+          // be threaded later when the tool opts into that path.
+          ...toolOptions?.now !== void 0 && { now: toolOptions.now },
+          ...subQueries && { subQueries }
         };
         const result = await recall(query, ctx, recallOpts);
         if (callbacks?.onChunksRetrieved) {