Message History

Message history is the simplest kind of memory. It is a list of messages from the current conversation.

Once enabled, each request includes the last 10 messages from the current memory thread, giving the agent short-term conversational context. This limit can be increased using the lastMessages parameter:

export const agent = new Agent({
  id: "test-agent",
  memory: new Memory({
    options: {
      lastMessages: 20,
    },
  }),
});

Querying Messages

Messages are stored in the MastraDBMessage format, which provides a consistent structure across the entire Mastra system.

Storage in Mastra uses domain-specific stores. To access message operations, first get the memory store:

// Get the memory store from storage
const storage = mastra.getStorage();
const memoryStore = await storage.getStore('memory');

// Get messages for a thread with pagination
const result = await memoryStore?.listMessages({
  threadId: "your-thread-id",
  page: 0,
  perPage: 50
});

console.log(result?.messages); // MastraDBMessage[]
console.log(result?.total); // Total count
console.log(result?.hasMore); // Whether more pages exist

// Get messages from multiple threads at once
const multiThreadResult = await memoryStore?.listMessages({
  threadId: ["thread-1", "thread-2", "thread-3"],
  page: 0,
  perPage: 100
});

// Get messages by their IDs
const messages = await memoryStore?.listMessagesById({ messageIds: messageIdArr });

The threadId parameter accepts either a single thread ID string or an array of thread IDs to query messages from multiple threads in a single request.

All message queries return MastraDBMessage[] format. If you need to convert messages to AI SDK formats for UI rendering, use the conversion utilities from @mastra/ai-sdk/ui:

import { toAISdkV5Messages } from '@mastra/ai-sdk/ui';

const storage = mastra.getStorage();
const memoryStore = await storage.getStore('memory');

const result = await memoryStore?.listMessages({ threadId: "your-thread-id" });

// Convert to AI SDK v5 UIMessage format for UI rendering
const uiMessages = toAISdkV5Messages(result?.messages ?? []);