> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 存储概览

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

## 存储域

`MastraCompositeStore` 可路由以下域键：

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

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

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

## 核心 schema

**消息**:

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

iduuidv4PRIMARYKEYNOT NULL消息的唯一标识符（格式：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）thread\_iduuidv4FK → threads.idNOT NULL父线程引用resourceIduuidv4CAN BE NULL拥有此消息的资源 IDcontenttextNOT NULLV2 格式的消息内容 JSON。例如：`{ format: 2, parts: [...] }`roletextNOT NULL`user | assistant` 枚举值createdAttimestampNOT NULL用于对线程中的消息排序

消息的 `content` 列包含符合 `MastraMessageContentV2` 类型的 JSON 对象，该类型旨在与 AI SDK 的 `UIMessage` 消息结构紧密对齐。

formatintegerNOT NULL消息格式版本（当前为 2）parts数组（JSON）NOT NULL消息部分的数组（文本、工具调用、文件、推理等）。该数组中条目的结构因 `type` 而异。experimental\_attachments数组（JSON）CAN BE NULL可选的文件附件数组contenttextCAN BE NULL可选的消息主要文本内容toolInvocations数组（JSON）CAN BE NULL汇总工具调用及其结果的可选数组reasoning对象（JSON）CAN BE NULL有关 assistant 响应背后推理过程的可选信息annotations对象（JSON）CAN BE NULL可选的额外元数据或注释

**线程**:

将相关消息组合在一起，并将其与资源关联。包含有关对话的元数据。

iduuidv4PRIMARYKEYNOT NULL线程的唯一标识符（格式：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）resourceIdtextNOT NULL此线程关联的外部资源的主标识符。用于对相关线程进行分组和检索。titletextNOT NULL对话线程的标题metadatatext字符串化 JSON 形式的自定义线程元数据。例如：

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

createdAttimestampNOT NULLupdatedAttimestampNOT NULL用于线程历史记录排序

**资源**:

存储资源范围工作记忆的用户特定数据。每个资源代表一个用户或实体，使工作记忆能够在该用户的所有对话线程之间持久保留。

idtextPRIMARYKEYNOT NULL资源标识符（用户或实体 ID）：与在线程和 Agent 调用中使用的 resourceId 相同workingMemorytextCAN BE NULLMarkdown 文本形式的持久工作记忆数据。包含跨对话线程持久保留的用户资料、偏好设置和上下文信息。metadatajsonbCAN BE NULLJSON 形式的额外资源元数据。例如：

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

createdAttimestampNOT NULL资源记录首次创建的时间updatedAttimestampNOT NULL工作记忆上次更新的时间

**工作流**:

在 Workflow 上调用 `suspend()` 时，其状态会按以下格式保存。调用 `resume()` 时，该状态会被重新还原。

workflow\_nametextNOT NULLWorkflow 的名称run\_iduuidv4NOT NULLWorkflow 执行的唯一标识符。用于跟踪暂停/恢复周期中的状态（格式：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）snapshottextNOT NULL序列化为 JSON 的 Workflow 状态。例如：

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

createdAttimestampNOT NULLupdatedAttimestampNOT NULL最后修改时间，用于跟踪 Workflow 执行期间的状态变化

**评估**:

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

inputtextNOT NULL提供给 Agent 的输入outputtextNOT NULL由 Agent 生成的输出resultjsonbNOT NULL包含分数和详细信息的评估结果数据。例如：

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

agent\_nametextNOT NULLmetric\_nametextNOT NULL例如 Faithfulness、Hallucination 等。instructionstextNOT NULLAgent 的系统提示词或指令test\_infojsonbNOT NULL额外的测试元数据和配置global\_run\_iduuidv4NOT NULL将相关评估运行分组（例如一次 CI 运行中的所有单元测试）run\_iduuidv4NOT NULL正在评估的运行的唯一标识符（格式：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）created\_attimestampNOT NULL

**追踪**:

捕获 OpenTelemetry Trace 以用于监控和调试。

idtextNOT NULLPRIMARYKEYTrace 的唯一标识符parentSpanIdtext父 Span 的 ID。如果 Span 位于顶层，则为 nullnametextNOT NULL层级操作名称（例如 `workflow.myWorkflow.execute`、`http.request`、`database.query`）traceIdtextNOT NULL将相关 Span 分组的根 Trace 标识符scopetextNOT NULL创建该 Span 的库、包或服务（例如 `@mastra/core`、`express`、`pg`）kindintegerNOT NULL`INTERNAL`（0，进程内）、`CLIENT`（1，传出调用）、`SERVER`（2，传入调用）、`PRODUCER`（3，异步任务创建）、`CONSUMER`（4，异步任务处理）attributesjsonb包含 Span 元数据的用户定义键值对statusjsonb包含 `code`（UNSET=0、ERROR=1、OK=2）和可选 `message` 的 JSON 对象。例如：

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

eventsjsonbSpan 期间发生的带时间戳事件linksjsonb指向其他相关 Span 的链接othertext字符串化 JSON 形式的额外 OpenTelemetry Span 字段。例如：

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

startTimebigintNOT NULLSpan 开始时距 Unix 纪元的纳秒数endTimebigintNOT NULLSpan 结束时距 Unix 纪元的纳秒数createdAttimestampNOT NULL