Skip to main content

Memory.query()

Deprecated

The Memory.query() method has been renamed to Memory.recall(). This page is kept for reference, but please use recall() in new code.

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

vectorSearchString?:

string
Search string for finding semantically similar messages. Requires semantic recall to be enabled in threadConfig.

perPage?:

number | false
Number of messages to retrieve per page. Set to false to fetch all messages without pagination.

page?:

number
Zero-based page number for pagination. Used with perPage to retrieve messages in batches.

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).

filter?:

{ dateRange?: { start?: Date; end?: Date } }
Filter options for message retrieval. Currently supports `dateRange` to filter messages by creation date.

orderBy?:

{ field: 'createdAt'; direction: 'ASC' | 'DESC' }
Sort order for retrieved messages. Defaults to descending by creation date.

threadConfig?:

MemoryConfig
Configuration options for message retrieval and semantic search

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:

MastraDBMessage[]
Array of retrieved messages in the database format

Extended usage example​

src/test-memory.ts
import { mastra } from "./mastra";

const agent = mastra.getAgent("agent");
const memory = await agent.getMemory();

// Retrieve messages with pagination
const { messages } = await memory!.query({
  threadId: "thread-123",
  perPage: 50,
  vectorSearchString: "What messages are there?",
  include: [
    {
      id: "msg-123",
    },
    {
      id: "msg-456",
      withPreviousMessages: 3,
      withNextMessages: 1,
    },
  ],
  threadConfig: {
    semanticRecall: true,
  },
});

console.log(messages); // MastraDBMessage[]

// Fetch all messages without pagination
const allMessages = await memory!.query({
  threadId: "thread-123",
  perPage: false, // Fetch all
});

// Convert to AI SDK format if needed
import { toAISdkV5Messages } from '@mastra/ai-sdk/ui';
const uiMessages = toAISdkV5Messages(messages);