MastraStorage

MastraStorageは以下を管理するための統一インターフェースを提供します：

一時停止されたワークフロー：一時停止されたワークフローのシリアル化された状態（後で再開できるように）
メモリ：アプリケーション内のresourceIdごとのスレッドとメッセージ
トレース：MastraのすべてのコンポーネントからのOpenTelemetryトレース
評価データセット：評価実行からのスコアと採点理由

Mastraは異なるストレージプロバイダーを提供していますが、それらを互換性のあるものとして扱うことができます。例えば、開発環境ではlibsqlを使用し、本番環境ではpostgresを使用することができ、コードは両方の環境で同じように動作します。

設定

Mastra はデフォルトのストレージオプションで設定できます。


import { Mastra } from "@mastra/core/mastra";
import { LibSQLStore } from "@mastra/libsql";
 
const mastra = new Mastra({
  storage: new LibSQLStore({
    url: "file:./mastra.db",
  }),
});

storage 設定を指定しない場合、Mastra はアプリケーションの再起動やデプロイメントの際にデータを永続化しません。ローカルテスト以外のデプロイメントでは、Mastra または new Memory() 内で独自のストレージ設定を指定する必要があります。

データスキーマ

Messages

会話メッセージとそのメタデータを保存します。各メッセージはスレッドに属し、送信者の役割とメッセージタイプに関するメタデータと共に実際のコンテンツを含みます。

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列には、AI SDKのUIMessageメッセージ形状と密接に整合するよう設計されたMastraMessageContentV2タイプに準拠するJSONオブジェクトが含まれます。

format

integer

NOT NULL

メッセージ形式のバージョン（現在は2）

parts

array (JSON)

NOT NULL

メッセージパーツの配列（テキスト、ツール呼び出し、ファイル、推論など）。この配列内のアイテムの構造はtypeによって異なります。

experimental_attachments

array (JSON)

CAN BE NULL

ファイル添付のオプション配列

content

text

CAN BE NULL

メッセージのオプションのメインテキストコンテンツ

toolInvocations

array (JSON)

CAN BE NULL

ツール呼び出しと結果を要約するオプション配列

reasoning

object (JSON)

CAN BE NULL

アシスタントの応答の背後にある推論プロセスに関するオプション情報

annotations

object (JSON)

CAN BE NULL

オプションの追加メタデータまたは注釈

Threads

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

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

スレッド順序履歴に使用

Resources

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

text

PRIMARYKEY

NOT NULL

リソース識別子（ユーザーまたはエンティティID）- スレッドとエージェント呼び出しで使用される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

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

注意: このテーブルは、リソーススコープのワーキングメモリをサポートするストレージアダプター（LibSQL、PostgreSQL、Upstash）によってのみ作成・使用されます。他のストレージアダプターでは、リソーススコープメモリが試行された場合に有用なエラーメッセージが提供されます。

Workflows

ワークフローでsuspendが呼び出されると、その状態は以下の形式で保存されます。resumeが呼び出されると、その状態が復元されます。

workflow_name

text

NOT NULL

ワークフローの名前

run_id

uuidv4

NOT NULL

ワークフロー実行の一意識別子。suspend/resumeサイクル全体で状態を追跡するために使用されます（形式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）

snapshot

text

NOT NULL

JSONとしてシリアル化されたワークフロー状態。例：


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

createdAt

timestamp

NOT NULL

updatedAt

timestamp

NOT NULL

最終更新時刻。ワークフロー実行中の状態変更を追跡するために使用されます

Eval Datasets

エージェントの出力に対してメトリクスを実行した評価結果を保存します。

input

text

NOT NULL

エージェントに提供された入力

output

text

NOT NULL

エージェントによって生成された出力

result

jsonb

NOT NULL

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


{
  "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

エージェントのシステムプロンプトまたは指示

test_info

jsonb

NOT NULL

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

global_run_id

uuidv4

NOT NULL

関連する評価実行をグループ化します（例：CI実行内のすべてのユニットテスト）

run_id

uuidv4

NOT NULL

評価対象の実行の一意識別子（形式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）

created_at

timestamp

NOT NULL

Traces

監視とデバッグのためのOpenTelemetryトレースをキャプチャします。

text

NOT NULL

PRIMARYKEY

一意のトレース識別子

parentSpanId

text

親スパンのID。スパンがトップレベルの場合はNull

name

text

NOT NULL

階層的な操作名（例：workflow.myWorkflow.execute、http.request、database.query）

traceId

text

NOT NULL

関連するスパンをグループ化するルートトレース識別子

scope

text

NOT NULL

スパンを作成したライブラリ/パッケージ/サービス（例：@mastra/core、express、pg）

kind

integer

NOT NULL

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

attributes

jsonb

スパンメタデータを含むユーザー定義のキー値ペア

status

jsonb

code（UNSET=0、ERROR=1、OK=2）とオプションのmessageを含むJSONオブジェクト。例：


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

events

jsonb

スパン中に発生したタイムスタンプ付きイベント

links

jsonb

他の関連スパンへのリンク

other

text

文字列化されたJSONとしての追加のOpenTelemetryスパンフィールド。例：


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

startTime

bigint

NOT NULL

スパンが開始されたUnixエポックからのナノ秒

endTime

bigint

NOT NULL

スパンが終了したUnixエポックからのナノ秒

createdAt

timestamp

NOT NULL

メッセージのクエリ

メッセージは内部的にV2形式で保存されており、これはAI SDKのUIMessage形式とほぼ同等です。getMessagesを使用してメッセージをクエリする際、希望する出力形式を指定でき、後方互換性のためデフォルトはv1になっています：


// デフォルトのV1形式でメッセージを取得（AI SDKのCoreMessage形式とほぼ同等）
const messagesV1 = await mastra.getStorage().getMessages({ threadId: 'your-thread-id' });
 
// V2形式でメッセージを取得（AI SDKのUIMessage形式とほぼ同等）
const messagesV2 = await mastra.getStorage().getMessages({ threadId: 'your-thread-id', format: 'v2' });

Storage Providers

Mastraは以下のプロバイダーをサポートしています：

ローカル開発については、LibSQL Storageをご確認ください
本番環境については、PostgreSQL Storageをご確認ください
サーバーレスデプロイメントについては、Upstash Storageをご確認ください