Memory.listThreads()

listThreads() 方法支持分页检索线程，并可根据 resourceId、metadata 或两者进行可选过滤。

🌐 The listThreads() method retrieves threads with pagination support and optional filtering by resourceId, metadata, or both.

使用示例

🌐 Usage Examples

列出所有线程并分页显示

🌐 List all threads with pagination

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

获取所有线程，无需分页

🌐 Fetch all threads without pagination

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

🌐 Use perPage: false to retrieve all matching threads at once.

warning

一般来说，建议使用分页，尤其是对于大数据集。请谨慎使用此选项。

🌐 Generally speaking it's recommended to use pagination, especially for large datasets. Use this option cautiously.

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

按资源ID筛选

🌐 Filter by resourceId

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

按元数据筛选

🌐 Filter by metadata

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

组合过滤器（资源ID和元数据）

🌐 Combined filter (resourceId & metadata)

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

参数

🌐 Parameters

filter?:

{ resourceId?: string; metadata?: Record<string, unknown> }

Optional filter object. resourceId filters threads by resource ID. metadata filters threads by metadata key-value pairs (AND logic - all must match)

page?:

number

Page number (0-indexed) to retrieve

perPage?:

number | false

Maximum number of threads to return per page, or false to fetch all

orderBy?:

{ field: 'createdAt' | 'updatedAt', direction: 'ASC' | 'DESC' }

Sort configuration with field and direction (defaults to { field: 'createdAt', direction: 'DESC' })

返回

🌐 Returns

result:

Promise<StorageListThreadsOutput>

A promise that resolves to paginated thread results with metadata

返回对象包含：

🌐 The return object contains:

• threads：线程对象数组
• total：符合筛选条件的线程总数
• page：当前页码（与输入参数 page 相同）
• perPage：每页条目数（与输入参数 perPage 相同）
• hasMore：布尔值，指示是否有更多结果可用

扩展使用示例

🌐 Extended usage example

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
}

元数据过滤

🌐 Metadata Filtering

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

🌐 The metadata filter uses AND logic - all specified key-value pairs must match for a thread to be included in the results:

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

相关

🌐 Related

• 内存类参考
• 内存入门
• 创建线程
• getThreadById