跳到主要内容

Memory.recall()

Memory.recall() 方法从特定 thread 检索消息，并支持分页、筛选选项和语义搜索。

使用示例
使用示例的直接链接

const { messages } = await memory.recall({
  threadId: 'thread-123',
  perPage: 20,
})

参数
参数的直接链接

threadId:

string
要从中检索消息的 thread 的唯一标识符

resourceId?:

string
拥有该 thread 的 resource 的可选 ID。如果提供，则验证 thread 所有权

vectorSearchString?:

string
用于查找语义相似消息的搜索字符串。需要在 threadConfig 中启用 semantic recall。

perPage?:

number | false
每页要检索的消息数。设为 false 可获取所有消息且不分页。如果未提供，则默认为 threadConfig.lastMessages。

page?:

number
从零开始的分页页码。与 perPage 一起使用，以分批检索消息。

include?:

{ id: string; threadId?: string; withPreviousMessages?: number; withNextMessages?: number }[]
要包含的特定消息 ID 数组，可选择包含上下文消息。每项包含一个 id（必需）、可选的 threadId（默认为主 threadId）、withPreviousMessages（之前的消息数；向量搜索时默认为 2，否则为 0）和 withNextMessages（之后的消息数；向量搜索时默认为 2，否则为 0）。

filter?:

{ dateRange?: { start?: Date; end?: Date; startExclusive?: boolean; endExclusive?: boolean }; metadata?: Record<string, string | number | boolean | null> }
消息检索的筛选选项。dateRange 按创建日期筛选消息。metadata 使用 AND 语义，通过完全匹配的标量键值对筛选浅层消息 metadata。Metadata 值可以是字符串、有限数值、布尔值或 null。

orderBy?:

{ field: 'createdAt'; direction: 'ASC' | 'DESC' }
检索消息的排序方式。默认按创建日期降序排列。

threadConfig?:

MemoryConfig
消息检索和语义搜索的配置选项
MemoryConfig

lastMessages?:

number | false
要检索的最近消息数。设为 false 可禁用。当未明确提供 perPage 时，此值用作默认值。

semanticRecall?:

boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }
在消息历史记录中启用语义搜索。可以是布尔值或包含配置选项的对象。启用后，需要同时配置 vector store 和 embedder。

workingMemory?:

WorkingMemory
Working memory 功能的配置。可以是 { enabled: boolean; template?: string; schema?: ZodObject<any> | JSONSchema7; scope?: 'thread' | 'resource' }，也可以是用于禁用的 { enabled: boolean }。

threads?:

{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }
与 memory thread 创建相关的设置。generateTitle 控制根据对话转录自动生成 thread 标题。可以是布尔值，也可以是包含自定义模型和 instructions 的对象。

Metadata 筛选
Metadata 筛选的直接链接

使用 filter.metadata 匹配存储在消息上的浅层标量 metadata：

const { messages } = await memory.recall({
  threadId: 'thread-123',
  filter: {
    metadata: {
      category: 'billing',
      escalated: true,
      priority: 2,
      archivedAt: null,
    },
  },
})

所有 metadata 条目均使用 AND 语义组合。消息必须以完全相同的类型匹配每个键和值。null 会匹配明确设为 null 的 metadata，但不会匹配缺失的键。

Metadata 筛选器仅支持浅层标量值：string、有限 number、boolean 和 null。不支持嵌套对象、数组、NaN 和无穷值。Metadata 键必须以字母或下划线开头，并且只能包含字母数字或下划线字符。长度上限为 128 个字符。不允许使用 __proto__、constructor 和 prototype 等保留的原型键。性能取决于存储后端。任意 metadata 筛选可能需要扫描候选消息，因此应尽可能使用 threadId、resourceId 或 dateRange 缩小查询范围。

返回值
返回值的直接链接

messages:

MastraDBMessage[]
以数据库格式返回的消息数组

扩展使用示例
扩展使用示例的直接链接

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!.recall({
  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!.recall({
  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)
On this page