@mastra/memory 1.18.0 → 1.18.1

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @mastra/memory
 
+## 1.18.1
+
+### Patch Changes
+
+- Added a public escape hatch so callers can supply an authoritative token estimate for file parts whose binary payload has been stripped before persistence (for example, files uploaded to cloud storage with a hidden reference token left in `data` and re-hydrated by LLM middleware before inference). ([#16565](https://github.com/mastra-ai/mastra/pull/16565))
+
+  For those pipelines TokenCounter has no on-device file size to measure, so Observational Memory thresholds and context budgets undercount large attachments. Callers can now stamp an estimate directly on the part:
+
+  ```ts
+  part.providerMetadata = {
+    mastra: {
+      tokenEstimate: { v: 0, source: 'client', key: 'client', tokens: 25_000 },
+    },
+  };
+  ```
+
+  When present, TokenCounter returns those tokens from both the sync and async paths and skips provider fetches. Invalid entries (NaN, negative, non-numeric) fall through to the default estimator. Parts without a client estimate are unaffected.
+
+  Related to https://github.com/mastra-ai/mastra/issues/16522
+
+- Updated dependencies [[`20787de`](https://github.com/mastra-ai/mastra/commit/20787de5965234a1af28fe35f49437c537dbfa0d), [`784ad98`](https://github.com/mastra-ai/mastra/commit/784ad989549de91dc5d33ab8ef36caa6f7dcd34e), [`fceae1f`](https://github.com/mastra-ai/mastra/commit/fceae1f5f5db4722cb078a663c6eb4bd22944123), [`090a647`](https://github.com/mastra-ai/mastra/commit/090a647ba5a66d36f203f9f49457e03a1ff4e6fb), [`bf02acb`](https://github.com/mastra-ai/mastra/commit/bf02acbb8a6110f638ac844e89f1ebf04cb7fe74), [`090a647`](https://github.com/mastra-ai/mastra/commit/090a647ba5a66d36f203f9f49457e03a1ff4e6fb), [`bdb4cbf`](https://github.com/mastra-ai/mastra/commit/bdb4cbf8ba4b685d7481f28bb9dc3de6c79c9ed2), [`0fd3fbe`](https://github.com/mastra-ai/mastra/commit/0fd3fbe40fb63657aedd72f6e7b38c8e8ee6940d), [`f84447d`](https://github.com/mastra-ai/mastra/commit/f84447d6c80f3471836a9b300d246b331fb47e0d), [`a1a5b3e`](https://github.com/mastra-ai/mastra/commit/a1a5b3e42ab2ca5161ea21db59ebf28442680fa7), [`af84f57`](https://github.com/mastra-ai/mastra/commit/af84f571ed762e92e8e61c5f9a72363520914274), [`8b3c6f9`](https://github.com/mastra-ai/mastra/commit/8b3c6f90f7879833ba7d1bc70937e1d8f69d0804), [`fed0475`](https://github.com/mastra-ai/mastra/commit/fed0475ccfea31e4fc251469ac05640d0742c1f0), [`0d53730`](https://github.com/mastra-ai/mastra/commit/0d53730c1ed87ef80c87caa5701c4170ea8028e6), [`522f44d`](https://github.com/mastra-ai/mastra/commit/522f44d947214bfc06cff50599bae1ef3494880d)]:
+  - @mastra/core@1.34.0
+
+## 1.18.1-alpha.0
+
+### Patch Changes
+
+- Added a public escape hatch so callers can supply an authoritative token estimate for file parts whose binary payload has been stripped before persistence (for example, files uploaded to cloud storage with a hidden reference token left in `data` and re-hydrated by LLM middleware before inference). ([#16565](https://github.com/mastra-ai/mastra/pull/16565))
+
+  For those pipelines TokenCounter has no on-device file size to measure, so Observational Memory thresholds and context budgets undercount large attachments. Callers can now stamp an estimate directly on the part:
+
+  ```ts
+  part.providerMetadata = {
+    mastra: {
+      tokenEstimate: { v: 0, source: 'client', key: 'client', tokens: 25_000 },
+    },
+  };
+  ```
+
+  When present, TokenCounter returns those tokens from both the sync and async paths and skips provider fetches. Invalid entries (NaN, negative, non-numeric) fall through to the default estimator. Parts without a client estimate are unaffected.
+
+  Related to https://github.com/mastra-ai/mastra/issues/16522
+
+- Updated dependencies [[`fceae1f`](https://github.com/mastra-ai/mastra/commit/fceae1f5f5db4722cb078a663c6eb4bd22944123), [`bf02acb`](https://github.com/mastra-ai/mastra/commit/bf02acbb8a6110f638ac844e89f1ebf04cb7fe74), [`0fd3fbe`](https://github.com/mastra-ai/mastra/commit/0fd3fbe40fb63657aedd72f6e7b38c8e8ee6940d), [`fed0475`](https://github.com/mastra-ai/mastra/commit/fed0475ccfea31e4fc251469ac05640d0742c1f0), [`522f44d`](https://github.com/mastra-ai/mastra/commit/522f44d947214bfc06cff50599bae1ef3494880d)]:
+  - @mastra/core@1.34.0-alpha.1
+
 ## 1.18.0
 
 ### Minor Changes

package/README.md

@@ -1,3 +1,28 @@
 # Mastra Memory
 
 Memory management for Mastra agents. Visit [the docs](https://mastra.ai/docs/memory/overview) for more information.
+
+## Token counting for file parts
+
+Observational Memory uses a built-in Token Counter to decide when to observe and reflect. You can attach an explicit estimate to an `image` or `file` part using `providerMetadata.mastra.tokenEstimate`:
+
+```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 Token Counter honors caller-supplied estimates verbatim on `image` and `file` parts. See [Caller-supplied token estimates for file parts](https://mastra.ai/docs/memory/observational-memory#caller-supplied-token-estimates-for-file-parts) for details.

package/dist/{chunk-LPMZNXSF.js → chunk-KGYJHNI6.js}

@@ -1013,6 +1013,8 @@ var ObservationStrategy = class _ObservationStrategy {
     this.scope = deps.scope;
     this.retrieval = deps.retrieval;
   }
+  deps;
+  opts;
   storage;
   messageHistory;
   tokenCounter;
@@ -2041,6 +2043,8 @@ var ObservationStep = class {
     this.turn = turn;
     this.stepNumber = stepNumber;
   }
+  turn;
+  stepNumber;
   _prepared = false;
   _context;
   /** Whether this step has been prepared. */
@@ -5529,6 +5533,7 @@ var IMAGE_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
   "avif"
 ]);
 var TOKEN_ESTIMATE_CACHE_VERSION = 6;
+var CLIENT_TOKEN_ESTIMATE_SOURCE = "client";
 var DEFAULT_IMAGE_ESTIMATOR = {
   baseTokens: 85,
   tileTokens: 170,
@@ -5636,6 +5641,16 @@ function setPartCacheEntry(part, key, entry) {
   const mastraMetadata = ensurePartMastraMetadata(part);
   mastraMetadata.tokenEstimate = mergeCacheEntry(mastraMetadata.tokenEstimate, key, entry);
 }
+function getClientPartTokenEstimate(part) {
+  const cache = getPartMastraMetadata(part)?.tokenEstimate;
+  if (!cache || typeof cache !== "object") return void 0;
+  const matches = (entry) => isTokenEstimateEntry(entry) && entry.source === CLIENT_TOKEN_ESTIMATE_SOURCE && Number.isFinite(entry.tokens) && entry.tokens >= 0;
+  if (matches(cache)) return cache;
+  for (const value of Object.values(cache)) {
+    if (matches(value)) return value;
+  }
+  return void 0;
+}
 function getMessageCacheEntry(message, key) {
   const contentLevelEntry = getCacheEntry(getContentMastraMetadata(message.content)?.tokenEstimate, key);
   if (contentLevelEntry) return contentLevelEntry;
@@ -6440,6 +6455,12 @@ var TokenCounter = class _TokenCounter {
     return this.estimateImageAssetTokens(part, part.data, "file");
   }
   countAttachmentPartSync(part) {
+    if (part.type === "image" || part.type === "file") {
+      const clientEstimate = getClientPartTokenEstimate(part);
+      if (clientEstimate) {
+        return clientEstimate.tokens;
+      }
+    }
     if (part.type === "image") {
       const estimate = this.estimateImageTokens(part);
       return this.readOrPersistFixedPartEstimate(part, "image", estimate.cachePayload, estimate.tokens);
@@ -6504,6 +6525,12 @@ var TokenCounter = class _TokenCounter {
     return void 0;
   }
   async countAttachmentPartAsync(part) {
+    if (part.type === "image" || part.type === "file") {
+      const clientEstimate = getClientPartTokenEstimate(part);
+      if (clientEstimate) {
+        return clientEstimate.tokens;
+      }
+    }
     const isImageAttachment = part.type === "image" || part.type === "file" && isImageLikeFilePart(part);
     const remotePayload = this.buildRemoteAttachmentCachePayload(part);
     if (remotePayload) {
@@ -9633,5 +9660,5 @@ function getObservationsAsOf(activeObservations, asOf) {
 }
 
 export { ModelByInputTokens, OBSERVER_SYSTEM_PROMPT, ObservationalMemory, ObservationalMemoryProcessor, TokenCounter, buildObserverPrompt, buildObserverSystemPrompt, combineObservationGroupRanges, deriveObservationGroupProvenance, extractCurrentTask, formatMessagesForObserver, formatToolResultForObserver, getObservationsAsOf, hasCurrentTaskSection, injectAnchorIds, optimizeObservationsForContext, parseAnchorId, parseObservationGroups, parseObserverOutput, reconcileObservationGroupsFromReflection, renderObservationGroupsForReflection, resolveToolResultValue, stripEphemeralAnchorIds, stripObservationGroups, truncateStringByTokens, wrapInObservationGroup };
-//# sourceMappingURL=chunk-LPMZNXSF.js.map
-//# sourceMappingURL=chunk-LPMZNXSF.js.map
+//# sourceMappingURL=chunk-KGYJHNI6.js.map
+//# sourceMappingURL=chunk-KGYJHNI6.js.map