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

# Memory.listThreads()

`listThreads()` 方法检索线程，支持分页，并可选择按 `resourceId`、`metadata` 或两者同时筛选。

## 用法示例

### 分页列出所有线程

```typescript
const result = await memory.listThreads({
  page: 0,
  perPage: 10,
})
```

### 不分页获取所有线程

使用 `perPage: false` 一次性检索所有匹配的线程。

> **注意:** 请使用分页，尤其是在处理大型数据集时。请谨慎使用此选项。

```typescript
const result = await memory.listThreads({
  filter: { resourceId: 'user-123' },
  perPage: false,
})
```

### 按 `resourceId` 筛选

```typescript
const result = await memory.listThreads({
  filter: { resourceId: 'user-123' },
  page: 0,
  perPage: 10,
})
```

### 按元数据筛选

```typescript
const result = await memory.listThreads({
  filter: { metadata: { category: 'support', priority: 'high' } },
  page: 0,
  perPage: 10,
})
```

### 组合筛选（resourceId 和 metadata）

```typescript
const result = await memory.listThreads({
  filter: {
    resourceId: 'user-123',
    metadata: { status: 'active' },
  },
  page: 0,
  perPage: 10,
})
```

## 参数

**filter** (`{ resourceId?: string; metadata?: Record<string, unknown> }`): 可选的筛选对象。resourceId 按资源 ID 筛选线程。metadata 按元数据键值对筛选线程（AND 逻辑，即所有条件都必须匹配）

**page** (`number`): 要检索的页码（从 0 开始）

**perPage** (`number | false`): 每页返回的最大线程数，设为 false 时获取所有线程

**orderBy** (`{ field: 'createdAt' | 'updatedAt', direction: 'ASC' | 'DESC' }`): 包含字段和方向的排序配置（默认为 { field: 'createdAt', direction: 'DESC' }）

## 返回值

**result** (`Promise<StorageListThreadsOutput>`): 兑现为带有元数据的分页线程结果的 Promise

返回对象包含：

- `threads`：线程对象数组
- `total`：与筛选条件匹配的线程总数
- `page`：当前页码（与输入的 `page` 参数相同）
- `perPage`：每页条目数（与输入的 `perPage` 参数相同）
- `hasMore`：表示是否还有更多结果的布尔值

## 扩展用法示例

```typescript
import { mastra } from './mastra'

const agent = mastra.getAgent('agent')
const memory = await agent.getMemory()

let currentPage = 0
const perPage = 25
let hasMorePages = true

// Fetch all active threads for a user, sorted by creation date
while (hasMorePages) {
  const result = await memory?.listThreads({
    filter: {
      resourceId: 'user-123',
      metadata: { status: 'active' },
    },
    page: currentPage,
    perPage: perPage,
    orderBy: { field: 'createdAt', direction: 'ASC' },
  })

  if (!result) {
    console.log('No threads')
    break
  }

  result.threads.forEach(thread => {
    console.log(`Thread: ${thread.id}, Created: ${thread.createdAt}`)
  })

  hasMorePages = result.hasMore
  currentPage++ // Move to next page
}
```

## 元数据筛选

元数据筛选使用 AND 逻辑，即线程必须匹配所有指定的键值对，才会包含在结果中：

```typescript
// This will only return threads where BOTH conditions are true:
// - category === 'support'
// - priority === 'high'
await memory.listThreads({
  filter: {
    metadata: {
      category: 'support',
      priority: 'high',
    },
  },
})
```

## 相关内容

- [Memory 类参考](https://mastra.zisheng.pro/reference/memory/memory-class)
- [Memory 入门](https://mastra.zisheng.pro/docs/memory/overview)
- [createThread](https://mastra.zisheng.pro/reference/memory/createThread)
- [getThreadById](https://mastra.zisheng.pro/reference/memory/getThreadById)