Skip to main content

MastraStorage

MastraStorage provides a unified interface for managing:

  • Suspended Workflows: the serialized state of suspended workflows (so they can be resumed later)
  • Memory: threads and messages per resourceId in your application
  • Traces: OpenTelemetry traces from all components of Mastra
  • Eval Datasets: scores and scoring reasons from eval runs


Diagram showing storage in Mastra

Mastra provides different storage providers, but you can treat them as interchangeable. Eg, you could use libsql in development but postgres in production, and your code will work the same both ways.

Configuration​

Mastra can be configured with a default storage option:

import { Mastra } from "@mastra/core/mastra";
import { LibSQLStore } from "@mastra/libsql";

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

If you do not specify any storage configuration, Mastra will not persist data across application restarts or deployments. For any deployment beyond local testing you should provide your own storage configuration either on Mastra or directly within new Memory().

Data Schema​

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.


id
uuidv4
PRIMARYKEY
NOT NULL
Unique identifier for the message (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
thread_id
uuidv4
FK → threads.id
NOT NULL
Parent thread reference
resourceId
uuidv4
CAN BE NULL
ID of the resource that owns this message
content
text
NOT NULL
JSON of the message content in V2 format. Example: { format: 2, parts: [...] }
role
text
NOT NULL
Enum of user | assistant
createdAt
timestamp
NOT NULL
Used 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.

format
integer
NOT NULL
Message format version (currently 2)
parts
array (JSON)
NOT NULL
Array of message parts (text, tool-invocation, file, reasoning, etc.). The structure of items in this array varies by type.
experimental_attachments
array (JSON)
CAN BE NULL
Optional array of file attachments
content
text
CAN BE NULL
Optional main text content of the message
toolInvocations
array (JSON)
CAN BE NULL
Optional array summarizing tool calls and results
reasoning
object (JSON)
CAN BE NULL
Optional information about the reasoning process behind the assistant's response
annotations
object (JSON)
CAN BE NULL
Optional additional metadata or annotations

Querying Messages​

Messages are stored in a V2 format internally, which is roughly equivalent to the AI SDK's UIMessage format. When querying messages using getMessages, you can specify the desired output format, defaulting to v1 for backwards compatibility:

// Get messages in the default V1 format (roughly equivalent to AI SDK's CoreMessage format)
const messagesV1 = await mastra
  .getStorage()
  .getMessages({ threadId: "your-thread-id" });

// Get messages in the V2 format (roughly equivalent to AI SDK's UIMessage format)
const messagesV2 = await mastra
  .getStorage()
  .getMessages({ threadId: "your-thread-id", format: "v2" });

You can also retrieve messages using an array of message IDs. Note that unlike getMessages, this defaults to the V2 format:

const messagesV1 = await mastra
  .getStorage()
  .getMessagesById({ messageIds: messageIdArr, format: "v1" });

const messagesV2 = await mastra
  .getStorage()
  .getMessagesById({ messageIds: messageIdArr });

Storage Providers​

Mastra supports the following providers:

On this page