@mastra/memory 0.12.2 → 0.13.0

package/integration-tests-v5/src/agent-memory.test.ts

@@ -0,0 +1,621 @@
+import { randomUUID } from 'node:crypto';
+import { google } from '@ai-sdk/google';
+import { openai } from '@ai-sdk/openai';
+import { Mastra } from '@mastra/core';
+import type { CoreMessage } from '@mastra/core';
+import { Agent } from '@mastra/core/agent';
+import type { UIMessageWithMetadata } from '@mastra/core/agent';
+import { RuntimeContext } from '@mastra/core/runtime-context';
+import { MockStore } from '@mastra/core/storage';
+import { fastembed } from '@mastra/fastembed';
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql';
+import { Memory } from '@mastra/memory';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { memoryProcessorAgent, weatherAgent } from './mastra/agents/weather';
+import { weatherTool, weatherToolCity } from './mastra/tools/weather';
+
+describe('Agent Memory Tests', () => {
+  const dbFile = 'file:mastra-agent.db';
+
+  it(`inherits storage from Mastra instance`, async () => {
+    const agent = new Agent({
+      name: 'test',
+      instructions: '',
+      model: openai('gpt-4o-mini'),
+      memory: new Memory({
+        options: {
+          lastMessages: 10,
+        },
+      }),
+    });
+    const mastra = new Mastra({
+      agents: {
+        agent,
+      },
+      storage: new LibSQLStore({
+        url: dbFile,
+      }),
+    });
+    const agentMemory = (await mastra.getAgent('agent').getMemory())!;
+    await expect(agentMemory.query({ threadId: '1' })).resolves.not.toThrow();
+    const agentMemory2 = (await agent.getMemory())!;
+    await expect(agentMemory2.query({ threadId: '1' })).resolves.not.toThrow();
+  });
+
+  it('should inherit storage from Mastra instance when workingMemory is enabled', async () => {
+    const mastra = new Mastra({
+      storage: new LibSQLStore({
+        url: dbFile,
+      }),
+      agents: {
+        testAgent: new Agent({
+          name: 'Test Agent',
+          instructions: 'You are a test agent',
+          model: openai('gpt-4o-mini'),
+          memory: new Memory({
+            options: {
+              workingMemory: {
+                enabled: true,
+              },
+            },
+          }),
+        }),
+      },
+    });
+
+    const agent = mastra.getAgent('testAgent');
+    const memory = await agent.getMemory();
+    expect(memory).toBeDefined();
+
+    // Should be able to create a thread and use working memory
+    const thread = await memory!.createThread({
+      resourceId: 'test-resource',
+      title: 'Test Thread',
+    });
+
+    expect(thread).toBeDefined();
+    expect(thread.id).toBeDefined();
+
+    // Should be able to update working memory without error
+    await memory!.updateWorkingMemory({
+      threadId: thread.id,
+      resourceId: 'test-resource',
+      workingMemory: '# Test Working Memory\n- Name: Test User',
+    });
+
+    // Should be able to retrieve working memory
+    const workingMemoryData = await memory!.getWorkingMemory({
+      threadId: thread.id,
+      resourceId: 'test-resource',
+    });
+
+    expect(workingMemoryData).toBe('# Test Working Memory\n- Name: Test User');
+  });
+
+  it('should work with resource-scoped working memory when storage supports it', async () => {
+    const mastra = new Mastra({
+      storage: new LibSQLStore({
+        url: dbFile,
+      }),
+      agents: {
+        testAgent: new Agent({
+          name: 'Test Agent',
+          instructions: 'You are a test agent',
+          model: openai('gpt-4o-mini'),
+          memory: new Memory({
+            options: {
+              workingMemory: {
+                enabled: true,
+                scope: 'resource',
+              },
+            },
+          }),
+        }),
+      },
+    });
+
+    const agent = mastra.getAgent('testAgent');
+    const memory = await agent.getMemory();
+
+    expect(memory).toBeDefined();
+
+    // Create a thread
+    const thread = await memory!.createThread({
+      resourceId: 'test-resource',
+      title: 'Test Thread',
+    });
+
+    // Update resource-scoped working memory
+    await memory!.updateWorkingMemory({
+      threadId: thread.id,
+      resourceId: 'test-resource',
+      workingMemory: '# Resource Memory\n- Shared across threads',
+    });
+
+    const workingMemoryData = await memory!.getWorkingMemory({
+      threadId: thread.id,
+      resourceId: 'test-resource',
+    });
+
+    expect(workingMemoryData).toBe('# Resource Memory\n- Shared across threads');
+  });
+
+  describe('Agent memory message persistence', () => {
+    // making a separate memory for agent to avoid conflicts with other tests
+    const memory = new Memory({
+      options: {
+        lastMessages: 10,
+        semanticRecall: true,
+      },
+      storage: new LibSQLStore({
+        url: dbFile,
+      }),
+      vector: new LibSQLVector({
+        connectionUrl: dbFile,
+      }),
+      embedder: fastembed,
+    });
+    const agent = new Agent({
+      name: 'test',
+      instructions:
+        'You are a weather agent. When asked about weather in any city, use the get_weather tool with the city name as the postal code.',
+      model: openai('gpt-4o'),
+      memory,
+      tools: { get_weather: weatherTool },
+    });
+    it('should save all user messages (not just the most recent)', async () => {
+      const threadId = randomUUID();
+      const resourceId = 'all-user-messages';
+
+      // Send multiple user messages
+      await agent.generateVNext(
+        [
+          { role: 'user', content: 'First message' },
+          { role: 'user', content: 'Second message' },
+        ],
+        {
+          threadId,
+          resourceId,
+        },
+      );
+
+      // Fetch messages from memory
+      const agentMemory = (await agent.getMemory())!;
+      const { messages, uiMessages } = await agentMemory.query({ threadId });
+      const userMessages = messages.filter((m: any) => m.role === 'user').map((m: any) => m.content);
+      const userUiMessages = uiMessages.filter((m: any) => m.role === 'user').map((m: any) => m.content);
+
+      expect(userMessages).toEqual(expect.arrayContaining(['First message', 'Second message']));
+      expect(userUiMessages).toEqual(expect.arrayContaining(['First message', 'Second message']));
+    });
+
+    it('should save assistant responses for both text and object output modes', async () => {
+      const threadId = randomUUID();
+      const resourceId = 'assistant-responses';
+      // 1. Text mode
+      await agent.generateVNext([{ role: 'user', content: 'What is 2+2?' }], {
+        threadId,
+        resourceId,
+        modelSettings: {
+          temperature: 0,
+        },
+      });
+
+      // 2. Object/output mode
+      await agent.generateVNext([{ role: 'user', content: 'Give me JSON' }], {
+        threadId,
+        resourceId,
+        output: z.object({
+          result: z.string(),
+        }),
+        modelSettings: {
+          temperature: 0,
+        },
+      });
+
+      // Fetch messages from memory
+      const agentMemory = (await agent.getMemory())!;
+      const { messages, uiMessages } = await agentMemory.query({ threadId });
+      const userMessages = messages.filter((m: any) => m.role === 'user').map((m: any) => m.content);
+      const userUiMessages = uiMessages.filter((m: any) => m.role === 'user').map((m: any) => m.content);
+      const assistantMessages = messages.filter((m: any) => m.role === 'assistant').map((m: any) => m.content);
+      const assistantUiMessages = uiMessages.filter((m: any) => m.role === 'assistant').map((m: any) => m.content);
+      expect(userMessages).toEqual(expect.arrayContaining(['What is 2+2?', 'Give me JSON']));
+      expect(userUiMessages).toEqual(expect.arrayContaining(['What is 2+2?', 'Give me JSON']));
+      function flattenAssistantMessages(messages: any[]) {
+        return messages.flatMap(msg =>
+          Array.isArray(msg) ? msg.map(part => (typeof part === 'object' && part.text ? part.text : part)) : msg,
+        );
+      }
+
+      expect(flattenAssistantMessages(assistantMessages)).toEqual(
+        expect.arrayContaining([expect.stringContaining('2 + 2'), expect.stringContaining('"result"')]),
+      );
+
+      expect(flattenAssistantMessages(assistantUiMessages)).toEqual(
+        expect.arrayContaining([expect.stringContaining('2 + 2'), expect.stringContaining('"result"')]),
+      );
+    });
+
+    it('should not save messages provided in the context option', async () => {
+      const threadId = randomUUID();
+      const resourceId = 'context-option-messages-not-saved';
+
+      const userMessageContent = 'This is a user message.';
+      const contextMessageContent1 = 'This is the first context message.';
+      const contextMessageContent2 = 'This is the second context message.';
+
+      // Send user messages and context messages
+      await agent.generateVNext(userMessageContent, {
+        threadId,
+        resourceId,
+        context: [
+          { role: 'system', content: contextMessageContent1 },
+          { role: 'user', content: contextMessageContent2 },
+        ],
+      });
+
+      // Fetch messages from memory
+      const agentMemory = (await agent.getMemory())!;
+      const { messages } = await agentMemory.query({ threadId });
+
+      // Assert that the context messages are NOT saved
+      const savedContextMessages = messages.filter(
+        (m: any) => m.content === contextMessageContent1 || m.content === contextMessageContent2,
+      );
+      expect(savedContextMessages.length).toBe(0);
+
+      // Assert that the user message IS saved
+      const savedUserMessages = messages.filter((m: any) => m.role === 'user');
+      expect(savedUserMessages.length).toBe(1);
+      expect(savedUserMessages[0].content).toBe(userMessageContent);
+    });
+
+    it('should persist UIMessageWithMetadata through agent generate and memory', async () => {
+      const threadId = randomUUID();
+      const resourceId = 'ui-message-metadata';
+
+      // Create messages with metadata
+      const messagesWithMetadata: UIMessageWithMetadata[] = [
+        {
+          id: 'msg1',
+          role: 'user',
+          content: 'Hello with metadata',
+          parts: [{ type: 'text', text: 'Hello with metadata' }],
+          metadata: {
+            source: 'web-ui',
+            timestamp: Date.now(),
+            customField: 'custom-value',
+          },
+        },
+        {
+          id: 'msg2',
+          role: 'user',
+          content: 'Another message with different metadata',
+          parts: [{ type: 'text', text: 'Another message with different metadata' }],
+          metadata: {
+            source: 'mobile-app',
+            version: '1.0.0',
+            userId: 'user-123',
+          },
+        },
+      ];
+
+      // Send messages with metadata
+      await agent.generateVNext(messagesWithMetadata, {
+        threadId,
+        resourceId,
+      });
+
+      // Fetch messages from memory
+      const agentMemory = (await agent.getMemory())!;
+      const { uiMessages } = await agentMemory.query({ threadId });
+
+      // Check that all user messages were saved
+      const savedUserMessages = uiMessages.filter((m: any) => m.role === 'user');
+      expect(savedUserMessages.length).toBe(2);
+
+      // Check that metadata was persisted in the stored messages
+      const firstMessage = uiMessages.find((m: any) => m.content === 'Hello with metadata');
+      const secondMessage = uiMessages.find((m: any) => m.content === 'Another message with different metadata');
+
+      expect(firstMessage).toBeDefined();
+      expect(firstMessage!.metadata).toEqual({
+        source: 'web-ui',
+        timestamp: expect.any(Number),
+        customField: 'custom-value',
+      });
+
+      expect(secondMessage).toBeDefined();
+      expect(secondMessage!.metadata).toEqual({
+        source: 'mobile-app',
+        version: '1.0.0',
+        userId: 'user-123',
+      });
+
+      // Check UI messages also preserve metadata
+      const firstUIMessage = uiMessages.find((m: any) => m.content === 'Hello with metadata');
+      const secondUIMessage = uiMessages.find((m: any) => m.content === 'Another message with different metadata');
+
+      expect(firstUIMessage?.metadata).toEqual({
+        source: 'web-ui',
+        timestamp: expect.any(Number),
+        customField: 'custom-value',
+      });
+
+      expect(secondUIMessage?.metadata).toEqual({
+        source: 'mobile-app',
+        version: '1.0.0',
+        userId: 'user-123',
+      });
+    });
+  });
+
+  describe('Agent thread metadata with generateTitle', () => {
+    // Agent with generateTitle: true
+    const memoryWithTitle = new Memory({
+      options: {
+        threads: { generateTitle: true },
+        semanticRecall: true,
+        lastMessages: 10,
+      },
+      storage: new LibSQLStore({ url: dbFile }),
+      vector: new LibSQLVector({ connectionUrl: dbFile }),
+      embedder: fastembed,
+    });
+    const agentWithTitle = new Agent({
+      name: 'title-on',
+      instructions: 'Test agent with generateTitle on.',
+      model: openai('gpt-4o'),
+      memory: memoryWithTitle,
+      tools: { get_weather: weatherTool },
+    });
+
+    const agentWithDynamicModelTitle = new Agent({
+      name: 'title-on',
+      instructions: 'Test agent with generateTitle on.',
+      model: ({ runtimeContext }) => openai(runtimeContext.get('model') as string),
+      memory: memoryWithTitle,
+      tools: { get_weather: weatherTool },
+    });
+
+    // Agent with generateTitle: false
+    const memoryNoTitle = new Memory({
+      options: {
+        threads: { generateTitle: false },
+        semanticRecall: true,
+        lastMessages: 10,
+      },
+      storage: new LibSQLStore({ url: dbFile }),
+      vector: new LibSQLVector({ connectionUrl: dbFile }),
+      embedder: fastembed,
+    });
+    const agentNoTitle = new Agent({
+      name: 'title-off',
+      instructions: 'Test agent with generateTitle off.',
+      model: openai('gpt-4o'),
+      memory: memoryNoTitle,
+      tools: { get_weather: weatherTool },
+    });
+
+    it('should preserve metadata when generateTitle is true', async () => {
+      const threadId = randomUUID();
+      const resourceId = 'gen-title-metadata';
+      const metadata = { foo: 'bar', custom: 123 };
+
+      const thread = await memoryWithTitle.createThread({
+        threadId,
+        resourceId,
+        metadata,
+      });
+
+      expect(thread).toBeDefined();
+      expect(thread?.metadata).toMatchObject(metadata);
+
+      await agentWithTitle.generateVNext([{ role: 'user', content: 'Hello, world!' }], { threadId, resourceId });
+      await agentWithTitle.generateVNext([{ role: 'user', content: 'Hello, world!' }], { threadId, resourceId });
+
+      const existingThread = await memoryWithTitle.getThreadById({ threadId });
+      expect(existingThread).toBeDefined();
+      expect(existingThread?.metadata).toMatchObject(metadata);
+    });
+
+    it('should use generateTitle with runtime context', async () => {
+      const threadId = randomUUID();
+      const resourceId = 'gen-title-metadata';
+      const metadata = { foo: 'bar', custom: 123 };
+
+      const thread = await memoryWithTitle.createThread({
+        threadId,
+        resourceId,
+        metadata,
+      });
+
+      expect(thread).toBeDefined();
+      expect(thread?.metadata).toMatchObject(metadata);
+
+      const runtimeContext = new RuntimeContext();
+      runtimeContext.set('model', 'gpt-4o-mini');
+      await agentWithDynamicModelTitle.generateVNext([{ role: 'user', content: 'Hello, world!' }], {
+        threadId,
+        resourceId,
+        runtimeContext,
+      });
+
+      const existingThread = await memoryWithTitle.getThreadById({ threadId });
+      expect(existingThread).toBeDefined();
+      expect(existingThread?.metadata).toMatchObject(metadata);
+    });
+
+    it('should preserve metadata when generateTitle is false', async () => {
+      const threadId = randomUUID();
+      const resourceId = 'no-gen-title-metadata';
+      const metadata = { foo: 'baz', custom: 456 };
+
+      const thread = await memoryNoTitle.createThread({
+        threadId,
+        resourceId,
+        metadata,
+      });
+
+      expect(thread).toBeDefined();
+      expect(thread?.metadata).toMatchObject(metadata);
+
+      await agentNoTitle.generateVNext([{ role: 'user', content: 'Hello, world!' }], { threadId, resourceId });
+      await agentNoTitle.generateVNext([{ role: 'user', content: 'Hello, world!' }], { threadId, resourceId });
+
+      const existingThread = await memoryNoTitle.getThreadById({ threadId });
+      expect(existingThread).toBeDefined();
+      expect(existingThread?.metadata).toMatchObject(metadata);
+    });
+  });
+});
+
+describe('Agent with message processors', () => {
+  it('should apply processors to filter tool messages from context', async () => {
+    const threadId = randomUUID();
+    const resourceId = 'processor-filter-tool-message';
+
+    // First, ask a question that will trigger a tool call
+    const firstResponse = await memoryProcessorAgent.generateVNext('What is the weather in London?', {
+      threadId,
+      resourceId,
+    });
+
+    // The response should contain the weather.
+    expect(firstResponse.text).toContain('65');
+
+    // Check that tool calls were saved to memory
+    const agentMemory = (await memoryProcessorAgent.getMemory())!;
+    const { messages: messagesFromMemory } = await agentMemory.query({ threadId });
+    const toolMessages = messagesFromMemory.filter(
+      m => m.role === 'tool' || (m.role === 'assistant' && typeof m.content !== 'string'),
+    );
+
+    expect(toolMessages.length).toBeGreaterThan(0);
+
+    // Now, ask a follow-up question. The processor should prevent the tool call history
+    // from being sent to the model.
+    const secondResponse = await memoryProcessorAgent.generateVNext('What was the tool you just used?', {
+      memory: {
+        thread: threadId,
+        resource: resourceId,
+        options: {
+          lastMessages: 10,
+        },
+      },
+    });
+
+    const secondResponseRequestMessages: CoreMessage[] = secondResponse.request.body.input;
+
+    expect(secondResponseRequestMessages.length).toBe(4);
+    // Filter out tool messages and tool results, should be the same as above.
+    expect(
+      secondResponseRequestMessages.filter(m => m.role !== 'tool' || (m as any)?.tool_calls?.[0]?.type !== 'function')
+        .length,
+    ).toBe(4);
+  }, 3000_000);
+});
+
+describe('Agent.fetchMemory', () => {
+  it('should return messages from memory', async () => {
+    const threadId = randomUUID();
+    const resourceId = 'fetch-memory-test';
+
+    const response = await weatherAgent.generateVNext('Just a simple greeting to populate memory.', {
+      threadId,
+      resourceId,
+    });
+
+    const { messages } = await weatherAgent.fetchMemory({ threadId, resourceId });
+
+    expect(messages).toBeDefined();
+    if (!messages) return;
+
+    expect(messages.length).toBe(2); // user message + assistant response
+
+    const userMessage = messages.find(m => m.role === 'user');
+    expect(userMessage).toBeDefined();
+    if (!userMessage) return;
+    expect(userMessage.content[0]).toEqual({ type: 'text', text: 'Just a simple greeting to populate memory.' });
+
+    const assistantMessage = messages.find(m => m.role === 'assistant');
+    expect(assistantMessage).toBeDefined();
+    if (!assistantMessage) return;
+    expect(assistantMessage.content).toEqual([{ type: 'text', text: response.text }]);
+  }, 30_000);
+
+  it('should apply processors when fetching memory', async () => {
+    const threadId = randomUUID();
+    const resourceId = 'fetch-memory-processor-test';
+
+    await memoryProcessorAgent.generateVNext('What is the weather in London?', { threadId, resourceId });
+
+    const { messages } = await memoryProcessorAgent.fetchMemory({ threadId, resourceId });
+
+    expect(messages).toBeDefined();
+    if (!messages) return;
+
+    const hasToolRelatedMessage = messages.some(
+      m => m.role === 'tool' || (Array.isArray(m.content) && m.content.some(c => c.type === 'tool-call')),
+    );
+    expect(hasToolRelatedMessage).toBe(false);
+
+    const userMessage = messages.find(m => m.role === 'user');
+    expect(userMessage).toBeDefined();
+    if (!userMessage) return;
+    expect(userMessage.content[0]).toEqual({ type: 'text', text: 'What is the weather in London?' });
+  }, 30_000);
+
+  it('should return nothing if thread does not exist', async () => {
+    const threadId = randomUUID();
+    const resourceId = 'fetch-memory-no-thread';
+
+    const result = await weatherAgent.fetchMemory({ threadId, resourceId });
+
+    expect(result.messages).toEqual([]);
+    expect(result.threadId).toBe(threadId);
+  });
+});
+
+describe('Agent memory test gemini', () => {
+  const memory = new Memory({
+    storage: new MockStore(),
+    options: {
+      threads: {
+        generateTitle: false,
+      },
+      lastMessages: 2,
+    },
+  });
+
+  const agent = new Agent({
+    name: 'gemini-agent',
+    instructions:
+      'You are a weather agent. When asked about weather in any city, use the get_weather tool with the city name.',
+    model: google.chat('gemini-2.5-flash-preview-05-20'),
+    memory,
+    tools: { get_weather: weatherToolCity },
+  });
+
+  const resource = 'weatherAgent-memory-test';
+  const thread = new Date().getTime().toString();
+
+  it('should not throw error when using gemini', async () => {
+    // generate two messages in the db
+    await agent.generateVNext(`What's the weather in Tokyo?`, {
+      memory: { resource, thread },
+    });
+
+    await new Promise(resolve => setTimeout(resolve, 1000));
+
+    // Will throw if the messages sent to the agent aren't cleaned up because a tool call message will be the first message sent to the agent
+    // Which some providers like gemini will not allow.
+    await expect(
+      agent.generateVNext(`What's the weather in London?`, {
+        memory: { resource, thread },
+      }),
+    ).resolves.not.toThrow();
+  });
+});

package/integration-tests-v5/src/mastra/agents/weather.ts

@@ -0,0 +1,75 @@
+import { openai } from '@ai-sdk/openai';
+import { createTool } from '@mastra/core';
+import { Agent } from '@mastra/core/agent';
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql';
+import { Memory } from '@mastra/memory';
+import { ToolCallFilter } from '@mastra/memory/processors';
+import { z } from 'zod';
+import { weatherTool } from '../tools/weather';
+
+export const memory = new Memory({
+  options: {
+    workingMemory: {
+      enabled: true,
+    },
+    lastMessages: 10,
+    semanticRecall: true,
+  },
+  storage: new LibSQLStore({
+    url: 'file:mastra.db', // relative path from bundled .mastra/output dir
+  }),
+  vector: new LibSQLVector({
+    connectionUrl: 'file:mastra.db', // relative path from bundled .mastra/output dir
+  }),
+  embedder: openai.embedding('text-embedding-3-small'),
+});
+
+export const weatherAgent = new Agent({
+  name: 'test',
+  instructions:
+    'You are a weather agent. When asked about weather in any city, use the get_weather tool with the city name as the postal code. When asked for clipboard contents use the clipboard tool to get the clipboard contents.',
+  model: openai('gpt-4o'),
+  memory,
+  tools: {
+    get_weather: weatherTool,
+    clipboard: createTool({
+      id: 'clipboard',
+      description: 'Returns the contents of the users clipboard',
+      inputSchema: z.object({}),
+    }),
+  },
+});
+
+const memoryWithProcessor = new Memory({
+  embedder: openai.embedding('text-embedding-3-small'),
+  storage: new LibSQLStore({
+    url: 'file:mastra.db',
+  }),
+  vector: new LibSQLVector({
+    connectionUrl: 'file:mastra.db',
+  }),
+  options: {
+    semanticRecall: {
+      topK: 20,
+      messageRange: {
+        before: 10,
+        after: 10,
+      },
+    },
+    lastMessages: 20,
+    threads: {
+      generateTitle: true,
+    },
+  },
+  processors: [new ToolCallFilter()],
+});
+
+export const memoryProcessorAgent = new Agent({
+  name: 'test-processor',
+  instructions: 'You are a test agent that uses a memory processor to filter out tool call messages.',
+  model: openai('gpt-4o'),
+  memory: memoryWithProcessor,
+  tools: {
+    get_weather: weatherTool,
+  },
+});