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

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.16.0-alpha.0"
+  version: "1.16.0-alpha.2"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,120 +1,120 @@
 {
-  "version": "1.16.0-alpha.0",
+  "version": "1.16.0-alpha.2",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 669
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 684
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js"
+      "implementation": "dist/chunk-MGHUIRKN.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 6311
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 6432
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 8734
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 8868
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 5811
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 5902
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 3421
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 3443
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 2820
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 2842
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 761
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 776
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 795
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 810
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 3535
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 3557
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 3147
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 3169
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 8919
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 9054
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 3523
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 3545
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 2377
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 2399
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 3546
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 3568
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 2350
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 2372
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 730
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 745
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 3431
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 3453
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 819
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 834
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 775
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 790
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 2407
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 2429
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 752
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 767
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HB6AYAFD.js",
-      "line": 723
+      "implementation": "dist/chunk-MGHUIRKN.js",
+      "line": 738
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
@@ -161,7 +161,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-HB6AYAFD.js",
+        "chunk-MGHUIRKN.js",
         "chunk-LSJJAJAF.js"
       ]
     }

package/dist/docs/references/docs-memory-observational-memory.md

@@ -339,6 +339,7 @@ Reflection works similarly — the Reflector runs in the background when observa
 | `observation.bufferActivation` | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                  |
 | `observation.blockAfter`       | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                                                                                                                                                                   |
 | `activateAfterIdle`            | none    | Forces buffered observations and buffered reflections to activate after a period of inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like `300_000`, `"5m"`, or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
+| `activateOnProviderChange`     | `false` | Forces buffered observations and reflections to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                   |
 | `reflection.bufferActivation`  | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                   |
 | `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                            |
 
@@ -350,6 +351,7 @@ const memory = new Memory({
     observationalMemory: {
       model: 'google/gemini-2.5-flash',
       activateAfterIdle: '5m',
+      activateOnProviderChange: true,
     },
   },
 })
@@ -357,6 +359,8 @@ const memory = new Memory({
 
 With a 5-minute prompt cache TTL, this activates buffered context after 5 minutes of inactivity so the next uncached prompt uses observations and reflections instead of a larger raw message window. If you prefer, `300_000` works the same way.
 
+Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered context to activate before the new provider runs. That avoids sending a large raw window to a provider that cannot reuse the previous prompt cache.
+
 ### Disabling
 
 To disable async buffering and use synchronous observation/reflection instead:

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 var chunkCK4U3AYR_cjs = require('./chunk-CK4U3AYR.cjs');
 var chunkIDRQZVB4_cjs = require('./chunk-IDRQZVB4.cjs');
-var chunk3NECGYWZ_cjs = require('./chunk-3NECGYWZ.cjs');
+var chunkEOHXGI4J_cjs = require('./chunk-EOHXGI4J.cjs');
 var v3 = require('zod/v3');
 var zod = require('zod');
 var z4 = require('zod/v4');
@@ -42,7 +42,7 @@ function _interopNamespace(e) {
 var z4__namespace = /*#__PURE__*/_interopNamespace(z4);
 var xxhash__default = /*#__PURE__*/_interopDefault(xxhash);
 
-// ../_vendored/ai_v4/dist/chunk-GBOGIFXJ.js
+// ../_vendored/ai_v4/dist/chunk-OPIPXJLE.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -15709,7 +15709,7 @@ function formatTimestamp(date) {
 }
 function truncateByTokens(text4, maxTokens, hint) {
   if (tokenx.estimateTokenCount(text4) <= maxTokens) return { text: text4, wasTruncated: false };
-  const truncated = chunk3NECGYWZ_cjs.truncateStringByTokens(text4, maxTokens);
+  const truncated = chunkEOHXGI4J_cjs.truncateStringByTokens(text4, maxTokens);
   const suffix = hint ? ` [${hint} for more]` : "";
   return { text: truncated + suffix, wasTruncated: true };
 }
@@ -15761,11 +15761,11 @@ ${JSON.stringify(inv.args, null, 2)}`;
             });
           }
           if (inv.state === "result") {
-            const { value: resultValue } = chunk3NECGYWZ_cjs.resolveToolResultValue(
+            const { value: resultValue } = chunkEOHXGI4J_cjs.resolveToolResultValue(
               part,
               inv.result
             );
-            const resultStr = chunk3NECGYWZ_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+            const resultStr = chunkEOHXGI4J_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));
@@ -15792,7 +15792,7 @@ ${typeof rawArgs === "string" ? rawArgs : JSON.stringify(rawArgs, null, 2)}`;
         const toolName = part.toolName;
         if (toolName) {
           const rawResult = part.output ?? part.result;
-          const resultStr = chunk3NECGYWZ_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+          const resultStr = chunkEOHXGI4J_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));
@@ -15871,7 +15871,7 @@ function renderFormattedParts(parts, timestamps, options) {
   const text4 = buildRenderedText(parts, timestamps);
   let totalTokens = tokenx.estimateTokenCount(text4);
   if (totalTokens > options.maxTokens) {
-    const truncated = chunk3NECGYWZ_cjs.truncateStringByTokens(text4, options.maxTokens);
+    const truncated = chunkEOHXGI4J_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));
@@ -15904,7 +15904,7 @@ function renderFormattedParts(parts, timestamps, options) {
   if (expandedTokens <= options.maxTokens) {
     return { text: expanded, truncated: false, tokenOffset: 0 };
   }
-  const hardTruncated = chunk3NECGYWZ_cjs.truncateStringByTokens(expanded, options.maxTokens);
+  const hardTruncated = chunkEOHXGI4J_cjs.truncateStringByTokens(expanded, options.maxTokens);
   return { text: hardTruncated, truncated: true, tokenOffset: expandedTokens - options.maxTokens };
 }
 async function recallPart({
@@ -15955,7 +15955,7 @@ async function recallPart({
 
 `;
           const fallbackText = `${fallbackNote}${firstNextPart.text}`;
-          const truncatedText2 = chunk3NECGYWZ_cjs.truncateStringByTokens(fallbackText, maxTokens);
+          const truncatedText2 = chunkEOHXGI4J_cjs.truncateStringByTokens(fallbackText, maxTokens);
           const wasTruncated2 = truncatedText2 !== fallbackText;
           return {
             text: truncatedText2,
@@ -15970,7 +15970,7 @@ async function recallPart({
     }
     throw new Error(`Part index ${partIndex} not found in message ${cursor}. Available indices: ${availableIndices}`);
   }
-  const truncatedText = chunk3NECGYWZ_cjs.truncateStringByTokens(target.text, maxTokens);
+  const truncatedText = chunkEOHXGI4J_cjs.truncateStringByTokens(target.text, maxTokens);
   const wasTruncated = truncatedText !== target.text;
   return {
     text: truncatedText,
@@ -17601,7 +17601,7 @@ ${workingMemory}`;
         "Observational memory requires @mastra/core support for request-response-id-rotation. Please bump @mastra/core to a newer version."
       );
     }
-    const { ObservationalMemory: OMClass } = await import('./observational-memory-X4N2R4CA.cjs');
+    const { ObservationalMemory: OMClass } = await import('./observational-memory-FCDIQ3SX.cjs');
     const onIndexObservations = this.hasRetrievalSearch(omConfig.retrieval) ? async (observation) => {
       await this.indexObservation(observation);
     } : void 0;
@@ -17610,6 +17610,7 @@ ${workingMemory}`;
       scope: omConfig.scope,
       retrieval: omConfig.retrieval,
       activateAfterIdle: omConfig.activateAfterIdle,
+      activateOnProviderChange: omConfig.activateOnProviderChange,
       shareTokenBudget: omConfig.shareTokenBudget,
       model: omConfig.model,
       onIndexObservations,
@@ -18525,18 +18526,18 @@ Notes:
     if (!effectiveConfig) return null;
     const engine = await this.omEngine;
     if (!engine) return null;
-    const { ObservationalMemoryProcessor } = await import('./observational-memory-X4N2R4CA.cjs');
+    const { ObservationalMemoryProcessor } = await import('./observational-memory-FCDIQ3SX.cjs');
     return new ObservationalMemoryProcessor(engine, this);
   }
 };
 
 Object.defineProperty(exports, "ModelByInputTokens", {
   enumerable: true,
-  get: function () { return chunk3NECGYWZ_cjs.ModelByInputTokens; }
+  get: function () { return chunkEOHXGI4J_cjs.ModelByInputTokens; }
 });
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunk3NECGYWZ_cjs.getObservationsAsOf; }
+  get: function () { return chunkEOHXGI4J_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "extractWorkingMemoryContent", {
   enumerable: true,