Convex Storage

The Convex storage implementation provides a serverless storage solution using Convex, a full-stack TypeScript development platform with real-time sync and automatic caching.

Installation

npm install @mastra/convex@beta

Convex Setup

Before using ConvexStore, you need to set up the Convex schema and storage handler in your Convex project.

1. Set up Convex Schema

In convex/schema.ts:

import { defineSchema } from 'convex/server';
import {
  mastraThreadsTable,
  mastraMessagesTable,
  mastraResourcesTable,
  mastraWorkflowSnapshotsTable,
  mastraScoresTable,
  mastraVectorIndexesTable,
  mastraVectorsTable,
  mastraDocumentsTable,
} from '@mastra/convex/server';

export default defineSchema({
  mastra_threads: mastraThreadsTable,
  mastra_messages: mastraMessagesTable,
  mastra_resources: mastraResourcesTable,
  mastra_workflow_snapshots: mastraWorkflowSnapshotsTable,
  mastra_scorers: mastraScoresTable,
  mastra_vector_indexes: mastraVectorIndexesTable,
  mastra_vectors: mastraVectorsTable,
  mastra_documents: mastraDocumentsTable,
});

2. Create the Storage Handler

In convex/mastra/storage.ts:

import { mastraStorage } from '@mastra/convex/server';

export const handle = mastraStorage;

3. Deploy to Convex

npx convex dev
# or for production
npx convex deploy

Usage

import { ConvexStore } from "@mastra/convex";

const storage = new ConvexStore({
  id: 'convex-storage',
  deploymentUrl: process.env.CONVEX_URL!,
  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
});

Parameters

deploymentUrl:

string

Convex deployment URL (e.g., https://your-project.convex.cloud)

adminAuthToken:

string

Convex admin authentication token for backend access

storageFunction?:

string

= mastra/storage:handle

Path to the storage mutation function (default: 'mastra/storage:handle')

Constructor Examples

import { ConvexStore } from "@mastra/convex";

// Basic configuration
const store = new ConvexStore({
  id: 'convex-storage',
  deploymentUrl: "https://your-project.convex.cloud",
  adminAuthToken: "your-admin-token",
});

// With custom storage function path
const storeCustom = new ConvexStore({
  id: 'convex-storage',
  deploymentUrl: "https://your-project.convex.cloud",
  adminAuthToken: "your-admin-token",
  storageFunction: "custom/path:handler",
});

Additional Notes

Schema Management

The storage implementation uses typed Convex tables for each Mastra domain:

Domain	Convex Table	Purpose
Threads	mastra_threads	Conversation threads
Messages	mastra_messages	Chat messages
Resources	mastra_resources	User working memory
Workflows	mastra_workflow_snapshots	Workflow state
Scorers	mastra_scorers	Evaluation data
Fallback	mastra_documents	Unknown tables

Architecture

All typed tables include:

• An id field for Mastra's record ID (distinct from Convex's auto-generated _id)
• A by_record_id index for efficient lookups by Mastra ID

This design ensures compatibility with Mastra's storage contract while leveraging Convex's automatic indexing and real-time capabilities.

Environment Variables

Set these environment variables for your deployment:

• CONVEX_URL – Your Convex deployment URL
• CONVEX_ADMIN_KEY – Admin authentication token (get from Convex dashboard)

Related

• Convex Vector Store
• Convex Documentation