Skip to Content
DocsStorageOverview

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
content
text
NOT NULL
role
text
NOT NULL
Enum of system | user | assistant | tool
type
text
NOT NULL
Enum of text | tool-call | tool-result
createdAt
timestamp
NOT NULL
Used for thread message ordering

Storage Providers

Mastra supports the following providers:

With CopilotKitOverview