> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Memory.recall()

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

## 使用示例

```typescript
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`): 消息检索和语义搜索的配置选项

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

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

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

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

## Metadata 筛选

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

```typescript
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[]`): 以数据库格式返回的消息数组

## 扩展使用示例

```typescript
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)
```

### 相关

- [Memory Class 参考文档](https://mastra.zisheng.pro/reference/memory/memory-class)
- [Memory 入门](https://mastra.zisheng.pro/docs/memory/overview)
- [语义召回](https://mastra.zisheng.pro/docs/memory/semantic-recall)
- [createThread](https://mastra.zisheng.pro/reference/memory/createThread)