@mastra/memory 0.1.0-alpha.83 → 0.1.0-alpha.85

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/memory
 
+## 0.1.0-alpha.85
+
+### Patch Changes
+
+- Updated dependencies [4534e77]
+  - @mastra/core@0.2.0-alpha.103
+
+## 0.1.0-alpha.84
+
+### Patch Changes
+
+- Updated dependencies [a9345f9]
+  - @mastra/core@0.2.0-alpha.102
+
 ## 0.1.0-alpha.83
 
 ### Patch Changes

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

@@ -0,0 +1,63 @@
+import { CoreMessage } from '@mastra/core';
+import { MastraMemory } from '@mastra/core/memory';
+import { MemoryConfig } from '@mastra/core/memory';
+import { Message } from 'ai';
+import { MessageType } from '@mastra/core/memory';
+import { SharedMemoryConfig } from '@mastra/core/memory';
+import { StorageGetMessagesArg } from '@mastra/core/storage';
+import { StorageThreadType } from '@mastra/core/memory';
+
+/**
+ * Concrete implementation of MastraMemory that adds support for thread configuration
+ * and message injection.
+ */
+export declare class Memory extends MastraMemory {
+    constructor(config: SharedMemoryConfig & {
+        embeddings?: any;
+    });
+    query({ threadId, selectBy, threadConfig, }: StorageGetMessagesArg): Promise<{
+        messages: CoreMessage[];
+        uiMessages: Message[];
+    }>;
+    rememberMessages({ threadId, vectorMessageSearch, config, }: {
+        threadId: string;
+        vectorMessageSearch?: string;
+        config?: MemoryConfig;
+    }): Promise<{
+        messages: CoreMessage[];
+        uiMessages: Message[];
+    }>;
+    getThreadById({ threadId }: {
+        threadId: string;
+    }): Promise<StorageThreadType | null>;
+    getThreadsByResourceId({ resourceId }: {
+        resourceId: string;
+    }): Promise<StorageThreadType[]>;
+    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[]>;
+    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 { }

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { Memory } from './_tsup-dts-rollup.js';

package/dist/index.js

@@ -0,0 +1,282 @@
+import { deepMerge } from '@mastra/core';
+import { MastraMemory } from '@mastra/core/memory';
+import '@mastra/core/storage';
+import { embed } from 'ai';
+
+// src/index.ts
+var Memory = class extends MastraMemory {
+  constructor(config) {
+    const embedderExample = `
+Example: 
+
+  import { openai } from '@ai-sdk/openai';
+
+  new Memory({ 
+    embedder: openai.embedding(\`text-embedding-3-small\`)
+  })
+
+`;
+    if (config.embeddings) {
+      throw new Error(
+        `The \`embeddings\` option is deprecated. Please use \`embedder\` instead.
+${embedderExample}
+`
+      );
+    }
+    if (config.vector && !config.embedder) {
+      throw new Error(
+        `The \`embedder\` option is required when a vector DB is attached to new Memory({ vector })
+
+${embedderExample}`
+      );
+    }
+    super({ name: "Memory", ...config });
+    const mergedConfig = this.getMergedThreadConfig({
+      workingMemory: config.options?.workingMemory || {
+        enabled: false,
+        template: this.defaultWorkingMemoryTemplate
+      }
+    });
+    this.threadConfig = mergedConfig;
+  }
+  async query({
+    threadId,
+    selectBy,
+    threadConfig
+  }) {
+    let vectorResults = null;
+    this.logger.info(`Memory query() with:`, {
+      threadId,
+      selectBy,
+      threadConfig
+    });
+    const config = this.getMergedThreadConfig(threadConfig || {});
+    const vectorConfig = typeof config?.semanticRecall === `boolean` ? {
+      topK: 2,
+      messageRange: { before: 2, after: 2 }
+    } : {
+      topK: config?.semanticRecall?.topK || 2,
+      messageRange: config?.semanticRecall?.messageRange || { before: 2, after: 2 }
+    };
+    if (selectBy?.vectorSearchString && this.vector) {
+      const embedder = this.getEmbedder();
+      const { embedding } = await embed({
+        value: selectBy.vectorSearchString,
+        model: embedder
+      });
+      const { indexName } = await this.createEmbeddingIndex();
+      vectorResults = await this.vector.query(indexName, embedding, vectorConfig.topK, {
+        thread_id: threadId
+      });
+    }
+    const rawMessages = await this.storage.__getMessages({
+      threadId,
+      selectBy: {
+        ...selectBy,
+        ...vectorResults?.length ? {
+          include: vectorResults.map((r) => ({
+            id: r.metadata?.message_id,
+            withNextMessages: typeof vectorConfig.messageRange === "number" ? vectorConfig.messageRange : vectorConfig.messageRange.after,
+            withPreviousMessages: typeof vectorConfig.messageRange === "number" ? vectorConfig.messageRange : vectorConfig.messageRange.before
+          }))
+        } : {}
+      },
+      threadConfig: config
+    });
+    const messages = this.parseMessages(rawMessages);
+    const uiMessages = this.convertToUIMessages(rawMessages);
+    return { messages, uiMessages };
+  }
+  async rememberMessages({
+    threadId,
+    vectorMessageSearch,
+    config
+  }) {
+    const threadConfig = this.getMergedThreadConfig(config || {});
+    if (!threadConfig.lastMessages && !threadConfig.semanticRecall) {
+      return {
+        messages: [],
+        uiMessages: []
+      };
+    }
+    const messages = await this.query({
+      threadId,
+      selectBy: {
+        last: threadConfig.lastMessages,
+        vectorSearchString: threadConfig.semanticRecall && vectorMessageSearch ? vectorMessageSearch : undefined
+      },
+      threadConfig: config
+    });
+    this.logger.info(`Remembered message history includes ${messages.messages.length} messages.`);
+    return messages;
+  }
+  async getThreadById({ threadId }) {
+    return this.storage.__getThreadById({ threadId });
+  }
+  async getThreadsByResourceId({ resourceId }) {
+    return this.storage.__getThreadsByResourceId({ resourceId });
+  }
+  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({
+    id,
+    title,
+    metadata
+  }) {
+    return this.storage.__updateThread({
+      id,
+      title,
+      metadata
+    });
+  }
+  async deleteThread(threadId) {
+    await this.storage.__deleteThread({ threadId });
+  }
+  async saveMessages({ messages }) {
+    await this.saveWorkingMemory(messages);
+    this.mutateMessagesToHideWorkingMemory(messages);
+    if (this.vector) {
+      const embedder = this.getEmbedder();
+      const { indexName } = await this.createEmbeddingIndex();
+      for (const message of messages) {
+        if (typeof message.content !== `string`) continue;
+        const { embedding } = await embed({ value: message.content, model: embedder, maxRetries: 3 });
+        await this.vector.upsert(
+          indexName,
+          [embedding],
+          [
+            {
+              text: message.content,
+              message_id: message.id,
+              thread_id: message.threadId
+            }
+          ]
+        );
+      }
+    }
+    return this.storage.__saveMessages({ messages });
+  }
+  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);
+  }
+  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>
+`;
+  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. `;
+  }
+};
+
+export { Memory };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/memory",
-  "version": "0.1.0-alpha.83",
+  "version": "0.1.0-alpha.85",
   "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.101"
+    "@mastra/core": "^0.2.0-alpha.103"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.49.2",