@mastra/memory 1.25.0-alpha.1 → 1.25.0

package/dist/{src-C3u7zaSu.cjs → src-DQO6B1AU.cjs}

@@ -14604,7 +14604,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
@@ -14667,8 +14667,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.
 
@@ -14676,11 +14690,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.
@@ -14706,9 +14741,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([
@@ -23732,6 +23774,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;
@@ -23797,6 +23844,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;
@@ -24445,7 +24495,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);
@@ -24947,7 +24997,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 = (0, _mastra_core_memory.getThreadOMMetadata)((await this.storage.getThreadById({ threadId }))?.metadata);
 		const currentTask = omMetadata?.currentTask;
 		const suggestedResponse = omMetadata?.suggestedResponse;
@@ -26079,7 +26132,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,
@@ -28507,4 +28560,4 @@ Object.defineProperty(exports, "wrapInObservationGroup", {
 	}
 });
 
-//# sourceMappingURL=src-C3u7zaSu.cjs.map
+//# sourceMappingURL=src-DQO6B1AU.cjs.map