儲存概覽

Mastra 儲存按域劃分。每個域擁有一組資料表或 collection。視乎你的 adapter 及設定，你可以使用所有域或只使用其中一部分。

儲存域

MastraCompositeStore 可以路由以下域 key：

並非每個儲存 adapter 都會實作所有域。當 adapter 套件有匯出對應的域 class 時，複合儲存可讓你為每個域混合使用 adapter。

Domain	說明
memory	持久儲存對話：訊息、thread 及 resource（包括 working memory）。
workflows	用於暫停及恢復的 Workflow 執行快照。
workflowDefinitions	持久儲存的動態 Workflow 定義（beta）。啟動時載入並即時註冊。
scores	Evals 執行產生的評估分數記錄。
observability	observability exporter 及 Studio 所用的 Trace 與 span。
datasets	實驗所用的 dataset 記錄、版本化項目及 dataset 版本。
experiments	實驗執行及逐項實驗結果。

以下結構描述定義涵蓋 memory、workflows、scores 及 observability 的內置資料庫支援資料表。其他域及非資料庫 adapter 會使用實作特定的儲存結構。

核心結構描述

訊息

儲存對話訊息及其 metadata。每則訊息均屬於一個 thread，並包含實際內容，以及傳送者 role 及訊息類型的 metadata。

id

uuidv4

PRIMARYKEY

NOT NULL

訊息的唯一識別碼（格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）

thread_id

uuidv4

FK → threads.id

NOT NULL

上層 thread 參照

resourceId

uuidv4

CAN BE NULL

擁有此訊息的 resource ID

content

text

NOT NULL

V2 格式的訊息內容 JSON。範例：{ format: 2, parts: [...] }

role

text

NOT NULL

user | assistant 列舉值

createdAt

timestamp

NOT NULL

用於排列 thread 訊息

訊息的 content 欄包含符合 MastraMessageContentV2 類型的 JSON 物件；此類型的設計與 AI SDK UIMessage 訊息結構緊密配合。

format

integer

NOT NULL

訊息格式版本（目前為 2）

parts

array (JSON)

NOT NULL

訊息部分的陣列（文字、Tool 調用、檔案、推理等）。此陣列內項目的結構視 type 而定。

experimental_attachments

array (JSON)

CAN BE NULL

可選的附件檔案陣列

content

text

CAN BE NULL

可選的訊息主要文字內容

toolInvocations

array (JSON)

CAN BE NULL

可選的陣列，概述 Tool 調用及結果

reasoning

object (JSON)

CAN BE NULL

關於 assistant 回應背後推理過程的可選資料

annotations

object (JSON)

CAN BE NULL

可選的其他 metadata 或註釋

Thread

將相關訊息分組並與 resource 關聯。包含對話的 metadata。

id

uuidv4

PRIMARYKEY

NOT NULL

thread 的唯一識別碼（格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）

resourceId

text

NOT NULL

與此 thread 關聯之外部 resource 的主要識別碼。用於分組及擷取相關 thread。

title

text

NOT NULL

對話 thread 的標題

metadata

text

以 JSON 字串表示的自訂 thread metadata。範例：

{
  "category": "support",
  "priority": 1
}

createdAt

timestamp

NOT NULL

updatedAt

timestamp

NOT NULL

用於排列 thread 歷史記錄

Resource

儲存 resource 範圍 working memory 的使用者專屬資料。每個 resource 代表一名使用者或一個實體，讓 working memory 可跨該使用者的所有對話 thread 持續保留。

id

text

PRIMARYKEY

NOT NULL

Resource 識別碼（使用者或實體 ID）：與 thread 及 Agent 調用所用的 resourceId 相同

workingMemory

text

CAN BE NULL

以 Markdown 文字儲存的持久 working memory 資料。包含跨對話 thread 持續保留的使用者個人檔案、偏好及情境資料。

metadata

jsonb

CAN BE NULL

JSON 格式的其他 resource metadata。範例：

{
  "preferences": {
    "language": "en",
    "timezone": "UTC"
  },
  "tags": [
    "premium",
    "beta-user"
  ]
}

createdAt

timestamp

NOT NULL

首次建立 resource 記錄的時間

updatedAt

timestamp

NOT NULL

最後更新 working memory 的時間

Workflow

在 Workflow 上調用 suspend() 時，其狀態會以下列格式儲存。調用 resume() 時，該狀態會重新還原。

workflow_name

text

NOT NULL

Workflow 名稱

run_id

uuidv4

NOT NULL

Workflow 執行的唯一識別碼。用於在暫停／恢復週期之間追蹤狀態（格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）

snapshot

text

NOT NULL

序列化為 JSON 的 Workflow 狀態。範例：

{
  "value": {
    "currentState": "running"
  },
  "context": {
    "stepResults": {},
    "attempts": {},
    "triggerData": {}
  },
  "activePaths": [],
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1648176000000
}

createdAt

timestamp

NOT NULL

updatedAt

timestamp

NOT NULL

最後修改時間，用於追蹤 Workflow 執行期間的狀態變更

Evals

儲存針對 Agent 輸出執行指標後所得的 Evals 結果。

input

text

NOT NULL

提供給 Agent 的輸入

output

text

NOT NULL

Agent 產生的輸出

result

jsonb

NOT NULL

包含分數及詳情的 Evals 結果資料。範例：

{
  "score": 0.95,
  "details": {
    "reason": "Response accurately reflects source material",
    "citations": [
      "page 1",
      "page 3"
    ]
  }
}

agent_name

text

NOT NULL

metric_name

text

NOT NULL

例如 Faithfulness、Hallucination 等。

instructions

text

NOT NULL

Agent 的 system prompt 或指示

test_info

jsonb

NOT NULL

其他測試 metadata 及設定

global_run_id

uuidv4

NOT NULL

將相關的評估執行分組（例如一次 CI 執行中的所有單元測試）

run_id

uuidv4

NOT NULL

受評估執行的唯一識別碼（格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）

created_at

timestamp

NOT NULL

Traces

擷取 OpenTelemetry Trace，以供監察及除錯。

id

text

NOT NULL

PRIMARYKEY

唯一 Trace 識別碼

parentSpanId

text

上層 span 的 ID。如果 span 位於最上層，則為 null

name

text

NOT NULL

階層式操作名稱（例如 workflow.myWorkflow.execute、http.request、database.query）

traceId

text

NOT NULL

將相關 span 分組的根 Trace 識別碼

scope

text

NOT NULL

建立 span 的程式庫／套件／服務（例如 @mastra/core、express、pg）

kind

integer

NOT NULL

INTERNAL（0，處理程序內）、CLIENT（1，向外調用）、SERVER（2，傳入調用）、PRODUCER（3，建立非同步工作）、CONSUMER（4，處理非同步工作）

attributes

jsonb

包含 span metadata、由使用者定義的鍵值配對

status

jsonb

包含 code（UNSET=0、ERROR=1、OK=2）及可選 message 的 JSON 物件。範例：

{
  "code": 1,
  "message": "HTTP request failed with status 500"
}

events

jsonb

span 期間發生並附有時間戳記的事件

links

jsonb

連至其他相關 span 的連結

other

text

以 JSON 字串表示的其他 OpenTelemetry span 欄位。範例：

{
  "droppedAttributesCount": 2,
  "droppedEventsCount": 1,
  "instrumentationLibrary": "@opentelemetry/instrumentation-http"
}

startTime

bigint

NOT NULL

span 開始時距 Unix epoch 的納秒數

endTime

bigint

NOT NULL

span 結束時距 Unix epoch 的納秒數

createdAt

timestamp

NOT NULL