Mastra Storage: a flexible storage system for AI Applications

Introducing Mastra Storage

If you've built AI applications before, you know how quickly data management can become overwhelming. Databases used in AI applications have unique challenges that come from - maintaining contextual conversation histories across multiple turns, persisting complex workflow states, tracking detailed evaluation metrics, or storing the monitoring data needed to understand your agents' behavior.

Mastra Storage was built to address this. It provides a unified system that stores, retrieves, and manages your AI application's data, from conversation threads to workflow states.

But what makes Mastra Storage particularly powerful is its flexibility. It's easy to get started but also easy to scale. Mastra Storage offers flexible storage backends that can change as your needs evolve. Whether you're building a prototype or scaling to production, the storage system is designed to adapt.

How Mastra Storage Works

At its core, Mastra Storage manages four essential types of data:

1. Memory

Every conversation with an AI agent generates a thread of messages. These threads are organized by resource IDs, making it easy to maintain context across multiple interactions. Whether you're building a customer support bot or a coding assistant, the agent can recall past conversations and maintain coherent dialogs.

2. Workflow

AI workflows often need to pause and resume, especially when waiting for user input or external data. Mastra Storage automatically handles the serialization and restoration of workflow states. This means your workflows can seamlessly pick up where they left off, maintaining their context and progress.

3. Evaluation Data

Improving AI systems requires measuring their performance. Our storage system keeps track of evaluation results, storing both the raw scores and the reasoning behind them. This data helps you understand how your agents are performing and where they need improvement.

4. Observability

Debugging AI applications can be challenging. That's why we integrated OpenTelemetry traces into our storage system. Every important operation is tracked, giving you visibility into what your agents are doing and why they made certain decisions.

Flexible by design

While Mastra Storage provides a unified interface for all these features, we understand that different applications have different needs. That's why we have flexible database options. Here's how it works in practice.

Mastra comes with default storage (LibSQL) built-in, so you can start with just:

import { Mastra } from '@mastra/core/mastra';
import { agent } from './agents'; // Your agent

const mastra = new Mastra({
  agents: { agent },
});

If you need to customize the storage location:

import { Mastra } from '@mastra/core/mastra';
import { DefaultStorage } from '@mastra/core/storage/libsql';
import { agent } from './agents';

const mastra = new Mastra({
  agents: { agent },
  storage: new DefaultStorage({
    config: {
      url: "file:.mastra/mastra.db"
    }
  })
});

If you want to use PostgreSQL for production, just switch by changing the storage provider:

import { Mastra } from '@mastra/core/mastra';
import { PostgresStore } from '@mastra/pg';
import { agent } from './agents';

const mastra = new Mastra({
  agents: { agent },
  storage: new PostgresStore({
    connectionString: "postgresql://user:password@localhost:5432/myapp"
  })
});

The unified interface allows data access patterns to remain the same, letting you bring the database you want.

Note: Switching databases requires migrating your existing data between backends.

Installation

To get started with Mastra Storage, first install the core package:

npm install @mastra/core

Then add any storage providers you need:

npm install @mastra/pg         # PostgreSQL
npm install @mastra/upstash    # Upstash
npm install @mastra/clickhouse # ClickHouse

To learn more about Mastra Storage, check out our documentation.

We're always looking to improve Mastra based on real-world usage patterns. If you're building AI applications, we'd love to hear about your storage needs and how we can help address them.