@mastra/memory 1.16.0-alpha.0 → 1.16.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @mastra/memory
 
+## 1.16.0-alpha.2
+
+### Minor Changes
+
+- Added `activateOnProviderChange` so observational memory can activate buffered observations and reflections before switching to a different provider or model. ([#15420](https://github.com/mastra-ai/mastra/pull/15420))
+
+  ```ts
+  const memory = new Memory({
+    options: {
+      observationalMemory: {
+        model: 'google/gemini-2.5-flash',
+        activateOnProviderChange: true,
+      },
+    },
+  });
+  ```
+
+  This helps keep prompt-cache savings when the next step cannot reuse the previous provider's cache.
+
+### Patch Changes
+
+- Fixed early observational memory activations so buffered reflections are only activated when they still leave a healthy active observation set. ([#15462](https://github.com/mastra-ai/mastra/pull/15462))
+
+  Before this change, idle-timeout (`activateAfterIdle`) and model/provider-change (`activateOnProviderChange`) activations could swap in a buffered reflection too early. In bad cases, that replaced a large raw observation tail with a much smaller mostly-compressed result, which hurt reflection quality.
+
+  Early activations now stay buffered unless both of these checks pass:
+  - The unreflected observation tail is at least as large as the buffered reflection, so the activated result is not dominated by compressed content.
+  - The combined post-activation size is at least 75% of what a normal threshold activation would produce, so early activations do not cliff far below the regular target.
+
+  This update also fixes false `provider_change` activations when older persisted messages only contain a bare model id like `gpt-5.4` while newer turns use the fully qualified `provider/modelId` form.
+
+- Updated dependencies [[`0474c2b`](https://github.com/mastra-ai/mastra/commit/0474c2b2e7c7e1ad8691dca031284841391ff1ef), [`f607106`](https://github.com/mastra-ai/mastra/commit/f607106854c6416c4a07d4082604b9f66d047221), [`62919a6`](https://github.com/mastra-ai/mastra/commit/62919a6ee0fbf3779ad21a97b1ec6696515d5104), [`0fd90a2`](https://github.com/mastra-ai/mastra/commit/0fd90a215caf5fca8099c15a67ca03e4427747a3)]:
+  - @mastra/core@1.26.0-alpha.4
+
+## 1.16.0-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [[`fdd54cf`](https://github.com/mastra-ai/mastra/commit/fdd54cf612a9af876e9fdd85e534454f6e7dd518), [`7db42a9`](https://github.com/mastra-ai/mastra/commit/7db42a9cccd3b29c44fb0731f792c51575e8421c), [`30456b6`](https://github.com/mastra-ai/mastra/commit/30456b6b08c8fd17e109dd093b73d93b65e83bc5), [`9d11a8c`](https://github.com/mastra-ai/mastra/commit/9d11a8c1c8924eb975a245a5884d40ca1b7e0491), [`d246696`](https://github.com/mastra-ai/mastra/commit/d246696139a3144a5b21b042d41c532688e957e1), [`354f9ce`](https://github.com/mastra-ai/mastra/commit/354f9ce1ca6af2074b6a196a23f8ec30012dccca), [`e9837b5`](https://github.com/mastra-ai/mastra/commit/e9837b53699e18711b09e0ca010a4106376f2653)]:
+  - @mastra/core@1.26.0-alpha.3
+  - @mastra/schema-compat@1.2.9-alpha.1
+
 ## 1.16.0-alpha.0
 
 ### Minor Changes

package/dist/{chunk-3NECGYWZ.cjs → chunk-EOHXGI4J.cjs}

@@ -208,6 +208,19 @@ var BufferingCoordinator = class _BufferingCoordinator {
   }
 };
 
+// src/processors/observational-memory/model-context.ts
+function didProviderChange(actorModel, lastModel) {
+  if (actorModel === void 0 || lastModel === void 0) return false;
+  const actorHasSlash = actorModel.includes("/");
+  const lastHasSlash = lastModel.includes("/");
+  if (actorHasSlash && lastHasSlash) {
+    return actorModel !== lastModel;
+  }
+  const actorModelId = actorHasSlash ? actorModel.slice(actorModel.indexOf("/") + 1) : actorModel;
+  const lastModelId = lastHasSlash ? lastModel.slice(lastModel.indexOf("/") + 1) : lastModel;
+  return actorModelId !== lastModelId;
+}
+
 // src/processors/observational-memory/date-utils.ts
 function formatRelativeTime(date, currentDate) {
   const diffMs = currentDate.getTime() - date.getTime();
@@ -494,7 +507,9 @@ function createActivationMarker(params) {
       observations: params.observations,
       triggeredBy: params.triggeredBy,
       lastActivityAt: params.lastActivityAt,
-      ttlExpiredMs: params.ttlExpiredMs
+      ttlExpiredMs: params.ttlExpiredMs,
+      previousModel: params.previousModel,
+      currentModel: params.currentModel
     }
   };
 }
@@ -1989,6 +2004,7 @@ var ObservationStep = class {
         resourceId,
         checkThreshold: true,
         messages: step0Messages,
+        currentModel: this.turn.actorModelContext,
         writer: this.turn.writer,
         messageList
       });
@@ -2012,6 +2028,8 @@ var ObservationStep = class {
         observationTokens: obsTokens,
         threadId,
         writer: this.turn.writer,
+        messageList,
+        currentModel: this.turn.actorModelContext,
         requestContext: this.turn.requestContext,
         observabilityContext: this.turn.observabilityContext,
         lastActivityAt: getLastActivityFromMessages(messageList.get.all.db())
@@ -2178,6 +2196,7 @@ var ObservationStep = class {
         threadId,
         resourceId,
         messages: messageList.get.all.db(),
+        currentModel: this.turn.actorModelContext,
         writer: this.turn.writer,
         messageList
       });
@@ -2189,6 +2208,7 @@ var ObservationStep = class {
           threadId,
           writer: this.turn.writer,
           messageList,
+          currentModel: this.turn.actorModelContext,
           requestContext: this.turn.requestContext,
           observabilityContext: this.turn.observabilityContext,
           lastActivityAt: getLastActivityFromMessages(messageList.get.all.db())
@@ -2233,6 +2253,8 @@ var ObservationTurn = class {
   requestContext;
   /** Optional observability context for nested OM spans. */
   observabilityContext;
+  /** Current actor model for this step. Updated by the processor before prepare(). */
+  actorModelContext;
   /** Optional processor-provided hooks for turn/step lifecycle integration. */
   hooks;
   constructor(opts) {
@@ -4101,12 +4123,44 @@ function validateCompression(reflectedTokens, targetThreshold) {
 }
 
 // src/processors/observational-memory/reflector-runner.ts
+function formatModelContext(provider, modelId) {
+  if (provider && modelId) {
+    return `${provider}/${modelId}`;
+  }
+  return modelId;
+}
+function getCurrentModel(model) {
+  return formatModelContext(model?.provider, model?.modelId);
+}
+function getLastModelFromMessageList(messageList) {
+  const messages = messageList?.get.all.db();
+  if (!messages) return void 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (!message || message.role !== "assistant" || !message.content || typeof message.content === "string") {
+      continue;
+    }
+    for (let j = message.content.parts.length - 1; j >= 0; j--) {
+      const part = message.content.parts[j];
+      if (part?.type === "step-start" && typeof part.model === "string" && part.model.length > 0) {
+        return part.model;
+      }
+    }
+    const metadata = message.content.metadata;
+    const model = formatModelContext(metadata?.provider, metadata?.modelId);
+    if (model) {
+      return model;
+    }
+  }
+  return void 0;
+}
 async function withAbortCheck(fn, abortSignal) {
   if (abortSignal?.aborted) throw new Error("The operation was aborted.");
   const result = await fn();
   if (abortSignal?.aborted) throw new Error("The operation was aborted.");
   return result;
 }
+var EARLY_ACTIVATION_SIZE_FLOOR_RATIO = 0.75;
 var ReflectorRunner = class {
   reflectionConfig;
   observationConfig;
@@ -4431,7 +4485,9 @@ var ReflectorRunner = class {
   }
   /**
    * Try to activate buffered reflection when threshold is reached.
-   * Returns true if activation succeeded.
+   * Returns a discriminated result so the caller can distinguish between
+   * "activated", "no buffer present", and "suppressed by overshoot guard"
+   * without re-deriving that state.
    */
   async tryActivateBufferedReflection(record, lockKey, writer, messageList, activationMetadata) {
     const bufferKey = this.buffering.getReflectionBufferKey(lockKey);
@@ -4454,8 +4510,8 @@ var ReflectorRunner = class {
       `[OM:reflect] tryActivateBufferedReflection: freshRecord.id=${freshRecord?.id}, freshBufferedReflection=${freshRecord?.bufferedReflection ? "present (" + freshRecord.bufferedReflection.length + " chars)" : "empty"}, freshObsTokens=${freshRecord?.observationTokenCount}`
     );
     if (!freshRecord?.bufferedReflection) {
-      omDebug(`[OM:reflect] tryActivateBufferedReflection: no buffered reflection after re-fetch, returning false`);
-      return false;
+      omDebug(`[OM:reflect] tryActivateBufferedReflection: no buffered reflection after re-fetch`);
+      return { status: "no-buffer" };
     }
     const beforeTokens = freshRecord.observationTokenCount ?? 0;
     const reflectedLineCount = freshRecord.reflectedObservationLineCount ?? 0;
@@ -4467,6 +4523,26 @@ var ReflectorRunner = class {
 
 ${unreflectedContent}` : freshRecord.bufferedReflection;
     const combinedTokenCount = this.tokenCounter.countObservations(combinedObservations);
+    if (activationMetadata?.triggeredBy === "ttl" || activationMetadata?.triggeredBy === "provider_change") {
+      const unreflectedTailTokens = unreflectedContent ? this.tokenCounter.countObservations(unreflectedContent) : 0;
+      const bufferedReflectionTokens = freshRecord.bufferedReflectionTokens ?? 0;
+      if (unreflectedTailTokens < bufferedReflectionTokens) {
+        omDebug(
+          `[OM:reflect] tryActivateBufferedReflection: suppressing early ${activationMetadata.triggeredBy} activation \u2014 unreflectedTailTokens=${unreflectedTailTokens} < bufferedReflectionTokens=${bufferedReflectionTokens}; keeping buffer for threshold activation`
+        );
+        return { status: "suppressed", reason: "composition" };
+      }
+      const bufferActivation = this.reflectionConfig.bufferActivation;
+      const reflectThreshold = getMaxThreshold(this.getEffectiveReflectionTokens(freshRecord));
+      const regularActivationTarget = reflectThreshold * (1 - bufferActivation);
+      const minCombinedTokens = Math.round(regularActivationTarget * EARLY_ACTIVATION_SIZE_FLOOR_RATIO);
+      if (combinedTokenCount < minCombinedTokens) {
+        omDebug(
+          `[OM:reflect] tryActivateBufferedReflection: suppressing early ${activationMetadata.triggeredBy} activation \u2014 combinedTokenCount=${combinedTokenCount} < minCombinedTokens=${minCombinedTokens} (${EARLY_ACTIVATION_SIZE_FLOOR_RATIO * 100}% of regular activation target ${Math.round(regularActivationTarget)}, threshold=${reflectThreshold}, bufferActivation=${bufferActivation}); keeping buffer for threshold activation`
+        );
+        return { status: "suppressed", reason: "size" };
+      }
+    }
     omDebug(
       `[OM:reflect] tryActivateBufferedReflection: activating, beforeTokens=${beforeTokens}, combinedTokenCount=${combinedTokenCount}, reflectedLineCount=${reflectedLineCount}, unreflectedLines=${unreflectedLines.length}`
     );
@@ -4496,6 +4572,8 @@ ${unreflectedContent}` : freshRecord.bufferedReflection;
         triggeredBy: activationMetadata?.triggeredBy,
         lastActivityAt: activationMetadata?.lastActivityAt,
         ttlExpiredMs: activationMetadata?.ttlExpiredMs,
+        previousModel: activationMetadata?.previousModel,
+        currentModel: activationMetadata?.currentModel,
         config: this.getObservationMarkerConfig(freshRecord)
       });
       void writer.custom(activationMarker).catch(() => {
@@ -4508,7 +4586,7 @@ ${unreflectedContent}` : freshRecord.bufferedReflection;
       );
     }
     BufferingCoordinator.reflectionBufferCycleIds.delete(bufferKey);
-    return true;
+    return { status: "activated" };
   }
   /**
    * Check if reflection needed and trigger if so.
@@ -4522,6 +4600,7 @@ ${unreflectedContent}` : freshRecord.bufferedReflection;
       writer,
       abortSignal,
       messageList,
+      currentModel,
       reflectionHooks,
       requestContext,
       observabilityContext,
@@ -4561,13 +4640,19 @@ ${unreflectedContent}` : freshRecord.bufferedReflection;
     const activateAfterIdle = this.reflectionConfig.activateAfterIdle;
     const ttlExpiredMs = activateAfterIdle !== void 0 && lastActivityAt !== void 0 ? Date.now() - lastActivityAt : void 0;
     const ttlExpired = ttlExpiredMs !== void 0 && activateAfterIdle !== void 0 && ttlExpiredMs >= activateAfterIdle;
-    if (observationTokens < reflectThreshold && !ttlExpired) {
+    const actorModel = getCurrentModel(currentModel);
+    const lastModel = getLastModelFromMessageList(messageList);
+    const providerChanged = this.reflectionConfig.activateOnProviderChange === true && didProviderChange(actorModel, lastModel);
+    if (observationTokens < reflectThreshold && !ttlExpired && !providerChanged) {
       return;
     }
+    const activationTriggeredBy = observationTokens >= reflectThreshold ? "threshold" : providerChanged ? "provider_change" : "ttl";
     const activationMetadata = {
-      triggeredBy: ttlExpired ? "ttl" : "threshold",
-      lastActivityAt: ttlExpired ? lastActivityAt : void 0,
-      ttlExpiredMs: ttlExpired ? ttlExpiredMs : void 0
+      triggeredBy: activationTriggeredBy,
+      lastActivityAt: activationTriggeredBy === "ttl" ? lastActivityAt : void 0,
+      ttlExpiredMs: activationTriggeredBy === "ttl" ? ttlExpiredMs : void 0,
+      previousModel: activationTriggeredBy === "provider_change" ? lastModel : void 0,
+      currentModel: activationTriggeredBy === "provider_change" ? actorModel : void 0
     };
     if (record.isReflecting) {
       if (isOpActiveInProcess(record.id, "reflecting")) {
@@ -4578,14 +4663,20 @@ ${unreflectedContent}` : freshRecord.bufferedReflection;
       await this.storage.setReflectingFlag(record.id, false);
     }
     if (this.buffering.isAsyncReflectionEnabled()) {
-      const activationSuccess = await this.tryActivateBufferedReflection(
+      const activationResult = await this.tryActivateBufferedReflection(
         record,
         lockKey,
         writer,
         messageList,
         activationMetadata
       );
-      if (activationSuccess) {
+      if (activationResult.status === "activated") {
+        return;
+      }
+      if (activationResult.status === "suppressed") {
+        omDebug(
+          `[OM:reflect] skipping sync fallback / re-buffer after suppressed early ${activationMetadata.triggeredBy} activation (reason=${activationResult.reason})`
+        );
         return;
       }
       if (this.reflectionConfig.blockAfter && observationTokens >= this.reflectionConfig.blockAfter) {
@@ -6286,6 +6377,36 @@ function getLastActivityFromMessages(messages) {
   }
   return void 0;
 }
+function formatModelContext2(provider, modelId) {
+  if (provider && modelId) {
+    return `${provider}/${modelId}`;
+  }
+  return modelId;
+}
+function getLastModelFromMessages(messages) {
+  if (!messages) return void 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (!message || message.role !== "assistant" || !message.content || typeof message.content === "string") {
+      continue;
+    }
+    for (let j = message.content.parts.length - 1; j >= 0; j--) {
+      const part = message.content.parts[j];
+      if (part?.type === "step-start" && typeof part.model === "string" && part.model.length > 0) {
+        return part.model;
+      }
+    }
+    const metadata = message.content.metadata;
+    const model = formatModelContext2(metadata?.provider, metadata?.modelId);
+    if (model) {
+      return model;
+    }
+  }
+  return void 0;
+}
+function getCurrentModel2(model) {
+  return formatModelContext2(model?.provider, model?.modelId);
+}
 function parseActivationTTL(value, fieldPath) {
   if (value === void 0) {
     return void 0;
@@ -6462,6 +6583,7 @@ Async buffering is enabled by default \u2014 this opt-out is only needed when us
       ),
       bufferActivation: asyncBufferingDisabled ? void 0 : config.observation?.bufferActivation ?? chunkD4J4XPGM_cjs.OBSERVATIONAL_MEMORY_DEFAULTS.observation.bufferActivation,
       activateAfterIdle: parseActivationTTL(config.activateAfterIdle, "activateAfterIdle"),
+      activateOnProviderChange: config.activateOnProviderChange ?? false,
       blockAfter: asyncBufferingDisabled ? void 0 : resolveBlockAfter(
         config.observation?.blockAfter ?? (config.observation?.bufferTokens ?? chunkD4J4XPGM_cjs.OBSERVATIONAL_MEMORY_DEFAULTS.observation.bufferTokens ? 1.2 : void 0),
         config.observation?.messageTokens ?? chunkD4J4XPGM_cjs.OBSERVATIONAL_MEMORY_DEFAULTS.observation.messageTokens
@@ -6481,6 +6603,7 @@ Async buffering is enabled by default \u2014 this opt-out is only needed when us
       providerOptions: config.reflection?.providerOptions ?? chunkD4J4XPGM_cjs.OBSERVATIONAL_MEMORY_DEFAULTS.reflection.providerOptions,
       bufferActivation: asyncBufferingDisabled ? void 0 : config?.reflection?.bufferActivation ?? chunkD4J4XPGM_cjs.OBSERVATIONAL_MEMORY_DEFAULTS.reflection.bufferActivation,
       activateAfterIdle: parseActivationTTL(config.activateAfterIdle, "activateAfterIdle"),
+      activateOnProviderChange: config.activateOnProviderChange ?? false,
       blockAfter: asyncBufferingDisabled ? void 0 : resolveBlockAfter(
         config.reflection?.blockAfter ?? (config.reflection?.bufferActivation ?? chunkD4J4XPGM_cjs.OBSERVATIONAL_MEMORY_DEFAULTS.reflection.bufferActivation ? 1.2 : void 0),
         config.reflection?.observationTokens ?? chunkD4J4XPGM_cjs.OBSERVATIONAL_MEMORY_DEFAULTS.reflection.observationTokens
@@ -8377,6 +8500,8 @@ ${grouped}` : grouped;
     let activationTriggeredBy = "threshold";
     let activationLastActivityAt;
     let activateAfterIdleExpiredMs;
+    let previousModel;
+    let currentModel;
     if (opts.checkThreshold) {
       const thresholdMessages = opts.messages ?? await this.loadMessagesFromStorage(
         threadId,
@@ -8387,7 +8512,14 @@ ${grouped}` : grouped;
       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;
-      if (ttlExpired) {
+      const actorModel = getCurrentModel2(opts.currentModel);
+      const lastModel = getLastModelFromMessages(thresholdMessages);
+      const providerChanged = this.observationConfig.activateOnProviderChange === true && didProviderChange(actorModel, lastModel);
+      if (providerChanged) {
+        activationTriggeredBy = "provider_change";
+        previousModel = lastModel;
+        currentModel = actorModel;
+      } else if (ttlExpired) {
         activationTriggeredBy = "ttl";
         activationLastActivityAt = lastActivityAt;
         activateAfterIdleExpiredMs = ttlExpiredMs;
@@ -8456,6 +8588,8 @@ ${grouped}` : grouped;
           triggeredBy: activationTriggeredBy,
           lastActivityAt: activationLastActivityAt,
           ttlExpiredMs: activateAfterIdleExpiredMs,
+          previousModel,
+          currentModel,
           config: this.getObservationMarkerConfig()
         });
         void opts.writer.custom(activationMarker).catch(() => {
@@ -8813,6 +8947,7 @@ var ObservationalMemoryProcessor = class {
       const observabilityContext = getOmObservabilityContext(args);
       state.__omObservabilityContext = observabilityContext;
       this.turn.observabilityContext = observabilityContext;
+      this.turn.actorModelContext = actorModelContext;
       {
         const step = this.turn.step(stepNumber);
         let ctx;
@@ -8971,5 +9106,5 @@ exports.stripEphemeralAnchorIds = stripEphemeralAnchorIds;
 exports.stripObservationGroups = stripObservationGroups;
 exports.truncateStringByTokens = truncateStringByTokens;
 exports.wrapInObservationGroup = wrapInObservationGroup;
-//# sourceMappingURL=chunk-3NECGYWZ.cjs.map
-//# sourceMappingURL=chunk-3NECGYWZ.cjs.map
+//# sourceMappingURL=chunk-EOHXGI4J.cjs.map
+//# sourceMappingURL=chunk-EOHXGI4J.cjs.map