Documentation Index
Fetch the complete documentation index at: https://mintlify.com/mastra-ai/mastra/llms.txt
Use this file to discover all available pages before exploring further.
Overview
MastraCompositeStore is the interface that all storage providers must implement. It provides standardized methods for persisting threads, messages, workflow runs, agents, and other data.
Type Definition
interface MastraCompositeStore {
// Thread operations
getThreadById(threadId: string): Promise<StorageThreadType | null>;
listThreads(args: StorageListThreadsInput): Promise<StorageListThreadsOutput>;
saveThread(thread: StorageThreadType): Promise<StorageThreadType>;
deleteThread(threadId: string): Promise<void>;
cloneThread?(input: StorageCloneThreadInput): Promise<StorageCloneThreadOutput>;
// Message operations
listMessages(args: StorageListMessagesInput): Promise<StorageListMessagesOutput>;
listMessagesByResourceId?(args: StorageListMessagesByResourceIdInput): Promise<StorageListMessagesOutput>;
saveMessages(messages: MastraDBMessage[]): Promise<MastraDBMessage[]>;
deleteMessage?(input: MessageDeleteInput): Promise<void>;
// Workflow operations
saveWorkflowRun(run: StorageWorkflowRun): Promise<void>;
getWorkflowRunById(runId: string, fields?: WorkflowStateField[]): Promise<WorkflowState | null>;
listWorkflowRuns(input?: StorageListWorkflowRunsInput): Promise<WorkflowRuns>;
deleteWorkflowRun(runId: string): Promise<void>;
// Agent operations (for stored agents)
createAgent?(input: StorageCreateAgentInput): Promise<StorageResolvedAgentType>;
getAgentByIdResolved?(id: string): Promise<StorageResolvedAgentType | null>;
updateAgent?(input: StorageUpdateAgentInput): Promise<StorageResolvedAgentType>;
deleteAgent?(id: string): Promise<void>;
listAgentsResolved?(input?: StorageListAgentsInput): Promise<StorageListAgentsOutput>;
// Initialization
init?(): Promise<void>;
}
Thread Methods
getThreadById
getThreadById(threadId: string): Promise<StorageThreadType | null>
The unique identifier of the thread
The thread or null if not found
listThreads
listThreads(args: StorageListThreadsInput): Promise<StorageListThreadsOutput>
args
StorageListThreadsInput
required
Query parameters including filters, pagination, and ordering
saveThread
saveThread(thread: StorageThreadType): Promise<StorageThreadType>
thread
StorageThreadType
required
The thread data to save
deleteThread
deleteThread(threadId: string): Promise<void>
The ID of the thread to delete
cloneThread (optional)
cloneThread?(input: StorageCloneThreadInput): Promise<StorageCloneThreadOutput>
input
StorageCloneThreadInput
required
Clone configuration including source thread ID, filters, and options
The cloned thread and messages
Message Methods
listMessages
listMessages(args: StorageListMessagesInput): Promise<StorageListMessagesOutput>
args
StorageListMessagesInput
required
Query parameters including thread ID(s), pagination, and filters
result
StorageListMessagesOutput
Paginated message results
listMessagesByResourceId (optional)
listMessagesByResourceId?(args: StorageListMessagesByResourceIdInput): Promise<StorageListMessagesOutput>
args
StorageListMessagesByResourceIdInput
required
Query parameters including resource ID, pagination, and filters
result
StorageListMessagesOutput
Paginated message results
saveMessages
saveMessages(messages: MastraDBMessage[]): Promise<MastraDBMessage[]>
messages
MastraDBMessage[]
required
Array of messages to save
deleteMessage (optional)
deleteMessage?(input: MessageDeleteInput): Promise<void>
input
MessageDeleteInput
required
Message ID and thread ID
Workflow Methods
saveWorkflowRun
saveWorkflowRun(run: StorageWorkflowRun): Promise<void>
run
StorageWorkflowRun
required
The workflow run data to save
getWorkflowRunById
getWorkflowRunById(runId: string, fields?: WorkflowStateField[]): Promise<WorkflowState | null>
Optional fields to include: ‘result’, ‘error’, ‘payload’, ‘steps’, ‘activeStepsPath’, ‘serializedStepGraph’
The workflow run state or null if not found
listWorkflowRuns
listWorkflowRuns(input?: StorageListWorkflowRunsInput): Promise<WorkflowRuns>
input
StorageListWorkflowRunsInput
Query parameters including workflow name, date range, status, and pagination
Object containing runs array and total count
deleteWorkflowRun
deleteWorkflowRun(runId: string): Promise<void>
The workflow run ID to delete
Agent Methods (Optional)
These methods are optional and only needed for storage providers that support stored agents.
createAgent
createAgent?(input: StorageCreateAgentInput): Promise<StorageResolvedAgentType>
input
StorageCreateAgentInput
required
Agent configuration including id, name, instructions, model, tools, etc.
The created agent with resolved configuration
getAgentByIdResolved
getAgentByIdResolved?(id: string): Promise<StorageResolvedAgentType | null>
agent
StorageResolvedAgentType | null
The agent or null if not found
updateAgent
updateAgent?(input: StorageUpdateAgentInput): Promise<StorageResolvedAgentType>
input
StorageUpdateAgentInput
required
Agent update data including id and fields to update
The updated agent with resolved configuration
deleteAgent
deleteAgent?(id: string): Promise<void>
listAgentsResolved
listAgentsResolved?(input?: StorageListAgentsInput): Promise<StorageListAgentsOutput>
Query parameters including filters and pagination
Initialization
init
Optional initialization method called when storage is first used. Use this to set up database schemas, create tables, or establish connections.
Available Storage Providers
Mastra provides several storage providers out of the box:
@mastra/libsql - LibSQL/Turso database storage@mastra/postgres - PostgreSQL storage@mastra/upstash - Upstash Redis storage@mastra/memory - In-memory storage (development only)
Example Usage
import { LibSQLStore } from '@mastra/libsql';
import { Mastra } from '@mastra/core';
import { Memory } from '@mastra/memory';
// Create storage instance
const storage = new LibSQLStore({
id: 'mastra-storage',
url: process.env.DATABASE_URL || ':memory:'
});
// Initialize storage (if needed)
await storage.init?.();
// Use with Mastra
const mastra = new Mastra({
storage,
agents: { /* ... */ },
workflows: { /* ... */ }
});
// Use with Memory
const memory = new Memory({
name: 'conversation-memory',
storage
});
// Thread operations
const thread = await storage.saveThread({
id: 'thread-123',
title: 'Support Conversation',
resourceId: 'user-456',
createdAt: new Date(),
updatedAt: new Date()
});
// Message operations
const messages = await storage.listMessages({
threadId: 'thread-123',
perPage: 50
});
// Workflow operations
const runs = await storage.listWorkflowRuns({
workflowName: 'data-processor',
status: 'success'
});