@mastra/memory 1.9.0-alpha.1 → 1.9.0-alpha.2

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 var chunkCK4U3AYR_cjs = require('./chunk-CK4U3AYR.cjs');
 var chunkIDRQZVB4_cjs = require('./chunk-IDRQZVB4.cjs');
-var chunkAR52LM55_cjs = require('./chunk-AR52LM55.cjs');
+var chunkLVV2RT42_cjs = require('./chunk-LVV2RT42.cjs');
 var v3 = require('zod/v3');
 var zod = require('zod');
 var z4 = require('zod/v4');
@@ -13,8 +13,9 @@ var utils = require('@mastra/core/utils');
 var schema = require('@mastra/schema-compat/schema');
 var asyncMutex = require('async-mutex');
 var xxhash = require('xxhash-wasm');
-var schema$1 = require('@mastra/core/schema');
 var tools = require('@mastra/core/tools');
+var tokenx = require('tokenx');
+var schema$1 = require('@mastra/core/schema');
 var processors = require('@mastra/core/processors');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -15446,6 +15447,425 @@ var DefaultEmbedManyResult3 = class {
 };
 createIdGenerator3({ prefix: "aiobj", size: 24 });
 createIdGenerator3({ prefix: "aiobj", size: 24 });
+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;
+  return parts.some((p) => !p.type?.startsWith("data-"));
+}
+function parseRangeFormat(cursor) {
+  if (cursor.includes(",")) {
+    const parts = cursor.split(",").map((p) => p.trim()).filter(Boolean);
+    if (parts.length >= 1) {
+      const first = parts[0];
+      const last = parts[parts.length - 1];
+      const firstColon = first.indexOf(":");
+      const lastColon = last.indexOf(":");
+      return {
+        startId: firstColon > 0 ? first.slice(0, firstColon) : first,
+        endId: lastColon > 0 ? last.slice(lastColon + 1) : last
+      };
+    }
+  }
+  const colonIndex = cursor.indexOf(":");
+  if (colonIndex > 0 && colonIndex < cursor.length - 1) {
+    return { startId: cursor.slice(0, colonIndex), endId: cursor.slice(colonIndex + 1) };
+  }
+  return null;
+}
+async function resolveCursorMessage(memory, cursor) {
+  const normalized = cursor.trim();
+  if (!normalized) {
+    throw new Error("Cursor is required");
+  }
+  const rangeIds = parseRangeFormat(normalized);
+  if (rangeIds) {
+    return {
+      hint: `The cursor "${cursor}" looks like a range. Use one of the individual message IDs as the cursor instead: start="${rangeIds.startId}" or end="${rangeIds.endId}".`,
+      ...rangeIds
+    };
+  }
+  const memoryStore = await memory.getMemoryStore();
+  const result = await memoryStore.listMessagesById({ messageIds: [normalized] });
+  const message = result.messages.find((message2) => message2.id === normalized);
+  if (!message) {
+    throw new Error(`Could not resolve cursor message: ${cursor}`);
+  }
+  return message;
+}
+var LOW_DETAIL_PART_TOKENS = 30;
+var AUTO_EXPAND_TEXT_TOKENS = 100;
+var AUTO_EXPAND_TOOL_TOKENS = 20;
+var HIGH_DETAIL_TOOL_RESULT_TOKENS = 4e3;
+var DEFAULT_MAX_RESULT_TOKENS = 2e3;
+function formatTimestamp(date) {
+  return date.toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "Z");
+}
+function truncateByTokens(text4, maxTokens, hint) {
+  if (tokenx.estimateTokenCount(text4) <= maxTokens) return { text: text4, wasTruncated: false };
+  const truncated = chunkLVV2RT42_cjs.truncateStringByTokens(text4, maxTokens);
+  const suffix = hint ? ` [${hint} for more]` : "";
+  return { text: truncated + suffix, wasTruncated: true };
+}
+function lowDetailPartLimit(type) {
+  if (type === "text") return AUTO_EXPAND_TEXT_TOKENS;
+  if (type === "tool-result" || type === "tool-call") return AUTO_EXPAND_TOOL_TOKENS;
+  return LOW_DETAIL_PART_TOKENS;
+}
+function makePart(msg, partIndex, type, fullText, detail) {
+  if (detail === "high") {
+    return { messageId: msg.id, partIndex, role: msg.role, type, text: fullText, fullText };
+  }
+  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 };
+}
+function formatMessageParts(msg, detail) {
+  const parts = [];
+  if (typeof msg.content === "string") {
+    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 partType = part.type;
+      if (partType === "text") {
+        const text4 = part.text;
+        parts.push(makePart(msg, i, "text", text4, detail));
+      } else if (partType === "tool-invocation") {
+        const inv = part.toolInvocation;
+        if (inv.state === "result") {
+          const { value: resultValue } = chunkLVV2RT42_cjs.resolveToolResultValue(
+            part,
+            inv.result
+          );
+          const resultStr = chunkLVV2RT42_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" ? "" : `
+${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 });
+        }
+      } else if (partType === "reasoning") {
+        const reasoning = part.reasoning;
+        if (reasoning) {
+          parts.push(makePart(msg, i, "reasoning", reasoning, detail));
+        }
+      } else if (partType === "image" || partType === "file") {
+        const filename = part.filename;
+        const label = filename ? `: ${filename}` : "";
+        const fullText = `[${partType === "image" ? "Image" : "File"}${label}]`;
+        parts.push({ messageId: msg.id, partIndex: i, role: msg.role, type: partType, text: fullText, fullText });
+      } else if (partType?.startsWith("data-")) ; else if (partType) {
+        const fullText = `[${partType}]`;
+        parts.push({ messageId: msg.id, partIndex: i, role: msg.role, type: partType, text: fullText, fullText });
+      }
+    }
+  } else if (msg.content?.content) {
+    parts.push(makePart(msg, 0, "text", msg.content.content, detail));
+  }
+  return parts;
+}
+function buildRenderedText(parts, timestamps) {
+  let currentMessageId = "";
+  const lines = [];
+  for (const part of parts) {
+    if (part.messageId !== currentMessageId) {
+      currentMessageId = part.messageId;
+      const ts = timestamps.get(part.messageId);
+      const tsStr = ts ? ` (${formatTimestamp(ts)})` : "";
+      if (lines.length > 0) lines.push("");
+      lines.push(`**${part.role}${tsStr}** [${part.messageId}]:`);
+    }
+    const indexLabel = `[p${part.partIndex}]`;
+    lines.push(`  ${indexLabel} ${part.text}`);
+  }
+  return lines.join("\n");
+}
+var MAX_EXPAND_USER_TEXT_TOKENS = 200;
+var MAX_EXPAND_OTHER_TOKENS = 50;
+function expandLimit(part) {
+  if (part.role === "user" && part.type === "text") return MAX_EXPAND_USER_TEXT_TOKENS;
+  return MAX_EXPAND_OTHER_TOKENS;
+}
+function expandPriority(part) {
+  if (part.role === "user" && part.type === "text") return 0;
+  if (part.type === "text" || part.type === "reasoning") return 1;
+  if (part.type === "tool-result") return 2;
+  if (part.type === "tool-call") return 3;
+  return 4;
+}
+function renderFormattedParts(parts, timestamps, options) {
+  const text4 = buildRenderedText(parts, timestamps);
+  let totalTokens = tokenx.estimateTokenCount(text4);
+  if (totalTokens > options.maxTokens) {
+    const truncated = chunkLVV2RT42_cjs.truncateStringByTokens(text4, options.maxTokens);
+    return { text: truncated, truncated: true, tokenOffset: totalTokens - options.maxTokens };
+  }
+  const truncatedIndices = parts.map((p, i) => ({ part: p, index: i })).filter(({ part }) => part.text !== part.fullText).sort((a, b) => expandPriority(a.part) - expandPriority(b.part));
+  if (truncatedIndices.length === 0) {
+    return { text: text4, truncated: false, tokenOffset: 0 };
+  }
+  let remaining = options.maxTokens - totalTokens;
+  for (const { part, index } of truncatedIndices) {
+    if (remaining <= 0) break;
+    const maxTokens = expandLimit(part);
+    const fullTokens = tokenx.estimateTokenCount(part.fullText);
+    const currentTokens = tokenx.estimateTokenCount(part.text);
+    const targetTokens = Math.min(fullTokens, maxTokens);
+    const delta = targetTokens - currentTokens;
+    if (delta <= 0) continue;
+    if (delta <= remaining && targetTokens >= fullTokens) {
+      parts[index] = { ...part, text: part.fullText };
+      remaining -= delta;
+    } else {
+      const expandedLimit = Math.min(currentTokens + remaining, maxTokens);
+      const hint = `recall cursor="${part.messageId}" partIndex=${part.partIndex} detail="high"`;
+      const { text: expanded2 } = truncateByTokens(part.fullText, expandedLimit, hint);
+      const expandedDelta = tokenx.estimateTokenCount(expanded2) - currentTokens;
+      parts[index] = { ...part, text: expanded2 };
+      remaining -= expandedDelta;
+    }
+  }
+  const expanded = buildRenderedText(parts, timestamps);
+  const expandedTokens = tokenx.estimateTokenCount(expanded);
+  if (expandedTokens <= options.maxTokens) {
+    return { text: expanded, truncated: false, tokenOffset: 0 };
+  }
+  const hardTruncated = chunkLVV2RT42_cjs.truncateStringByTokens(expanded, options.maxTokens);
+  return { text: hardTruncated, truncated: true, tokenOffset: expandedTokens - options.maxTokens };
+}
+async function recallPart({
+  memory,
+  threadId,
+  cursor,
+  partIndex,
+  maxTokens = DEFAULT_MAX_RESULT_TOKENS
+}) {
+  if (!memory || typeof memory.getMemoryStore !== "function") {
+    throw new Error("Memory instance is required for recall");
+  }
+  if (!threadId) {
+    throw new Error("Thread ID is required for recall");
+  }
+  const resolved = await resolveCursorMessage(memory, cursor);
+  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(
+      `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);
+  if (!target) {
+    throw new Error(
+      `Part index ${partIndex} not found in message ${cursor}. Available indices: ${allParts.map((p) => p.partIndex).join(", ")}`
+    );
+  }
+  const truncatedText = chunkLVV2RT42_cjs.truncateStringByTokens(target.text, maxTokens);
+  const wasTruncated = truncatedText !== target.text;
+  return {
+    text: truncatedText,
+    messageId: target.messageId,
+    partIndex: target.partIndex,
+    role: target.role,
+    type: target.type,
+    truncated: wasTruncated
+  };
+}
+async function recallMessages({
+  memory,
+  threadId,
+  resourceId,
+  cursor,
+  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 (typeof memory.getMemoryStore !== "function") {
+    throw new Error("recall requires a Memory instance with storage access");
+  }
+  const MAX_PAGE = 50;
+  const MAX_LIMIT = 20;
+  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);
+  if ("hint" in resolved) {
+    return {
+      messages: resolved.hint,
+      count: 0,
+      cursor,
+      page: normalizedPage,
+      limit: normalizedLimit,
+      detail,
+      hasNextPage: false,
+      hasPrevPage: false,
+      truncated: false,
+      tokenOffset: 0
+    };
+  }
+  const anchor = resolved;
+  if (anchor.threadId !== threadId) {
+    throw new Error("The requested cursor does not belong to the current thread");
+  }
+  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,
+    resourceId,
+    page: 0,
+    perPage: fetchCount,
+    orderBy: { field: "createdAt", direction: isForward ? "ASC" : "DESC" },
+    filter: {
+      dateRange: isForward ? {
+        start: anchor.createdAt,
+        startExclusive: true
+      } : {
+        end: anchor.createdAt,
+        endExclusive: true
+      }
+    }
+  });
+  const visibleMessages = result.messages.filter(hasVisibleParts);
+  const total = visibleMessages.length;
+  const hasMore = total > skip + normalizedLimit;
+  let messages;
+  if (isForward) {
+    messages = visibleMessages.slice(skip, skip + normalizedLimit);
+  } else {
+    const endIdx = Math.max(total - skip, 0);
+    const startIdx = Math.max(endIdx - normalizedLimit, 0);
+    messages = visibleMessages.slice(startIdx, endIdx);
+  }
+  const hasNextPage = isForward ? hasMore : pageIndex > 0;
+  const hasPrevPage = isForward ? pageIndex > 0 : hasMore;
+  const allParts = [];
+  const timestamps = /* @__PURE__ */ new Map();
+  for (const msg of messages) {
+    timestamps.set(msg.id, msg.createdAt);
+    allParts.push(...formatMessageParts(msg, detail));
+  }
+  if (detail === "high" && allParts.length > 0) {
+    const firstPart = allParts[0];
+    const sameMsgParts = allParts.filter((p) => p.messageId === firstPart.messageId);
+    const otherMsgParts = allParts.filter((p) => p.messageId !== firstPart.messageId);
+    const rendered2 = renderFormattedParts([firstPart], timestamps, { maxTokens });
+    let text4 = rendered2.text;
+    const hints = [];
+    if (sameMsgParts.length > 1) {
+      const nextPart = sameMsgParts[1];
+      hints.push(`next part: partIndex=${nextPart.partIndex} on cursor="${firstPart.messageId}"`);
+    }
+    if (otherMsgParts.length > 0) {
+      const next = otherMsgParts[0];
+      hints.push(`next message: partIndex=${next.partIndex} on cursor="${next.messageId}"`);
+    } else if (hasNextPage) {
+      hints.push(`more messages available on page ${normalizedPage + 1}`);
+    }
+    if (hints.length > 0) {
+      text4 += `
+
+High detail returns 1 part at a time. To continue: ${hints.join(", or ")}.`;
+    }
+    return {
+      messages: text4,
+      count: 1,
+      cursor,
+      page: normalizedPage,
+      limit: normalizedLimit,
+      detail,
+      hasNextPage: otherMsgParts.length > 0 || hasNextPage,
+      hasPrevPage,
+      truncated: rendered2.truncated,
+      tokenOffset: rendered2.tokenOffset
+    };
+  }
+  const rendered = renderFormattedParts(allParts, timestamps, { maxTokens });
+  return {
+    messages: rendered.text,
+    count: messages.length,
+    cursor,
+    page: normalizedPage,
+    limit: normalizedLimit,
+    detail,
+    hasNextPage,
+    hasPrevPage,
+    truncated: rendered.truncated,
+    tokenOffset: rendered.tokenOffset
+  };
+}
+var recallTool = (_memoryConfig) => {
+  return tools.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.',
+    inputSchema: zod.z.object({
+      cursor: zod.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."),
+      page: zod.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."
+      ),
+      limit: zod.z.number().int().positive().max(20).optional().describe("Maximum number of messages to return. Defaults to 20."),
+      detail: zod.z.enum(["low", "high"]).optional().describe(
+        'Detail level. "low" (default) returns truncated text and tool names. "high" returns full content with tool args/results.'
+      ),
+      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."
+      )
+    }),
+    execute: async ({
+      cursor,
+      page,
+      limit,
+      detail,
+      partIndex
+    }, context2) => {
+      const memory = context2?.memory;
+      const threadId = context2?.agent?.threadId;
+      const resourceId = context2?.agent?.resourceId;
+      if (!memory) {
+        throw new Error("Memory instance is required for recall");
+      }
+      if (!threadId) {
+        throw new Error("Thread ID is required for recall");
+      }
+      if (partIndex !== void 0 && partIndex !== null) {
+        return recallPart({
+          memory,
+          threadId,
+          cursor,
+          partIndex
+        });
+      }
+      return recallMessages({
+        memory,
+        threadId,
+        resourceId,
+        cursor,
+        page,
+        limit,
+        detail: detail ?? "low"
+      });
+    }
+  });
+};
 function deepMergeWorkingMemory(existing, update) {
   if (!update || typeof update !== "object" || Object.keys(update).length === 0) {
     return existing && typeof existing === "object" ? { ...existing } : {};
@@ -16425,15 +16845,15 @@ Notes:
   }
   listTools(config) {
     const mergedConfig = this.getMergedThreadConfig(config);
+    const tools = {};
     if (mergedConfig.workingMemory?.enabled && !mergedConfig.readOnly) {
-      return {
-        updateWorkingMemory: this.isVNextWorkingMemoryConfig(mergedConfig) ? (
-          // use the new experimental tool
-          __experimental_updateWorkingMemoryToolVNext(mergedConfig)
-        ) : updateWorkingMemoryTool(mergedConfig)
-      };
+      tools.updateWorkingMemory = this.isVNextWorkingMemoryConfig(mergedConfig) ? __experimental_updateWorkingMemoryToolVNext(mergedConfig) : updateWorkingMemoryTool(mergedConfig);
     }
-    return {};
+    const omConfig = normalizeObservationalMemoryConfig(mergedConfig.observationalMemory);
+    if (omConfig?.retrieval && (omConfig.scope ?? "thread") === "thread") {
+      tools.recall = recallTool();
+    }
+    return tools;
   }
   /**
    * Updates a list of messages and syncs the vector database for semantic recall.
@@ -17015,10 +17435,11 @@ Notes:
         "Observational memory requires @mastra/core support for request-response-id-rotation. Please bump @mastra/core to a newer version."
       );
     }
-    const { ObservationalMemory } = await import('./observational-memory-NH7VDTXM.cjs');
+    const { ObservationalMemory } = await import('./observational-memory-MJJFU26W.cjs');
     return new ObservationalMemory({
       storage: memoryStore,
       scope: omConfig.scope,
+      retrieval: omConfig.retrieval,
       shareTokenBudget: omConfig.shareTokenBudget,
       model: omConfig.model,
       observation: omConfig.observation ? {
@@ -17049,7 +17470,7 @@ Notes:
 
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunkAR52LM55_cjs.getObservationsAsOf; }
+  get: function () { return chunkLVV2RT42_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "extractWorkingMemoryContent", {
   enumerable: true,