@mastra/memory 1.15.1 → 1.16.0-alpha.1

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.15.1"
+  version: "1.16.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,120 +1,120 @@
 {
-  "version": "1.15.1",
+  "version": "1.16.0-alpha.1",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 666
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 669
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js"
+      "implementation": "dist/chunk-HB6AYAFD.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 6234
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 6311
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 8633
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 8734
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 5786
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 5811
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 3416
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 3421
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 2815
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 2820
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 758
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 761
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 792
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 795
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 3530
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 3535
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 3142
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 3147
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 8818
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 8919
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 3518
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 3523
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 2372
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 2377
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 3541
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 3546
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 2345
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 2350
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 727
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 730
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 3426
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 3431
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 816
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 819
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 772
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 775
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 2402
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 2407
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 749
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 752
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-7NCBGOHT.js",
-      "line": 720
+      "implementation": "dist/chunk-HB6AYAFD.js",
+      "line": 723
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
@@ -161,7 +161,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-7NCBGOHT.js",
+        "chunk-HB6AYAFD.js",
         "chunk-LSJJAJAF.js"
       ]
     }

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

@@ -333,13 +333,29 @@ Reflection works similarly — the Reflector runs in the background when observa
 
 ### Settings
 
-| Setting                        | Default | What it controls                                                                                                                                                                      |
-| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observation.bufferTokens`     | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).    |
-| `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.                  |
-| `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.                                                                                                                           |
+| Setting                        | Default | What it controls                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`     | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                     |
+| `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. |
+| `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.                                                                                                                                                                                                                                                                            |
+
+If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations or reflections first and send a smaller compressed context window.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: '5m',
+    },
+  },
+})
+```
+
+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.
 
 ### Disabling
 

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

@@ -36,6 +36,8 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **scope** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
 
+**activateAfterIdle** (`number | string`): Time before buffered observations or buffered reflections are forced to activate after inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like \`300\_000\`, \`"5m"\`, or \`"1hr"\`. When the gap between the current time and the last assistant message part timestamp exceeds this value, buffered observational memory activates before the next prompt. Useful for aligning with prompt cache TTLs.
+
 **shareTokenBudget** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
 
 **retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): \*\*Experimental.\*\* Enable retrieval-mode observation groups as durable pointers to raw message history. \`true\` enables cross-thread browsing by default. \`{ vector: true }\` also enables semantic search using Memory's vector store and embedder. \`{ scope: 'thread' }\` restricts the recall tool to the current thread only. Default scope is \`'resource'\`. (Default: `false`)

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 var chunkCK4U3AYR_cjs = require('./chunk-CK4U3AYR.cjs');
 var chunkIDRQZVB4_cjs = require('./chunk-IDRQZVB4.cjs');
-var chunk3TU4GGH3_cjs = require('./chunk-3TU4GGH3.cjs');
+var chunk3NECGYWZ_cjs = require('./chunk-3NECGYWZ.cjs');
 var v3 = require('zod/v3');
 var zod = require('zod');
 var z4 = require('zod/v4');
@@ -15709,7 +15709,7 @@ function formatTimestamp(date) {
 }
 function truncateByTokens(text4, maxTokens, hint) {
   if (tokenx.estimateTokenCount(text4) <= maxTokens) return { text: text4, wasTruncated: false };
-  const truncated = chunk3TU4GGH3_cjs.truncateStringByTokens(text4, maxTokens);
+  const truncated = chunk3NECGYWZ_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 } = chunk3TU4GGH3_cjs.resolveToolResultValue(
+            const { value: resultValue } = chunk3NECGYWZ_cjs.resolveToolResultValue(
               part,
               inv.result
             );
-            const resultStr = chunk3TU4GGH3_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+            const resultStr = chunk3NECGYWZ_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 = chunk3TU4GGH3_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+          const resultStr = chunk3NECGYWZ_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 = chunk3TU4GGH3_cjs.truncateStringByTokens(text4, options.maxTokens);
+    const truncated = chunk3NECGYWZ_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 = chunk3TU4GGH3_cjs.truncateStringByTokens(expanded, options.maxTokens);
+  const hardTruncated = chunk3NECGYWZ_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 = chunk3TU4GGH3_cjs.truncateStringByTokens(fallbackText, maxTokens);
+          const truncatedText2 = chunk3NECGYWZ_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 = chunk3TU4GGH3_cjs.truncateStringByTokens(target.text, maxTokens);
+  const truncatedText = chunk3NECGYWZ_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-GH6IRH6E.cjs');
+    const { ObservationalMemory: OMClass } = await import('./observational-memory-X4N2R4CA.cjs');
     const onIndexObservations = this.hasRetrievalSearch(omConfig.retrieval) ? async (observation) => {
       await this.indexObservation(observation);
     } : void 0;
@@ -17609,6 +17609,7 @@ ${workingMemory}`;
       storage: memoryStore,
       scope: omConfig.scope,
       retrieval: omConfig.retrieval,
+      activateAfterIdle: omConfig.activateAfterIdle,
       shareTokenBudget: omConfig.shareTokenBudget,
       model: omConfig.model,
       onIndexObservations,
@@ -18524,18 +18525,18 @@ Notes:
     if (!effectiveConfig) return null;
     const engine = await this.omEngine;
     if (!engine) return null;
-    const { ObservationalMemoryProcessor } = await import('./observational-memory-GH6IRH6E.cjs');
+    const { ObservationalMemoryProcessor } = await import('./observational-memory-X4N2R4CA.cjs');
     return new ObservationalMemoryProcessor(engine, this);
   }
 };
 
 Object.defineProperty(exports, "ModelByInputTokens", {
   enumerable: true,
-  get: function () { return chunk3TU4GGH3_cjs.ModelByInputTokens; }
+  get: function () { return chunk3NECGYWZ_cjs.ModelByInputTokens; }
 });
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunk3TU4GGH3_cjs.getObservationsAsOf; }
+  get: function () { return chunk3NECGYWZ_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "extractWorkingMemoryContent", {
   enumerable: true,