@mastra/memory 1.18.3-alpha.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # @mastra/memory
 
+## 1.19.0
+
+### Minor Changes
+
+- Added `activateAfterIdle: "auto"` for Observational Memory early activation. ([#16663](https://github.com/mastra-ai/mastra/pull/16663))
+
+  Mastra can now choose an idle activation timeout from the active model provider's prompt cache behavior. OpenAI also respects `providerOptions.openai.promptCacheRetention` when available.
+
+  ```ts
+  const memory = new Memory({
+    options: {
+      observationalMemory: {
+        model: 'google/gemini-2.5-flash',
+        activateAfterIdle: 'auto',
+        activateOnProviderChange: true,
+      },
+    },
+  });
+  ```
+
+- Add `observeAttachments` to `ObservationConfig` for Observational Memory. Use it to control whether image/file parts on observed messages are forwarded to the Observer model alongside their placeholder text lines. ([#16671](https://github.com/mastra-ai/mastra/pull/16671))
+  - `true` (default) — forward all attachments (existing behavior).
+  - `false` — drop all attachments; placeholders still appear in the observer transcript.
+  - `string[]` — allowlist of mimeType patterns, e.g. `['image/*']` or `['application/pdf']`. Matching is case-insensitive and supports exact, `type/*`, and `*` patterns.
+
+  Useful when the Observer model is text-only (some DeepSeek endpoints, etc.) while the main agent uses a multimodal model. Tool-result attachments are filtered with the same rule.
+
+  ```ts
+  new Memory({
+    options: {
+      observationalMemory: {
+        observation: {
+          model: 'deepseek/deepseek-chat', // text-only observer
+          observeAttachments: false, // or e.g. ['image/*', 'application/pdf']
+        },
+      },
+    },
+  });
+  ```
+
+### Patch Changes
+
+- feat(memory): start background buffering of unobserved messages when agent goes idle ([#16694](https://github.com/mastra-ai/mastra/pull/16694))
+
+  In OM buffering mode, when the agent goes idle (turn.end()), any unobserved messages are now buffered in the background via a fire-and-forget buffer() call. This ensures observations are computed proactively rather than waiting for the next turn's step.prepare().
+
+- Updated dependencies [[`452036a`](https://github.com/mastra-ai/mastra/commit/452036a0d965b4f4c1efd93606e4f03b50b807a5), [`c272d50`](https://github.com/mastra-ai/mastra/commit/c272d50610a54496b6b6d92ccd4d37b333a2613a), [`27fd1b7`](https://github.com/mastra-ai/mastra/commit/27fd1b79ac62eb7694f92587eb7d1be05b59be01), [`5ba7253`](https://github.com/mastra-ai/mastra/commit/5ba7253745c85e8df8012a76d954c640ffa336f7), [`5556cc1`](https://github.com/mastra-ai/mastra/commit/5556cc1befec71518d84f826b3bfe3a079a9daf7), [`f73980d`](https://github.com/mastra-ai/mastra/commit/f73980d651eb5f7f1ab20582de4615a1b6f10fce), [`5499303`](https://github.com/mastra-ai/mastra/commit/54993032c1ebc09642625b78d2014e0cf84a3cae), [`a702009`](https://github.com/mastra-ai/mastra/commit/a702009d3cfaa745120f501e21c783ed4d6a3072), [`9aee493`](https://github.com/mastra-ai/mastra/commit/9aee493ed6089b5133472623dcce49934bf2d509), [`d8692af`](https://github.com/mastra-ai/mastra/commit/d8692afa253028e39cdce2aafa0ac414071a762e), [`1a9cc60`](https://github.com/mastra-ai/mastra/commit/1a9cc6069f9910fc3d59e4953ac8cd95d89ad6f5), [`8cdb86c`](https://github.com/mastra-ai/mastra/commit/8cdb86ceed1137bc2768e147dce85a0692b9fb26), [`8534d79`](https://github.com/mastra-ai/mastra/commit/8534d791fa1cb70fe1c19e2604c4b63cc10dd051), [`eda90c5`](https://github.com/mastra-ai/mastra/commit/eda90c5bfd7de11805ecc9f4552716c895fbaf78), [`a935b0a`](https://github.com/mastra-ai/mastra/commit/a935b0a0977ae3f196b33ec7621f528069c82db0), [`9c88701`](https://github.com/mastra-ai/mastra/commit/9c8870195b41a38dc40b6ba2aa55eda04df8fa69), [`c78f8cd`](https://github.com/mastra-ai/mastra/commit/c78f8cd6222a86e6c60ae5210b6929ad5221b6fb), [`e146aad`](https://github.com/mastra-ai/mastra/commit/e146aadbba66c410ba0e74bac4c50135495cb8dd), [`ac79462`](https://github.com/mastra-ai/mastra/commit/ac79462b98f1062394c45093aa515b0766f27ee2), [`1a0ec78`](https://github.com/mastra-ai/mastra/commit/1a0ec789a26cae443744e9abbd62ed6ee676af39), [`e47bca7`](https://github.com/mastra-ai/mastra/commit/e47bca7b72866d3abd173b9f530ac4318113a8ff), [`afc004f`](https://github.com/mastra-ai/mastra/commit/afc004f5cc7e30697809e7021820b9f5881e6719), [`0031d0f`](https://github.com/mastra-ai/mastra/commit/0031d0f13831d7843ac5d498734a7d92862e2ce3), [`841a222`](https://github.com/mastra-ai/mastra/commit/841a222560d8c19238f8213713f30535cdd82284), [`64c1e0b`](https://github.com/mastra-ai/mastra/commit/64c1e0b35165c96b659818bd0177aa18794ef11f), [`40d83a9`](https://github.com/mastra-ai/mastra/commit/40d83a90d9be31a1b83e04649edb703eb7753e33), [`4e88dc6`](https://github.com/mastra-ai/mastra/commit/4e88dc6b89f154c0eae37221c8126be0c23c569f), [`19018f0`](https://github.com/mastra-ai/mastra/commit/19018f05722af74a5978781a7731a654b26f7f2a), [`19281c7`](https://github.com/mastra-ai/mastra/commit/19281c70424f757219782de16c2699743c5e04d0), [`3498b49`](https://github.com/mastra-ai/mastra/commit/3498b4946be94f4313cd817733589680dcda5278), [`d52b6fe`](https://github.com/mastra-ai/mastra/commit/d52b6fe1c56853eb38864baae0bbfa75cc739ccb), [`408be73`](https://github.com/mastra-ai/mastra/commit/408be73449dfab92b51eab8c6623b6c443debc25), [`359439b`](https://github.com/mastra-ai/mastra/commit/359439bb8c635e048176306828195f8297f50021), [`71a820b`](https://github.com/mastra-ai/mastra/commit/71a820b2353fa1406772c50760a3732058a8b337), [`1698f5e`](https://github.com/mastra-ai/mastra/commit/1698f5ec141d34f22a873efdb145ce3cdf848a5e)]:
+  - @mastra/core@1.36.0
+
+## 1.19.0-alpha.1
+
+### Minor Changes
+
+- Added `activateAfterIdle: "auto"` for Observational Memory early activation. ([#16663](https://github.com/mastra-ai/mastra/pull/16663))
+
+  Mastra can now choose an idle activation timeout from the active model provider's prompt cache behavior. OpenAI also respects `providerOptions.openai.promptCacheRetention` when available.
+
+  ```ts
+  const memory = new Memory({
+    options: {
+      observationalMemory: {
+        model: 'google/gemini-2.5-flash',
+        activateAfterIdle: 'auto',
+        activateOnProviderChange: true,
+      },
+    },
+  });
+  ```
+
+- Add `observeAttachments` to `ObservationConfig` for Observational Memory. Use it to control whether image/file parts on observed messages are forwarded to the Observer model alongside their placeholder text lines. ([#16671](https://github.com/mastra-ai/mastra/pull/16671))
+  - `true` (default) — forward all attachments (existing behavior).
+  - `false` — drop all attachments; placeholders still appear in the observer transcript.
+  - `string[]` — allowlist of mimeType patterns, e.g. `['image/*']` or `['application/pdf']`. Matching is case-insensitive and supports exact, `type/*`, and `*` patterns.
+
+  Useful when the Observer model is text-only (some DeepSeek endpoints, etc.) while the main agent uses a multimodal model. Tool-result attachments are filtered with the same rule.
+
+  ```ts
+  new Memory({
+    options: {
+      observationalMemory: {
+        observation: {
+          model: 'deepseek/deepseek-chat', // text-only observer
+          observeAttachments: false, // or e.g. ['image/*', 'application/pdf']
+        },
+      },
+    },
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`c272d50`](https://github.com/mastra-ai/mastra/commit/c272d50610a54496b6b6d92ccd4d37b333a2613a), [`d8692af`](https://github.com/mastra-ai/mastra/commit/d8692afa253028e39cdce2aafa0ac414071a762e), [`841a222`](https://github.com/mastra-ai/mastra/commit/841a222560d8c19238f8213713f30535cdd82284)]:
+  - @mastra/core@1.36.0-alpha.4
+
 ## 1.18.3-alpha.0
 
 ### Patch Changes

package/dist/{chunk-BK3AYI7X.cjs → chunk-5IJQOXJM.cjs}

@@ -21,6 +21,47 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 var xxhash__default = /*#__PURE__*/_interopDefault(xxhash);
 var imageSize__default = /*#__PURE__*/_interopDefault(imageSize);
 
+// src/processors/observational-memory/activation-ttl.ts
+var MINUTE = 6e4;
+var HOUR = 60 * MINUTE;
+var SHORT_TTL = 5 * MINUTE;
+var OPENAI_EXTENDED_TTL = HOUR;
+var GEMINI_TTL = 24 * HOUR;
+var DEEPSEEK_TTL = HOUR;
+var GROQ_TTL = 2 * HOUR;
+function normalize(value) {
+  return value?.toLowerCase() ?? "";
+}
+function isOpenAIShortTtlModel(modelId) {
+  return /^gpt-4/.test(modelId) || /^gpt-5(?:$|-|\.([1-4])(?:$|-))/.test(modelId);
+}
+function getOpenAIPromptCacheRetention(providerOptions) {
+  const openaiOptions = providerOptions?.openai;
+  return typeof openaiOptions?.promptCacheRetention === "string" ? openaiOptions.promptCacheRetention.toLowerCase() : void 0;
+}
+function resolveActivationTTL(activateAfterIdle, modelContext) {
+  if (activateAfterIdle !== "auto") {
+    return activateAfterIdle;
+  }
+  return resolveAutoActivationTTL(modelContext);
+}
+function resolveAutoActivationTTL(modelContext) {
+  const provider = normalize(modelContext?.provider);
+  const modelId = normalize(modelContext?.modelId);
+  if (provider.includes("openai")) {
+    const promptCacheRetention = getOpenAIPromptCacheRetention(modelContext?.providerOptions);
+    if (promptCacheRetention === "24h") return OPENAI_EXTENDED_TTL;
+    if (promptCacheRetention === "in_memory") return SHORT_TTL;
+    return isOpenAIShortTtlModel(modelId) ? SHORT_TTL : OPENAI_EXTENDED_TTL;
+  }
+  if (provider.includes("google") || provider.includes("gemini")) return GEMINI_TTL;
+  if (provider.includes("deepseek")) return DEEPSEEK_TTL;
+  if (provider.includes("groq")) return GROQ_TTL;
+  if (provider.includes("anthropic")) return SHORT_TTL;
+  if (provider.includes("xai") || provider.includes("grok")) return SHORT_TTL;
+  if (provider.includes("openrouter")) return SHORT_TTL;
+  return SHORT_TTL;
+}
 var OM_DEBUG_LOG = process.env.OM_DEBUG ? path.join(process.cwd(), "om-debug.log") : null;
 function omDebug(msg) {
   if (!OM_DEBUG_LOG) return;
@@ -3152,6 +3193,35 @@ function isImageLikeObserverFilePart(part) {
   }
   return hasObserverImageFilenameExtension(part.filename);
 }
+function resolveObserverAttachmentMimeType(part) {
+  if (typeof part.mimeType === "string" && part.mimeType.length > 0) {
+    return part.mimeType.toLowerCase();
+  }
+  if (part.type === "image") {
+    return "image/*";
+  }
+  if (isImageLikeObserverFilePart(part)) {
+    return "image/*";
+  }
+  return "application/octet-stream";
+}
+function matchObserverMimePattern(mimeType, pattern) {
+  const normalized = pattern.trim().toLowerCase();
+  if (!normalized) return false;
+  if (normalized === "*" || normalized === "*/*") return true;
+  if (normalized.endsWith("/*")) {
+    const prefix = normalized.slice(0, normalized.length - 1);
+    return mimeType.startsWith(prefix);
+  }
+  return mimeType === normalized;
+}
+function shouldIncludeObserverAttachment(part, filter) {
+  if (filter === void 0 || filter === true) return true;
+  if (filter === false) return false;
+  if (!Array.isArray(filter) || filter.length === 0) return false;
+  const mimeType = resolveObserverAttachmentMimeType(part);
+  return filter.some((pattern) => matchObserverMimePattern(mimeType, pattern));
+}
 function toObserverInputAttachmentPart(part) {
   if (part.type === "image") {
     return {
@@ -3250,22 +3320,26 @@ function mapToolResultBlockToAttachment(block) {
       return void 0;
   }
 }
-function extractToolResultAttachments(result, counter) {
+function extractToolResultAttachments(result, counter, attachmentFilter) {
   if (!isRecord(result) || result.type !== "content" || !Array.isArray(result.value)) {
     return { resultWithoutAttachments: result, attachments: [] };
   }
   const record = result;
   const attachments = [];
+  let hadAttachmentBlocks = false;
   const newValue = record.value.map((block) => {
     const attachment = mapToolResultBlockToAttachment(block);
     if (!attachment) {
       return block;
     }
-    attachments.push(toObserverInputAttachmentPart(attachment));
+    hadAttachmentBlocks = true;
+    if (shouldIncludeObserverAttachment(attachment, attachmentFilter)) {
+      attachments.push(toObserverInputAttachmentPart(attachment));
+    }
     const placeholder = formatObserverAttachmentPlaceholder(attachment, counter);
     return { type: isRecord(block) ? block.type : void 0, placeholder };
   });
-  if (attachments.length === 0) {
+  if (!hadAttachmentBlocks) {
     return { resultWithoutAttachments: result, attachments };
   }
   return { resultWithoutAttachments: { ...record, value: newValue }, attachments };
@@ -3324,6 +3398,7 @@ function getTemporalGapMarkerText(msg) {
 function formatObserverMessage(msg, counter, options) {
   const maxLen = options?.maxPartLength;
   const maxToolResultTokens = options?.maxToolResultTokens ?? DEFAULT_OBSERVER_TOOL_RESULT_MAX_TOKENS;
+  const attachmentFilter = options?.attachmentFilter;
   const role = msg.role.charAt(0).toUpperCase() + msg.role.slice(1);
   const attachments = [];
   const messageCreatedAt = normalizeObserverCreatedAt(msg.createdAt);
@@ -3361,7 +3436,8 @@ function formatObserverMessage(msg, counter, options) {
           );
           const { resultWithoutAttachments, attachments: extractedAttachments } = extractToolResultAttachments(
             resultForObserver,
-            counter
+            counter,
+            attachmentFilter
           );
           if (extractedAttachments.length > 0) {
             attachments.push(...extractedAttachments);
@@ -3390,9 +3466,11 @@ function formatObserverMessage(msg, counter, options) {
       }
       if (partType === "image" || partType === "file") {
         const attachment = part;
-        const inputAttachment = toObserverInputAttachmentPart(attachment);
-        if (inputAttachment) {
-          attachments.push(inputAttachment);
+        if (shouldIncludeObserverAttachment(attachment, attachmentFilter)) {
+          const inputAttachment = toObserverInputAttachmentPart(attachment);
+          if (inputAttachment) {
+            attachments.push(inputAttachment);
+          }
         }
         pushLine(
           partType === "image" ? "Image" : "File",
@@ -3980,13 +4058,11 @@ async function withOmTracingSpan({
     entityType: observability.EntityType.OUTPUT_STEP_PROCESSOR,
     entityName: config.entityName,
     tracingContext: observabilityContext?.tracingContext ?? observabilityContext?.tracing,
-    attributes: {
-      metadata: {
-        omPhase: phase,
-        omInputTokens: inputTokens,
-        omSelectedModel: typeof model === "string" ? model : "(dynamic-model)",
-        ...metadata
-      }
+    metadata: {
+      omPhase: phase,
+      omInputTokens: inputTokens,
+      omSelectedModel: typeof model === "string" ? model : "(dynamic-model)",
+      ...metadata
     },
     requestContext
   });
@@ -4057,7 +4133,9 @@ var ObserverRunner = class {
           includeThreadTitle: this.observationConfig.threadTitle
         })
       },
-      buildObserverHistoryMessage(messagesToObserve)
+      buildObserverHistoryMessage(messagesToObserve, {
+        attachmentFilter: this.observationConfig.observeAttachments
+      })
     ];
     const doGenerate = async () => {
       return withRetry(
@@ -4154,7 +4232,9 @@ var ObserverRunner = class {
           this.observationConfig.threadTitle
         )
       },
-      buildMultiThreadObserverHistoryMessage(messagesByThread, threadOrder)
+      buildMultiThreadObserverHistoryMessage(messagesByThread, threadOrder, {
+        attachmentFilter: this.observationConfig.observeAttachments
+      })
     ];
     for (const msgs of messagesByThread.values()) {
       for (const msg of msgs) {
@@ -4985,7 +5065,10 @@ ${unreflectedContent}` : freshRecord.bufferedReflection;
         ttlExpiredMs: activationMetadata?.ttlExpiredMs,
         previousModel: activationMetadata?.previousModel,
         currentModel: activationMetadata?.currentModel,
-        config: this.getObservationMarkerConfig(freshRecord)
+        config: {
+          ...this.getObservationMarkerConfig(freshRecord),
+          activateAfterIdle: activationMetadata?.activateAfterIdle ?? this.reflectionConfig.activateAfterIdle
+        }
       });
       void writer.custom({ ...activationMarker, transient: true }).catch(() => {
       });
@@ -5048,7 +5131,7 @@ ${unreflectedContent}` : freshRecord.bufferedReflection;
         );
       }
     }
-    const activateAfterIdle = this.reflectionConfig.activateAfterIdle;
+    const activateAfterIdle = resolveActivationTTL(this.reflectionConfig.activateAfterIdle, currentModel);
     const ttlExpiredMs = activateAfterIdle !== void 0 && lastActivityAt !== void 0 ? Date.now() - lastActivityAt : void 0;
     const ttlExpired = ttlExpiredMs !== void 0 && activateAfterIdle !== void 0 && ttlExpiredMs >= activateAfterIdle;
     const actorModel = getCurrentModel(currentModel);
@@ -5061,6 +5144,7 @@ ${unreflectedContent}` : freshRecord.bufferedReflection;
     const activationMetadata = {
       triggeredBy: activationTriggeredBy,
       lastActivityAt: activationTriggeredBy === "ttl" ? lastActivityAt : void 0,
+      activateAfterIdle: activationTriggeredBy === "ttl" ? activateAfterIdle : void 0,
       ttlExpiredMs: activationTriggeredBy === "ttl" ? ttlExpiredMs : void 0,
       previousModel: activationTriggeredBy === "provider_change" ? lastModel : void 0,
       currentModel: activationTriggeredBy === "provider_change" ? actorModel : void 0
@@ -6901,6 +6985,9 @@ function parseActivationTTL(value, fieldPath) {
   if (value === void 0 || value === false) {
     return void 0;
   }
+  if (value === "auto") {
+    return value;
+  }
   if (typeof value === "number") {
     if (!Number.isFinite(value) || value < 0) {
       throw new Error(`${fieldPath} must be a non-negative number of milliseconds or a duration string like "5m".`);
@@ -7073,7 +7160,8 @@ Async buffering is enabled by default \u2014 this opt-out is only needed when us
       ),
       previousObserverTokens: config.observation?.previousObserverTokens ?? 2e3,
       instruction: config.observation?.instruction,
-      threadTitle: config.observation?.threadTitle ?? false
+      threadTitle: config.observation?.threadTitle ?? false,
+      observeAttachments: config.observation?.observeAttachments ?? true
     };
     this.reflectionConfig = {
       model: reflectionModel,
@@ -8996,6 +9084,7 @@ ${grouped}` : grouped;
     }
     let activationTriggeredBy = "threshold";
     let activationLastActivityAt;
+    let activationActivateAfterIdle;
     let activateAfterIdleExpiredMs;
     let previousModel;
     let currentModel;
@@ -9005,7 +9094,7 @@ ${grouped}` : grouped;
         resourceId,
         record.lastObservedAt ? new Date(record.lastObservedAt) : void 0
       );
-      const activateAfterIdle = this.observationConfig.activateAfterIdle;
+      const activateAfterIdle = resolveActivationTTL(this.observationConfig.activateAfterIdle, opts.currentModel);
       const lastActivityAt = getLastActivityFromMessages(thresholdMessages);
       const ttlExpiredMs = activateAfterIdle !== void 0 && lastActivityAt !== void 0 ? Date.now() - lastActivityAt : void 0;
       const ttlExpired = ttlExpiredMs !== void 0 && activateAfterIdle !== void 0 && ttlExpiredMs >= activateAfterIdle;
@@ -9019,6 +9108,7 @@ ${grouped}` : grouped;
       } else if (ttlExpired) {
         activationTriggeredBy = "ttl";
         activationLastActivityAt = lastActivityAt;
+        activationActivateAfterIdle = activateAfterIdle;
         activateAfterIdleExpiredMs = ttlExpiredMs;
       } else {
         const status = await this.getStatus({ threadId, resourceId, messages: thresholdMessages });
@@ -9087,7 +9177,10 @@ ${grouped}` : grouped;
           ttlExpiredMs: activateAfterIdleExpiredMs,
           previousModel,
           currentModel,
-          config: this.getObservationMarkerConfig()
+          config: {
+            ...this.getObservationMarkerConfig(),
+            activateAfterIdle: activationActivateAfterIdle ?? this.observationConfig.activateAfterIdle
+          }
         });
         void opts.writer.custom({ ...activationMarker, transient: true }).catch(() => {
         });
@@ -9546,7 +9639,7 @@ var ObservationalMemoryProcessor = class {
     const { threadId, resourceId } = context;
     const memoryContext = memory.parseMemoryRequestContext(requestContext);
     const readOnly = memoryContext?.memoryConfig?.readOnly;
-    const actorModelContext = model?.modelId ? { provider: model.provider, modelId: model.modelId } : void 0;
+    const actorModelContext = model?.modelId ? { provider: model.provider, modelId: model.modelId, providerOptions: args.providerOptions } : void 0;
     state.__omActorModelContext = actorModelContext;
     return this.engine.getTokenCounter().runWithModelContext(actorModelContext, async () => {
       const reproCaptureEnabled = isOmReproCaptureEnabled();
@@ -9760,5 +9853,5 @@ exports.stripEphemeralAnchorIds = stripEphemeralAnchorIds;
 exports.stripObservationGroups = stripObservationGroups;
 exports.truncateStringByTokens = truncateStringByTokens;
 exports.wrapInObservationGroup = wrapInObservationGroup;
-//# sourceMappingURL=chunk-BK3AYI7X.cjs.map
-//# sourceMappingURL=chunk-BK3AYI7X.cjs.map
+//# sourceMappingURL=chunk-5IJQOXJM.cjs.map
+//# sourceMappingURL=chunk-5IJQOXJM.cjs.map