@mastra/server 1.18.0-alpha.2 → 1.18.0-alpha.3

package/dist/{chunk-FGZC4JP7.js → chunk-SDKSW2BQ.js}

@@ -3,7 +3,7 @@ import { __commonJS as __commonJS$3, require_token_error as require_token_error$
 import { actionIdPathParams, actionRunPathParams, streamAgentBuilderBodySchema, startAsyncAgentBuilderBodySchema, resumeAgentBuilderBodySchema, streamLegacyAgentBuilderBodySchema } from './chunk-S7PYDU5I.js';
 import { __commonJS as __commonJS$1, require_token_error, __toESM } from './chunk-BZZVTO7B.js';
 import { __commonJS as __commonJS$2, require_token_error as require_token_error$1, __toESM as __toESM$1 } from './chunk-PWAXLHKP.js';
-import { e, truncateStringByTokens, resolveToolResultValue, formatToolResultForObserver, estimateTokenCount } from './chunk-PVUR75AM.js';
+import { e, truncateStringByTokens, estimateTokenCount, resolveToolResultValue, formatToolResultForObserver } from './chunk-YUTITKH2.js';
 import { LIST_WORKFLOWS_ROUTE, GET_WORKFLOW_BY_ID_ROUTE, LIST_WORKFLOW_RUNS_ROUTE, GET_WORKFLOW_RUN_BY_ID_ROUTE, CREATE_WORKFLOW_RUN_ROUTE, STREAM_WORKFLOW_ROUTE, START_ASYNC_WORKFLOW_ROUTE, START_WORKFLOW_RUN_ROUTE, OBSERVE_STREAM_WORKFLOW_ROUTE, RESUME_ASYNC_WORKFLOW_ROUTE, RESUME_WORKFLOW_ROUTE, RESUME_STREAM_WORKFLOW_ROUTE, CANCEL_WORKFLOW_RUN_ROUTE, STREAM_LEGACY_WORKFLOW_ROUTE, OBSERVE_STREAM_LEGACY_WORKFLOW_ROUTE } from './chunk-G2ZZKKQI.js';
 import { listWorkflowsResponseSchema, workflowInfoSchema, workflowRunsResponseSchema, listWorkflowRunsQuerySchema, workflowRunResultSchema, workflowRunResultQuerySchema, createWorkflowRunResponseSchema, workflowExecutionResultSchema, workflowControlResponseSchema } from './chunk-7X4P2I6L.js';
 import { streamResponseSchema } from './chunk-V7EVEI4C.js';
@@ -16143,7 +16143,7 @@ function parseRangeFormat(cursor) {
   }
   return null;
 }
-async function resolveCursorMessage(memory, cursor) {
+async function resolveCursorMessage(memory, cursor, access) {
   const normalized = cursor.trim();
   if (!normalized) {
     throw new Error("Cursor is required");
@@ -16161,8 +16161,171 @@ async function resolveCursorMessage(memory, cursor) {
   if (!message) {
     throw new Error(`Could not resolve cursor message: ${cursor}`);
   }
+  if (access?.resourceId && message.resourceId !== access.resourceId) {
+    throw new Error(`Could not resolve cursor message: ${cursor}`);
+  }
+  if (access?.threadScope && message.threadId !== access.threadScope) {
+    throw new Error(`Could not resolve cursor message: ${cursor}`);
+  }
   return message;
 }
+async function listThreadsForResource({
+  memory,
+  resourceId,
+  currentThreadId,
+  page = 0,
+  limit = 20,
+  before,
+  after
+}) {
+  if (!resourceId) {
+    throw new Error("Resource ID is required to list threads");
+  }
+  const MAX_LIMIT = 50;
+  const normalizedLimit = Math.min(Math.max(limit, 1), MAX_LIMIT);
+  const hasDateFilter = !!(before || after);
+  const beforeDate = before ? new Date(before) : null;
+  const afterDate = after ? new Date(after) : null;
+  const result = await memory.listThreads({
+    filter: { resourceId },
+    page: hasDateFilter ? 0 : page,
+    perPage: hasDateFilter ? false : normalizedLimit,
+    orderBy: { field: "updatedAt", direction: "DESC" }
+  });
+  let threads = result.threads;
+  if (beforeDate) {
+    threads = threads.filter((t) => t.createdAt < beforeDate);
+  }
+  if (afterDate) {
+    threads = threads.filter((t) => t.createdAt > afterDate);
+  }
+  let hasMore;
+  if (hasDateFilter) {
+    const offset = page * normalizedLimit;
+    hasMore = offset + normalizedLimit < threads.length;
+    threads = threads.slice(offset, offset + normalizedLimit);
+  } else {
+    hasMore = result.hasMore;
+  }
+  if (threads.length === 0) {
+    return {
+      threads: "No threads found matching the criteria.",
+      count: 0,
+      page,
+      hasMore: false
+    };
+  }
+  const lines = [];
+  for (const thread of threads) {
+    const isCurrent = thread.id === currentThreadId;
+    const title = thread.title || "(untitled)";
+    const updated = formatTimestamp(thread.updatedAt);
+    const created = formatTimestamp(thread.createdAt);
+    const marker21 = isCurrent ? " \u2190 current" : "";
+    lines.push(`- **${title}**${marker21}`);
+    lines.push(`  id: ${thread.id}`);
+    lines.push(`  updated: ${updated} | created: ${created}`);
+  }
+  return {
+    threads: lines.join("\n"),
+    count: threads.length,
+    page,
+    hasMore
+  };
+}
+async function searchMessagesForResource({
+  memory,
+  resourceId,
+  currentThreadId,
+  query,
+  topK = 10,
+  maxTokens = DEFAULT_MAX_RESULT_TOKENS,
+  before,
+  after,
+  threadScope
+}) {
+  if (!memory.searchMessages) {
+    return {
+      results: "Search is not configured. Enable it with `retrieval: { vector: true }` and configure a vector store and embedder on your Memory instance.",
+      count: 0
+    };
+  }
+  const MAX_TOPK = 20;
+  const clampedTopK = Math.min(Math.max(topK, 1), MAX_TOPK);
+  const effectiveTopK = threadScope || before || after ? Math.max(clampedTopK * 3, clampedTopK + 10) : clampedTopK;
+  const searchTopK = Math.min(MAX_TOPK, effectiveTopK);
+  const beforeDate = before ? new Date(before) : void 0;
+  const afterDate = after ? new Date(after) : void 0;
+  const { results } = await memory.searchMessages({
+    query,
+    resourceId,
+    topK: searchTopK,
+    filter: {
+      ...threadScope ? { threadId: threadScope } : {},
+      ...afterDate ? { observedAfter: afterDate } : {},
+      ...beforeDate ? { observedBefore: beforeDate } : {}
+    }
+  });
+  if (results.length === 0) {
+    return {
+      results: "No matching messages found.",
+      count: 0
+    };
+  }
+  const threadIds = [...new Set(results.map((r) => r.threadId))];
+  const threadMap = /* @__PURE__ */ new Map();
+  if (memory.getThreadById) {
+    await Promise.all(
+      threadIds.map(async (id) => {
+        const thread = await memory.getThreadById({ threadId: id });
+        if (thread) threadMap.set(id, thread);
+      })
+    );
+  }
+  const filteredMatches = results.filter((match) => {
+    if (threadScope && match.threadId !== threadScope) return false;
+    if (beforeDate && match.observedAt && match.observedAt >= beforeDate) return false;
+    if (afterDate && match.observedAt && match.observedAt <= afterDate) return false;
+    return true;
+  });
+  if (filteredMatches.length === 0) {
+    return { results: "No matching messages found.", count: 0 };
+  }
+  const limitedMatches = filteredMatches.slice(0, clampedTopK);
+  const sections = limitedMatches.map((match) => {
+    const thread = threadMap.get(match.threadId);
+    const title = thread?.title || "(untitled)";
+    const isCurrentThread = match.threadId === currentThreadId;
+    const generationLabel = isCurrentThread ? "Current thread memory" : "Older memory from another thread";
+    const generationDetail = isCurrentThread ? "This result came from the current thread." : "This result came from an older memory generation in another thread.";
+    const threadLine = `- thread: ${match.threadId}${thread ? ` (${title})` : ""}`;
+    const sourceLine = match.range ? `- source: raw messages from ID ${match.range.split(":")[0] ?? "(unknown)"} through ID ${match.range.split(":")[1] ?? "(unknown)"}` : "- source: raw message range unavailable";
+    const updatedLine = thread ? `- thread updated: ${formatTimestamp(thread.updatedAt)}` : void 0;
+    const groupLine = match.groupId ? `- observation group: ${match.groupId}` : void 0;
+    const scoreLine = `- score: ${match.score.toFixed(2)}`;
+    const body = (match.text || "").trim() || "_Observation text unavailable._";
+    return [
+      `### ${generationLabel}`,
+      "",
+      generationDetail,
+      threadLine,
+      sourceLine,
+      updatedLine,
+      groupLine,
+      scoreLine,
+      "",
+      "```text",
+      body,
+      "```"
+    ].filter(Boolean).join("\n");
+  });
+  const assembled = sections.join("\n\n");
+  const { text: limited } = truncateByTokens(assembled, maxTokens);
+  return {
+    results: limited,
+    count: limitedMatches.length
+  };
+}
 var LOW_DETAIL_PART_TOKENS = 30;
 var AUTO_EXPAND_TEXT_TOKENS = 100;
 var AUTO_EXPAND_TOOL_TOKENS = 20;
@@ -16313,8 +16476,10 @@ function renderFormattedParts(parts, timestamps, options) {
 async function recallPart({
   memory,
   threadId,
+  resourceId,
   cursor,
   partIndex,
+  threadScope,
   maxTokens = DEFAULT_MAX_RESULT_TOKENS
 }) {
   if (!memory || typeof memory.getMemoryStore !== "function") {
@@ -16323,13 +16488,10 @@ async function recallPart({
   if (!threadId) {
     throw new Error("Thread ID is required for recall");
   }
-  const resolved = await resolveCursorMessage(memory, cursor);
+  const resolved = await resolveCursorMessage(memory, cursor, { resourceId, threadScope });
   if ("hint" in resolved) {
     throw new Error(resolved.hint);
   }
-  if (resolved.threadId !== threadId) {
-    throw new Error("The requested cursor does not belong to the current thread");
-  }
   const allParts = formatMessageParts(resolved, "high");
   if (allParts.length === 0) {
     throw new Error(
@@ -16361,6 +16523,7 @@ async function recallMessages({
   page = 1,
   limit = 20,
   detail = "low",
+  threadScope,
   maxTokens = DEFAULT_MAX_RESULT_TOKENS
 }) {
   if (!memory) {
@@ -16377,7 +16540,7 @@ async function recallMessages({
   const rawPage = page === 0 ? 1 : page;
   const normalizedPage = Math.max(Math.min(rawPage, MAX_PAGE), -MAX_PAGE);
   const normalizedLimit = Math.min(limit, MAX_LIMIT);
-  const resolved = await resolveCursorMessage(memory, cursor);
+  const resolved = await resolveCursorMessage(memory, cursor, { resourceId, threadScope });
   if ("hint" in resolved) {
     return {
       messages: resolved.hint,
@@ -16393,15 +16556,27 @@ async function recallMessages({
     };
   }
   const anchor = resolved;
-  if (anchor.threadId !== threadId) {
-    throw new Error("The requested cursor does not belong to the current thread");
+  if (anchor.threadId && anchor.threadId !== threadId) {
+    return {
+      messages: `Cursor does not belong to the active thread. Expected thread "${threadId}" but cursor "${cursor}" belongs to "${anchor.threadId}".`,
+      count: 0,
+      cursor,
+      page: normalizedPage,
+      limit: normalizedLimit,
+      detail,
+      hasNextPage: false,
+      hasPrevPage: false,
+      truncated: false,
+      tokenOffset: 0
+    };
   }
+  const resolvedThreadId = threadId;
   const isForward = normalizedPage > 0;
   const pageIndex = Math.max(Math.abs(normalizedPage), 1) - 1;
   const skip = pageIndex * normalizedLimit;
   const fetchCount = skip + normalizedLimit + 1;
   const result = await memory.recall({
-    threadId,
+    threadId: resolvedThreadId,
     resourceId,
     page: 0,
     perPage: fetchCount,
@@ -16484,55 +16659,233 @@ High detail returns 1 part at a time. To continue: ${hints.join(", or ")}.`;
     tokenOffset: rendered.tokenOffset
   };
 }
-var recallTool = (_memoryConfig) => {
+async function recallThreadFromStart({
+  memory,
+  threadId,
+  resourceId,
+  page = 1,
+  limit = 20,
+  detail = "low",
+  maxTokens = DEFAULT_MAX_RESULT_TOKENS
+}) {
+  if (!memory) {
+    throw new Error("Memory instance is required for recall");
+  }
+  if (!threadId) {
+    throw new Error("Thread ID is required for recall");
+  }
+  if (resourceId && memory.getThreadById) {
+    const thread = await memory.getThreadById({ threadId });
+    if (!thread || thread.resourceId !== resourceId) {
+      throw new Error("Thread not found");
+    }
+  }
+  const MAX_PAGE = 50;
+  const MAX_LIMIT = 20;
+  const normalizedPage = Math.max(Math.min(page, MAX_PAGE), 1);
+  const normalizedLimit = Math.min(Math.max(limit, 1), MAX_LIMIT);
+  const pageIndex = normalizedPage - 1;
+  const fetchCount = pageIndex * normalizedLimit + normalizedLimit + 1;
+  const result = await memory.recall({
+    threadId,
+    resourceId,
+    page: 0,
+    perPage: fetchCount,
+    orderBy: { field: "createdAt", direction: "ASC" }
+  });
+  const visibleMessages = result.messages.filter(hasVisibleParts);
+  const total = visibleMessages.length;
+  const skip = pageIndex * normalizedLimit;
+  const hasMore = total > skip + normalizedLimit;
+  const messages = visibleMessages.slice(skip, skip + normalizedLimit);
+  const allParts = [];
+  const timestamps = /* @__PURE__ */ new Map();
+  for (const msg of messages) {
+    timestamps.set(msg.id, msg.createdAt);
+    allParts.push(...formatMessageParts(msg, detail));
+  }
+  const rendered = renderFormattedParts(allParts, timestamps, { maxTokens });
+  return {
+    messages: rendered.text || "(no messages in this thread)",
+    count: messages.length,
+    cursor: messages[0]?.id || "",
+    page: normalizedPage,
+    limit: normalizedLimit,
+    detail,
+    hasNextPage: hasMore,
+    hasPrevPage: pageIndex > 0,
+    truncated: rendered.truncated,
+    tokenOffset: rendered.tokenOffset
+  };
+}
+var recallTool = (_memoryConfig, options) => {
+  const retrievalScope = options?.retrievalScope ?? "thread";
+  const isResourceScope = retrievalScope === "resource";
+  const description = isResourceScope ? 'Browse conversation history. Use mode="threads" to list all threads for the current user. Use mode="messages" (default) to browse messages in the current thread or pass threadId to browse another thread in the active resource. If you pass only a cursor, it must belong to the current thread. Use mode="search" to find messages by content across all threads.' : `Browse conversation history in the current thread. Use mode="messages" (default) to page through messages near a cursor. Use mode="search" to find messages by content in this thread. Use mode="threads" to get the current thread's ID and title.`;
   return createTool({
     id: "recall",
-    description: 'Retrieve raw message history near an observation group cursor. Observation group ranges use the format startId:endId. Pass either the start or end message ID as the cursor. Use detail="low" (default) for an overview, detail="high" for full content, or provide partIndex to fetch a specific part from the cursor message.',
+    description,
     inputSchema: z.object({
-      cursor: z.string().min(1).describe("A single message ID to use as the pagination cursor. Extract it from the start or end of a range."),
+      ...isResourceScope ? {
+        mode: z.enum(["messages", "threads", "search"]).optional().describe(
+          'What to retrieve. "messages" (default) pages through message history. "threads" lists all threads for the current user. "search" finds messages by semantic similarity across all threads.'
+        ),
+        threadId: z.string().min(1).optional().describe('Browse a different thread. Use mode="threads" first to discover thread IDs.'),
+        before: z.string().optional().describe(
+          'For mode="threads": only show threads created before this date. ISO 8601 or natural date string (e.g. "2026-03-15", "2026-03-10T00:00:00Z").'
+        ),
+        after: z.string().optional().describe(
+          'For mode="threads": only show threads created after this date. ISO 8601 or natural date string (e.g. "2026-03-01", "2026-03-10T00:00:00Z").'
+        )
+      } : {
+        mode: z.enum(["messages", "threads", "search"]).optional().describe(
+          'What to retrieve. "messages" (default) pages through message history. "threads" returns info about the current thread. "search" finds messages by semantic similarity in this thread.'
+        )
+      },
+      query: z.string().min(1).optional().describe('Search query for mode="search". Finds messages semantically similar to this text.'),
+      cursor: z.string().min(1).optional().describe(
+        'A message ID to use as the pagination cursor. For mode="messages", provide either cursor or threadId. If only cursor is provided, it must belong to the current thread. Extract it from the start or end of an observation group range.'
+      ),
       page: z.number().int().min(-50).max(50).optional().describe(
-        "Pagination offset from the cursor. Positive pages move forward, negative pages move backward, and 0 is treated as 1."
+        "Pagination offset. For messages: positive pages move forward from cursor, negative move backward. For threads: page number (0-indexed). 0 is treated as 1 for messages."
       ),
-      limit: z.number().int().positive().max(20).optional().describe("Maximum number of messages to return. Defaults to 20."),
+      limit: z.number().int().positive().max(20).optional().describe("Maximum number of items to return per page. Defaults to 20."),
       detail: z.enum(["low", "high"]).optional().describe(
-        'Detail level. "low" (default) returns truncated text and tool names. "high" returns full content with tool args/results.'
+        'Detail level for messages. "low" (default) returns truncated text and tool names. "high" returns full content with tool args/results.'
       ),
       partIndex: z.number().int().min(0).optional().describe(
         "Fetch a single part from the cursor message by its positional index. When provided, returns only that part at high detail. Indices are shown as [p0], [p1], etc. in recall results."
       )
     }),
     execute: async ({
+      mode,
+      query,
       cursor,
+      threadId: explicitThreadId,
       page,
       limit,
       detail,
-      partIndex
+      partIndex,
+      before,
+      after
     }, context2) => {
       const memory = context2?.memory;
-      const threadId = context2?.agent?.threadId;
+      const currentThreadId = context2?.agent?.threadId;
       const resourceId = context2?.agent?.resourceId;
       if (!memory) {
         throw new Error("Memory instance is required for recall");
       }
-      if (!threadId) {
+      if (mode === "search") {
+        if (!query) {
+          throw new Error('query is required for mode="search"');
+        }
+        if (!resourceId) {
+          throw new Error("Resource ID is required for recall");
+        }
+        return searchMessagesForResource({
+          memory,
+          resourceId,
+          currentThreadId: currentThreadId || void 0,
+          query,
+          topK: limit ?? 10,
+          before,
+          after,
+          threadScope: !isResourceScope ? currentThreadId || void 0 : void 0
+        });
+      }
+      if (mode === "threads") {
+        if (!isResourceScope) {
+          if (!currentThreadId || !memory.getThreadById) {
+            return { error: "Could not resolve current thread." };
+          }
+          const thread = await memory.getThreadById({ threadId: currentThreadId });
+          if (!thread) {
+            return { error: "Could not resolve current thread." };
+          }
+          return {
+            threads: `- **${thread.title || "(untitled)"}** \u2190 current
+  id: ${thread.id}
+  updated: ${formatTimestamp(thread.updatedAt)} | created: ${formatTimestamp(thread.createdAt)}`,
+            count: 1,
+            page: 0,
+            hasMore: false
+          };
+        }
+        if (!resourceId) {
+          throw new Error("Resource ID is required for recall");
+        }
+        return listThreadsForResource({
+          memory,
+          resourceId,
+          currentThreadId: currentThreadId || "",
+          page: page ?? 0,
+          limit: limit ?? 20,
+          before,
+          after
+        });
+      }
+      const hasExplicitThreadId = typeof explicitThreadId === "string" && explicitThreadId.length > 0;
+      const hasCursor = typeof cursor === "string" && cursor.length > 0;
+      if (!hasExplicitThreadId && !hasCursor) {
+        throw new Error('Either cursor or threadId is required for mode="messages"');
+      }
+      let targetThreadId;
+      let threadScope;
+      if (!isResourceScope) {
+        targetThreadId = currentThreadId;
+        threadScope = currentThreadId || void 0;
+      } else if (hasExplicitThreadId) {
+        if (!resourceId) {
+          throw new Error("Resource ID is required for recall");
+        }
+        if (!memory.getThreadById) {
+          throw new Error("Memory instance cannot verify thread access for recall");
+        }
+        const thread = await memory.getThreadById({ threadId: explicitThreadId });
+        if (!thread || thread.resourceId !== resourceId) {
+          throw new Error("Thread does not belong to the active resource");
+        }
+        targetThreadId = thread.id;
+        threadScope = thread.id;
+      } else {
+        targetThreadId = currentThreadId;
+        threadScope = currentThreadId || void 0;
+      }
+      if (hasCursor && !hasExplicitThreadId && !currentThreadId) {
+        throw new Error("Current thread is required when browsing by cursor");
+      }
+      if (!targetThreadId) {
         throw new Error("Thread ID is required for recall");
       }
+      if (!cursor) {
+        return recallThreadFromStart({
+          memory,
+          threadId: targetThreadId,
+          resourceId: isResourceScope ? resourceId : void 0,
+          page: page ?? 1,
+          limit: limit ?? 20,
+          detail: detail ?? "low"
+        });
+      }
       if (partIndex !== void 0 && partIndex !== null) {
         return recallPart({
           memory,
-          threadId,
+          threadId: targetThreadId,
+          resourceId: isResourceScope ? resourceId : void 0,
           cursor,
-          partIndex
+          partIndex,
+          threadScope
         });
       }
       return recallMessages({
         memory,
-        threadId,
-        resourceId,
+        threadId: targetThreadId,
+        resourceId: isResourceScope ? resourceId : void 0,
         cursor,
         page,
         limit,
-        detail: detail ?? "low"
+        detail: detail ?? "low",
+        threadScope
       });
     }
   });
@@ -16784,6 +17137,19 @@ var Memory = class extends MastraMemory {
       observationalMemory: config.options?.observationalMemory
     });
     this.threadConfig = mergedConfig;
+    const omConfig = normalizeObservationalMemoryConfig(mergedConfig.observationalMemory);
+    if (omConfig?.retrieval && typeof omConfig.retrieval === "object" && omConfig.retrieval.vector) {
+      if (!this.vector) {
+        throw new Error(
+          "`retrieval: { vector: true }` requires a vector store. Pass a `vector` option to your Memory instance."
+        );
+      }
+      if (!this.embedder) {
+        throw new Error(
+          "`retrieval: { vector: true }` requires an embedder. Pass an `embedder` option to your Memory instance."
+        );
+      }
+    }
   }
   /**
    * Gets the memory storage domain, throwing if not available.
@@ -17553,13 +17919,17 @@ ${workingMemory}`;
         "Observational memory requires @mastra/core support for request-response-id-rotation. Please bump @mastra/core to a newer version."
       );
     }
-    const { ObservationalMemory: OMClass } = await import('./observational-memory-UGDENJPE-NVMIXNI4.js');
+    const { ObservationalMemory: OMClass } = await import('./observational-memory-SN7GKMHZ-IWVBFBS6.js');
+    const onIndexObservations = this.hasRetrievalSearch(omConfig.retrieval) ? async (observation) => {
+      await this.indexObservation(observation);
+    } : void 0;
     return new OMClass({
       storage: memoryStore,
       scope: omConfig.scope,
       retrieval: omConfig.retrieval,
       shareTokenBudget: omConfig.shareTokenBudget,
       model: omConfig.model,
+      onIndexObservations,
       observation: omConfig.observation ? {
         model: omConfig.observation.model,
         messageTokens: omConfig.observation.messageTokens,
@@ -17695,6 +18065,176 @@ Notes:
     const isMDWorkingMemory = !(`schema` in config.workingMemory) && (typeof config.workingMemory.template === `string` || config.workingMemory.template) && config.workingMemory;
     return Boolean(isMDWorkingMemory && isMDWorkingMemory.version === `vnext`);
   }
+  getObservationEmbeddingIndexName(dimensions) {
+    const defaultDimensions = 384;
+    const usedDimensions = dimensions ?? defaultDimensions;
+    const separator = this.vector?.indexSeparator ?? "_";
+    return `memory${separator}observations${separator}${usedDimensions}`;
+  }
+  async createObservationEmbeddingIndex(dimensions) {
+    const defaultDimensions = 384;
+    const usedDimensions = dimensions ?? defaultDimensions;
+    const indexName = this.getObservationEmbeddingIndexName(dimensions);
+    if (typeof this.vector === `undefined`) {
+      throw new Error(
+        `Tried to create observation embedding index but no vector db is attached to this Memory instance.`
+      );
+    }
+    await this.vector.createIndex({
+      indexName,
+      dimension: usedDimensions
+    });
+    return { indexName };
+  }
+  /**
+   * Search observation groups across threads by semantic similarity.
+   * Requires a vector store and embedder to be configured.
+   */
+  async searchMessages({
+    query,
+    resourceId,
+    topK = 10,
+    filter: filter32
+  }) {
+    if (!this.vector) {
+      throw new Error("searchMessages requires a vector store. Configure vector and embedder on your Memory instance.");
+    }
+    const { embeddings, dimension } = await this.embedMessageContent(query);
+    const { indexName } = await this.createObservationEmbeddingIndex(dimension);
+    const vectorFilter = { resource_id: resourceId };
+    if (filter32?.threadId) {
+      vectorFilter.thread_id = filter32.threadId;
+    }
+    if (filter32?.observedAfter || filter32?.observedBefore) {
+      vectorFilter.observed_at = {
+        ...filter32.observedAfter ? { $gt: filter32.observedAfter.toISOString() } : {},
+        ...filter32.observedBefore ? { $lt: filter32.observedBefore.toISOString() } : {}
+      };
+    }
+    const queryResults = [];
+    await Promise.all(
+      embeddings.map(async (embedding) => {
+        const results2 = await this.vector.query({
+          indexName,
+          queryVector: embedding,
+          topK,
+          filter: vectorFilter
+        });
+        for (const r of results2) {
+          if (!r.metadata?.thread_id) {
+            continue;
+          }
+          const groupId = typeof r.metadata.group_id === "string" ? r.metadata.group_id : void 0;
+          if (!groupId) {
+            continue;
+          }
+          queryResults.push({
+            threadId: r.metadata.thread_id,
+            score: r.score,
+            groupId,
+            range: typeof r.metadata.range === "string" ? r.metadata.range : void 0,
+            text: typeof r.metadata.text === "string" ? r.metadata.text : void 0,
+            observedAt: typeof r.metadata.observed_at === "string" || r.metadata.observed_at instanceof Date ? new Date(r.metadata.observed_at) : void 0
+          });
+        }
+      })
+    );
+    const bestByGroup = /* @__PURE__ */ new Map();
+    for (const result of queryResults) {
+      if (!result.groupId) {
+        continue;
+      }
+      const existing = bestByGroup.get(result.groupId);
+      if (!existing || result.score > existing.score) {
+        bestByGroup.set(result.groupId, result);
+      }
+    }
+    const results = [...bestByGroup.values()].sort((a, b) => b.score - a.score);
+    return { results };
+  }
+  /**
+   * Index a single observation group into the observation vector store.
+   */
+  async indexObservation({
+    text: text42,
+    groupId,
+    range,
+    threadId,
+    resourceId,
+    observedAt
+  }) {
+    if (!this.vector || !this.embedder) return;
+    const embedResult = await this.embedMessageContent(text42);
+    if (embedResult.embeddings.length === 0 || embedResult.dimension === void 0) {
+      return;
+    }
+    const { indexName } = await this.createObservationEmbeddingIndex(embedResult.dimension);
+    await this.vector.upsert({
+      indexName,
+      vectors: embedResult.embeddings,
+      metadata: embedResult.chunks.map((chunk) => ({
+        group_id: groupId,
+        range,
+        thread_id: threadId,
+        resource_id: resourceId,
+        observed_at: observedAt?.toISOString(),
+        text: chunk
+      }))
+    });
+  }
+  /**
+   * Index a list of messages directly (without querying storage).
+   * Used by observe-time indexing to vectorize newly-observed messages.
+   */
+  async indexMessagesList(messages) {
+    if (!this.vector || !this.embedder) return;
+    const embeddingData = [];
+    let dimension;
+    await Promise.all(
+      messages.map(async (message) => {
+        let textForEmbedding = null;
+        if (message.content.content && typeof message.content.content === "string" && message.content.content.trim() !== "") {
+          textForEmbedding = message.content.content;
+        } else if (message.content.parts && message.content.parts.length > 0) {
+          const joined = message.content.parts.filter((part) => part.type === "text").map((part) => part.text).join(" ").trim();
+          if (joined) textForEmbedding = joined;
+        }
+        if (!textForEmbedding) return;
+        const embedResult = await this.embedMessageContent(textForEmbedding);
+        dimension = embedResult.dimension;
+        embeddingData.push({
+          embeddings: embedResult.embeddings,
+          metadata: embedResult.chunks.map(() => ({
+            message_id: message.id,
+            thread_id: message.threadId,
+            resource_id: message.resourceId
+          }))
+        });
+      })
+    );
+    if (embeddingData.length > 0 && dimension !== void 0) {
+      const { indexName } = await this.createEmbeddingIndex(dimension);
+      const allVectors = [];
+      const allMetadata = [];
+      for (const data of embeddingData) {
+        allVectors.push(...data.embeddings);
+        allMetadata.push(...data.metadata);
+      }
+      await this.vector.upsert({
+        indexName,
+        vectors: allVectors,
+        metadata: allMetadata
+      });
+    }
+  }
+  /**
+   * Check whether retrieval search (vector-based) is enabled.
+   * Returns true when `retrieval: { vector: true }` and Memory has vector + embedder configured.
+   */
+  hasRetrievalSearch(retrieval) {
+    if (!retrieval || retrieval === true) return false;
+    return !!retrieval.vector && !!this.vector && !!this.embedder;
+  }
   listTools(config) {
     const mergedConfig = this.getMergedThreadConfig(config);
     const tools = {};
@@ -17702,8 +18242,9 @@ Notes:
       tools.updateWorkingMemory = this.isVNextWorkingMemoryConfig(mergedConfig) ? __experimental_updateWorkingMemoryToolVNext(mergedConfig) : updateWorkingMemoryTool(mergedConfig);
     }
     const omConfig = normalizeObservationalMemoryConfig(mergedConfig.observationalMemory);
-    if (omConfig?.retrieval && (omConfig.scope ?? "thread") === "thread") {
-      tools.recall = recallTool();
+    if (omConfig?.retrieval) {
+      const retrievalScope = typeof omConfig.retrieval === "object" ? omConfig.retrieval.scope ?? "resource" : "resource";
+      tools.recall = recallTool(mergedConfig, { retrievalScope });
     }
     return tools;
   }
@@ -18266,7 +18807,7 @@ Notes:
     if (!effectiveConfig) return null;
     const engine = await this.omEngine;
     if (!engine) return null;
-    const { ObservationalMemoryProcessor } = await import('./observational-memory-UGDENJPE-NVMIXNI4.js');
+    const { ObservationalMemoryProcessor } = await import('./observational-memory-SN7GKMHZ-IWVBFBS6.js');
     return new ObservationalMemoryProcessor(engine, this);
   }
 };
@@ -29467,5 +30008,5 @@ var OBSERVE_STREAM_LEGACY_AGENT_BUILDER_ACTION_ROUTE = createRoute({
 });
 
 export { CANCEL_AGENT_BUILDER_ACTION_RUN_ROUTE, CREATE_AGENT_BUILDER_ACTION_RUN_ROUTE, GET_AGENT_BUILDER_ACTION_BY_ID_ROUTE, GET_AGENT_BUILDER_ACTION_RUN_BY_ID_ROUTE, LIST_AGENT_BUILDER_ACTIONS_ROUTE, LIST_AGENT_BUILDER_ACTION_RUNS_ROUTE, OBSERVE_STREAM_AGENT_BUILDER_ACTION_ROUTE, OBSERVE_STREAM_LEGACY_AGENT_BUILDER_ACTION_ROUTE, RESUME_AGENT_BUILDER_ACTION_ROUTE, RESUME_ASYNC_AGENT_BUILDER_ACTION_ROUTE, RESUME_STREAM_AGENT_BUILDER_ACTION_ROUTE, START_AGENT_BUILDER_ACTION_RUN_ROUTE, START_ASYNC_AGENT_BUILDER_ACTION_ROUTE, STREAM_AGENT_BUILDER_ACTION_ROUTE, STREAM_LEGACY_AGENT_BUILDER_ACTION_ROUTE, agent_builder_exports };
-//# sourceMappingURL=chunk-FGZC4JP7.js.map
-//# sourceMappingURL=chunk-FGZC4JP7.js.map
+//# sourceMappingURL=chunk-SDKSW2BQ.js.map
+//# sourceMappingURL=chunk-SDKSW2BQ.js.map