Skip to main content
Mastra v1 is coming in January 2026. Get ahead by starting new projects with the beta or upgrade your existing project today.

Memory.query()

the .query() method retrieves messages from a specific thread, with support for pagination, filtering options, and semantic search.

Usage ExampleDirect link to Usage Example

await memory?.query({ threadId: "user-123" });

ParametersDirect link to 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 parametersDirect link to 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).

threadConfig parametersDirect link to 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.

ReturnsDirect link to 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 exampleDirect link to 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);