ストレージの概要

Mastra ストレージはドメイン単位で構成されます。各ドメインは一連のテーブルまたはコレクションを所有します。使用するアダプターと設定に応じて、すべてのドメインまたは一部のドメインのみを使用できます。

ストレージドメイン

MastraCompositeStore は、次のドメインキーを振り分けられます。

すべてのストレージアダプターがすべてのドメインを実装しているわけではありません。対応するドメインクラスをアダターパッケージがエクスポートしていれば、複合ストレージによってドメインごとにアダプターを組み合わせられます。

ドメイン	説明
memory	会話の永続化：メッセージ、スレッド、リソース（ワーキングメモリを含む）。
workflows	一時停止と再開に使用する Workflow 実行スナップショット。
workflowDefinitions	永続化された動的 Workflow 定義（ベータ版）。起動時に読み込まれ、ライブ登録されます。
scores	Eval 実行による評価スコアレコード。
observability	Observability Exporter と Studio が使用する Trace と Span。
datasets	実験で使用するデータセットレコード、バージョン管理された項目、データセットバージョン。
experiments	実験の実行と項目ごとの実験結果。

以下のスキーマ定義は、memory、workflows、scores、observability について文書化された、組み込みのデータベースベースのテーブルを対象としています。その他のドメインと非データベースアダプターは、実装固有のストレージ構造を使用します。

コアスキーマ

メッセージ

会話メッセージとそのメタデータを保存します。各メッセージはスレッドに属し、実際の内容に加えて、送信者のロールとメッセージタイプに関するメタデータを含みます。

id

uuidv4

PRIMARYKEY

NOT NULL

メッセージの一意な識別子（形式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）

thread_id

uuidv4

FK → threads.id

NOT NULL

親スレッドへの参照

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

スレッド内のメッセージ順序に使用

メッセージの 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

任意の追加メタデータまたは注釈

スレッド

関連するメッセージをグループ化し、リソースに関連付けます。会話に関するメタデータを含みます。

id

uuidv4

PRIMARYKEY

NOT NULL

スレッドの一意な識別子（形式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）

resourceId

text

NOT NULL

このスレッドに関連付けられた外部リソースの主識別子。関連スレッドのグループ化と取得に使用します。

title

text

NOT NULL

会話スレッドのタイトル

metadata

text

文字列化された JSON 形式のカスタムスレッドメタデータ。例：

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

createdAt

timestamp

NOT NULL

updatedAt

timestamp

NOT NULL

スレッド履歴の並べ替えに使用

リソース

リソース単位のワーキングメモリに使用するユーザー固有データを保存します。各リソースはユーザーまたはエンティティを表し、そのユーザーのすべての会話スレッドにわたってワーキングメモリを永続化できます。

id

text

PRIMARYKEY

NOT NULL

リソース識別子（ユーザーまたはエンティティ ID）：スレッドと Agent 呼び出しで使用する resourceId と同じ値

workingMemory

text

CAN BE NULL

Markdown テキスト形式の永続的なワーキングメモリデータ。会話スレッド間で維持されるユーザープロフィール、設定、コンテキスト情報を含みます。

metadata

jsonb

CAN BE NULL

JSON 形式の追加リソースメタデータ。例：

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

createdAt

timestamp

NOT NULL

リソースレコードが最初に作成された日時

updatedAt

timestamp

NOT NULL

ワーキングメモリが最後に更新された日時

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 実行中の状態変化の追跡に使用します

Eval

Agent の出力に対してメトリクスを実行した Eval 結果を保存します。

input

text

NOT NULL

Agent に提供された入力

output

text

NOT NULL

Agent が生成した出力

result

jsonb

NOT NULL

スコアと詳細を含む Eval 結果データ。例：

{
  "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 のシステムプロンプトまたは指示

test_info

jsonb

NOT NULL

追加のテストメタデータと設定

global_run_id

uuidv4

NOT NULL

関連する評価実行をグループ化します（例：1回の 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 を作成したライブラリ、パッケージ、サービス（例：@mastra/core、express、pg）

kind

integer

NOT NULL

INTERNAL（0、プロセス内）、CLIENT（1、発信呼び出し）、SERVER（2、着信呼び出し）、PRODUCER（3、非同期ジョブ作成）、CONSUMER（4、非同期ジョブ処理）

attributes

jsonb

Span メタデータを格納するユーザー定義のキーと値のペア

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 エポックからの経過ナノ秒

endTime

bigint

NOT NULL

Span 終了時の Unix エポックからの経過ナノ秒

createdAt

timestamp

NOT NULL