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 APIsuiMessages
: Formatted messages suitable for UI display, including proper threading of tool calls and resultsmessagesV2
: The current internal message format with enhanced structure and metadata
Semantic Search
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
.