Memory.query()
the .query() method retrieves messages from a specific thread, with support for pagination, filtering options, and semantic search.
Usage Example
await memory?.query({ threadId: "user-123" });Parameters
threadId:
string
The unique identifier of the thread to retrieve messages from
resourceId?:
string
Optional ID of the resource that owns the thread. If provided, validates thread ownership
selectBy?:
object
Options for filtering and selecting messages
threadConfig?:
MemoryConfig
Configuration options for message retrieval and semantic search
format?:
'v1' | 'v2'
Message format to return. Defaults to 'v2' for current format, 'v1' for backwards compatibility
selectBy parameters
vectorSearchString?:
string
Search string for finding semantically similar messages. Requires semantic recall to be enabled in threadConfig.
last?:
number | false
Number of most recent messages to retrieve. Set to false to disable limit. Note: threadConfig.lastMessages (default: 10) will override this if smaller.
include?:
{ id: string; threadId?: string; withPreviousMessages?: number; withNextMessages?: number }[]
Array of specific message IDs to include with optional context messages. Each item has an `id` (required), optional `threadId` (defaults to main threadId), `withPreviousMessages` (number of messages before, defaults to 2 for vector search, 0 otherwise), and `withNextMessages` (number of messages after, defaults to 2 for vector search, 0 otherwise).
pagination?:
{ dateRange?: { start?: Date; end?: Date }; page?: number; perPage?: number }
Pagination options for retrieving messages in batches. Includes `dateRange` (filter by date range), `page` (0-based page number), and `perPage` (messages per page).
threadConfig parameters
lastMessages?:
number | false
= 10
Number of most recent messages to retrieve. Set to false to disable.
semanticRecall?:
boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }
= false
Enable semantic search in message history. Can be a boolean or an object with configuration options. When enabled, requires both vector store and embedder to be configured.
workingMemory?:
WorkingMemory
= { enabled: false, template: '# User Information\n- **First Name**:\n- **Last Name**:\n...' }
Configuration for working memory feature. Can be `{ enabled: boolean; template?: string; schema?: ZodObject<any> | JSONSchema7; scope?: 'thread' | 'resource' }` or `{ enabled: boolean }` to disable.
threads?:
{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }
= { generateTitle: false }
Settings related to memory thread creation. `generateTitle` controls automatic thread title generation from the user's first message. Can be a boolean or an object with custom model and instructions.
Returns
messages:
CoreMessage[]
Array of retrieved messages in their core format
uiMessages:
UIMessageWithMetadata[]
Array of messages formatted for UI display, including proper threading of tool calls and results
Extended usage example
src/test-memory.ts
import { mastra } from "./mastra";
const agent = mastra.getAgent("agent");
const memory = await agent.getMemory();
const { messages, uiMessages } = await memory!.query({
threadId: "thread-123",
selectBy: {
last: 50,
vectorSearchString: "What messages are there?",
include: [
{
id: "msg-123"
},
{
id: "msg-456",
withPreviousMessages: 3,
withNextMessages: 1
}
]
},
threadConfig: {
semanticRecall: true
}
});
console.log(messages);
console.log(uiMessages);