存储概览

Mastra 存储按域组织。每个域拥有一组表或集合。根据所用的适配器和配置，你可以使用所有域，也可以只使用其中一部分。

存储域

MastraCompositeStore 可路由以下域键：

并非每个存储适配器都实现了所有域。当适配器包导出对应的域类时，组合存储允许你为不同的域混用适配器。

域	描述
memory	对话持久化：消息、线程和资源（包括工作记忆）。
workflows	用于暂停和恢复的 Workflow 运行快照。
workflowDefinitions	持久化的动态 Workflow定义（Beta）。启动时会加载并实时注册。
scores	来自评估运行的评分记录。
observability	供可观测性导出器和 Studio 使用的 Trace 和 Span。
datasets	供实验使用的数据集记录、版本化条目和数据集版本。
experiments	实验运行和每个条目的实验结果。

以下 schema 定义涵盖了为 memory、workflows、scores 和 observability 文档所说明的内置数据库支持的表。其他域和非数据库适配器使用特定于实现的存储结构。

核心 schema

消息

存储对话消息及其元数据。每条消息都属于一个线程，包含实际内容以及发送者角色和消息类型的元数据。

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

数组（JSON）

NOT NULL

消息部分的数组（文本、工具调用、文件、推理等）。该数组中条目的结构因 type 而异。

experimental_attachments

数组（JSON）

CAN BE NULL

可选的文件附件数组

content

text

CAN BE NULL

可选的消息主要文本内容

toolInvocations

数组（JSON）

CAN BE NULL

汇总工具调用及其结果的可选数组

reasoning

对象（JSON）

CAN BE NULL

有关 assistant 响应背后推理过程的可选信息

annotations

对象（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 上调用 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 执行期间的状态变化

评估

存储针对 Agent 输出运行指标所得的评估结果。

input

text

NOT NULL

提供给 Agent 的输入

output

text

NOT NULL

由 Agent 生成的输出

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

Agent 的系统提示词或指令

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

追踪

捕获 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