Memory.listThreads()

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

用法示例

分页列出所有线程

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

不分页获取所有线程

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

注意

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

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

按 resourceId 筛选

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

按元数据筛选

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

组合筛选（resourceId 和 metadata）

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：表示是否还有更多结果的布尔值

扩展用法示例

src/test-memory.ts

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 逻辑，即线程必须匹配所有指定的键值对，才会包含在结果中：

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

相关内容

• Memory 类参考
• Memory 入门
• createThread
• getThreadById