儲存空間概觀

Mastra 儲存空間以 domain 組織。每個 domain 都擁有一組資料表或 collection。視 adapter 與設定而定，你可以使用所有 domain，或只使用其中一部分。

儲存 domain

MastraCompositeStore 可以路由下列 domain key：

並非每個儲存 adapter 都會實作所有 domain。只要 adapter 套件匯出對應的 domain 類別，複合儲存空間就能讓你為各 domain 混用不同 adapter。

Domain	說明
memory	對話持久化：訊息、thread 與資源（包括 working memory）。
workflows	用於暫停與繼續執行的 Workflow run snapshot。
workflowDefinitions	持久化的動態 Workflow 定義（beta）。啟動時載入並即時註冊。
scores	評估執行所產生的評估分數記錄。
observability	供可觀測性 exporter 與 Studio 使用的 Trace 和 span。
datasets	實驗使用的 dataset 記錄、版本化項目與 dataset 版本。
experiments	實驗執行與各項目的實驗結果。

下列 schema 定義涵蓋 memory、workflows、scores 與 observability 中有文件說明、以資料庫為基礎的內建資料表。其他 domain 與非資料庫 adapter 則使用各實作專屬的儲存結構。

核心 schema

訊息

儲存對話訊息及其 metadata。每則訊息都屬於一個 thread，並包含實際內容，以及傳送者角色與訊息型別的 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

擁有此訊息之資源的 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

將相關訊息組合在一起並與資源建立關聯。包含對話的 metadata。

id

uuidv4

PRIMARYKEY

NOT NULL

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

resourceId

text

NOT NULL

此 thread 所關聯外部資源的主要識別碼。用於分組及擷取相關 thread。

title

text

NOT NULL

對話 thread 的標題

metadata

text

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

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

createdAt

timestamp

NOT NULL

updatedAt

timestamp

NOT NULL

用於排列 thread 歷程

資源

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

id

text

PRIMARYKEY

NOT NULL

資源識別碼（使用者或實體 ID）：與 thread 和 Agent 呼叫中使用的 resourceId 相同

workingMemory

text

CAN BE NULL

以 Markdown 文字表示的持久 working memory 資料。包含可跨對話 thread 持久保存的使用者個人資料、偏好與上下文資訊。

metadata

jsonb

CAN BE NULL

以 JSON 表示的其他資源 metadata。範例：

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

createdAt

timestamp

NOT NULL

資源記錄首次建立的時間

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 輸出執行指標所得的評估結果。

input

text

NOT NULL

提供給 Agent 的輸入

output

text

NOT NULL

Agent 產生的輸出

result

jsonb

NOT NULL

包含分數與詳細資料的評估結果資料。範例：

{
  "score": 0.95,
  "details": {
    "reason": "回應準確反映來源資料",
    "citations": [
      "第 1 頁",
      "第 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

Trace

擷取 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 的 library／套件／服務（例如 @mastra/core、express、pg）

kind

integer

NOT NULL

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

attributes

jsonb

包含 span metadata 的使用者自訂 key-value pair

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