@mastra/memory 1.9.1-alpha.1 → 1.10.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.9.1-alpha.1"
+  version: "1.10.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,126 +1,131 @@
 {
-  "version": "1.9.1-alpha.1",
+  "version": "1.10.0",
   "package": "@mastra/memory",
   "exports": {
+    "ModelByInputTokens": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 343
+    },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js"
+      "implementation": "dist/chunk-7A3UGAXY.js"
     },
     "OBSERVATION_CONTEXT_INSTRUCTIONS": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js"
+      "implementation": "dist/chunk-7A3UGAXY.js"
     },
     "OBSERVATION_CONTEXT_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js"
+      "implementation": "dist/chunk-7A3UGAXY.js"
     },
     "OBSERVATION_CONTINUATION_HINT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js"
+      "implementation": "dist/chunk-7A3UGAXY.js"
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js"
+      "implementation": "dist/chunk-7A3UGAXY.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 3457
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 3505
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 2888
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 2936
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 1471
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 1519
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 938
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 986
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 384
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 432
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 411
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 459
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 1585
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 1633
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 1204
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 1252
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 7585
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 7807
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 1573
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 1621
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 495
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 543
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 1596
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 1644
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 468
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 516
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 356
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 404
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 1481
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 1529
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 438
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 486
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 391
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 439
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 525
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 573
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 378
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 426
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-T5FHEWK6.js",
-      "line": 349
+      "implementation": "dist/chunk-7A3UGAXY.js",
+      "line": 397
     },
     "extractWorkingMemoryContent": {
       "types": "dist/index.d.ts",
@@ -151,7 +156,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-T5FHEWK6.js"
+        "chunk-7A3UGAXY.js"
       ]
     }
   }

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

@@ -137,6 +137,42 @@ const memory = new Memory({
 
 See [model configuration](https://mastra.ai/reference/memory/observational-memory) for using different models per agent.
 
+### Token-tiered model selection
+
+You can use `ModelByInputTokens` to specify different Observer or Reflector models based on input token count. OM selects the matching model tier at runtime from the configured `upTo` thresholds.
+
+```typescript
+import { Memory, ModelByInputTokens } from '@mastra/memory'
+
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      observation: {
+        model: new ModelByInputTokens({
+          upTo: {
+            10_000: 'google/gemini-2.5-flash', // Fast and cheap for small inputs
+            40_000: 'openai/gpt-4o', // Stronger for medium inputs
+            1_000_000: 'openai/gpt-4.5', // Most capable for very large inputs
+          },
+        }),
+      },
+      reflection: {
+        model: new ModelByInputTokens({
+          upTo: {
+            20_000: 'google/gemini-2.5-flash',
+            80_000: 'openai/gpt-4o',
+          },
+        }),
+      },
+    },
+  },
+})
+```
+
+The `upTo` keys are inclusive upper bounds. OM computes the actual input token count for the Observer or Reflector call, resolves the matching tier directly, and uses that concrete model for the run.
+
+If the input exceeds the largest configured threshold, an error is thrown — ensure your thresholds cover the full range of possible input sizes, or use a model with a sufficiently large context window at the highest tier.
+
 ## Scopes
 
 ### Thread scope (default)

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

@@ -32,7 +32,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **enabled** (`boolean`): Enable or disable Observational Memory. When omitted from a config object, defaults to \`true\`. Only \`enabled: false\` explicitly disables it. (Default: `true`)
 
-**model** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with \`observation.model\` or \`reflection.model\` — an error will be thrown if both are set. When using \`observationalMemory: true\`, defaults to \`google/gemini-2.5-flash\`. When passing a config object, this or \`observation.model\`/\`reflection.model\` must be set. Use \`"default"\` to explicitly use the default model (\`google/gemini-2.5-flash\`). (Default: `'google/gemini-2.5-flash' (when using observationalMemory: true)`)
+**model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with \`observation.model\` or \`reflection.model\` — an error will be thrown if both are set. When using \`observationalMemory: true\`, defaults to \`google/gemini-2.5-flash\`. When passing a config object, this or \`observation.model\`/\`reflection.model\` must be set. Use \`"default"\` to explicitly use the default model (\`google/gemini-2.5-flash\`). (Default: `'google/gemini-2.5-flash' (when using observationalMemory: true)`)
 
 **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'`)
 
@@ -42,7 +42,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 
-**observation.model** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Observer agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`reflection.model\`.
+**observation.model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]`): Model for the Observer agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`reflection.model\`.
 
 **observation.instruction** (`string`): Custom instruction appended to the Observer's system prompt. Use this to customize what the Observer focuses on, such as domain-specific preferences or priorities.
 
@@ -68,7 +68,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **reflection** (`ObservationalMemoryReflectionConfig`): Configuration for the reflection step. Controls when the Reflector agent runs and how it behaves.
 
-**reflection.model** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Reflector agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`observation.model\`.
+**reflection.model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]`): Model for the Reflector agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`observation.model\`.
 
 **reflection.instruction** (`string`): Custom instruction appended to the Reflector's system prompt. Use this to customize how the Reflector consolidates observations, such as prioritizing certain types of information.
 
@@ -612,6 +612,45 @@ When `retrieval: true` is set with `scope: 'thread'`, OM registers a `recall` to
 
 **tokenOffset** (`number`): Approximate number of tokens that were trimmed when \`truncated\` is true.
 
+### ModelByInputTokens
+
+`ModelByInputTokens` selects a model based on the input token count. It chooses the model for the smallest threshold that covers the actual input size.
+
+#### Constructor
+
+```typescript
+new ModelByInputTokens(config)
+```
+
+Where `config` is an object with `upTo` keys that map token thresholds (numbers) to model targets.
+
+#### Example
+
+```typescript
+import { ModelByInputTokens } from '@mastra/memory'
+
+const selector = new ModelByInputTokens({
+  upTo: {
+    10_000: 'google/gemini-2.5-flash', // Fast for small inputs
+    40_000: 'openai/gpt-4o', // Stronger for medium inputs
+    1_000_000: 'openai/gpt-4.5', // Most capable for large inputs
+  },
+})
+```
+
+#### Behavior
+
+- Thresholds are sorted internally, so the order in the config object does not matter.
+- `inputTokens ≤ smallest threshold` → uses that threshold's model
+- `inputTokens > largest threshold` → `resolve()` throws an error. If this happens during an OM Observer or Reflector run, OM aborts via TripWire, so callers receive an empty `text` result or streamed `tripwire` instead of a normal assistant response.
+- OM computes the input token count for the Observer or Reflector call and resolves the matching model tier directly
+
+#### Methods
+
+**resolve** (`(inputTokens: number) => MastraModelConfig`): Returns the model for the given input token count. Throws if inputTokens exceeds the largest configured threshold. When this happens during an OM run, callers receive a TripWire/empty-text outcome instead of a normal assistant response.
+
+**getThresholds** (`() => number[]`): Returns the configured thresholds in ascending order. Useful for introspection.
+
 ### Related
 
 - [Observational Memory](https://mastra.ai/docs/memory/observational-memory)

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 var chunkCK4U3AYR_cjs = require('./chunk-CK4U3AYR.cjs');
 var chunkIDRQZVB4_cjs = require('./chunk-IDRQZVB4.cjs');
-var chunkCNOHXG5O_cjs = require('./chunk-CNOHXG5O.cjs');
+var chunkEVBFYGDL_cjs = require('./chunk-EVBFYGDL.cjs');
 var v3 = require('zod/v3');
 var zod = require('zod');
 var z4 = require('zod/v4');
@@ -15503,7 +15503,7 @@ function formatTimestamp(date) {
 }
 function truncateByTokens(text4, maxTokens, hint) {
   if (tokenx.estimateTokenCount(text4) <= maxTokens) return { text: text4, wasTruncated: false };
-  const truncated = chunkCNOHXG5O_cjs.truncateStringByTokens(text4, maxTokens);
+  const truncated = chunkEVBFYGDL_cjs.truncateStringByTokens(text4, maxTokens);
   const suffix = hint ? ` [${hint} for more]` : "";
   return { text: truncated + suffix, wasTruncated: true };
 }
@@ -15536,11 +15536,11 @@ function formatMessageParts(msg, detail) {
       } else if (partType === "tool-invocation") {
         const inv = part.toolInvocation;
         if (inv.state === "result") {
-          const { value: resultValue } = chunkCNOHXG5O_cjs.resolveToolResultValue(
+          const { value: resultValue } = chunkEVBFYGDL_cjs.resolveToolResultValue(
             part,
             inv.result
           );
-          const resultStr = chunkCNOHXG5O_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+          const resultStr = chunkEVBFYGDL_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));
@@ -15603,7 +15603,7 @@ function renderFormattedParts(parts, timestamps, options) {
   const text4 = buildRenderedText(parts, timestamps);
   let totalTokens = tokenx.estimateTokenCount(text4);
   if (totalTokens > options.maxTokens) {
-    const truncated = chunkCNOHXG5O_cjs.truncateStringByTokens(text4, options.maxTokens);
+    const truncated = chunkEVBFYGDL_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));
@@ -15636,7 +15636,7 @@ function renderFormattedParts(parts, timestamps, options) {
   if (expandedTokens <= options.maxTokens) {
     return { text: expanded, truncated: false, tokenOffset: 0 };
   }
-  const hardTruncated = chunkCNOHXG5O_cjs.truncateStringByTokens(expanded, options.maxTokens);
+  const hardTruncated = chunkEVBFYGDL_cjs.truncateStringByTokens(expanded, options.maxTokens);
   return { text: hardTruncated, truncated: true, tokenOffset: expandedTokens - options.maxTokens };
 }
 async function recallPart({
@@ -15671,7 +15671,7 @@ async function recallPart({
       `Part index ${partIndex} not found in message ${cursor}. Available indices: ${allParts.map((p) => p.partIndex).join(", ")}`
     );
   }
-  const truncatedText = chunkCNOHXG5O_cjs.truncateStringByTokens(target.text, maxTokens);
+  const truncatedText = chunkEVBFYGDL_cjs.truncateStringByTokens(target.text, maxTokens);
   const wasTruncated = truncatedText !== target.text;
   return {
     text: truncatedText,
@@ -17403,7 +17403,10 @@ Notes:
     );
     const memoryContext = context2?.get("MastraMemory");
     const runtimeMemoryConfig = memoryContext?.memoryConfig;
-    const effectiveConfig = runtimeMemoryConfig ? this.getMergedThreadConfig(runtimeMemoryConfig) : this.threadConfig;
+    const effectiveConfig = runtimeMemoryConfig ? this.getMergedThreadConfig({
+      ...runtimeMemoryConfig,
+      observationalMemory: runtimeMemoryConfig.observationalMemory
+    }) : this.threadConfig;
     const omConfig = normalizeObservationalMemoryConfig(effectiveConfig.observationalMemory);
     if (!omConfig || hasObservationalMemory) {
       return null;
@@ -17435,7 +17438,7 @@ Notes:
         "Observational memory requires @mastra/core support for request-response-id-rotation. Please bump @mastra/core to a newer version."
       );
     }
-    const { ObservationalMemory } = await import('./observational-memory-APEZUJUQ.cjs');
+    const { ObservationalMemory } = await import('./observational-memory-COYJCVX3.cjs');
     return new ObservationalMemory({
       storage: memoryStore,
       scope: omConfig.scope,
@@ -17468,9 +17471,13 @@ Notes:
   }
 };
 
+Object.defineProperty(exports, "ModelByInputTokens", {
+  enumerable: true,
+  get: function () { return chunkEVBFYGDL_cjs.ModelByInputTokens; }
+});
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunkCNOHXG5O_cjs.getObservationsAsOf; }
+  get: function () { return chunkEVBFYGDL_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "extractWorkingMemoryContent", {
   enumerable: true,