@mastra/memory 1.16.0 → 1.17.0

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"
+  version: "1.17.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,120 +1,120 @@
 {
-  "version": "1.16.0",
+  "version": "1.17.0",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 684
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 745
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js"
+      "implementation": "dist/chunk-MPBMHIAQ.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 6432
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 6518
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 8870
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 9060
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 5902
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 5988
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 3443
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 3529
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 2842
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 2912
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 776
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 837
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 810
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 871
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 3557
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 3643
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 3169
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 3255
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 9056
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 9252
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 3545
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 3631
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 2399
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 2460
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 3568
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 3654
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 2372
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 2433
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 745
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 806
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 3453
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 3539
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 834
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 895
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 790
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 851
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 2429
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 2490
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 767
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 828
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-OOA4C7IX.js",
-      "line": 738
+      "implementation": "dist/chunk-MPBMHIAQ.js",
+      "line": 799
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
@@ -161,7 +161,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-OOA4C7IX.js",
+        "chunk-MPBMHIAQ.js",
         "chunk-LSJJAJAF.js"
       ]
     }

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

@@ -46,6 +46,37 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 
 > **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It uses background agents for managing memory. When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
 
+## Temporal gap markers
+
+Temporal gap markers insert a short reminder before a new user message when enough time has passed since the previous message in the thread. They help the agent and the UI see that the conversation resumed after a meaningful pause.
+
+Temporal gap markers are off by default. Enable them with `temporalMarkers: true` in the `observationalMemory` config:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+
+export const agent = new Agent({
+  name: 'my-agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5-mini',
+  memory: new Memory({
+    options: {
+      observationalMemory: {
+        model: 'google/gemini-2.5-flash',
+        temporalMarkers: true,
+      },
+    },
+  }),
+})
+```
+
+Mastra inserts a temporal gap marker when the gap is at least 10 minutes. The marker is stored in memory and also emitted as a transient reminder event, so clients can render it as a lightweight timeline hint.
+
+The observer also sees these markers when it processes the thread, so the observations it writes can anchor memories to when they happened (for example, "User asked about deployment after a 2-day gap").
+
+See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
+
 ## Benefits
 
 - **Prompt caching**: OM's context is stable and observations append over time rather than being dynamically retrieved each turn. This keeps the prompt prefix cacheable, which reduces costs.

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

@@ -40,6 +40,8 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **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`)
 
+**temporalMarkers** (`boolean`): Insert temporal-gap reminder markers before new user messages when the previous message in the thread is at least 10 minutes older. The marker is persisted in memory, emitted as an inline reminder event so clients can render it specially, and shown to the observer so it can anchor observations to when events occurred. (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`)
 
 **observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 var chunkCK4U3AYR_cjs = require('./chunk-CK4U3AYR.cjs');
 var chunkIDRQZVB4_cjs = require('./chunk-IDRQZVB4.cjs');
-var chunkHAUWGR76_cjs = require('./chunk-HAUWGR76.cjs');
+var chunk5MTY2UYL_cjs = require('./chunk-5MTY2UYL.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 = chunkHAUWGR76_cjs.truncateStringByTokens(text4, maxTokens);
+  const truncated = chunk5MTY2UYL_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 } = chunkHAUWGR76_cjs.resolveToolResultValue(
+            const { value: resultValue } = chunk5MTY2UYL_cjs.resolveToolResultValue(
               part,
               inv.result
             );
-            const resultStr = chunkHAUWGR76_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+            const resultStr = chunk5MTY2UYL_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 = chunkHAUWGR76_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+          const resultStr = chunk5MTY2UYL_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 = chunkHAUWGR76_cjs.truncateStringByTokens(text4, options.maxTokens);
+    const truncated = chunk5MTY2UYL_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 = chunkHAUWGR76_cjs.truncateStringByTokens(expanded, options.maxTokens);
+  const hardTruncated = chunk5MTY2UYL_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 = chunkHAUWGR76_cjs.truncateStringByTokens(fallbackText, maxTokens);
+          const truncatedText2 = chunk5MTY2UYL_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 = chunkHAUWGR76_cjs.truncateStringByTokens(target.text, maxTokens);
+  const truncatedText = chunk5MTY2UYL_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-EWU3QFIE.cjs');
+    const { ObservationalMemory: OMClass } = await import('./observational-memory-UCFGVLVW.cjs');
     const onIndexObservations = this.hasRetrievalSearch(omConfig.retrieval) ? async (observation) => {
       await this.indexObservation(observation);
     } : void 0;
@@ -18526,18 +18526,20 @@ Notes:
     if (!effectiveConfig) return null;
     const engine = await this.omEngine;
     if (!engine) return null;
-    const { ObservationalMemoryProcessor } = await import('./observational-memory-EWU3QFIE.cjs');
-    return new ObservationalMemoryProcessor(engine, this);
+    const { ObservationalMemoryProcessor } = await import('./observational-memory-UCFGVLVW.cjs');
+    return new ObservationalMemoryProcessor(engine, this, {
+      temporalMarkers: effectiveConfig.temporalMarkers
+    });
   }
 };
 
 Object.defineProperty(exports, "ModelByInputTokens", {
   enumerable: true,
-  get: function () { return chunkHAUWGR76_cjs.ModelByInputTokens; }
+  get: function () { return chunk5MTY2UYL_cjs.ModelByInputTokens; }
 });
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunkHAUWGR76_cjs.getObservationsAsOf; }
+  get: function () { return chunk5MTY2UYL_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "extractWorkingMemoryContent", {
   enumerable: true,