@mastra/memory 1.18.0 → 1.18.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.18.0"
+  version: "1.18.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,119 +1,119 @@
 {
-  "version": "1.18.0",
+  "version": "1.18.1",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
+      "implementation": "dist/chunk-KGYJHNI6.js",
       "line": 745
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js"
+      "implementation": "dist/chunk-KGYJHNI6.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 6827
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 6854
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 9401
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 9428
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 6297
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 6312
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 3655
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 3659
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 2963
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 2967
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
+      "implementation": "dist/chunk-KGYJHNI6.js",
       "line": 837
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
+      "implementation": "dist/chunk-KGYJHNI6.js",
       "line": 871
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 3769
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 3773
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 3381
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 3385
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 9613
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 9640
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 3757
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 3761
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 2511
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 2515
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 3780
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 3784
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 2484
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 2488
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
+      "implementation": "dist/chunk-KGYJHNI6.js",
       "line": 806
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 3665
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 3669
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
+      "implementation": "dist/chunk-KGYJHNI6.js",
       "line": 895
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
+      "implementation": "dist/chunk-KGYJHNI6.js",
       "line": 851
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
-      "line": 2541
+      "implementation": "dist/chunk-KGYJHNI6.js",
+      "line": 2545
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
+      "implementation": "dist/chunk-KGYJHNI6.js",
       "line": 828
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LPMZNXSF.js",
+      "implementation": "dist/chunk-KGYJHNI6.js",
       "line": 799
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
@@ -149,7 +149,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-LPMZNXSF.js",
+        "chunk-KGYJHNI6.js",
         "chunk-LSJJAJAF.js"
       ]
     }

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

@@ -392,6 +392,40 @@ OM caches token estimates in message metadata to reduce repeat counting work dur
 - Message and conversation overhead are still recalculated on every pass. The cache only stores payload estimates, so counting semantics stay the same.
 - `data-*` and `reasoning` parts are still skipped and aren't cached.
 
+### Caller-supplied token estimates for file parts
+
+You can attach a token estimate directly to an `image` or `file` part using `providerMetadata.mastra.tokenEstimate`. The Token Counter honors this value verbatim and skips its own estimator:
+
+```typescript
+const filePart = {
+  type: 'file',
+  data: 'storage://bucket/large-report.pdf',
+  mimeType: 'application/pdf',
+  filename: 'large-report.pdf',
+  providerMetadata: {
+    mastra: {
+      tokenEstimate: {
+        v: 0,
+        source: 'client',
+        key: 'client',
+        tokens: 100_000,
+      },
+    },
+  },
+}
+```
+
+The `tokenEstimate` object follows the same shape the Token Counter uses internally for cached estimates:
+
+- `v` — cache schema version. Set to `0`. Caller-supplied entries are exempt from the framework's version check, so the value isn't read.
+- `source` — cache lineage marker. Must be `'client'`. This is what tells the Token Counter the entry is authoritative and should be honored verbatim instead of being recomputed or overwritten.
+- `key` — content fingerprint slot. Set to `'client'`. Framework entries use a content hash here so they invalidate when the payload changes; the `'client'` sentinel keeps caller estimates stable across writes.
+- `tokens` — the token count to use. Must be a finite non-negative number.
+
+Additional notes:
+
+- The estimate is only honored on `image` and `file` parts. `text` and `tool-invocation` parts are always counted normally, even if they carry a `tokenEstimate`.
+
 ## Async buffering
 
 Without async buffering, the Observer runs synchronously when the message threshold is reached — the agent pauses mid-conversation while the Observer LLM call completes. With async buffering (enabled by default), observations are pre-computed in the background as the conversation grows. When the threshold is hit, buffered observations activate instantly with no pause.

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkNRYX4QWV_cjs = require('./chunk-NRYX4QWV.cjs');
+var chunkLCRYFBV3_cjs = require('./chunk-LCRYFBV3.cjs');
 var v3 = require('zod/v3');
 var zod = require('zod');
 var z4 = require('zod/v4');
@@ -67,7 +67,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var require_secure_json_parse = __commonJS({
-  "../../../node_modules/.pnpm/secure-json-parse@2.7.0/node_modules/secure-json-parse/index.js"(exports$1, module) {
+  "../../../node_modules/.pnpm/secure-json-parse@2.7.0/node_modules/secure-json-parse/index.js"(exports, module) {
     var hasBuffer = typeof Buffer !== "undefined";
     var suspectProtoRx3 = /"(?:_|\\u005[Ff])(?:_|\\u005[Ff])(?:p|\\u0070)(?:r|\\u0072)(?:o|\\u006[Ff])(?:t|\\u0074)(?:o|\\u006[Ff])(?:_|\\u005[Ff])(?:_|\\u005[Ff])"\s*:/;
     var suspectConstructorRx3 = /"(?:c|\\u0063)(?:o|\\u006[Ff])(?:n|\\u006[Ee])(?:s|\\u0073)(?:t|\\u0074)(?:r|\\u0072)(?:u|\\u0075)(?:c|\\u0063)(?:t|\\u0074)(?:o|\\u006[Ff])(?:r|\\u0072)"\s*:/;
@@ -16056,7 +16056,7 @@ function formatTimestamp(date) {
 }
 function truncateByTokens(text4, maxTokens, hint) {
   if (tokenx.estimateTokenCount(text4) <= maxTokens) return { text: text4, wasTruncated: false };
-  const truncated = chunkNRYX4QWV_cjs.truncateStringByTokens(text4, maxTokens);
+  const truncated = chunkLCRYFBV3_cjs.truncateStringByTokens(text4, maxTokens);
   const suffix = hint ? ` [${hint} for more]` : "";
   return { text: truncated + suffix, wasTruncated: true };
 }
@@ -16108,11 +16108,11 @@ ${JSON.stringify(inv.args, null, 2)}`;
             });
           }
           if (inv.state === "result") {
-            const { value: resultValue } = chunkNRYX4QWV_cjs.resolveToolResultValue(
+            const { value: resultValue } = chunkLCRYFBV3_cjs.resolveToolResultValue(
               part,
               inv.result
             );
-            const resultStr = chunkNRYX4QWV_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+            const resultStr = chunkLCRYFBV3_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));
@@ -16139,7 +16139,7 @@ ${typeof rawArgs === "string" ? rawArgs : JSON.stringify(rawArgs, null, 2)}`;
         const toolName = part.toolName;
         if (toolName) {
           const rawResult = part.output ?? part.result;
-          const resultStr = chunkNRYX4QWV_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+          const resultStr = chunkLCRYFBV3_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));
@@ -16218,7 +16218,7 @@ function renderFormattedParts(parts, timestamps, options) {
   const text4 = buildRenderedText(parts, timestamps);
   let totalTokens = tokenx.estimateTokenCount(text4);
   if (totalTokens > options.maxTokens) {
-    const truncated = chunkNRYX4QWV_cjs.truncateStringByTokens(text4, options.maxTokens);
+    const truncated = chunkLCRYFBV3_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));
@@ -16251,7 +16251,7 @@ function renderFormattedParts(parts, timestamps, options) {
   if (expandedTokens <= options.maxTokens) {
     return { text: expanded, truncated: false, tokenOffset: 0 };
   }
-  const hardTruncated = chunkNRYX4QWV_cjs.truncateStringByTokens(expanded, options.maxTokens);
+  const hardTruncated = chunkLCRYFBV3_cjs.truncateStringByTokens(expanded, options.maxTokens);
   return { text: hardTruncated, truncated: true, tokenOffset: expandedTokens - options.maxTokens };
 }
 async function recallPart({
@@ -16302,7 +16302,7 @@ async function recallPart({
 
 `;
           const fallbackText = `${fallbackNote}${firstNextPart.text}`;
-          const truncatedText2 = chunkNRYX4QWV_cjs.truncateStringByTokens(fallbackText, maxTokens);
+          const truncatedText2 = chunkLCRYFBV3_cjs.truncateStringByTokens(fallbackText, maxTokens);
           const wasTruncated2 = truncatedText2 !== fallbackText;
           return {
             text: truncatedText2,
@@ -16317,7 +16317,7 @@ async function recallPart({
     }
     throw new Error(`Part index ${partIndex} not found in message ${cursor}. Available indices: ${availableIndices}`);
   }
-  const truncatedText = chunkNRYX4QWV_cjs.truncateStringByTokens(target.text, maxTokens);
+  const truncatedText = chunkLCRYFBV3_cjs.truncateStringByTokens(target.text, maxTokens);
   const wasTruncated = truncatedText !== target.text;
   return {
     text: truncatedText,
@@ -18075,7 +18075,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-TZ67ZA32.cjs');
+    const { ObservationalMemory: OMClass } = await import('./observational-memory-5UNUGOE5.cjs');
     const onIndexObservations = this.hasRetrievalSearch(omConfig.retrieval) ? async (observation) => {
       await this.indexObservation(observation);
     } : void 0;
@@ -19001,7 +19001,7 @@ Notes:
     if (!effectiveConfig) return null;
     const engine = await this.omEngine;
     if (!engine) return null;
-    const { ObservationalMemoryProcessor } = await import('./observational-memory-TZ67ZA32.cjs');
+    const { ObservationalMemoryProcessor } = await import('./observational-memory-5UNUGOE5.cjs');
     return new ObservationalMemoryProcessor(engine, this, {
       temporalMarkers: effectiveConfig.temporalMarkers
     });
@@ -19010,11 +19010,11 @@ Notes:
 
 Object.defineProperty(exports, "ModelByInputTokens", {
   enumerable: true,
-  get: function () { return chunkNRYX4QWV_cjs.ModelByInputTokens; }
+  get: function () { return chunkLCRYFBV3_cjs.ModelByInputTokens; }
 });
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunkNRYX4QWV_cjs.getObservationsAsOf; }
+  get: function () { return chunkLCRYFBV3_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "MessageHistory", {
   enumerable: true,