@mastra/memory 0.1.0-alpha.70 → 0.1.0-alpha.73

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @mastra/memory
 
+## 0.1.0-alpha.73
+
+### Minor Changes
+
+- d7d465a: Breaking change for Memory: embeddings: {} has been replaced with embedder: new OpenAIEmbedder() (or whichever embedder you want - check the docs)
+
+### Patch Changes
+
+- Updated dependencies [d7d465a]
+- Updated dependencies [d7d465a]
+- Updated dependencies [2017553]
+- Updated dependencies [a10b7a3]
+- Updated dependencies [16e5b04]
+  - @mastra/core@0.2.0-alpha.91
+
+## 0.1.0-alpha.72
+
+### Patch Changes
+
+- Updated dependencies [8151f44]
+- Updated dependencies [e897f1c]
+- Updated dependencies [3700be1]
+  - @mastra/core@0.2.0-alpha.90
+
+## 0.1.0-alpha.71
+
+### Minor Changes
+
+- 27275c9: Added new short term "working" memory for agents. Also added a "maskStreamTags" helper to assist in hiding working memory xml blocks in streamed responses
+
+### Patch Changes
+
+- Updated dependencies [27275c9]
+  - @mastra/core@0.2.0-alpha.89
+
 ## 0.1.0-alpha.70
 
 ### Patch Changes

package/dist/index.d.ts

@@ -8,7 +8,9 @@ import { Message } from 'ai';
  * and message injection.
  */
 declare class Memory extends MastraMemory {
-    constructor(config: SharedMemoryConfig);
+    constructor(config: SharedMemoryConfig & {
+        embeddings?: any;
+    });
     query({ threadId, selectBy, threadConfig, }: StorageGetMessagesArg): Promise<{
         messages: CoreMessage[];
         uiMessages: Message[];
@@ -27,18 +29,31 @@ declare class Memory extends MastraMemory {
     getThreadsByResourceId({ resourceId }: {
         resourceId: string;
     }): Promise<StorageThreadType[]>;
-    saveThread({ thread }: {
+    saveThread({ thread, memoryConfig, }: {
         thread: StorageThreadType;
+        memoryConfig?: MemoryConfig;
     }): Promise<StorageThreadType>;
     updateThread({ id, title, metadata, }: {
         id: string;
         title: string;
         metadata: Record<string, unknown>;
     }): Promise<StorageThreadType>;
+    deleteThread(threadId: string): Promise<void>;
     saveMessages({ messages }: {
         messages: MessageType[];
     }): Promise<MessageType[]>;
-    deleteThread(threadId: string): Promise<void>;
+    protected mutateMessagesToHideWorkingMemory(messages: MessageType[]): void;
+    protected parseWorkingMemory(text: string): string | null;
+    protected getWorkingMemory({ threadId }: {
+        threadId: string;
+    }): Promise<string | null>;
+    private saveWorkingMemory;
+    getSystemMessage({ threadId, memoryConfig, }: {
+        threadId: string;
+        memoryConfig?: MemoryConfig;
+    }): Promise<string | null>;
+    defaultWorkingMemoryTemplate: string;
+    private getWorkingMemoryWithInstruction;
 }
 
 export { Memory };

package/dist/index.js

@@ -1,9 +1,35 @@
+import { deepMerge } from '@mastra/core';
 import { MastraMemory } from '@mastra/core/memory';
 
 // src/index.ts
 var Memory = class extends MastraMemory {
   constructor(config) {
+    if (config.embeddings) {
+      throw new Error(
+        'The `embeddings` option is deprecated. Please use `embedder` instead. Example: new Memory({ embedder: new OpenAIEmbedder({ model: "text-embedding-3-small" }) })'
+      );
+    }
     super({ name: "Memory", ...config });
+    this.defaultWorkingMemoryTemplate = `
+<user>
+  <first_name></first_name>
+  <last_name></last_name>
+  <location></location>
+  <occupation></occupation>
+  <interests></interests>
+  <goals></goals>
+  <events></events>
+  <facts></facts>
+  <projects></projects>
+</user>
+`;
+    const mergedConfig = this.getMergedThreadConfig({
+      workingMemory: config.options?.workingMemory || {
+        enabled: false,
+        template: this.defaultWorkingMemoryTemplate
+      }
+    });
+    this.threadConfig = mergedConfig;
   }
   async query({
     threadId,
@@ -25,9 +51,10 @@ var Memory = class extends MastraMemory {
       messageRange: config?.semanticRecall?.messageRange || { before: 2, after: 2 }
     };
     if (selectBy?.vectorSearchString && this.vector) {
-      const { embeddings } = await this.vector.embed(selectBy.vectorSearchString, this.parseEmbeddingOptions());
+      const embedder = this.getEmbedder();
+      const { embedding } = await embedder.embed(selectBy.vectorSearchString);
       await this.vector.createIndex("memory_messages", 1536);
-      vectorResults = await this.vector.query("memory_messages", embeddings[0], vectorConfig.topK, {
+      vectorResults = await this.vector.query("memory_messages", embedding, vectorConfig.topK, {
         thread_id: threadId
       });
     }
@@ -78,7 +105,20 @@ var Memory = class extends MastraMemory {
   async getThreadsByResourceId({ resourceId }) {
     return this.storage.__getThreadsByResourceId({ resourceId });
   }
-  async saveThread({ thread }) {
+  async saveThread({
+    thread,
+    memoryConfig
+  }) {
+    const config = this.getMergedThreadConfig(memoryConfig || {});
+    if (config.workingMemory?.enabled && !thread?.metadata?.workingMemory) {
+      return this.storage.__saveThread({
+        thread: deepMerge(thread, {
+          metadata: {
+            workingMemory: config.workingMemory.template || this.defaultWorkingMemoryTemplate
+          }
+        })
+      });
+    }
     return this.storage.__saveThread({ thread });
   }
   async updateThread({
@@ -92,25 +132,126 @@ var Memory = class extends MastraMemory {
       metadata
     });
   }
+  async deleteThread(threadId) {
+    await this.storage.__deleteThread({ threadId });
+  }
   async saveMessages({ messages }) {
+    await this.saveWorkingMemory(messages);
+    this.mutateMessagesToHideWorkingMemory(messages);
     if (this.vector) {
       await this.vector.createIndex("memory_messages", 1536);
       for (const message of messages) {
         if (typeof message.content !== `string`) continue;
-        const { embeddings } = await this.vector.embed(message.content, this.parseEmbeddingOptions());
-        await this.vector.upsert("memory_messages", embeddings, [
-          {
-            text: message.content,
-            message_id: message.id,
-            thread_id: message.threadId
-          }
-        ]);
+        const embedder = this.getEmbedder();
+        const { embedding } = await embedder.embed(message.content);
+        await this.vector.upsert(
+          "memory_messages",
+          [embedding],
+          [
+            {
+              text: message.content,
+              message_id: message.id,
+              thread_id: message.threadId
+            }
+          ]
+        );
       }
     }
     return this.storage.__saveMessages({ messages });
   }
-  async deleteThread(threadId) {
-    await this.storage.__deleteThread({ threadId });
+  mutateMessagesToHideWorkingMemory(messages) {
+    const workingMemoryRegex = /<working_memory>([^]*?)<\/working_memory>/g;
+    for (const message of messages) {
+      if (typeof message?.content === `string`) {
+        message.content = message.content.replace(workingMemoryRegex, ``).trim();
+      } else if (Array.isArray(message?.content)) {
+        for (const content of message.content) {
+          if (content.type === `text`) {
+            content.text = content.text.replace(workingMemoryRegex, ``).trim();
+          }
+        }
+      }
+    }
+  }
+  parseWorkingMemory(text) {
+    if (!this.threadConfig.workingMemory?.enabled) return null;
+    const workingMemoryRegex = /<working_memory>([^]*?)<\/working_memory>/g;
+    const matches = text.match(workingMemoryRegex);
+    const match = matches?.[0];
+    if (match) {
+      return match.replace(/<\/?working_memory>/g, "").trim();
+    }
+    return null;
+  }
+  async getWorkingMemory({ threadId }) {
+    if (!this.threadConfig.workingMemory?.enabled) return null;
+    const thread = await this.storage.__getThreadById({ threadId });
+    if (!thread) return this.threadConfig?.workingMemory?.template || this.defaultWorkingMemoryTemplate;
+    const memory = thread.metadata?.workingMemory || this.threadConfig.workingMemory.template || this.defaultWorkingMemoryTemplate;
+    return memory.split(`>
+`).map((c) => c.trim()).join(`>`);
+  }
+  async saveWorkingMemory(messages) {
+    const latestMessage = messages[messages.length - 1];
+    if (!latestMessage || !this.threadConfig.workingMemory?.enabled) {
+      return;
+    }
+    const latestContent = !latestMessage?.content ? null : typeof latestMessage.content === "string" ? latestMessage.content : latestMessage.content.filter((c) => c.type === "text").map((c) => c.text).join("\n");
+    const threadId = latestMessage?.threadId;
+    if (!latestContent || !threadId) {
+      return;
+    }
+    const newMemory = this.parseWorkingMemory(latestContent);
+    if (!newMemory) {
+      return;
+    }
+    const thread = await this.storage.__getThreadById({ threadId });
+    if (!thread) return;
+    await this.storage.__updateThread({
+      id: thread.id,
+      title: thread.title || "",
+      metadata: deepMerge(thread.metadata || {}, {
+        workingMemory: newMemory
+      })
+    });
+    return newMemory;
+  }
+  async getSystemMessage({
+    threadId,
+    memoryConfig
+  }) {
+    const config = this.getMergedThreadConfig(memoryConfig);
+    if (!config.workingMemory?.enabled) {
+      return null;
+    }
+    const workingMemory = await this.getWorkingMemory({ threadId });
+    if (!workingMemory) {
+      return null;
+    }
+    return this.getWorkingMemoryWithInstruction(workingMemory);
+  }
+  getWorkingMemoryWithInstruction(workingMemoryBlock) {
+    return `WORKING_MEMORY_SYSTEM_INSTRUCTION:
+Store and update any conversation-relevant information by including "<working_memory>text</working_memory>" in your responses. Updates replace existing memory while maintaining this structure. If information might be referenced again - store it!
+
+Guidelines:
+1. Store anything that could be useful later in the conversation
+2. Update proactively when information changes, no matter how small
+3. Use nested tags 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"
+
+Memory Structure:
+<working_memory>
+  ${workingMemoryBlock}
+</working_memory>
+
+Notes:
+- Update memory whenever referenced information changes
+- If you're unsure whether to store something, store it (eg if the user tells you their name or the value of another empty section in your working memory, output the <working_memory> block 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
+- Do not remove empty sections - you must output the empty sections along with the ones you're filling in
+- REMEMBER: the way you update your working memory is by outputting the entire "<working_memory>text</working_memory>" block in your response. The system will pick this up and store it for you. The user will not see it.
+- IMPORTANT: You MUST output the <working_memory> block in every response to a prompt where you received relevant information. `;
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/memory",
-  "version": "0.1.0-alpha.70",
+  "version": "0.1.0-alpha.73",
   "description": "",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,7 +36,7 @@
     "pg-pool": "^3.7.0",
     "postgres": "^3.4.5",
     "redis": "^4.7.0",
-    "@mastra/core": "^0.2.0-alpha.88"
+    "@mastra/core": "^0.2.0-alpha.91"
   },
   "devDependencies": {
     "@babel/preset-env": "^7.26.0",
@@ -48,7 +48,8 @@
     "vitest": "^3.0.4"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --treeshake",
+    "check": "tsc --noEmit",
+    "build": "pnpm run check && tsup src/index.ts --format esm --dts --clean --treeshake",
     "dev": "tsup src/index.ts --format esm --dts --clean --watch",
     "test:integration": "cd integration-tests && pnpm run test",
     "test": "pnpm test:integration"

package/src/index.ts

@@ -1,4 +1,4 @@
-import { CoreMessage } from '@mastra/core';
+import { CoreMessage, deepMerge } from '@mastra/core';
 import { MastraMemory, MessageType, MemoryConfig, SharedMemoryConfig, StorageThreadType } from '@mastra/core/memory';
 import { StorageGetMessagesArg } from '@mastra/core/storage';
 import { Message as AiMessage } from 'ai';
@@ -8,8 +8,28 @@ import { Message as AiMessage } from 'ai';
  * and message injection.
  */
 export class Memory extends MastraMemory {
-  constructor(config: SharedMemoryConfig) {
+  constructor(
+    config: SharedMemoryConfig & {
+      /* @deprecated use embedder instead */
+      embeddings?: any;
+    },
+  ) {
+    // Check for deprecated embeddings object
+    if (config.embeddings) {
+      throw new Error(
+        'The `embeddings` option is deprecated. Please use `embedder` instead. Example: new Memory({ embedder: new OpenAIEmbedder({ model: "text-embedding-3-small" }) })',
+      );
+    }
+
     super({ name: 'Memory', ...config });
+
+    const mergedConfig = this.getMergedThreadConfig({
+      workingMemory: config.options?.workingMemory || {
+        enabled: false,
+        template: this.defaultWorkingMemoryTemplate,
+      },
+    });
+    this.threadConfig = mergedConfig;
   }
 
   async query({
@@ -46,10 +66,11 @@ export class Memory extends MastraMemory {
           };
 
     if (selectBy?.vectorSearchString && this.vector) {
-      const { embeddings } = await this.vector.embed(selectBy.vectorSearchString, this.parseEmbeddingOptions());
+      const embedder = this.getEmbedder();
+      const { embedding } = await embedder.embed(selectBy.vectorSearchString);
 
       await this.vector.createIndex('memory_messages', 1536);
-      vectorResults = await this.vector.query('memory_messages', embeddings[0]!, vectorConfig.topK, {
+      vectorResults = await this.vector.query('memory_messages', embedding, vectorConfig.topK, {
         thread_id: threadId,
       });
     }
@@ -124,7 +145,26 @@ export class Memory extends MastraMemory {
     return this.storage.__getThreadsByResourceId({ resourceId });
   }
 
-  async saveThread({ thread }: { thread: StorageThreadType }): Promise<StorageThreadType> {
+  async saveThread({
+    thread,
+    memoryConfig,
+  }: {
+    thread: StorageThreadType;
+    memoryConfig?: MemoryConfig;
+  }): Promise<StorageThreadType> {
+    const config = this.getMergedThreadConfig(memoryConfig || {});
+
+    if (config.workingMemory?.enabled && !thread?.metadata?.workingMemory) {
+      // if working memory is enabled but the thread doesn't have it, we need to set it
+      return this.storage.__saveThread({
+        thread: deepMerge(thread, {
+          metadata: {
+            workingMemory: config.workingMemory.template || this.defaultWorkingMemoryTemplate,
+          },
+        }),
+      });
+    }
+
     return this.storage.__saveThread({ thread });
   }
 
@@ -144,30 +184,189 @@ export class Memory extends MastraMemory {
     });
   }
 
+  async deleteThread(threadId: string): Promise<void> {
+    await this.storage.__deleteThread({ threadId });
+
+    // TODO: Also clean up vector storage if it exists
+    // if (this.vector) {
+    //   await this.vector.deleteThread(threadId); ?? filter by thread attributes and delete all returned messages?
+    // }
+  }
+
   async saveMessages({ messages }: { messages: MessageType[] }): Promise<MessageType[]> {
+    // First save working memory from any messages
+    await this.saveWorkingMemory(messages);
+
+    // Then strip working memory tags from all messages
+    this.mutateMessagesToHideWorkingMemory(messages);
+
     if (this.vector) {
       await this.vector.createIndex('memory_messages', 1536);
       for (const message of messages) {
         if (typeof message.content !== `string`) continue;
-        const { embeddings } = await this.vector.embed(message.content, this.parseEmbeddingOptions());
-        await this.vector.upsert('memory_messages', embeddings, [
-          {
-            text: message.content,
-            message_id: message.id,
-            thread_id: message.threadId,
-          },
-        ]);
+        const embedder = this.getEmbedder();
+        const { embedding } = await embedder.embed(message.content);
+        await this.vector.upsert(
+          'memory_messages',
+          [embedding],
+          [
+            {
+              text: message.content,
+              message_id: message.id,
+              thread_id: message.threadId,
+            },
+          ],
+        );
       }
     }
+
     return this.storage.__saveMessages({ messages });
   }
 
-  async deleteThread(threadId: string): Promise<void> {
-    await this.storage.__deleteThread({ threadId });
+  protected mutateMessagesToHideWorkingMemory(messages: MessageType[]) {
+    const workingMemoryRegex = /<working_memory>([^]*?)<\/working_memory>/g;
+    for (const message of messages) {
+      if (typeof message?.content === `string`) {
+        message.content = message.content.replace(workingMemoryRegex, ``).trim();
+      } else if (Array.isArray(message?.content)) {
+        for (const content of message.content) {
+          if (content.type === `text`) {
+            content.text = content.text.replace(workingMemoryRegex, ``).trim();
+          }
+        }
+      }
+    }
+  }
 
-    // TODO: Also clean up vector storage if it exists
-    // if (this.vector) {
-    //   await this.vector.deleteThread(threadId); ?? filter by thread attributes and delete all returned messages?
-    // }
+  protected parseWorkingMemory(text: string): string | null {
+    if (!this.threadConfig.workingMemory?.enabled) return null;
+
+    const workingMemoryRegex = /<working_memory>([^]*?)<\/working_memory>/g;
+    const matches = text.match(workingMemoryRegex);
+    const match = matches?.[0];
+
+    if (match) {
+      return match.replace(/<\/?working_memory>/g, '').trim();
+    }
+
+    return null;
+  }
+
+  protected async getWorkingMemory({ threadId }: { threadId: string }): Promise<string | null> {
+    if (!this.threadConfig.workingMemory?.enabled) return null;
+
+    // Get thread from storage
+    const thread = await this.storage.__getThreadById({ threadId });
+    if (!thread) return this.threadConfig?.workingMemory?.template || this.defaultWorkingMemoryTemplate;
+
+    // Return working memory from metadata
+    const memory =
+      (thread.metadata?.workingMemory as string) ||
+      this.threadConfig.workingMemory.template ||
+      this.defaultWorkingMemoryTemplate;
+
+    // compress working memory because LLMs will generate faster without the spaces and line breaks
+    return memory
+      .split(`>\n`)
+      .map(c => c.trim()) // remove extra whitespace
+      .join(`>`); // and linebreaks
+  }
+
+  private async saveWorkingMemory(messages: MessageType[]) {
+    const latestMessage = messages[messages.length - 1];
+
+    if (!latestMessage || !this.threadConfig.workingMemory?.enabled) {
+      return;
+    }
+
+    const latestContent = !latestMessage?.content
+      ? null
+      : typeof latestMessage.content === 'string'
+        ? latestMessage.content
+        : latestMessage.content
+            .filter(c => c.type === 'text')
+            .map(c => c.text)
+            .join('\n');
+
+    const threadId = latestMessage?.threadId;
+    if (!latestContent || !threadId) {
+      return;
+    }
+
+    const newMemory = this.parseWorkingMemory(latestContent);
+    if (!newMemory) {
+      return;
+    }
+
+    const thread = await this.storage.__getThreadById({ threadId });
+    if (!thread) return;
+
+    // Update thread metadata with new working memory
+    await this.storage.__updateThread({
+      id: thread.id,
+      title: thread.title || '',
+      metadata: deepMerge(thread.metadata || {}, {
+        workingMemory: newMemory,
+      }),
+    });
+    return newMemory;
+  }
+
+  public async getSystemMessage({
+    threadId,
+    memoryConfig,
+  }: {
+    threadId: string;
+    memoryConfig?: MemoryConfig;
+  }): Promise<string | null> {
+    const config = this.getMergedThreadConfig(memoryConfig);
+    if (!config.workingMemory?.enabled) {
+      return null;
+    }
+
+    const workingMemory = await this.getWorkingMemory({ threadId });
+    if (!workingMemory) {
+      return null;
+    }
+
+    return this.getWorkingMemoryWithInstruction(workingMemory);
+  }
+
+  public defaultWorkingMemoryTemplate = `
+<user>
+  <first_name></first_name>
+  <last_name></last_name>
+  <location></location>
+  <occupation></occupation>
+  <interests></interests>
+  <goals></goals>
+  <events></events>
+  <facts></facts>
+  <projects></projects>
+</user>
+`;
+
+  private getWorkingMemoryWithInstruction(workingMemoryBlock: string) {
+    return `WORKING_MEMORY_SYSTEM_INSTRUCTION:
+Store and update any conversation-relevant information by including "<working_memory>text</working_memory>" in your responses. Updates replace existing memory while maintaining this structure. If information might be referenced again - store it!
+
+Guidelines:
+1. Store anything that could be useful later in the conversation
+2. Update proactively when information changes, no matter how small
+3. Use nested tags 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"
+
+Memory Structure:
+<working_memory>
+  ${workingMemoryBlock}
+</working_memory>
+
+Notes:
+- Update memory whenever referenced information changes
+- If you're unsure whether to store something, store it (eg if the user tells you their name or the value of another empty section in your working memory, output the <working_memory> block 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
+- Do not remove empty sections - you must output the empty sections along with the ones you're filling in
+- REMEMBER: the way you update your working memory is by outputting the entire "<working_memory>text</working_memory>" block in your response. The system will pick this up and store it for you. The user will not see it.
+- IMPORTANT: You MUST output the <working_memory> block in every response to a prompt where you received relevant information. `;
   }
 }