@mastra/memory 1.25.0-alpha.1 → 1.25.0

package/dist/{src-DoNjfXNm.js → src-BgdYYHLc.js}

@@ -14583,7 +14583,7 @@ var constants_exports = /* @__PURE__ */ __exportAll({
 	OBSERVATION_CONTEXT_INSTRUCTIONS: () => OBSERVATION_CONTEXT_INSTRUCTIONS,
 	OBSERVATION_CONTEXT_PROMPT: () => OBSERVATION_CONTEXT_PROMPT,
 	OBSERVATION_CONTINUATION_HINT: () => OBSERVATION_CONTINUATION_HINT,
-	OBSERVATION_RETRIEVAL_INSTRUCTIONS: () => OBSERVATION_RETRIEVAL_INSTRUCTIONS
+	getRetrievalInstructions: () => getRetrievalInstructions
 });
 /**
 * Default configuration values matching the spec
@@ -14646,8 +14646,22 @@ SYSTEM REMINDERS: Messages wrapped in <system-reminder>...</system-reminder> con
 /**
 * Instructions for retrieval mode — explains observation-group ranges and the recall tool.
 * Appended to context when `retrieval` is enabled.
+*
+* The content adapts to the retrieval scope:
+* - `'resource'`: covers routing between `search`, `threads`, and `messages` across
+*   all of the user's threads, including fallback when search results are unsuitable.
+* - `'thread'`: covers cursor-based browsing and search within the current thread.
+*
+* @param scope - The retrieval scope the recall tool was registered with.
+* @param customInstructions - Optional application-provided guidance appended after
+*   the native instructions. Never replaces them.
+* @param searchEnabled - Whether semantic search (`retrieval: { vector: true }`) is
+*   available. When false, the guidance only covers \`threads\`/\`messages\` browsing so
+*   the agent is not steered toward a mode that cannot work.
 */
-const OBSERVATION_RETRIEVAL_INSTRUCTIONS = `## Recall — looking up source messages
+function getRetrievalInstructions(scope = "resource", customInstructions, searchEnabled = true) {
+	const isResource = scope === "resource";
+	const base = `## Recall — looking up source messages
 
 Your memory is comprised of observations which are sometimes wrapped in <observation-group> xml tags containing ranges like <observation-group range="startId:endId">. These ranges point back to the raw messages that each observation group was derived from. The original messages are still available — use the **recall** tool to retrieve them.
 
@@ -14655,11 +14669,32 @@ Your memory is comprised of observations which are sometimes wrapped in <observa
 - The user asks you to **repeat, show, or reproduce** something from a past conversation
 - The user asks for **exact content** — code, text, quotes, error messages, URLs, file paths, specific numbers
 - Your observations mention something but your memory lacks the detail needed to fully answer (e.g. you know a blog post was shared but only have a summary of it)
-- You want to **verify or expand on** an observation before responding
+- You want to **verify or expand on** an observation before responding${isResource ? `
+- The user references another conversation that your observations don't cover — even if you have no observations yet, their other threads may contain it` : ""}
 
 **Default to using recall when the user references specific past content.** Your observations capture the gist, not the details. If there's any doubt whether your memory is complete enough, use recall.
 
-### How to use recall
+${isResource ? searchEnabled ? `### Choosing a mode
+The recall tool works across ALL of this user's conversation threads, not just the current one.
+
+- Use \`mode: "search"\` with a \`query\` when you don't know which thread contains the answer. Each result includes its thread ID and the raw message IDs it came from, which you can use as a \`cursor\`.
+- Use \`mode: "messages"\` when you already know the thread — pass \`threadId\` to read another thread, or a \`cursor\` from an observation-group range or a search result.
+- Use \`mode: "threads"\` to list the user's threads (IDs, titles, dates) when you need to discover where something was discussed. Use \`before\`/\`after\` to narrow by date.
+
+**If search results look irrelevant, do not give up.** Search only covers content that has been indexed — a short or recent conversation may exist in raw message history before any observation of it was created. When search returns nothing suitable but the user is clearly referring to a past conversation, call \`mode: "threads"\` to find candidate threads (titles and dates are strong clues), then read them with \`mode: "messages"\`. If a search result already gives you a thread ID, go straight to \`mode: "messages"\`.` : `### Choosing a mode
+The recall tool works across ALL of this user's conversation threads, not just the current one.
+
+- Use \`mode: "threads"\` to list the user's threads (IDs, titles, dates) when you need to discover where something was discussed. Use \`before\`/\`after\` to narrow by date.
+- Use \`mode: "messages"\` when you know the thread — pass \`threadId\` to read another thread, or a \`cursor\` from an observation-group range.
+
+When the user refers to a past conversation you don't have a cursor for, call \`mode: "threads"\` to find candidate threads (titles and dates are strong clues), then read them with \`mode: "messages"\`. Raw history may exist for threads that have no observations yet.` : `### Choosing a mode
+The recall tool is limited to the current conversation thread.
+
+- Use \`mode: "messages"\` (default) to page through this thread's message history near a cursor.${searchEnabled ? `
+- Use \`mode: "search"\` with a \`query\` to find messages by content within this thread.` : ""}
+- Use \`mode: "threads"\` to get the current thread's ID, title, and dates.`}
+
+### How to use recall with a cursor
 Each range has the format \`startId:endId\` where both are message IDs separated by a colon.
 
 1. Find the observation group relevant to the user's question and extract the start or end ID from its range.
@@ -14685,9 +14720,16 @@ Low-detail results may include truncation hints like:
 ### When recall is NOT needed
 - The user is asking for a high-level summary and your observations already cover it
 - The question is about general preferences or facts that don't require source text
-- There is no relevant range in your observations for the topic
+${isResource ? `- No relevant observation range exists AND ${searchEnabled ? "`search`/`threads`" : "`threads`"} turned up nothing — but remember that raw history may exist for threads that have no observations yet, so check before concluding the information is unavailable` : `- There is no relevant range in your observations for the topic`}
 
 Observation groups with range IDs and your recall tool allows you to think back and remember details you're fuzzy on.`;
+	const custom = customInstructions?.trim();
+	if (!custom) return base;
+	return `${base}
+
+### Additional recall guidance
+${custom}`;
+}
 //#endregion
 //#region src/processors/observational-memory/extractor.ts
 const BUILT_IN_SLUGS = /* @__PURE__ */ new Set([
@@ -23711,6 +23753,11 @@ var ObservationalMemory = class ObservationalMemory {
 	scope;
 	/** Whether retrieval-mode observation groups are enabled. */
 	retrieval;
+	/** Scope the recall tool was registered with — controls which retrieval instructions are injected. */
+	retrievalScope;
+	/** Application-provided guidance appended after the native retrieval instructions. */
+	retrievalInstructions;
+	retrievalSearch;
 	observationConfig;
 	reflectionConfig;
 	onDebugEvent;
@@ -23776,6 +23823,9 @@ var ObservationalMemory = class ObservationalMemory {
 		this.storage = config.storage;
 		this.scope = config.scope ?? "thread";
 		this.retrieval = Boolean(config.retrieval);
+		this.retrievalScope = typeof config.retrieval === "object" ? config.retrieval.scope ?? "resource" : "resource";
+		this.retrievalInstructions = typeof config.retrieval === "object" ? config.retrieval.instructions : void 0;
+		this.retrievalSearch = typeof config.retrieval === "object" && Boolean(config.retrieval.vector);
 		this.onIndexObservations = config.onIndexObservations;
 		this.hooks = config.hooks;
 		this.mastra = config.mastra;
@@ -24424,7 +24474,7 @@ var ObservationalMemory = class ObservationalMemory {
 	formatObservationsForContext(observations, currentTask, suggestedResponse, extractedValues, unobservedContextBlocks, currentDate, retrieval = false) {
 		let optimized = retrieval ? renderObservationGroupsForReflection(observations) ?? optimizeObservationsForContext(observations) : optimizeObservationsForContext(observations);
 		if (currentDate) optimized = addRelativeTimeToObservations(optimized, currentDate);
-		const messages = [`${OBSERVATION_CONTEXT_PROMPT}\n\n${OBSERVATION_CONTEXT_INSTRUCTIONS}${retrieval ? `\n\n${OBSERVATION_RETRIEVAL_INSTRUCTIONS}` : ""}`];
+		const messages = [`${OBSERVATION_CONTEXT_PROMPT}\n\n${OBSERVATION_CONTEXT_INSTRUCTIONS}${retrieval ? `\n\n${getRetrievalInstructions(this.retrievalScope, this.retrievalInstructions, this.retrievalSearch)}` : ""}`];
 		if (unobservedContextBlocks) messages.push(`The following content is from OTHER conversations different from the current conversation, they're here for reference,  but they're not necessarily your focus:\nSTART_OTHER_CONVERSATIONS_BLOCK\n${unobservedContextBlocks}\nEND_OTHER_CONVERSATIONS_BLOCK`);
 		const observationChunks = this.splitObservationContextChunks(optimized);
 		if (observationChunks.length > 0) messages.push("<observations>", ...observationChunks);
@@ -24926,7 +24976,10 @@ ${formattedMessages}
 	async buildContextSystemMessages(opts) {
 		const { threadId, resourceId, unobservedContextBlocks } = opts;
 		const record = opts.record ?? await this.getOrCreateRecord(threadId, resourceId);
-		if (!record.activeObservations) return void 0;
+		if (!record.activeObservations) {
+			if (this.retrieval && this.retrievalScope === "resource") return [getRetrievalInstructions(this.retrievalScope, this.retrievalInstructions, this.retrievalSearch)];
+			return;
+		}
 		const omMetadata = getThreadOMMetadata((await this.storage.getThreadById({ threadId }))?.metadata);
 		const currentTask = omMetadata?.currentTask;
 		const suggestedResponse = omMetadata?.suggestedResponse;
@@ -26058,7 +26111,7 @@ var ObservationalMemoryProcessor = class {
 					threadId,
 					resourceId
 				});
-				const systemMessages = ctx.hasObservations && ctx.omRecord ? await this.engine.buildContextSystemMessages({
+				const systemMessages = ctx.omRecord ? await this.engine.buildContextSystemMessages({
 					threadId,
 					resourceId,
 					record: ctx.omRecord,
@@ -28253,4 +28306,4 @@ Notes:
 //#endregion
 export { extractCurrentTask as A, OBSERVATION_CONTEXT_INSTRUCTIONS as B, WorkingMemoryExtractor as C, OBSERVER_SYSTEM_PROMPT as D, TokenCounter as E, injectAnchorIds as F, OBSERVATION_CONTINUATION_HINT as H, parseAnchorId as I, stripEphemeralAnchorIds as L, hasCurrentTaskSection as M, optimizeObservationsForContext as N, buildObserverPrompt as O, parseObserverOutput as P, Extractor as R, deepMergeWorkingMemory as S, summarizeConversation as T, OBSERVATION_CONTEXT_PROMPT as V, reconcileObservationGroupsFromReflection as _, extractWorkingMemoryContent as a, wrapInObservationGroup as b, WORKING_MEMORY_STATE_ID as c, getObservationsAsOf as d, ObservationalMemoryProcessor as f, parseObservationGroups as g, deriveObservationGroupProvenance as h, WorkingMemory as i, formatMessagesForObserver as j, buildObserverSystemPrompt as k, WORKING_MEMORY_STATE_PROCESSOR_ID as l, combineObservationGroupRanges as m, MessageHistory$1 as n, extractWorkingMemoryTags as o, ObservationalMemory as p, SemanticRecall as r, removeWorkingMemoryTags as s, Memory as t, WorkingMemoryStateProcessor as u, renderObservationGroupsForReflection as v, SUMMARIZE_THREAD_DEFAULTS as w, ModelByInputTokens as x, stripObservationGroups as y, OBSERVATIONAL_MEMORY_DEFAULTS as z };
 
-//# sourceMappingURL=src-DoNjfXNm.js.map
+//# sourceMappingURL=src-BgdYYHLc.js.map