@mastra/memory 1.18.2 → 1.19.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @mastra/memory
 
+## 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
+
+- 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().
+
 ## 1.18.2
 
 ### Patch Changes

package/dist/{chunk-4AQHFADP.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;
@@ -2447,7 +2488,12 @@ var ObservationTurn = class {
     return this._currentStep;
   }
   /**
-   * Finalize the turn: save any remaining messages and return the latest record state.
+   * Finalize the turn: save any remaining messages and return the current cached record.
+   *
+   * When async observation buffering is enabled and there are unobserved messages,
+   * a background buffer operation is kicked off so that observations are computed
+   * proactively while the agent is idle, rather than waiting for the next turn.
+   * The returned record does not wait for that background buffering pass to finish.
    */
   async end() {
     if (this._ended) throw new Error("Turn already ended");
@@ -2458,6 +2504,24 @@ var ObservationTurn = class {
     if (unsavedMessages.length > 0) {
       await this.om.persistMessages(unsavedMessages, this.threadId, this.resourceId);
     }
+    if (this.om.buffering.isAsyncObservationEnabled()) {
+      const allMessages = this.messageList.get.all.db();
+      const record = this._record;
+      const unobservedMessages = this.om.getUnobservedMessages(allMessages, record);
+      if (unobservedMessages.length > 0) {
+        void this.om.buffer({
+          threadId: this.threadId,
+          resourceId: this.resourceId,
+          messages: unobservedMessages,
+          record,
+          writer: this.writer,
+          requestContext: this.requestContext,
+          observabilityContext: this.observabilityContext
+        }).catch((err) => {
+          omDebug(`[OM:turn.end] idle buffer failed: ${err?.message}`);
+        });
+      }
+    }
     return { record: this._record };
   }
   /**
@@ -3129,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 {
@@ -3227,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 };
@@ -3301,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);
@@ -3338,7 +3436,8 @@ function formatObserverMessage(msg, counter, options) {
           );
           const { resultWithoutAttachments, attachments: extractedAttachments } = extractToolResultAttachments(
             resultForObserver,
-            counter
+            counter,
+            attachmentFilter
           );
           if (extractedAttachments.length > 0) {
             attachments.push(...extractedAttachments);
@@ -3367,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",
@@ -3957,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
   });
@@ -4034,7 +4133,9 @@ var ObserverRunner = class {
           includeThreadTitle: this.observationConfig.threadTitle
         })
       },
-      buildObserverHistoryMessage(messagesToObserve)
+      buildObserverHistoryMessage(messagesToObserve, {
+        attachmentFilter: this.observationConfig.observeAttachments
+      })
     ];
     const doGenerate = async () => {
       return withRetry(
@@ -4131,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) {
@@ -4962,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(() => {
       });
@@ -5025,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);
@@ -5038,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
@@ -6878,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".`);
@@ -7050,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,
@@ -8973,6 +9084,7 @@ ${grouped}` : grouped;
     }
     let activationTriggeredBy = "threshold";
     let activationLastActivityAt;
+    let activationActivateAfterIdle;
     let activateAfterIdleExpiredMs;
     let previousModel;
     let currentModel;
@@ -8982,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;
@@ -8996,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 });
@@ -9064,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(() => {
         });
@@ -9523,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();
@@ -9737,5 +9853,5 @@ exports.stripEphemeralAnchorIds = stripEphemeralAnchorIds;
 exports.stripObservationGroups = stripObservationGroups;
 exports.truncateStringByTokens = truncateStringByTokens;
 exports.wrapInObservationGroup = wrapInObservationGroup;
-//# sourceMappingURL=chunk-4AQHFADP.cjs.map
-//# sourceMappingURL=chunk-4AQHFADP.cjs.map
+//# sourceMappingURL=chunk-5IJQOXJM.cjs.map
+//# sourceMappingURL=chunk-5IJQOXJM.cjs.map