ContextQMD
Back to Mastra

Reference: Storage overview | Storage

docs/src/content/en/reference/storage/overview.mdx

2025-12-1812.9 KB
Original Source

import { SchemaTable } from "@site/src/components/SchemaTable"; import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem";

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.

DomainDescription
memoryConversation persistence: messages, threads, and resources (including working memory).
workflowsWorkflow run snapshots used for suspend and resume.
scoresEvaluation score records from eval runs.
observabilityTraces and spans used by observability exporters and Studio.
datasetsDataset records, versioned items, and dataset versions used by experiments.
experimentsExperiment 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

<Tabs> <TabItem value="messages" label="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. 
<SchemaTable
  columns={[

{ name: 'id', type: 'uuidv4', description: 'Unique identifier for the message (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)', constraints: [{ type: 'primaryKey' }, { type: 'nullable', value: false }], }, { name: 'thread_id', type: 'uuidv4', description: 'Parent thread reference', constraints: [ { type: 'foreignKey', value: 'threads.id' }, { type: 'nullable', value: false }, ], }, { name: 'resourceId', type: 'uuidv4', description: 'ID of the resource that owns this message', constraints: [{ type: 'nullable', value: true }], }, { name: 'content', type: 'text', description: 'JSON of the message content in V2 format. Example: { format: 2, parts: [...] }', constraints: [{ type: 'nullable', value: false }], }, { name: 'role', type: 'text', description: 'Enum of user | assistant', constraints: [{ type: 'nullable', value: false }], }, { name: 'createdAt', type: 'timestamp', description: 'Used for thread message ordering', constraints: [{ type: 'nullable', value: false }], }, ]} />

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.

<SchemaTable
  columns={[

{ name: 'format', type: 'integer', description: 'Message format version (currently 2)', constraints: [{ type: 'nullable', value: false }], }, { name: 'parts', type: 'array (JSON)', description: 'Array of message parts (text, tool-invocation, file, reasoning, etc.). The structure of items in this array varies by type.', constraints: [{ type: 'nullable', value: false }], }, { name: 'experimental_attachments', type: 'array (JSON)', description: 'Optional array of file attachments', constraints: [{ type: 'nullable', value: true }], }, { name: 'content', type: 'text', description: 'Optional main text content of the message', constraints: [{ type: 'nullable', value: true }], }, { name: 'toolInvocations', type: 'array (JSON)', description: 'Optional array summarizing tool calls and results', constraints: [{ type: 'nullable', value: true }], }, { name: 'reasoning', type: 'object (JSON)', description: "Optional information about the reasoning process behind the assistant's response", constraints: [{ type: 'nullable', value: true }], }, { name: 'annotations', type: 'object (JSON)', description: 'Optional additional metadata or annotations', constraints: [{ type: 'nullable', value: true }], }, ]} /> </TabItem>

<TabItem value="threads" label="Threads"> Groups related messages together and associates them with a resource. Contains metadata about the conversation. 
<SchemaTable
  columns={[

{ name: 'id', type: 'uuidv4', description: 'Unique identifier for the thread (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)', constraints: [{ type: 'primaryKey' }, { type: 'nullable', value: false }], }, { name: 'resourceId', type: 'text', description: 'Primary identifier of the external resource this thread is associated with. Used to group and retrieve related threads.', constraints: [{ type: 'nullable', value: false }], }, { name: 'title', type: 'text', description: 'Title of the conversation thread', constraints: [{ type: 'nullable', value: false }], }, { name: 'metadata', type: 'text', description: 'Custom thread metadata as stringified JSON. Example:', example: { category: 'support', priority: 1, }, }, { name: 'createdAt', type: 'timestamp', constraints: [{ type: 'nullable', value: false }], }, { name: 'updatedAt', type: 'timestamp', description: 'Used for thread ordering history', constraints: [{ type: 'nullable', value: false }], }, ]} /> </TabItem>

<TabItem value="resources" label="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. 
<SchemaTable
  columns={[

{ name: 'id', type: 'text', description: 'Resource identifier (user or entity ID) - same as resourceId used in threads and agent calls', constraints: [{ type: 'primaryKey' }, { type: 'nullable', value: false }], }, { name: 'workingMemory', type: 'text', description: 'Persistent working memory data as Markdown text. Contains user profile, preferences, and contextual information that persists across conversation threads.', constraints: [{ type: 'nullable', value: true }], }, { name: 'metadata', type: 'jsonb', description: 'Additional resource metadata as JSON. Example:', example: { preferences: { language: 'en', timezone: 'UTC' }, tags: ['premium', 'beta-user'], }, constraints: [{ type: 'nullable', value: true }], }, { name: 'createdAt', type: 'timestamp', description: 'When the resource record was first created', constraints: [{ type: 'nullable', value: false }], }, { name: 'updatedAt', type: 'timestamp', description: 'When the working memory was last updated', constraints: [{ type: 'nullable', value: false }], }, ]} /> </TabItem>

<TabItem value="workflows" label="Workflows"> When `suspend()` is called on a workflow, its state is saved in the following format. When `resume()` is called, that state is rehydrated. 
<SchemaTable
  columns={[

{ name: 'workflow_name', type: 'text', description: 'Name of the workflow', constraints: [{ type: 'nullable', value: false }], }, { name: 'run_id', type: 'uuidv4', description: 'Unique identifier for the workflow execution. Used to track state across suspend/resume cycles (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)', constraints: [{ type: 'nullable', value: false }], }, { name: 'snapshot', type: 'text', description: 'Serialized workflow state as JSON. Example:', example: { value: { currentState: 'running' }, context: { stepResults: {}, attempts: {}, triggerData: {}, }, activePaths: [], runId: '550e8400-e29b-41d4-a716-446655440000', timestamp: 1648176000000, }, constraints: [{ type: 'nullable', value: false }], }, { name: 'createdAt', type: 'timestamp', constraints: [{ type: 'nullable', value: false }], }, { name: 'updatedAt', type: 'timestamp', description: 'Last modification time, used to track state changes during workflow execution', constraints: [{ type: 'nullable', value: false }], }, ]} /> </TabItem>

<TabItem value="evals" label="Evals"> Stores eval results from running metrics against agent outputs. 
<SchemaTable
  columns={[

{ name: 'input', type: 'text', description: 'Input provided to the agent', constraints: [{ type: 'nullable', value: false }], }, { name: 'output', type: 'text', description: 'Output generated by the agent', constraints: [{ type: 'nullable', value: false }], }, { name: 'result', type: 'jsonb', description: 'Eval result data that includes score and details. Example:', example: { score: 0.95, details: { reason: 'Response accurately reflects source material', citations: ['page 1', 'page 3'], }, }, constraints: [{ type: 'nullable', value: false }], }, { name: 'agent_name', type: 'text', constraints: [{ type: 'nullable', value: false }], }, { name: 'metric_name', type: 'text', description: 'e.g Faithfulness, Hallucination, etc.', constraints: [{ type: 'nullable', value: false }], }, { name: 'instructions', type: 'text', description: 'System prompt or instructions for the agent', constraints: [{ type: 'nullable', value: false }], }, { name: 'test_info', type: 'jsonb', description: 'Additional test metadata and configuration', constraints: [{ type: 'nullable', value: false }], }, { name: 'global_run_id', type: 'uuidv4', description: 'Groups related evaluation runs (e.g. all unit tests in a CI run)', constraints: [{ type: 'nullable', value: false }], }, { name: 'run_id', type: 'uuidv4', description: 'Unique identifier for the run being evaluated (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)', constraints: [{ type: 'nullable', value: false }], }, { name: 'created_at', type: 'timestamp', constraints: [{ type: 'nullable', value: false }], }, ]} /> </TabItem>

<TabItem value="traces" label="Traces"> Captures OpenTelemetry traces for monitoring and debugging. 
<SchemaTable
  columns={[

{ name: 'id', type: 'text', description: 'Unique trace identifier', constraints: [{ type: 'nullable', value: false }, { type: 'primaryKey' }], }, { name: 'parentSpanId', type: 'text', description: 'ID of the parent span. Null if span is top level', }, { name: 'name', type: 'text', description: 'Hierarchical operation name (e.g. workflow.myWorkflow.execute, http.request, database.query)', constraints: [{ type: 'nullable', value: false }], }, { name: 'traceId', type: 'text', description: 'Root trace identifier that groups related spans', constraints: [{ type: 'nullable', value: false }], }, { name: 'scope', type: 'text', description: 'Library/package/service that created the span (e.g. @mastra/core, express, pg)', constraints: [{ type: 'nullable', value: false }], }, { name: 'kind', type: 'integer', description: 'INTERNAL (0, within process), CLIENT (1, outgoing calls), SERVER (2, incoming calls), PRODUCER (3, async job creation), CONSUMER (4, async job processing)', constraints: [{ type: 'nullable', value: false }], }, { name: 'attributes', type: 'jsonb', description: 'User defined key-value pairs that contain span metadata', }, { name: 'status', type: 'jsonb', description: 'JSON object with code (UNSET=0, ERROR=1, OK=2) and optional message. Example:', example: { code: 1, message: 'HTTP request failed with status 500', }, }, { name: 'events', type: 'jsonb', description: 'Time-stamped events that occurred during the span', }, { name: 'links', type: 'jsonb', description: 'Links to other related spans', }, { name: 'other', type: 'text', description: 'Additional OpenTelemetry span fields as stringified JSON. Example:', example: { droppedAttributesCount: 2, droppedEventsCount: 1, instrumentationLibrary: '@opentelemetry/instrumentation-http', }, }, { name: 'startTime', type: 'bigint', description: 'Nanoseconds since Unix epoch when span started', constraints: [{ type: 'nullable', value: false }], }, { name: 'endTime', type: 'bigint', description: 'Nanoseconds since Unix epoch when span ended', constraints: [{ type: 'nullable', value: false }], }, { name: 'createdAt', type: 'timestamp', constraints: [{ type: 'nullable', value: false }], }, ]} /> </TabItem> </Tabs>