Skip to Content

query

Retrieves messages from a specific thread, with support for pagination, filtering options, and semantic search.

Usage Example

import { Memory } from "@mastra/memory"; const memory = new Memory({ /* config */ }); // Get last 50 messages const { messages, uiMessages, messagesV2 } = await memory.query({ threadId: "thread-123", selectBy: { last: 50, }, }); // Get messages with context around specific messages const { messages: contextMessages } = await memory.query({ threadId: "thread-123", selectBy: { include: [ { id: "msg-123", // Get just this message (no context) }, { id: "msg-456", // Get this message with custom context withPreviousMessages: 3, // 3 messages before withNextMessages: 1, // 1 message after }, ], }, }); // Semantic search in messages const { messages } = await memory.query({ threadId: "thread-123", selectBy: { vectorSearchString: "What was discussed about deployment?", }, threadConfig: { semanticRecall: true, }, });

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

selectBy

vectorSearchString?:

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

last?:

number | false
= 40
Number of most recent messages to retrieve. Set to false to disable limit. Note: threadConfig.lastMessages (default: 40) will override this if smaller.

include?:

array
Array of specific message IDs to include with optional context messages

include

id:

string
ID of the message to include

threadId?:

string
Optional thread ID (defaults to the main threadId parameter)

withPreviousMessages?:

number
Number of messages to include before this message. Defaults to 2 when using vector search, 0 otherwise.

withNextMessages?:

number
Number of messages to include after this message. Defaults to 2 when using vector search, 0 otherwise.

Returns

messages:

CoreMessage[]
Array of retrieved messages in their core format (v1 format for backwards compatibility)

uiMessages:

UIMessage[]
Array of messages formatted for UI display, including proper threading of tool calls and results

messagesV2:

MastraMessageV2[]
Array of messages in the v2 format, the current internal message format

Additional Notes

The query function returns three different message formats:

  • messages: Core message format (v1) used for backwards compatibility with older APIs
  • uiMessages: Formatted messages suitable for UI display, including proper threading of tool calls and results
  • messagesV2: The current internal message format with enhanced structure and metadata

When using vectorSearchString, ensure that:

  • Semantic recall is enabled in your threadConfig
  • A vector database is configured in your Memory instance
  • An embedding model is provided

The function will automatically include context messages around semantically similar results based on the configured messageRange.