@mastra/memory 0.11.3-alpha.0 → 0.11.3

package/.turbo/turbo-build.log

@@ -1,9 +1,9 @@
 
-> @mastra/memory@0.11.3-alpha.0 build /home/runner/work/mastra/mastra/packages/memory
+> @mastra/memory@0.11.3-alpha.1 build /home/runner/work/mastra/mastra/packages/memory
 > pnpm run check && tsup --silent src/index.ts src/processors/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting
 
 
-> @mastra/memory@0.11.3-alpha.0 check /home/runner/work/mastra/mastra/packages/memory
+> @mastra/memory@0.11.3-alpha.1 check /home/runner/work/mastra/mastra/packages/memory
 > tsc --noEmit
 
 Analysis will use the bundled TypeScript version 5.8.3

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @mastra/memory
 
+## 0.11.3
+
+### Patch Changes
+
+- 4b20131: Fixed an issue where per-resource semantic recall wouldn't always be enabled properly in agent tool calls
+- 2ba5b76: Allow passing jsonSchema into workingMemory schema
+- c3a30de: added new experimental vnext working memory
+- 626b0f4: [Cloud-126] Working Memory Playground - Added working memory to playground to allow users to view/edit working memory
+- Updated dependencies [0b56518]
+- Updated dependencies [db5cc15]
+- Updated dependencies [2ba5b76]
+- Updated dependencies [5237998]
+- Updated dependencies [c3a30de]
+- Updated dependencies [37c1acd]
+- Updated dependencies [1aa60b1]
+- Updated dependencies [89ec9d4]
+- Updated dependencies [cf3a184]
+- Updated dependencies [d6bfd60]
+- Updated dependencies [626b0f4]
+- Updated dependencies [c22a91f]
+- Updated dependencies [f7403ab]
+- Updated dependencies [6c89d7f]
+  - @mastra/core@0.10.15
+
+## 0.11.3-alpha.1
+
+### Patch Changes
+
+- 2ba5b76: Allow passing jsonSchema into workingMemory schema
+- c3a30de: added new experimental vnext working memory
+- Updated dependencies [0b56518]
+- Updated dependencies [2ba5b76]
+- Updated dependencies [c3a30de]
+- Updated dependencies [cf3a184]
+- Updated dependencies [d6bfd60]
+  - @mastra/core@0.10.15-alpha.1
+
 ## 0.11.3-alpha.0
 
 ### Patch Changes

package/dist/_tsup-dts-rollup.d.cts

@@ -17,6 +17,8 @@ import type { TiktokenBPE } from 'js-tiktoken/lite';
 import type { UIMessage } from 'ai';
 import type { WorkingMemoryTemplate } from '@mastra/core/memory';
 
+export declare const __experimental_updateWorkingMemoryToolVNext: (config: MemoryConfig_2) => CoreTool;
+
 /**
  * Concrete implementation of MastraMemory that adds support for thread configuration
  * and message injection.
@@ -47,7 +49,7 @@ export declare class Memory extends MastraMemory {
     getThreadsByResourceId({ resourceId }: {
         resourceId: string;
     }): Promise<StorageThreadType[]>;
-    saveThread({ thread, memoryConfig, }: {
+    saveThread({ thread }: {
         thread: StorageThreadType;
         memoryConfig?: MemoryConfig;
     }): Promise<StorageThreadType>;
@@ -63,6 +65,20 @@ export declare class Memory extends MastraMemory {
         workingMemory: string;
         memoryConfig?: MemoryConfig;
     }): Promise<void>;
+    private updateWorkingMemoryMutexes;
+    /**
+     * @warning experimental! can be removed or changed at any time
+     */
+    __experimental_updateWorkingMemoryVNext({ threadId, resourceId, workingMemory, searchString, memoryConfig, }: {
+        threadId: string;
+        resourceId?: string;
+        workingMemory: string;
+        searchString?: string;
+        memoryConfig?: MemoryConfig;
+    }): Promise<{
+        success: boolean;
+        reason: string;
+    }>;
     protected chunkText(text: string, tokenSize?: number): string[];
     private hasher;
     private embeddingCache;
@@ -110,6 +126,11 @@ export declare class Memory extends MastraMemory {
         template: WorkingMemoryTemplate;
         data: string | null;
     }): string;
+    protected __experimental_getWorkingMemoryToolInstructionVNext({ template, data, }: {
+        template: WorkingMemoryTemplate;
+        data: string | null;
+    }): string;
+    private isVNextWorkingMemoryConfig;
     getTools(config?: MemoryConfig): Record<string, CoreTool>;
     /**
      * Updates the metadata of a list of messages

package/dist/_tsup-dts-rollup.d.ts

@@ -17,6 +17,8 @@ import type { TiktokenBPE } from 'js-tiktoken/lite';
 import type { UIMessage } from 'ai';
 import type { WorkingMemoryTemplate } from '@mastra/core/memory';
 
+export declare const __experimental_updateWorkingMemoryToolVNext: (config: MemoryConfig_2) => CoreTool;
+
 /**
  * Concrete implementation of MastraMemory that adds support for thread configuration
  * and message injection.
@@ -47,7 +49,7 @@ export declare class Memory extends MastraMemory {
     getThreadsByResourceId({ resourceId }: {
         resourceId: string;
     }): Promise<StorageThreadType[]>;
-    saveThread({ thread, memoryConfig, }: {
+    saveThread({ thread }: {
         thread: StorageThreadType;
         memoryConfig?: MemoryConfig;
     }): Promise<StorageThreadType>;
@@ -63,6 +65,20 @@ export declare class Memory extends MastraMemory {
         workingMemory: string;
         memoryConfig?: MemoryConfig;
     }): Promise<void>;
+    private updateWorkingMemoryMutexes;
+    /**
+     * @warning experimental! can be removed or changed at any time
+     */
+    __experimental_updateWorkingMemoryVNext({ threadId, resourceId, workingMemory, searchString, memoryConfig, }: {
+        threadId: string;
+        resourceId?: string;
+        workingMemory: string;
+        searchString?: string;
+        memoryConfig?: MemoryConfig;
+    }): Promise<{
+        success: boolean;
+        reason: string;
+    }>;
     protected chunkText(text: string, tokenSize?: number): string[];
     private hasher;
     private embeddingCache;
@@ -110,6 +126,11 @@ export declare class Memory extends MastraMemory {
         template: WorkingMemoryTemplate;
         data: string | null;
     }): string;
+    protected __experimental_getWorkingMemoryToolInstructionVNext({ template, data, }: {
+        template: WorkingMemoryTemplate;
+        data: string | null;
+    }): string;
+    private isVNextWorkingMemoryConfig;
     getTools(config?: MemoryConfig): Record<string, CoreTool>;
     /**
      * Updates the metadata of a list of messages

package/dist/index.cjs

@@ -4,6 +4,7 @@ var core = require('@mastra/core');
 var agent = require('@mastra/core/agent');
 var memory = require('@mastra/core/memory');
 var ai = require('ai');
+var asyncMutex = require('async-mutex');
 var xxhash = require('xxhash-wasm');
 var zod = require('zod');
 var zodToJsonSchema = require('zod-to-json-schema');
@@ -43,6 +44,56 @@ var updateWorkingMemoryTool = (memoryConfig) => ({
     return { success: true };
   }
 });
+var __experimental_updateWorkingMemoryToolVNext = (config) => ({
+  description: "Update the working memory with new information.",
+  parameters: zod.z.object({
+    newMemory: zod.z.string().optional().nullable().describe(`The ${config.workingMemory?.schema ? "JSON" : "Markdown"} formatted working memory content to store`),
+    searchString: zod.z.string().optional().nullable().describe(
+      "The working memory string to find. Will be replaced with the newMemory string. If this is omitted or doesn't exist, the newMemory string will be appended to the end of your working memory. Replacing single lines at a time is encouraged for greater accuracy. If updateReason is not 'append-new-memory', this search string must be provided or the tool call will be rejected."
+    ),
+    updateReason: zod.z.enum(["append-new-memory", "clarify-existing-memory", "replace-irrelevant-memory"]).optional().nullable().describe(
+      "The reason you're updating working memory. Passing any value other than 'append-new-memory' requires a searchString to be provided. Defaults to append-new-memory"
+    )
+  }),
+  execute: async (params) => {
+    const { context, threadId, memory, resourceId } = params;
+    if (!threadId || !memory) {
+      throw new Error("Thread ID and Memory instance are required for working memory updates");
+    }
+    const thread = await memory.getThreadById({ threadId });
+    if (!thread) {
+      throw new Error(`Thread ${threadId} not found`);
+    }
+    if (thread.resourceId && thread.resourceId !== resourceId) {
+      throw new Error(`Thread with id ${threadId} resourceId does not match the current resourceId ${resourceId}`);
+    }
+    const workingMemory = context.newMemory || "";
+    if (!context.updateReason) context.updateReason = `append-new-memory`;
+    if (context.searchString && config.workingMemory?.scope === `resource` && context.updateReason === `replace-irrelevant-memory`) {
+      context.searchString = void 0;
+    }
+    if (context.updateReason === `append-new-memory` && context.searchString) {
+      context.searchString = void 0;
+    }
+    if (context.updateReason !== `append-new-memory` && !context.searchString) {
+      return {
+        success: false,
+        reason: `updateReason was ${context.updateReason} but no searchString was provided. Unable to replace undefined with "${context.newMemory}"`
+      };
+    }
+    const result = await memory.__experimental_updateWorkingMemoryVNext({
+      threadId,
+      resourceId: resourceId || thread.resourceId,
+      workingMemory,
+      searchString: context.searchString,
+      memoryConfig: config
+    });
+    if (result) {
+      return result;
+    }
+    return { success: true };
+  }
+});
 
 // src/index.ts
 var CHARS_PER_TOKEN = 4;
@@ -205,32 +256,7 @@ var Memory = class extends memory.MastraMemory {
   async getThreadsByResourceId({ resourceId }) {
     return this.storage.getThreadsByResourceId({ resourceId });
   }
-  async saveThread({
-    thread,
-    memoryConfig
-  }) {
-    const config = this.getMergedThreadConfig(memoryConfig || {});
-    if (config.workingMemory?.enabled) {
-      const scope = config.workingMemory.scope || "thread";
-      const workingMemory = await this.getWorkingMemoryTemplate({ memoryConfig: config });
-      if (scope === "resource" && thread.resourceId) {
-        const existingResource = await this.storage.getResourceById({ resourceId: thread.resourceId });
-        if (!existingResource?.workingMemory) {
-          await this.storage.updateResource({
-            resourceId: thread.resourceId,
-            workingMemory: workingMemory?.content
-          });
-        }
-      } else if (scope === "thread" && !thread?.metadata?.workingMemory) {
-        return this.storage.saveThread({
-          thread: core.deepMerge(thread, {
-            metadata: {
-              workingMemory: workingMemory?.content
-            }
-          })
-        });
-      }
-    }
+  async saveThread({ thread }) {
     return this.storage.saveThread({ thread });
   }
   async updateThread({
@@ -278,6 +304,87 @@ var Memory = class extends memory.MastraMemory {
       });
     }
   }
+  updateWorkingMemoryMutexes = /* @__PURE__ */ new Map();
+  /**
+   * @warning experimental! can be removed or changed at any time
+   */
+  async __experimental_updateWorkingMemoryVNext({
+    threadId,
+    resourceId,
+    workingMemory,
+    searchString,
+    memoryConfig
+  }) {
+    const config = this.getMergedThreadConfig(memoryConfig || {});
+    if (!config.workingMemory?.enabled) {
+      throw new Error("Working memory is not enabled for this memory instance");
+    }
+    const mutexKey = memoryConfig?.workingMemory?.scope === `resource` ? `resource-${resourceId}` : `thread-${threadId}`;
+    const mutex = this.updateWorkingMemoryMutexes.has(mutexKey) ? this.updateWorkingMemoryMutexes.get(mutexKey) : new asyncMutex.Mutex();
+    this.updateWorkingMemoryMutexes.set(mutexKey, mutex);
+    const release = await mutex.acquire();
+    try {
+      const existingWorkingMemory = await this.getWorkingMemory({ threadId, resourceId, memoryConfig }) || "";
+      const template = await this.getWorkingMemoryTemplate({ memoryConfig });
+      let reason = "";
+      if (existingWorkingMemory) {
+        if (searchString && existingWorkingMemory?.includes(searchString)) {
+          workingMemory = existingWorkingMemory.replace(searchString, workingMemory);
+          reason = `found and replaced searchString with newMemory`;
+        } else if (existingWorkingMemory.includes(workingMemory) || template?.content?.trim() === workingMemory.trim()) {
+          return {
+            success: false,
+            reason: `attempted to insert duplicate data into working memory. this entry was skipped`
+          };
+        } else {
+          if (searchString) {
+            reason = `attempted to replace working memory string that doesn't exist. Appending to working memory instead.`;
+          } else {
+            reason = `appended newMemory to end of working memory`;
+          }
+          workingMemory = existingWorkingMemory + `
+${workingMemory}`;
+        }
+      } else if (workingMemory === template?.content) {
+        return {
+          success: false,
+          reason: `try again when you have data to add. newMemory was equal to the working memory template`
+        };
+      } else {
+        reason = `started new working memory`;
+      }
+      workingMemory = template?.content ? workingMemory.replaceAll(template?.content, "") : workingMemory;
+      const scope = config.workingMemory.scope || "thread";
+      if (scope === "resource" && resourceId) {
+        await this.storage.updateResource({
+          resourceId,
+          workingMemory
+        });
+        if (reason) {
+          return { success: true, reason };
+        }
+      } else {
+        const thread = await this.storage.getThreadById({ threadId });
+        if (!thread) {
+          throw new Error(`Thread ${threadId} not found`);
+        }
+        await this.storage.updateThread({
+          id: threadId,
+          title: thread.title || "Untitled Thread",
+          metadata: {
+            ...thread.metadata,
+            workingMemory
+          }
+        });
+      }
+      return { success: true, reason };
+    } catch (e) {
+      this.logger.error(e instanceof Error ? e.stack || e.message : JSON.stringify(e));
+      return { success: false, reason: "Tool error." };
+    } finally {
+      release();
+    }
+  }
   chunkText(text, tokenSize = 4096) {
     const charSize = tokenSize * CHARS_PER_TOKEN;
     const chunks = [];
@@ -524,7 +631,10 @@ var Memory = class extends memory.MastraMemory {
     if (!workingMemoryTemplate) {
       return null;
     }
-    return this.getWorkingMemoryToolInstruction({
+    return this.isVNextWorkingMemoryConfig(memoryConfig) ? this.__experimental_getWorkingMemoryToolInstructionVNext({
+      template: workingMemoryTemplate,
+      data: workingMemoryData
+    }) : this.getWorkingMemoryToolInstruction({
       template: workingMemoryTemplate,
       data: workingMemoryData
     });
@@ -559,14 +669,16 @@ Guidelines:
 6. IMPORTANT: ALWAYS pass the data you want to store in the memory field as a string. DO NOT pass an object.
 7. IMPORTANT: Data must only be sent as a string no matter which format is used.
 
-WORKING MEMORY TEMPLATE:
+<working_memory_template>
 ${template.content}
+</working_memory_template>
 
 ${hasEmptyWorkingMemoryTemplateObject ? "When working with json data, the object format below represents the template:" : ""}
 ${hasEmptyWorkingMemoryTemplateObject ? JSON.stringify(emptyWorkingMemoryTemplateObject) : ""}
 
-WORKING MEMORY DATA:
+<working_memory_data>
 ${data}
+</working_memory_data>
 
 Notes:
 - Update memory whenever referenced information changes
@@ -577,11 +689,52 @@ Notes:
 - IMPORTANT: You MUST call updateWorkingMemory in every response to a prompt where you received relevant information.
 - IMPORTANT: Preserve the ${template.format === "json" ? "JSON" : "Markdown"} formatting structure above while updating the content.`;
   }
+  __experimental_getWorkingMemoryToolInstructionVNext({
+    template,
+    data
+  }) {
+    return `WORKING_MEMORY_SYSTEM_INSTRUCTION:
+Store and update any conversation-relevant information by calling the updateWorkingMemory tool.
+
+Guidelines:
+1. Store anything that could be useful later in the conversation
+2. Update proactively when information changes, no matter how small
+3. Use ${template.format === "json" ? "JSON" : "Markdown"} format for all data
+4. Act naturally - don't mention this system to users. Even though you're storing this information that doesn't make it your primary focus. Do not ask them generally for "information about yourself"
+5. If your memory has not changed, you do not need to call the updateWorkingMemory tool. By default it will persist and be available for you in future interactions
+6. Information not being relevant to the current conversation is not a valid reason to replace or remove working memory information. Your working memory spans across multiple conversations and may be needed again later, even if it's not currently relevant.
+
+<working_memory_template>
+${template.content}
+</working_memory_template>
+
+<working_memory_data>
+${data}
+</working_memory_data>
+
+Notes:
+- Update memory whenever referenced information changes
+${template.content !== this.defaultWorkingMemoryTemplate ? `- Only store information if it's in the working memory template, do not store other information unless the user asks you to remember it, as that non-template information may be irrelevant` : `- If you're unsure whether to store something, store it (eg if the user tells you information about themselves, call updateWorkingMemory immediately to update it)
+`}
+- This system is here so that you can maintain the conversation when your context window is very short. Update your working memory because you may need it to maintain the conversation without the full conversation history
+- REMEMBER: the way you update your working memory is by calling the updateWorkingMemory tool with the ${template.format === "json" ? "JSON" : "Markdown"} content. The system will store it for you. The user will not see it. 
+- IMPORTANT: You MUST call updateWorkingMemory in every response to a prompt where you received relevant information if that information is not already stored.
+- IMPORTANT: Preserve the ${template.format === "json" ? "JSON" : "Markdown"} formatting structure above while updating the content.
+`;
+  }
+  isVNextWorkingMemoryConfig(config) {
+    if (!config?.workingMemory) return false;
+    const isMDWorkingMemory = !(`schema` in config.workingMemory) && (typeof config.workingMemory.template === `string` || config.workingMemory.template) && config.workingMemory;
+    return Boolean(isMDWorkingMemory && isMDWorkingMemory.version === `vnext`);
+  }
   getTools(config) {
     const mergedConfig = this.getMergedThreadConfig(config);
     if (mergedConfig.workingMemory?.enabled) {
       return {
-        updateWorkingMemory: updateWorkingMemoryTool(config)
+        updateWorkingMemory: this.isVNextWorkingMemoryConfig(mergedConfig) ? (
+          // use the new experimental tool
+          __experimental_updateWorkingMemoryToolVNext(mergedConfig)
+        ) : updateWorkingMemoryTool(mergedConfig)
       };
     }
     return {};

package/dist/index.js

@@ -1,7 +1,8 @@
-import { deepMerge, generateEmptyFromSchema } from '@mastra/core';
+import { generateEmptyFromSchema } from '@mastra/core';
 import { MessageList } from '@mastra/core/agent';
 import { MastraMemory } from '@mastra/core/memory';
 import { embedMany } from 'ai';
+import { Mutex } from 'async-mutex';
 import xxhash from 'xxhash-wasm';
 import { z, ZodObject } from 'zod';
 import zodToJsonSchema from 'zod-to-json-schema';
@@ -36,6 +37,56 @@ var updateWorkingMemoryTool = (memoryConfig) => ({
     return { success: true };
   }
 });
+var __experimental_updateWorkingMemoryToolVNext = (config) => ({
+  description: "Update the working memory with new information.",
+  parameters: z.object({
+    newMemory: z.string().optional().nullable().describe(`The ${config.workingMemory?.schema ? "JSON" : "Markdown"} formatted working memory content to store`),
+    searchString: z.string().optional().nullable().describe(
+      "The working memory string to find. Will be replaced with the newMemory string. If this is omitted or doesn't exist, the newMemory string will be appended to the end of your working memory. Replacing single lines at a time is encouraged for greater accuracy. If updateReason is not 'append-new-memory', this search string must be provided or the tool call will be rejected."
+    ),
+    updateReason: z.enum(["append-new-memory", "clarify-existing-memory", "replace-irrelevant-memory"]).optional().nullable().describe(
+      "The reason you're updating working memory. Passing any value other than 'append-new-memory' requires a searchString to be provided. Defaults to append-new-memory"
+    )
+  }),
+  execute: async (params) => {
+    const { context, threadId, memory, resourceId } = params;
+    if (!threadId || !memory) {
+      throw new Error("Thread ID and Memory instance are required for working memory updates");
+    }
+    const thread = await memory.getThreadById({ threadId });
+    if (!thread) {
+      throw new Error(`Thread ${threadId} not found`);
+    }
+    if (thread.resourceId && thread.resourceId !== resourceId) {
+      throw new Error(`Thread with id ${threadId} resourceId does not match the current resourceId ${resourceId}`);
+    }
+    const workingMemory = context.newMemory || "";
+    if (!context.updateReason) context.updateReason = `append-new-memory`;
+    if (context.searchString && config.workingMemory?.scope === `resource` && context.updateReason === `replace-irrelevant-memory`) {
+      context.searchString = void 0;
+    }
+    if (context.updateReason === `append-new-memory` && context.searchString) {
+      context.searchString = void 0;
+    }
+    if (context.updateReason !== `append-new-memory` && !context.searchString) {
+      return {
+        success: false,
+        reason: `updateReason was ${context.updateReason} but no searchString was provided. Unable to replace undefined with "${context.newMemory}"`
+      };
+    }
+    const result = await memory.__experimental_updateWorkingMemoryVNext({
+      threadId,
+      resourceId: resourceId || thread.resourceId,
+      workingMemory,
+      searchString: context.searchString,
+      memoryConfig: config
+    });
+    if (result) {
+      return result;
+    }
+    return { success: true };
+  }
+});
 
 // src/index.ts
 var CHARS_PER_TOKEN = 4;
@@ -198,32 +249,7 @@ var Memory = class extends MastraMemory {
   async getThreadsByResourceId({ resourceId }) {
     return this.storage.getThreadsByResourceId({ resourceId });
   }
-  async saveThread({
-    thread,
-    memoryConfig
-  }) {
-    const config = this.getMergedThreadConfig(memoryConfig || {});
-    if (config.workingMemory?.enabled) {
-      const scope = config.workingMemory.scope || "thread";
-      const workingMemory = await this.getWorkingMemoryTemplate({ memoryConfig: config });
-      if (scope === "resource" && thread.resourceId) {
-        const existingResource = await this.storage.getResourceById({ resourceId: thread.resourceId });
-        if (!existingResource?.workingMemory) {
-          await this.storage.updateResource({
-            resourceId: thread.resourceId,
-            workingMemory: workingMemory?.content
-          });
-        }
-      } else if (scope === "thread" && !thread?.metadata?.workingMemory) {
-        return this.storage.saveThread({
-          thread: deepMerge(thread, {
-            metadata: {
-              workingMemory: workingMemory?.content
-            }
-          })
-        });
-      }
-    }
+  async saveThread({ thread }) {
     return this.storage.saveThread({ thread });
   }
   async updateThread({
@@ -271,6 +297,87 @@ var Memory = class extends MastraMemory {
       });
     }
   }
+  updateWorkingMemoryMutexes = /* @__PURE__ */ new Map();
+  /**
+   * @warning experimental! can be removed or changed at any time
+   */
+  async __experimental_updateWorkingMemoryVNext({
+    threadId,
+    resourceId,
+    workingMemory,
+    searchString,
+    memoryConfig
+  }) {
+    const config = this.getMergedThreadConfig(memoryConfig || {});
+    if (!config.workingMemory?.enabled) {
+      throw new Error("Working memory is not enabled for this memory instance");
+    }
+    const mutexKey = memoryConfig?.workingMemory?.scope === `resource` ? `resource-${resourceId}` : `thread-${threadId}`;
+    const mutex = this.updateWorkingMemoryMutexes.has(mutexKey) ? this.updateWorkingMemoryMutexes.get(mutexKey) : new Mutex();
+    this.updateWorkingMemoryMutexes.set(mutexKey, mutex);
+    const release = await mutex.acquire();
+    try {
+      const existingWorkingMemory = await this.getWorkingMemory({ threadId, resourceId, memoryConfig }) || "";
+      const template = await this.getWorkingMemoryTemplate({ memoryConfig });
+      let reason = "";
+      if (existingWorkingMemory) {
+        if (searchString && existingWorkingMemory?.includes(searchString)) {
+          workingMemory = existingWorkingMemory.replace(searchString, workingMemory);
+          reason = `found and replaced searchString with newMemory`;
+        } else if (existingWorkingMemory.includes(workingMemory) || template?.content?.trim() === workingMemory.trim()) {
+          return {
+            success: false,
+            reason: `attempted to insert duplicate data into working memory. this entry was skipped`
+          };
+        } else {
+          if (searchString) {
+            reason = `attempted to replace working memory string that doesn't exist. Appending to working memory instead.`;
+          } else {
+            reason = `appended newMemory to end of working memory`;
+          }
+          workingMemory = existingWorkingMemory + `
+${workingMemory}`;
+        }
+      } else if (workingMemory === template?.content) {
+        return {
+          success: false,
+          reason: `try again when you have data to add. newMemory was equal to the working memory template`
+        };
+      } else {
+        reason = `started new working memory`;
+      }
+      workingMemory = template?.content ? workingMemory.replaceAll(template?.content, "") : workingMemory;
+      const scope = config.workingMemory.scope || "thread";
+      if (scope === "resource" && resourceId) {
+        await this.storage.updateResource({
+          resourceId,
+          workingMemory
+        });
+        if (reason) {
+          return { success: true, reason };
+        }
+      } else {
+        const thread = await this.storage.getThreadById({ threadId });
+        if (!thread) {
+          throw new Error(`Thread ${threadId} not found`);
+        }
+        await this.storage.updateThread({
+          id: threadId,
+          title: thread.title || "Untitled Thread",
+          metadata: {
+            ...thread.metadata,
+            workingMemory
+          }
+        });
+      }
+      return { success: true, reason };
+    } catch (e) {
+      this.logger.error(e instanceof Error ? e.stack || e.message : JSON.stringify(e));
+      return { success: false, reason: "Tool error." };
+    } finally {
+      release();
+    }
+  }
   chunkText(text, tokenSize = 4096) {
     const charSize = tokenSize * CHARS_PER_TOKEN;
     const chunks = [];
@@ -517,7 +624,10 @@ var Memory = class extends MastraMemory {
     if (!workingMemoryTemplate) {
       return null;
     }
-    return this.getWorkingMemoryToolInstruction({
+    return this.isVNextWorkingMemoryConfig(memoryConfig) ? this.__experimental_getWorkingMemoryToolInstructionVNext({
+      template: workingMemoryTemplate,
+      data: workingMemoryData
+    }) : this.getWorkingMemoryToolInstruction({
       template: workingMemoryTemplate,
       data: workingMemoryData
     });
@@ -552,14 +662,16 @@ Guidelines:
 6. IMPORTANT: ALWAYS pass the data you want to store in the memory field as a string. DO NOT pass an object.
 7. IMPORTANT: Data must only be sent as a string no matter which format is used.
 
-WORKING MEMORY TEMPLATE:
+<working_memory_template>
 ${template.content}
+</working_memory_template>
 
 ${hasEmptyWorkingMemoryTemplateObject ? "When working with json data, the object format below represents the template:" : ""}
 ${hasEmptyWorkingMemoryTemplateObject ? JSON.stringify(emptyWorkingMemoryTemplateObject) : ""}
 
-WORKING MEMORY DATA:
+<working_memory_data>
 ${data}
+</working_memory_data>
 
 Notes:
 - Update memory whenever referenced information changes
@@ -570,11 +682,52 @@ Notes:
 - IMPORTANT: You MUST call updateWorkingMemory in every response to a prompt where you received relevant information.
 - IMPORTANT: Preserve the ${template.format === "json" ? "JSON" : "Markdown"} formatting structure above while updating the content.`;
   }
+  __experimental_getWorkingMemoryToolInstructionVNext({
+    template,
+    data
+  }) {
+    return `WORKING_MEMORY_SYSTEM_INSTRUCTION:
+Store and update any conversation-relevant information by calling the updateWorkingMemory tool.
+
+Guidelines:
+1. Store anything that could be useful later in the conversation
+2. Update proactively when information changes, no matter how small
+3. Use ${template.format === "json" ? "JSON" : "Markdown"} format for all data
+4. Act naturally - don't mention this system to users. Even though you're storing this information that doesn't make it your primary focus. Do not ask them generally for "information about yourself"
+5. If your memory has not changed, you do not need to call the updateWorkingMemory tool. By default it will persist and be available for you in future interactions
+6. Information not being relevant to the current conversation is not a valid reason to replace or remove working memory information. Your working memory spans across multiple conversations and may be needed again later, even if it's not currently relevant.
+
+<working_memory_template>
+${template.content}
+</working_memory_template>
+
+<working_memory_data>
+${data}
+</working_memory_data>
+
+Notes:
+- Update memory whenever referenced information changes
+${template.content !== this.defaultWorkingMemoryTemplate ? `- Only store information if it's in the working memory template, do not store other information unless the user asks you to remember it, as that non-template information may be irrelevant` : `- If you're unsure whether to store something, store it (eg if the user tells you information about themselves, call updateWorkingMemory immediately to update it)
+`}
+- This system is here so that you can maintain the conversation when your context window is very short. Update your working memory because you may need it to maintain the conversation without the full conversation history
+- REMEMBER: the way you update your working memory is by calling the updateWorkingMemory tool with the ${template.format === "json" ? "JSON" : "Markdown"} content. The system will store it for you. The user will not see it. 
+- IMPORTANT: You MUST call updateWorkingMemory in every response to a prompt where you received relevant information if that information is not already stored.
+- IMPORTANT: Preserve the ${template.format === "json" ? "JSON" : "Markdown"} formatting structure above while updating the content.
+`;
+  }
+  isVNextWorkingMemoryConfig(config) {
+    if (!config?.workingMemory) return false;
+    const isMDWorkingMemory = !(`schema` in config.workingMemory) && (typeof config.workingMemory.template === `string` || config.workingMemory.template) && config.workingMemory;
+    return Boolean(isMDWorkingMemory && isMDWorkingMemory.version === `vnext`);
+  }
   getTools(config) {
     const mergedConfig = this.getMergedThreadConfig(config);
     if (mergedConfig.workingMemory?.enabled) {
       return {
-        updateWorkingMemory: updateWorkingMemoryTool(config)
+        updateWorkingMemory: this.isVNextWorkingMemoryConfig(mergedConfig) ? (
+          // use the new experimental tool
+          __experimental_updateWorkingMemoryToolVNext(mergedConfig)
+        ) : updateWorkingMemoryTool(mergedConfig)
       };
     }
     return {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/memory",
-  "version": "0.11.3-alpha.0",
+  "version": "0.11.3",
   "description": "",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,6 +40,7 @@
     "pg-pool": "^3.10.1",
     "postgres": "^3.4.7",
     "redis": "^4.7.1",
+    "async-mutex": "^0.5.0",
     "xxhash-wasm": "^1.1.0",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.5"
@@ -55,8 +56,8 @@
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.34.0",
     "vitest": "^3.2.4",
-    "@mastra/core": "0.10.15-alpha.0",
-    "@internal/lint": "0.0.19"
+    "@internal/lint": "0.0.20",
+    "@mastra/core": "0.10.15"
   },
   "peerDependencies": {
     "@mastra/core": ">=0.10.9-0 <0.11.0-0"

package/src/index.ts

@@ -1,4 +1,4 @@
-import { deepMerge, generateEmptyFromSchema } from '@mastra/core';
+import { generateEmptyFromSchema } from '@mastra/core';
 import type { CoreTool, MastraMessageV1 } from '@mastra/core';
 import { MessageList } from '@mastra/core/agent';
 import type { MastraMessageV2 } from '@mastra/core/agent';
@@ -7,13 +7,14 @@ import type { MemoryConfig, SharedMemoryConfig, StorageThreadType, WorkingMemory
 import type { StorageGetMessagesArg } from '@mastra/core/storage';
 import { embedMany } from 'ai';
 import type { CoreMessage, TextPart, UIMessage } from 'ai';
+import { Mutex } from 'async-mutex';
 import type { JSONSchema7 } from 'json-schema';
 
 import xxhash from 'xxhash-wasm';
 import { ZodObject } from 'zod';
 import type { ZodTypeAny } from 'zod';
 import zodToJsonSchema from 'zod-to-json-schema';
-import { updateWorkingMemoryTool } from './tools/working-memory';
+import { updateWorkingMemoryTool, __experimental_updateWorkingMemoryToolVNext } from './tools/working-memory';
 
 // Average characters per token based on OpenAI's tokenization
 const CHARS_PER_TOKEN = 4;
@@ -252,39 +253,7 @@ export class Memory extends MastraMemory {
     return this.storage.getThreadsByResourceId({ resourceId });
   }
 
-  async saveThread({
-    thread,
-    memoryConfig,
-  }: {
-    thread: StorageThreadType;
-    memoryConfig?: MemoryConfig;
-  }): Promise<StorageThreadType> {
-    const config = this.getMergedThreadConfig(memoryConfig || {});
-
-    if (config.workingMemory?.enabled) {
-      const scope = config.workingMemory.scope || 'thread';
-      const workingMemory = await this.getWorkingMemoryTemplate({ memoryConfig: config });
-      if (scope === 'resource' && thread.resourceId) {
-        // For resource scope, initialize working memory in resource table
-        const existingResource = await this.storage.getResourceById({ resourceId: thread.resourceId });
-        if (!existingResource?.workingMemory) {
-          await this.storage.updateResource({
-            resourceId: thread.resourceId,
-            workingMemory: workingMemory?.content,
-          });
-        }
-      } else if (scope === 'thread' && !thread?.metadata?.workingMemory) {
-        // For thread scope, initialize working memory in thread metadata (existing behavior)
-        return this.storage.saveThread({
-          thread: deepMerge(thread, {
-            metadata: {
-              workingMemory: workingMemory?.content,
-            },
-          }),
-        });
-      }
-    }
-
+  async saveThread({ thread }: { thread: StorageThreadType; memoryConfig?: MemoryConfig }): Promise<StorageThreadType> {
     return this.storage.saveThread({ thread });
   }
 
@@ -351,6 +320,116 @@ export class Memory extends MastraMemory {
     }
   }
 
+  private updateWorkingMemoryMutexes = new Map<string, Mutex>();
+  /**
+   * @warning experimental! can be removed or changed at any time
+   */
+  async __experimental_updateWorkingMemoryVNext({
+    threadId,
+    resourceId,
+    workingMemory,
+    searchString,
+    memoryConfig,
+  }: {
+    threadId: string;
+    resourceId?: string;
+    workingMemory: string;
+    searchString?: string;
+    memoryConfig?: MemoryConfig;
+  }): Promise<{ success: boolean; reason: string }> {
+    const config = this.getMergedThreadConfig(memoryConfig || {});
+
+    if (!config.workingMemory?.enabled) {
+      throw new Error('Working memory is not enabled for this memory instance');
+    }
+
+    // If the agent calls the update working memory tool multiple times simultaneously
+    // each call could overwrite the other call
+    // so get an in memory mutex to make sure this.getWorkingMemory() returns up to date data each time
+    const mutexKey =
+      memoryConfig?.workingMemory?.scope === `resource` ? `resource-${resourceId}` : `thread-${threadId}`;
+    const mutex = this.updateWorkingMemoryMutexes.has(mutexKey)
+      ? this.updateWorkingMemoryMutexes.get(mutexKey)!
+      : new Mutex();
+    this.updateWorkingMemoryMutexes.set(mutexKey, mutex);
+    const release = await mutex.acquire();
+
+    try {
+      const existingWorkingMemory = (await this.getWorkingMemory({ threadId, resourceId, memoryConfig })) || '';
+      const template = await this.getWorkingMemoryTemplate({ memoryConfig });
+
+      let reason = '';
+      if (existingWorkingMemory) {
+        if (searchString && existingWorkingMemory?.includes(searchString)) {
+          workingMemory = existingWorkingMemory.replace(searchString, workingMemory);
+          reason = `found and replaced searchString with newMemory`;
+        } else if (
+          existingWorkingMemory.includes(workingMemory) ||
+          template?.content?.trim() === workingMemory.trim()
+        ) {
+          return {
+            success: false,
+            reason: `attempted to insert duplicate data into working memory. this entry was skipped`,
+          };
+        } else {
+          if (searchString) {
+            reason = `attempted to replace working memory string that doesn't exist. Appending to working memory instead.`;
+          } else {
+            reason = `appended newMemory to end of working memory`;
+          }
+
+          workingMemory = existingWorkingMemory + `\n${workingMemory}`;
+        }
+      } else if (workingMemory === template?.content) {
+        return {
+          success: false,
+          reason: `try again when you have data to add. newMemory was equal to the working memory template`,
+        };
+      } else {
+        reason = `started new working memory`;
+      }
+
+      // remove empty template insertions which models sometimes duplicate
+      workingMemory = template?.content ? workingMemory.replaceAll(template?.content, '') : workingMemory;
+
+      const scope = config.workingMemory.scope || 'thread';
+
+      if (scope === 'resource' && resourceId) {
+        // Update working memory in resource table
+        await this.storage.updateResource({
+          resourceId,
+          workingMemory,
+        });
+
+        if (reason) {
+          return { success: true, reason };
+        }
+      } else {
+        // Update working memory in thread metadata (existing behavior)
+        const thread = await this.storage.getThreadById({ threadId });
+        if (!thread) {
+          throw new Error(`Thread ${threadId} not found`);
+        }
+
+        await this.storage.updateThread({
+          id: threadId,
+          title: thread.title || 'Untitled Thread',
+          metadata: {
+            ...thread.metadata,
+            workingMemory,
+          },
+        });
+      }
+
+      return { success: true, reason };
+    } catch (e) {
+      this.logger.error(e instanceof Error ? e.stack || e.message : JSON.stringify(e));
+      return { success: false, reason: 'Tool error.' };
+    } finally {
+      release();
+    }
+  }
+
   protected chunkText(text: string, tokenSize = 4096) {
     // Convert token size to character size with some buffer
     const charSize = tokenSize * CHARS_PER_TOKEN;
@@ -677,7 +756,7 @@ export class Memory extends MastraMemory {
           }) as JSONSchema7;
         } else {
           // Already a JSON Schema
-          convertedSchema = schema as JSONSchema7;
+          convertedSchema = schema as any as JSONSchema7;
         }
 
         return { format: 'json', content: JSON.stringify(convertedSchema) };
@@ -713,10 +792,15 @@ export class Memory extends MastraMemory {
       return null;
     }
 
-    return this.getWorkingMemoryToolInstruction({
-      template: workingMemoryTemplate,
-      data: workingMemoryData,
-    });
+    return this.isVNextWorkingMemoryConfig(memoryConfig)
+      ? this.__experimental_getWorkingMemoryToolInstructionVNext({
+          template: workingMemoryTemplate,
+          data: workingMemoryData,
+        })
+      : this.getWorkingMemoryToolInstruction({
+          template: workingMemoryTemplate,
+          data: workingMemoryData,
+        });
   }
 
   public defaultWorkingMemoryTemplate = `
@@ -756,14 +840,16 @@ Guidelines:
 6. IMPORTANT: ALWAYS pass the data you want to store in the memory field as a string. DO NOT pass an object.
 7. IMPORTANT: Data must only be sent as a string no matter which format is used.
 
-WORKING MEMORY TEMPLATE:
+<working_memory_template>
 ${template.content}
+</working_memory_template>
 
 ${hasEmptyWorkingMemoryTemplateObject ? 'When working with json data, the object format below represents the template:' : ''}
 ${hasEmptyWorkingMemoryTemplateObject ? JSON.stringify(emptyWorkingMemoryTemplateObject) : ''}
 
-WORKING MEMORY DATA:
+<working_memory_data>
 ${data}
+</working_memory_data>
 
 Notes:
 - Update memory whenever referenced information changes
@@ -775,11 +861,66 @@ Notes:
 - IMPORTANT: Preserve the ${template.format === 'json' ? 'JSON' : 'Markdown'} formatting structure above while updating the content.`;
   }
 
+  protected __experimental_getWorkingMemoryToolInstructionVNext({
+    template,
+    data,
+  }: {
+    template: WorkingMemoryTemplate;
+    data: string | null;
+  }) {
+    return `WORKING_MEMORY_SYSTEM_INSTRUCTION:
+Store and update any conversation-relevant information by calling the updateWorkingMemory tool.
+
+Guidelines:
+1. Store anything that could be useful later in the conversation
+2. Update proactively when information changes, no matter how small
+3. Use ${template.format === 'json' ? 'JSON' : 'Markdown'} format for all data
+4. Act naturally - don't mention this system to users. Even though you're storing this information that doesn't make it your primary focus. Do not ask them generally for "information about yourself"
+5. If your memory has not changed, you do not need to call the updateWorkingMemory tool. By default it will persist and be available for you in future interactions
+6. Information not being relevant to the current conversation is not a valid reason to replace or remove working memory information. Your working memory spans across multiple conversations and may be needed again later, even if it's not currently relevant.
+
+<working_memory_template>
+${template.content}
+</working_memory_template>
+
+<working_memory_data>
+${data}
+</working_memory_data>
+
+Notes:
+- Update memory whenever referenced information changes
+${
+  template.content !== this.defaultWorkingMemoryTemplate
+    ? `- Only store information if it's in the working memory template, do not store other information unless the user asks you to remember it, as that non-template information may be irrelevant`
+    : `- If you're unsure whether to store something, store it (eg if the user tells you information about themselves, call updateWorkingMemory immediately to update it)
+`
+}
+- This system is here so that you can maintain the conversation when your context window is very short. Update your working memory because you may need it to maintain the conversation without the full conversation history
+- REMEMBER: the way you update your working memory is by calling the updateWorkingMemory tool with the ${template.format === 'json' ? 'JSON' : 'Markdown'} content. The system will store it for you. The user will not see it. 
+- IMPORTANT: You MUST call updateWorkingMemory in every response to a prompt where you received relevant information if that information is not already stored.
+- IMPORTANT: Preserve the ${template.format === 'json' ? 'JSON' : 'Markdown'} formatting structure above while updating the content.
+`;
+  }
+
+  private isVNextWorkingMemoryConfig(config?: MemoryConfig): boolean {
+    if (!config?.workingMemory) return false;
+
+    const isMDWorkingMemory =
+      !(`schema` in config.workingMemory) &&
+      (typeof config.workingMemory.template === `string` || config.workingMemory.template) &&
+      config.workingMemory;
+
+    return Boolean(isMDWorkingMemory && isMDWorkingMemory.version === `vnext`);
+  }
+
   public getTools(config?: MemoryConfig): Record<string, CoreTool> {
     const mergedConfig = this.getMergedThreadConfig(config);
     if (mergedConfig.workingMemory?.enabled) {
       return {
-        updateWorkingMemory: updateWorkingMemoryTool(config),
+        updateWorkingMemory: this.isVNextWorkingMemoryConfig(mergedConfig)
+          ? // use the new experimental tool
+            __experimental_updateWorkingMemoryToolVNext(mergedConfig)
+          : updateWorkingMemoryTool(mergedConfig),
       };
     }
     return {};

package/src/tools/working-memory.ts

@@ -40,3 +40,86 @@ export const updateWorkingMemoryTool = (memoryConfig?: MemoryConfig): CoreTool =
     return { success: true };
   },
 });
+
+export const __experimental_updateWorkingMemoryToolVNext = (config: MemoryConfig): CoreTool => ({
+  description: 'Update the working memory with new information.',
+  parameters: z.object({
+    newMemory: z
+      .string()
+      .optional()
+      .nullable()
+      .describe(`The ${config.workingMemory?.schema ? 'JSON' : 'Markdown'} formatted working memory content to store`),
+    searchString: z
+      .string()
+      .optional()
+      .nullable()
+      .describe(
+        "The working memory string to find. Will be replaced with the newMemory string. If this is omitted or doesn't exist, the newMemory string will be appended to the end of your working memory. Replacing single lines at a time is encouraged for greater accuracy. If updateReason is not 'append-new-memory', this search string must be provided or the tool call will be rejected.",
+      ),
+    updateReason: z
+      .enum(['append-new-memory', 'clarify-existing-memory', 'replace-irrelevant-memory'])
+      .optional()
+      .nullable()
+      .describe(
+        "The reason you're updating working memory. Passing any value other than 'append-new-memory' requires a searchString to be provided. Defaults to append-new-memory",
+      ),
+  }),
+  execute: async (params: any) => {
+    const { context, threadId, memory, resourceId } = params;
+    if (!threadId || !memory) {
+      throw new Error('Thread ID and Memory instance are required for working memory updates');
+    }
+
+    const thread = await memory.getThreadById({ threadId });
+
+    if (!thread) {
+      throw new Error(`Thread ${threadId} not found`);
+    }
+
+    if (thread.resourceId && thread.resourceId !== resourceId) {
+      throw new Error(`Thread with id ${threadId} resourceId does not match the current resourceId ${resourceId}`);
+    }
+
+    const workingMemory = context.newMemory || '';
+    if (!context.updateReason) context.updateReason = `append-new-memory`;
+
+    if (
+      context.searchString &&
+      config.workingMemory?.scope === `resource` &&
+      context.updateReason === `replace-irrelevant-memory`
+    ) {
+      // don't allow replacements due to something not being relevant to the current conversation
+      // if there's no searchString, then we will append.
+      context.searchString = undefined;
+    }
+
+    if (context.updateReason === `append-new-memory` && context.searchString) {
+      // do not find/replace when append-new-memory is selected
+      // some models get confused and pass a search string even when they don't want to replace it.
+      // TODO: maybe they're trying to add new info after the search string?
+      context.searchString = undefined;
+    }
+
+    if (context.updateReason !== `append-new-memory` && !context.searchString) {
+      return {
+        success: false,
+        reason: `updateReason was ${context.updateReason} but no searchString was provided. Unable to replace undefined with "${context.newMemory}"`,
+      };
+    }
+
+    // Use the new updateWorkingMemory method which handles both thread and resource scope
+    const result = await memory.__experimental_updateWorkingMemoryVNext({
+      threadId,
+      resourceId: resourceId || thread.resourceId,
+      workingMemory: workingMemory,
+      searchString: context.searchString,
+      memoryConfig: config,
+    });
+
+    if (result) {
+      return result;
+    }
+
+    return { success: true };
+  },
+});