@mastra/memory 1.15.1-alpha.0 → 1.15.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-alpha.0"
+  version: "1.15.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,119 +1,119 @@
 {
-  "version": "1.15.1-alpha.0",
+  "version": "1.15.1",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
+      "implementation": "dist/chunk-7NCBGOHT.js",
       "line": 666
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js"
+      "implementation": "dist/chunk-7NCBGOHT.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 6230
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 6234
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 8629
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 8633
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 5782
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 5786
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 3412
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 3416
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 2811
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 2815
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
+      "implementation": "dist/chunk-7NCBGOHT.js",
       "line": 758
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
+      "implementation": "dist/chunk-7NCBGOHT.js",
       "line": 792
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 3526
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 3530
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 3138
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 3142
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 8814
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 8818
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 3514
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 3518
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 2368
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 2372
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 3537
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 3541
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 2341
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 2345
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
+      "implementation": "dist/chunk-7NCBGOHT.js",
       "line": 727
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 3422
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 3426
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
+      "implementation": "dist/chunk-7NCBGOHT.js",
       "line": 816
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
+      "implementation": "dist/chunk-7NCBGOHT.js",
       "line": 772
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
-      "line": 2398
+      "implementation": "dist/chunk-7NCBGOHT.js",
+      "line": 2402
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
+      "implementation": "dist/chunk-7NCBGOHT.js",
       "line": 749
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HAEQMUD4.js",
+      "implementation": "dist/chunk-7NCBGOHT.js",
       "line": 720
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
@@ -161,7 +161,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-HAEQMUD4.js",
+        "chunk-7NCBGOHT.js",
         "chunk-LSJJAJAF.js"
       ]
     }

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

@@ -307,8 +307,8 @@ Both scenarios are safe - guardrails prevent inappropriate content from being pe
 
 ## Related documentation
 
-- [Processors](https://mastra.ai/docs/agents/processors) - General processor concepts and custom processor creation
-- [Guardrails](https://mastra.ai/docs/agents/guardrails) - Security and validation processors
-- [Memory Overview](https://mastra.ai/docs/memory/overview) - Memory types and configuration
+- [Processors](https://mastra.ai/docs/agents/processors): General processor concepts and custom processor creation
+- [Guardrails](https://mastra.ai/docs/agents/guardrails): Security and validation processors
+- [Memory Overview](https://mastra.ai/docs/memory/overview): Memory types and configuration
 
 When creating custom processors avoid mutating the input `messages` array or its objects directly.

package/dist/docs/references/docs-memory-message-history.md

@@ -6,6 +6,12 @@ You can also retrieve message history to display past conversations in your UI.
 
 > **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](https://mastra.ai/docs/memory/storage) for more detail.
 
+> **Warning:** When you use memory with a client application, send **only the new message** from the client instead of the full conversation history.
+>
+> Sending the full history is redundant because Mastra loads messages from storage, and it can cause message ordering bugs when client-side timestamps conflict with stored timestamps.
+>
+> For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
+
 ## Getting started
 
 Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/memory/storage) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
@@ -100,8 +106,8 @@ await agent.stream('Hello', {
 
 You can use this history in two ways:
 
-- **Automatic inclusion** - Mastra automatically fetches and includes recent messages in the context window. By default, it includes the last 10 messages, keeping agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
-- [**Manual querying**](#querying) - For more control, use the `recall()` function to query threads and messages directly. This lets you choose exactly which memories are included in the context window, or fetch messages to render conversation history in your UI.
+- **Automatic inclusion**: Mastra automatically fetches and includes recent messages in the context window. By default, it includes the last 10 messages, keeping agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
+- [**Manual querying**](#querying): For more control, use the `recall()` function to query threads and messages directly. This lets you choose exactly which memories are included in the context window, or fetch messages to render conversation history in your UI.
 
 > **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
 

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

@@ -38,6 +38,12 @@ const memory = new Memory({
 
 See [configuration options](https://mastra.ai/reference/memory/observational-memory) for full API details.
 
+> **Warning:** When you use OM with a client application, send **only the new message** from the client instead of the full conversation history.
+>
+> Observational memory still relies on stored conversation history. Sending the full history is redundant and can cause message ordering bugs when client-side timestamps conflict with stored timestamps.
+>
+> For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
+
 > **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.
 
 ## Benefits
@@ -157,7 +163,7 @@ With retrieval mode enabled, OM:
 - Registers a `recall` tool the agent can call to:
 
   - Page through the raw messages behind any observation group range
-  - Search by semantic similarity (`mode: "search"` with a `query` string) — requires `vector: true`
+  - Search by semantic similarity (`mode: "search"` with a `query` string); requires `vector: true`
   - List all threads (`mode: "threads"`), browse other threads (`threadId`), and search across all threads (default `scope: 'resource'`)
   - When `scope: 'thread'`: restrict browsing and search to the current thread only
 

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

@@ -397,4 +397,4 @@ const response = await agent.generate('What do you know about me?', {
 
 - [Working memory with template](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-template)
 - [Working memory with schema](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-schema)
-- [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example) - Complete example showing resource-scoped memory persistence
+- [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example): Complete example showing resource-scoped memory persistence

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 var chunkCK4U3AYR_cjs = require('./chunk-CK4U3AYR.cjs');
 var chunkIDRQZVB4_cjs = require('./chunk-IDRQZVB4.cjs');
-var chunkOUMWCVQI_cjs = require('./chunk-OUMWCVQI.cjs');
+var chunk3TU4GGH3_cjs = require('./chunk-3TU4GGH3.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 = chunkOUMWCVQI_cjs.truncateStringByTokens(text4, maxTokens);
+  const truncated = chunk3TU4GGH3_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 } = chunkOUMWCVQI_cjs.resolveToolResultValue(
+            const { value: resultValue } = chunk3TU4GGH3_cjs.resolveToolResultValue(
               part,
               inv.result
             );
-            const resultStr = chunkOUMWCVQI_cjs.formatToolResultForObserver(resultValue, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+            const resultStr = chunk3TU4GGH3_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 = chunkOUMWCVQI_cjs.formatToolResultForObserver(rawResult, { maxTokens: HIGH_DETAIL_TOOL_RESULT_TOKENS });
+          const resultStr = chunk3TU4GGH3_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 = chunkOUMWCVQI_cjs.truncateStringByTokens(text4, options.maxTokens);
+    const truncated = chunk3TU4GGH3_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 = chunkOUMWCVQI_cjs.truncateStringByTokens(expanded, options.maxTokens);
+  const hardTruncated = chunk3TU4GGH3_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 = chunkOUMWCVQI_cjs.truncateStringByTokens(fallbackText, maxTokens);
+          const truncatedText2 = chunk3TU4GGH3_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 = chunkOUMWCVQI_cjs.truncateStringByTokens(target.text, maxTokens);
+  const truncatedText = chunk3TU4GGH3_cjs.truncateStringByTokens(target.text, maxTokens);
   const wasTruncated = truncatedText !== target.text;
   return {
     text: truncatedText,
@@ -16453,6 +16453,25 @@ function deepMergeWorkingMemory(existing, update) {
   }
   return result;
 }
+function stripNullsFromOptional(value, schema) {
+  if (Array.isArray(value)) {
+    const itemSchema = schema.items ?? {};
+    return value.map((item) => stripNullsFromOptional(item, itemSchema));
+  }
+  if (typeof value === "object" && value !== null) {
+    const properties = schema.properties ?? {};
+    const required = schema.required ?? [];
+    const result = {};
+    for (const [key, propertyValue] of Object.entries(value)) {
+      if (propertyValue === null && !required.includes(key)) {
+        continue;
+      }
+      result[key] = stripNullsFromOptional(propertyValue, properties[key] ?? {});
+    }
+    return result;
+  }
+  return value;
+}
 var updateWorkingMemoryTool = (memoryConfig) => {
   const schema$2 = memoryConfig?.workingMemory?.schema;
   let inputSchema = zod.z.object({
@@ -16462,7 +16481,7 @@ var updateWorkingMemoryTool = (memoryConfig) => {
     const standardSchema2 = schema$1.isStandardSchemaWithJSON(schema$2) ? schema$2 : schema$1.toStandardSchema(schema$2);
     const jsonSchema4 = schema.standardSchemaToJSONSchema(standardSchema2, { io: "input" });
     delete jsonSchema4.$schema;
-    inputSchema = schema$1.toStandardSchema({
+    const wrappedSchema = schema$1.toStandardSchema({
       $schema: "http://json-schema.org/draft-07/schema#",
       type: "object",
       description: "The JSON formatted working memory content to store.",
@@ -16471,6 +16490,41 @@ var updateWorkingMemoryTool = (memoryConfig) => {
       },
       required: ["memory"]
     });
+    inputSchema = {
+      "~standard": {
+        version: 1,
+        vendor: "mastra",
+        validate: (value) => {
+          const wrappedResult = wrappedSchema["~standard"].validate(value);
+          if (wrappedResult instanceof Promise) {
+            return wrappedResult.then((result) => {
+              if (!("issues" in result) || !result.issues) {
+                return result;
+              }
+              if (!value || typeof value !== "object" || Array.isArray(value) || "memory" in value) {
+                return result;
+              }
+              return wrappedSchema["~standard"].validate({
+                memory: stripNullsFromOptional(value, jsonSchema4)
+              });
+            });
+          }
+          if (!("issues" in wrappedResult) || !wrappedResult.issues) {
+            return wrappedResult;
+          }
+          if (!value || typeof value !== "object" || Array.isArray(value) || "memory" in value) {
+            return wrappedResult;
+          }
+          return wrappedSchema["~standard"].validate({
+            memory: stripNullsFromOptional(value, jsonSchema4)
+          });
+        },
+        jsonSchema: {
+          input: (props) => wrappedSchema["~standard"].jsonSchema.input(props),
+          output: (props) => wrappedSchema["~standard"].jsonSchema.output(props)
+        }
+      }
+    };
   }
   const usesMergeSemantics = Boolean(schema$2);
   const description = schema$2 ? `Update the working memory with new information. Data is merged with existing memory - only include fields you want to add or update. To preserve existing data, omit the field entirely. Arrays are replaced entirely when provided, so pass the complete array or omit it to keep the existing values.` : `Update the working memory with new information. Any data not included will be overwritten. Always pass data as string to the memory field. Never pass an object.`;
@@ -17547,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-TKXRH2LD.cjs');
+    const { ObservationalMemory: OMClass } = await import('./observational-memory-GH6IRH6E.cjs');
     const onIndexObservations = this.hasRetrievalSearch(omConfig.retrieval) ? async (observation) => {
       await this.indexObservation(observation);
     } : void 0;
@@ -18470,18 +18524,18 @@ Notes:
     if (!effectiveConfig) return null;
     const engine = await this.omEngine;
     if (!engine) return null;
-    const { ObservationalMemoryProcessor } = await import('./observational-memory-TKXRH2LD.cjs');
+    const { ObservationalMemoryProcessor } = await import('./observational-memory-GH6IRH6E.cjs');
     return new ObservationalMemoryProcessor(engine, this);
   }
 };
 
 Object.defineProperty(exports, "ModelByInputTokens", {
   enumerable: true,
-  get: function () { return chunkOUMWCVQI_cjs.ModelByInputTokens; }
+  get: function () { return chunk3TU4GGH3_cjs.ModelByInputTokens; }
 });
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunkOUMWCVQI_cjs.getObservationsAsOf; }
+  get: function () { return chunk3TU4GGH3_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "extractWorkingMemoryContent", {
   enumerable: true,