# Storage overview

Mastra storage is organized into domains. Each domain owns a set of tables or collections. Depending on your adapter and configuration, you may use all domains or only a subset.

## Storage domains

`MastraCompositeStore` can route the following domain keys:

Not every storage adapter implements every domain. Composite storage lets you mix adapters per domain when the adapter packages export the corresponding domain classes.

| Domain          | Description                                                                            |
| --------------- | -------------------------------------------------------------------------------------- |
| `memory`        | Conversation persistence: messages, threads, and resources (including working memory). |
| `workflows`     | Workflow run snapshots used for suspend and resume.                                    |
| `scores`        | Evaluation score records from eval runs.                                               |
| `observability` | Traces and spans used by observability exporters and Studio.                           |
| `datasets`      | Dataset records, versioned items, and dataset versions used by experiments.            |
| `experiments`   | Experiment runs and per-item experiment results.                                       |

The schema definitions below cover the built-in database-backed tables documented for `memory`, `workflows`, `scores`, and `observability`. Other domains, and non-database adapters, use implementation-specific storage structures.

## Core schema

**Messages**:

Stores conversation messages and their metadata. Each message belongs to a thread and contains the actual content along with metadata about the sender role and message type.

iduuidv4PRIMARYKEYNOT NULLUnique identifier for the message (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)thread\_iduuidv4FK → threads.idNOT NULLParent thread referenceresourceIduuidv4CAN BE NULLID of the resource that owns this messagecontenttextNOT NULLJSON of the message content in V2 format. Example: `{ format: 2, parts: [...] }`roletextNOT NULLEnum of `user | assistant`createdAttimestampNOT NULLUsed for thread message ordering

The message `content` column contains a JSON object conforming to the `MastraMessageContentV2` type, which is designed to align closely with the AI SDK `UIMessage` message shape.

formatintegerNOT NULLMessage format version (currently 2)partsarray (JSON)NOT NULLArray of message parts (text, tool-invocation, file, reasoning, etc.). The structure of items in this array varies by `type`.experimental\_attachmentsarray (JSON)CAN BE NULLOptional array of file attachmentscontenttextCAN BE NULLOptional main text content of the messagetoolInvocationsarray (JSON)CAN BE NULLOptional array summarizing tool calls and resultsreasoningobject (JSON)CAN BE NULLOptional information about the reasoning process behind the assistant's responseannotationsobject (JSON)CAN BE NULLOptional additional metadata or annotations

**Threads**:

Groups related messages together and associates them with a resource. Contains metadata about the conversation.

iduuidv4PRIMARYKEYNOT NULLUnique identifier for the thread (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)resourceIdtextNOT NULLPrimary identifier of the external resource this thread is associated with. Used to group and retrieve related threads.titletextNOT NULLTitle of the conversation threadmetadatatextCustom thread metadata as stringified JSON. Example:

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

createdAttimestampNOT NULLupdatedAttimestampNOT NULLUsed for thread ordering history

**Resources**:

Stores user-specific data for resource-scoped working memory. Each resource represents a user or entity, allowing working memory to persist across all conversation threads for that user.

idtextPRIMARYKEYNOT NULLResource identifier (user or entity ID) - same as resourceId used in threads and agent callsworkingMemorytextCAN BE NULLPersistent working memory data as Markdown text. Contains user profile, preferences, and contextual information that persists across conversation threads.metadatajsonbCAN BE NULLAdditional resource metadata as JSON. Example:

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

createdAttimestampNOT NULLWhen the resource record was first createdupdatedAttimestampNOT NULLWhen the working memory was last updated

**Workflows**:

When `suspend()` is called on a workflow, its state is saved in the following format. When `resume()` is called, that state is rehydrated.

workflow\_nametextNOT NULLName of the workflowrun\_iduuidv4NOT NULLUnique identifier for the workflow execution. Used to track state across suspend/resume cycles (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)snapshottextNOT NULLSerialized workflow state as JSON. Example:

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

createdAttimestampNOT NULLupdatedAttimestampNOT NULLLast modification time, used to track state changes during workflow execution

**Evals**:

Stores eval results from running metrics against agent outputs.

inputtextNOT NULLInput provided to the agentoutputtextNOT NULLOutput generated by the agentresultjsonbNOT NULLEval result data that includes score and details. Example:

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

agent\_nametextNOT NULLmetric\_nametextNOT NULLe.g Faithfulness, Hallucination, etc.instructionstextNOT NULLSystem prompt or instructions for the agenttest\_infojsonbNOT NULLAdditional test metadata and configurationglobal\_run\_iduuidv4NOT NULLGroups related evaluation runs (e.g. all unit tests in a CI run)run\_iduuidv4NOT NULLUnique identifier for the run being evaluated (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)created\_attimestampNOT NULL

**Traces**:

Captures OpenTelemetry traces for monitoring and debugging.

idtextNOT NULLPRIMARYKEYUnique trace identifierparentSpanIdtextID of the parent span. Null if span is top levelnametextNOT NULLHierarchical operation name (e.g. `workflow.myWorkflow.execute`, `http.request`, `database.query`)traceIdtextNOT NULLRoot trace identifier that groups related spansscopetextNOT NULLLibrary/package/service that created the span (e.g. `@mastra/core`, `express`, `pg`)kindintegerNOT NULL`INTERNAL` (0, within process), `CLIENT` (1, outgoing calls), `SERVER` (2, incoming calls), `PRODUCER` (3, async job creation), `CONSUMER` (4, async job processing)attributesjsonbUser defined key-value pairs that contain span metadatastatusjsonbJSON object with `code` (UNSET=0, ERROR=1, OK=2) and optional `message`. Example:

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

eventsjsonbTime-stamped events that occurred during the spanlinksjsonbLinks to other related spansothertextAdditional OpenTelemetry span fields as stringified JSON. Example:

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

startTimebigintNOT NULLNanoseconds since Unix epoch when span startedendTimebigintNOT NULLNanoseconds since Unix epoch when span endedcreatedAttimestampNOT NULL