@mastra/memory 1.14.0-alpha.2 → 1.15.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @mastra/memory
 
+## 1.15.0-alpha.0
+
+### Minor Changes
+
+- Updated the recall tool to support more precise message browsing for agents. ([#15116](https://github.com/mastra-ai/mastra/pull/15116))
+
+  Agents using `recall` can now pass `partType` and `toolName` to narrow message results to specific parts, such as tool calls or tool results for one tool. This change also adds `threadId: "current"` support across recall modes and `anchor: "start" | "end"` for no-cursor message paging, making it easier to inspect recent thread activity and past tool usage.
+
+## 1.14.0
+
+### Minor Changes
+
+- Added usage data to ObserveHooks callbacks and standalone reflect() return. ([#15047](https://github.com/mastra-ai/mastra/pull/15047))
+
+  **ObserveHooks:** `onObservationEnd` and `onReflectionEnd` now receive a result object containing token usage from the underlying LLM call. This enables reliable usage tracking across all observation and reflection paths (sync, async buffered, and resource-scoped).
+
+  **Standalone reflect():** `reflect()` now returns `{ reflected, record, usage? }` so callers can capture token usage without hooks.
+
+  **Examples**
+
+  ```ts
+  // Via hooks
+  await memory.observe({
+    threadId,
+    messages,
+    hooks: {
+      onObservationEnd: ({ usage }) => {
+        // usage: { inputTokens, outputTokens, totalTokens }
+      },
+      onReflectionEnd: ({ usage }) => {
+        // usage: { inputTokens, outputTokens, totalTokens }
+      },
+    },
+  });
+
+  // Via standalone reflect()
+  const { reflected, usage } = await memory.reflect(threadId, resourceId);
+  ```
+
+  Existing callbacks that accept no arguments continue to work without changes.
+
+- Added tracing support to Memory operations (recall, save, delete, update working memory). When an `observabilityContext` is provided, Memory creates `MEMORY_OPERATION` spans that capture operation type, message counts, embedding token usage, and vector result counts. Tracing is fully opt-in — existing usage without `observabilityContext` is unaffected. ([#14305](https://github.com/mastra-ai/mastra/pull/14305))
+
+  **Example usage:**
+
+  ```typescript
+  import { Memory } from '@mastra/memory';
+  import { InMemoryStore } from '@mastra/core/storage';
+
+  const memory = new Memory({ storage: new InMemoryStore() });
+
+  // Pass observabilityContext to create observable spans
+  await memory.recall({
+    threadId: 'thread-1',
+    observabilityContext: { tracingContext: { currentSpan: parentSpan } },
+  });
+
+  await memory.saveMessages({
+    messages: [userMessage, assistantMessage],
+    observabilityContext: { tracingContext: { currentSpan: parentSpan } },
+  });
+  ```
+
+- Added per-record config overrides for observation and reflection thresholds in Observational Memory. Each thread can now have its own `messageTokens` and `observationTokens` thresholds that override the instance-level defaults, without requiring a process restart or cache invalidation. If no per-record override is set, the instance-level config is used as before. ([#15102](https://github.com/mastra-ai/mastra/pull/15102))
+
+### Patch Changes
+
+- Fixed observational memory buffering so sealed assistant chunks stay split instead of being merged back into one persisted message during long tool runs. ([#14995](https://github.com/mastra-ai/mastra/pull/14995))
+
+- Fixed recall() to hide dynamic system reminder messages by default, with includeSystemReminders available when callers need raw reminder history. ([#15100](https://github.com/mastra-ai/mastra/pull/15100))
+
+- Updated dependencies [[`f32b9e1`](https://github.com/mastra-ai/mastra/commit/f32b9e115a3c754d1c8cfa3f4256fba87b09cfb7), [`7d6f521`](https://github.com/mastra-ai/mastra/commit/7d6f52164d0cca099f0b07cb2bba334360f1c8ab), [`a50d220`](https://github.com/mastra-ai/mastra/commit/a50d220b01ecbc5644d489a3d446c3bd4ab30245), [`665477b`](https://github.com/mastra-ai/mastra/commit/665477bc104fd52cfef8e7610d7664781a70c220), [`4cc2755`](https://github.com/mastra-ai/mastra/commit/4cc2755a7194cb08720ff2ab4dffb4b4a5103dfd), [`ac7baf6`](https://github.com/mastra-ai/mastra/commit/ac7baf66ef1db15e03975ef4ebb02724f015a391), [`ed425d7`](https://github.com/mastra-ai/mastra/commit/ed425d78e7c66cbda8209fee910856f98c6c6b82), [`1371703`](https://github.com/mastra-ai/mastra/commit/1371703835080450ef3f9aea58059a95d0da2e5a), [`0df8321`](https://github.com/mastra-ai/mastra/commit/0df832196eeb2450ab77ce887e8553abdd44c5a6), [`98f8a8b`](https://github.com/mastra-ai/mastra/commit/98f8a8bdf5761b9982f3ad3acbe7f1cc3efa71f3), [`ba6f7e9`](https://github.com/mastra-ai/mastra/commit/ba6f7e9086d8281393f2acae60fda61de3bff1f9), [`7eb2596`](https://github.com/mastra-ai/mastra/commit/7eb25960d607e07468c9a10c5437abd2deaf1e9a), [`1805ddc`](https://github.com/mastra-ai/mastra/commit/1805ddc9c9b3b14b63749735a13c05a45af43a80), [`fff91cf`](https://github.com/mastra-ai/mastra/commit/fff91cf914de0e731578aacebffdeebef82f0440), [`61109b3`](https://github.com/mastra-ai/mastra/commit/61109b34feb0e38d54bee4b8ca83eb7345b1d557), [`33f1ead`](https://github.com/mastra-ai/mastra/commit/33f1eadfa19c86953f593478e5fa371093b33779)]:
+  - @mastra/core@1.23.0
+
 ## 1.14.0-alpha.2
 
 ### Minor Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-memory
 description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
 metadata:
   package: "@mastra/memory"
-  version: "1.14.0-alpha.2"
+  version: "1.15.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.14.0-alpha.2",
+  "version": "1.15.0-alpha.0",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {

package/dist/index.cjs

@@ -15448,10 +15448,16 @@ var DefaultEmbedManyResult3 = class {
 };
 createIdGenerator3({ prefix: "aiobj", size: 24 });
 createIdGenerator3({ prefix: "aiobj", size: 24 });
+function getMessageParts(msg) {
+  if (typeof msg.content === "string") return [];
+  if (Array.isArray(msg.content)) return msg.content;
+  const parts = msg.content?.parts;
+  return Array.isArray(parts) ? parts : [];
+}
 function hasVisibleParts(msg) {
   if (typeof msg.content === "string") return msg.content.length > 0;
-  const parts = msg.content?.parts;
-  if (!parts || !Array.isArray(parts)) return false;
+  const parts = getMessageParts(msg);
+  if (parts.length === 0) return Boolean(msg.content?.content);
   return parts.some((p) => !p.type?.startsWith("data-"));
 }
 function parseRangeFormat(cursor) {
@@ -15712,13 +15718,13 @@ function lowDetailPartLimit(type) {
   if (type === "tool-result" || type === "tool-call") return AUTO_EXPAND_TOOL_TOKENS;
   return LOW_DETAIL_PART_TOKENS;
 }
-function makePart(msg, partIndex, type, fullText, detail) {
+function makePart(msg, partIndex, type, fullText, detail, toolName) {
   if (detail === "high") {
-    return { messageId: msg.id, partIndex, role: msg.role, type, text: fullText, fullText };
+    return { messageId: msg.id, partIndex, role: msg.role, type, text: fullText, fullText, toolName };
   }
   const hint = `recall cursor="${msg.id}" partIndex=${partIndex} detail="high"`;
   const { text: text4 } = truncateByTokens(fullText, lowDetailPartLimit(type), hint);
-  return { messageId: msg.id, partIndex, role: msg.role, type, text: text4, fullText };
+  return { messageId: msg.id, partIndex, role: msg.role, type, text: text4, fullText, toolName };
 }
 function formatMessageParts(msg, detail) {
   const parts = [];
@@ -15726,32 +15732,73 @@ function formatMessageParts(msg, detail) {
     parts.push(makePart(msg, 0, "text", msg.content, detail));
     return parts;
   }
-  if (msg.content?.parts && Array.isArray(msg.content.parts)) {
-    for (let i = 0; i < msg.content.parts.length; i++) {
-      const part = msg.content.parts[i];
+  const messageParts = getMessageParts(msg);
+  if (messageParts.length > 0) {
+    for (let i = 0; i < messageParts.length; i++) {
+      const part = messageParts[i];
       const partType = part.type;
       if (partType === "text") {
         const text4 = part.text;
-        parts.push(makePart(msg, i, "text", text4, detail));
+        if (text4) {
+          parts.push(makePart(msg, i, "text", text4, detail));
+        }
       } else if (partType === "tool-invocation") {
         const inv = part.toolInvocation;
-        if (inv.state === "result") {
-          const { value: resultValue } = chunkZVRO2GUN_cjs.resolveToolResultValue(
-            part,
-            inv.result
-          );
-          const resultStr = chunkZVRO2GUN_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
-          const fullText = `[Tool Result: ${inv.toolName}]
-${resultStr}`;
-          parts.push(makePart(msg, i, "tool-result", fullText, detail));
-        } else {
-          const argsStr = detail === "low" ? "" : `
+        if (inv?.toolName) {
+          const hasArgs = inv.args != null;
+          if (inv.state !== "partial-call" && hasArgs) {
+            const argsStr = detail === "low" ? "" : `
 ${JSON.stringify(inv.args, null, 2)}`;
-          const fullText = `[Tool Call: ${inv.toolName}]${argsStr}`;
-          parts.push({ messageId: msg.id, partIndex: i, role: msg.role, type: "tool-call", text: fullText, fullText });
+            const fullText = `[Tool Call: ${inv.toolName}]${argsStr}`;
+            parts.push({
+              messageId: msg.id,
+              partIndex: i,
+              role: msg.role,
+              type: "tool-call",
+              text: fullText,
+              fullText,
+              toolName: inv.toolName
+            });
+          }
+          if (inv.state === "result") {
+            const { value: resultValue } = chunkZVRO2GUN_cjs.resolveToolResultValue(
+              part,
+              inv.result
+            );
+            const resultStr = chunkZVRO2GUN_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+            const fullText = `[Tool Result: ${inv.toolName}]
+${resultStr}`;
+            parts.push(makePart(msg, i, "tool-result", fullText, detail, inv.toolName));
+          }
+        }
+      } else if (partType === "tool-call") {
+        const toolName = part.toolName;
+        if (toolName) {
+          const rawArgs = part.input ?? part.args;
+          const argsStr = detail === "low" || rawArgs == null ? "" : `
+${typeof rawArgs === "string" ? rawArgs : JSON.stringify(rawArgs, null, 2)}`;
+          const fullText = `[Tool Call: ${toolName}]${argsStr}`;
+          parts.push({
+            messageId: msg.id,
+            partIndex: i,
+            role: msg.role,
+            type: "tool-call",
+            text: fullText,
+            fullText,
+            toolName
+          });
+        }
+      } else if (partType === "tool-result") {
+        const toolName = part.toolName;
+        if (toolName) {
+          const rawResult = part.output ?? part.result;
+          const resultStr = chunkZVRO2GUN_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+          const fullText = `[Tool Result: ${toolName}]
+${resultStr}`;
+          parts.push(makePart(msg, i, "tool-result", fullText, detail, toolName));
         }
       } else if (partType === "reasoning") {
-        const reasoning = part.reasoning;
+        const reasoning = part.reasoning ?? part.text;
         if (reasoning) {
           parts.push(makePart(msg, i, "reasoning", reasoning, detail));
         }
@@ -15889,7 +15936,7 @@ async function recallPart({
       `Message ${cursor} has no visible content (it may be an internal system message). Try a neighboring message ID instead.`
     );
   }
-  const target = allParts.find((p) => p.partIndex === partIndex);
+  const target = [...allParts].reverse().find((p) => p.partIndex === partIndex);
   if (!target) {
     const availableIndices = allParts.map((p) => p.partIndex).join(", ");
     const highestVisiblePartIndex = Math.max(...allParts.map((p) => p.partIndex));
@@ -15942,6 +15989,8 @@ async function recallMessages({
   page = 1,
   limit = 20,
   detail = "low",
+  partType,
+  toolName,
   threadScope,
   maxTokens = DEFAULT_MAX_RESULT_TOKENS
 }) {
@@ -16031,12 +16080,18 @@ async function recallMessages({
   }
   const hasNextPage = isForward ? hasMore : pageIndex > 0;
   const hasPrevPage = isForward ? pageIndex > 0 : hasMore;
-  const allParts = [];
+  let allParts = [];
   const timestamps = /* @__PURE__ */ new Map();
   for (const msg of messages) {
     timestamps.set(msg.id, msg.createdAt);
     allParts.push(...formatMessageParts(msg, detail));
   }
+  if (toolName) {
+    allParts = allParts.filter((p) => (p.type === "tool-call" || p.type === "tool-result") && p.toolName === toolName);
+  }
+  if (partType) {
+    allParts = allParts.filter((p) => p.type === partType);
+  }
   if (detail === "high" && allParts.length > 0) {
     const firstPart = allParts[0];
     const sameMsgParts = allParts.filter((p) => p.messageId === firstPart.messageId);
@@ -16073,8 +16128,9 @@ High detail returns 1 part at a time. To continue: ${hints.join(", or ")}.`;
     };
   }
   const rendered = renderFormattedParts(allParts, timestamps, { maxTokens });
+  const emptyMessage = allParts.length === 0 ? partType || toolName ? "(no message parts matched the current filters)" : "(no visible message parts found for this page)" : "(no messages found)";
   return {
-    messages: rendered.text,
+    messages: rendered.text || emptyMessage,
     count: messages.length,
     cursor,
     page: normalizedPage,
@@ -16093,6 +16149,9 @@ async function recallThreadFromStart({
   page = 1,
   limit = 20,
   detail = "low",
+  partType,
+  toolName,
+  anchor = "start",
   maxTokens = DEFAULT_MAX_RESULT_TOKENS
 }) {
   if (!memory) {
@@ -16118,29 +16177,37 @@ async function recallThreadFromStart({
     resourceId,
     page: 0,
     perPage: fetchCount,
-    orderBy: { field: "createdAt", direction: "ASC" }
+    orderBy: { field: "createdAt", direction: anchor === "end" ? "DESC" : "ASC" }
   });
-  const visibleMessages = result.messages.filter(hasVisibleParts);
-  const total = visibleMessages.length;
+  const visibleMessages = anchor === "end" ? result.messages.slice(0, fetchCount).filter(hasVisibleParts).reverse() : result.messages.slice(0, fetchCount).filter(hasVisibleParts);
   const skip = pageIndex * normalizedLimit;
-  const hasMore = total > skip + normalizedLimit;
   const messages = visibleMessages.slice(skip, skip + normalizedLimit);
-  const allParts = [];
+  const hasExtraMessage = visibleMessages.length > skip + messages.length;
+  const hasNextPage = messages.length > 0 ? anchor === "end" ? pageIndex > 0 : hasExtraMessage : false;
+  const hasPrevPage = messages.length > 0 ? anchor === "end" ? hasExtraMessage : pageIndex > 0 : pageIndex > 0;
+  let allParts = [];
   const timestamps = /* @__PURE__ */ new Map();
   for (const msg of messages) {
     timestamps.set(msg.id, msg.createdAt);
     allParts.push(...formatMessageParts(msg, detail));
   }
+  if (toolName) {
+    allParts = allParts.filter((p) => (p.type === "tool-call" || p.type === "tool-result") && p.toolName === toolName);
+  }
+  if (partType) {
+    allParts = allParts.filter((p) => p.type === partType);
+  }
   const rendered = renderFormattedParts(allParts, timestamps, { maxTokens });
+  const emptyMessage = messages.length === 0 ? pageIndex > 0 ? `(no messages found on page ${normalizedPage} for this thread)` : "(no messages in this thread)" : partType || toolName ? "(no message parts matched the current filters)" : "(no messages found)";
   return {
-    messages: rendered.text || "(no messages in this thread)",
+    messages: rendered.text || emptyMessage,
     count: messages.length,
     cursor: messages[0]?.id || "",
     page: normalizedPage,
     limit: normalizedLimit,
     detail,
-    hasNextPage: hasMore,
-    hasPrevPage: pageIndex > 0,
+    hasNextPage,
+    hasPrevPage,
     truncated: rendered.truncated,
     tokenOffset: rendered.tokenOffset
   };
@@ -16157,7 +16224,9 @@ var recallTool = (_memoryConfig, options) => {
         mode: zod.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: zod.z.string().min(1).optional().describe('Browse a different thread. Use mode="threads" first to discover thread IDs.'),
+        threadId: zod.z.string().min(1).optional().describe(
+          'Browse a different thread, or use "current" for the active thread. Use mode="threads" first to discover thread IDs.'
+        ),
         before: zod.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").'
         ),
@@ -16173,6 +16242,9 @@ var recallTool = (_memoryConfig, options) => {
       cursor: zod.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.'
       ),
+      anchor: zod.z.enum(["start", "end"]).optional().describe(
+        'For mode="messages" without a cursor, page from the start (oldest-first) or end (newest-first) of the thread. Defaults to "start".'
+      ),
       page: zod.z.number().int().min(-50).max(50).optional().describe(
         "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."
       ),
@@ -16180,6 +16252,10 @@ var recallTool = (_memoryConfig, options) => {
       detail: zod.z.enum(["low", "high"]).optional().describe(
         'Detail level for messages. "low" (default) returns truncated text and tool names. "high" returns full content with tool args/results.'
       ),
+      partType: zod.z.enum(["text", "tool-call", "tool-result", "reasoning", "image", "file"]).optional().describe('Filter results to only include parts of this type. Only applies to mode="messages".'),
+      toolName: zod.z.string().min(1).optional().describe(
+        'Filter results to only include tool-call and tool-result parts matching this tool name. Only applies to mode="messages".'
+      ),
       partIndex: zod.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."
       )
@@ -16189,9 +16265,12 @@ var recallTool = (_memoryConfig, options) => {
       query,
       cursor,
       threadId: explicitThreadId,
+      anchor,
       page,
       limit,
       detail,
+      partType,
+      toolName,
       partIndex,
       before,
       after
@@ -16199,9 +16278,13 @@ var recallTool = (_memoryConfig, options) => {
       const memory = context2?.memory;
       const currentThreadId = context2?.agent?.threadId;
       const resourceId = context2?.agent?.resourceId;
+      const resolvedExplicitThreadId = explicitThreadId === "current" ? currentThreadId : explicitThreadId;
       if (!memory) {
         throw new Error("Memory instance is required for recall");
       }
+      if (explicitThreadId === "current" && !currentThreadId) {
+        throw new Error("Could not resolve current thread.");
+      }
       if (mode === "search") {
         if (!query) {
           throw new Error('query is required for mode="search"');
@@ -16217,11 +16300,12 @@ var recallTool = (_memoryConfig, options) => {
           topK: limit ?? 10,
           before,
           after,
-          threadScope: !isResourceScope ? currentThreadId || void 0 : void 0
+          threadScope: !isResourceScope ? currentThreadId || void 0 : resolvedExplicitThreadId || void 0
         });
       }
       if (mode === "threads") {
-        if (!isResourceScope) {
+        const requestedCurrentThread = explicitThreadId === "current";
+        if (!isResourceScope || requestedCurrentThread) {
           if (!currentThreadId || !memory.getThreadById) {
             return { error: "Could not resolve current thread." };
           }
@@ -16229,6 +16313,9 @@ var recallTool = (_memoryConfig, options) => {
           if (!thread) {
             return { error: "Could not resolve current thread." };
           }
+          if (isResourceScope && resourceId && thread.resourceId !== resourceId) {
+            throw new Error("Thread does not belong to the active resource");
+          }
           return {
             threads: `- **${thread.title || "(untitled)"}** \u2190 current
   id: ${thread.id}
@@ -16251,7 +16338,7 @@ var recallTool = (_memoryConfig, options) => {
           after
         });
       }
-      const hasExplicitThreadId = typeof explicitThreadId === "string" && explicitThreadId.length > 0;
+      const hasExplicitThreadId = typeof resolvedExplicitThreadId === "string" && resolvedExplicitThreadId.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"');
@@ -16268,7 +16355,7 @@ var recallTool = (_memoryConfig, options) => {
         if (!memory.getThreadById) {
           throw new Error("Memory instance cannot verify thread access for recall");
         }
-        const thread = await memory.getThreadById({ threadId: explicitThreadId });
+        const thread = await memory.getThreadById({ threadId: resolvedExplicitThreadId });
         if (!thread || thread.resourceId !== resourceId) {
           throw new Error("Thread does not belong to the active resource");
         }
@@ -16309,7 +16396,10 @@ var recallTool = (_memoryConfig, options) => {
           resourceId: isResourceScope ? resourceId : void 0,
           page: page ?? 1,
           limit: limit ?? 20,
-          detail: detail ?? "low"
+          detail: detail ?? "low",
+          partType,
+          toolName,
+          anchor: anchor ?? "start"
         });
       }
       if (partIndex !== void 0 && partIndex !== null) {
@@ -16330,6 +16420,8 @@ var recallTool = (_memoryConfig, options) => {
         page,
         limit,
         detail: detail ?? "low",
+        partType,
+        toolName,
         threadScope
       });
     }