Memory API

Memory API 提供用於管理 Mastra 中對話 thread 和訊息歷史記錄的方法。

取得所有 thread

取得特定資源的所有 memory thread：

const threads = await mastraClient.listMemoryThreads({
  resourceId: 'resource-1',
  agentId: 'agent-1', // Optional - can be omitted if storage is configured
})

如果省略 agentId 且伺服器設定了儲存，則會直接使用儲存取得 thread。當多個 Agent 共享相同 thread 時（例如包含多個 Agent 步驟的 Workflow），這會很有用。

建立新 thread

建立新的 memory thread：

const thread = await mastraClient.createMemoryThread({
  title: 'New Conversation',
  metadata: { category: 'support' },
  resourceId: 'resource-1',
  agentId: 'agent-1',
})

使用特定 thread

取得特定 memory thread 的執行個體：

const thread = mastraClient.getMemoryThread({ threadId: 'thread-id', agentId: 'agent-id' })

Thread 方法

取得 thread 詳情

取得特定 thread 的詳細資訊：

const details = await thread.get()

更新 thread

更新 thread 屬性：

const updated = await thread.update({
  title: 'Updated Title',
  metadata: { status: 'resolved' },
  resourceId: 'resource-1',
})

刪除 thread

刪除 thread 及其訊息：

await thread.delete()

複製 thread

建立包含 thread 所有訊息的副本：

const { thread: clonedThread, clonedMessages } = await thread.clone()

使用選項進行複製：

const { thread: clonedThread, clonedMessages } = await thread.clone({
  newThreadId: 'custom-clone-id',
  title: 'Cloned Conversation',
  metadata: { branch: 'experiment-1' },
  options: {
    messageLimit: 10, // Only clone last 10 messages
  },
})

篩選訊息後進行複製：

const { thread: clonedThread } = await thread.clone({
  options: {
    messageFilter: {
      startDate: new Date('2024-01-01'),
      endDate: new Date('2024-01-31'),
    },
  },
})

複製回應包含：

• thread：新建立的、包含複製中繼資料的 thread
• clonedMessages：具有新 ID 的已複製訊息陣列

訊息操作

儲存訊息

將訊息儲存到 memory：

const result = await mastraClient.saveMessageToMemory({
  messages: [
    {
      role: 'user',
      content: 'Hello!',
      id: '1',
      threadId: 'thread-1',
      resourceId: 'resource-1',
      createdAt: new Date(),
      format: 2,
    },
  ],
  agentId: 'agent-1',
})

// result.messages contains the saved messages
console.log(result.messages)

取得 thread 訊息

取得與 memory thread 關聯的訊息：

// Get all messages in the thread (paginated)
const result = await thread.listMessages()
console.log(result.messages) // Array of messages
console.log(result.total) // Total count
console.log(result.hasMore) // Whether more pages exist

// Get messages with pagination
const result = await thread.listMessages({
  page: 0,
  perPage: 20,
})

// Get messages with ordering
const result = await thread.listMessages({
  orderBy: { field: 'createdAt', direction: 'ASC' },
})

// Get messages with shallow metadata filters
const result = await thread.listMessages({
  filter: {
    metadata: {
      category: 'billing',
      escalated: true,
      priority: 2,
      archivedAt: null,
    },
  },
})

中繼資料篩選條件只相符淺層標量值：string、有限的 number、boolean 和 null。每個鍵值對都必須以 AND 語義相符。null 只相符明確設為 null 的鍵。中繼資料鍵必須以字母或底線開頭，且只能包含字母數字或底線字元，長度上限為 128 個字元。不允許使用 __proto__、constructor 和 prototype 等保留的原型鍵。效能取決於伺服器的儲存後端，任意中繼資料篩選條件可能會掃描候選訊息。

刪除訊息

從 thread 中刪除一條或多條訊息：

// Delete a single message
const result = await thread.deleteMessages('message-id')

// Delete multiple messages
const result = await thread.deleteMessages(['message-1', 'message-2', 'message-3'])

// Returns: { success: true, message: "Message deleted successfully" }

工作記憶

Working memory 讓 Agent 能夠跨互動持久保留使用者相關資訊。其範圍既可以限定為特定 thread，也可以涵蓋單一資源（使用者）的所有 thread。

取得 Working memory

取得 thread 目前的 Working memory：

const workingMemory = await mastraClient.getWorkingMemory({
  agentId: 'agent-1',
  threadId: 'thread-1',
  resourceId: 'user-123', // Optional, required for resource-scoped memory
})

回應包含：

• workingMemory：目前 Working memory 內容（字串或 null）
• source：memory 來自 "thread" 還是 "resource" 範圍
• workingMemoryTemplate：用於 Working memory 的模板（如果已設定）
• threadExists：thread 是否存在

更新 Working memory

更新 thread 的 Working memory 內容：

await mastraClient.updateWorkingMemory({
  agentId: 'agent-1',
  threadId: 'thread-1',
  workingMemory: `# User Profile
- Name: John Doe
- Location: New York
- Preferences: Prefers formal communication
`,
  resourceId: 'user-123', // Optional, required for resource-scoped memory
})

// Returns: { success: true }

對於資源範圍的 Working memory，必須提供 resourceId 參數。這樣，memory 就能跨該使用者的所有對話 thread 持久保留。

取得 Memory 狀態

檢查 memory 系統的狀態：

const status = await mastraClient.getMemoryStatus('agent-id')