Présentation du stockage

Le stockage est la couche de persistance de l’environnement d’exécution Mastra. Il maintient la mémoire, l’état des Workflows, les données d’observabilité, les résultats d’Evals, les planifications et l’état des Agents de longue durée après le redémarrage d’un processus.

Le stockage alimente les fonctionnalités suivantes :

• Mémoire : historique des messages, threads, ressources et mémoire de travail.
• Workflows : snapshots persistants des exécutions de Workflows suspendues et reprises.
• Observabilité : Traces, spans, métriques, journaux et retours.
• Evals : scores, Datasets, Experiments et résultats d’évaluation.
• Agents de longue durée : tâches en arrière-plan, planifications, objectifs et état des threads.

Quand configurer le stockage

Configurez un adaptateur de stockage persistant lorsque l’état doit résister aux redémarrages ou être partagé entre plusieurs processus. Le stockage persistant permet également de conserver l’état visible dans Studio d’une session à l’autre. Le stockage en mémoire par défaut convient aux tests et aux courtes expérimentations locales, mais ses données sont perdues à l’arrêt du processus.

Utilisez le stockage si votre application nécessite l’un des comportements suivants :

• Les Agents se souviennent des messages précédents ou d’informations sur les utilisateurs.
• Les Workflows peuvent être suspendus puis repris après un redémarrage.
• Les Traces, métriques, journaux, scores ou retours restent disponibles pour analyse.
• Les planifications et tâches en arrière-plan se poursuivent d’un déploiement à l’autre.
• Plusieurs processus d’exécution lisent et écrivent le même état.

Fonctionnement du stockage

Le stockage Mastra est organisé en domaines. Chaque domaine gère un type de données d’exécution, et un adaptateur de stockage implémente un ou plusieurs domaines.

Domaine	Données stockées
memory	Threads, messages, ressources, mémoire de travail et autres états de mémoire des Agents.
workflows	Snapshots de Workflows utilisés pour suspendre et reprendre des exécutions.
observability	Traces, spans, métriques, journaux et retours.
scores	Enregistrements des scores d’Evals.
datasets	Enregistrements et éléments de Datasets utilisés par les Evals et les Experiments.
experiments	Exécutions d’Experiments et résultats par élément.
backgroundTasks	Enregistrements des tâches en arrière-plan et état de leur exécution.
schedules	Définitions des planifications et historique des déclenchements.
threadState	État persistant des tâches, objectifs et threads.

La prise en charge des adaptateurs varie selon le domaine. Pour consulter la liste complète des domaines et les schémas intégrés, reportez-vous à la référence du stockage.

Choisir un backend selon la forme des données

Les différents domaines écrivent et interrogent des types de données distincts. Choisissez un backend selon le modèle d’accès du domaine :

• memory : lit et écrit des lignes à chaque appel d’Agent mémorisé. Utilisez une base de données transactionnelle comme libSQL, PostgreSQL ou MongoDB.
• observability : écrit un volume important de données de télémétrie et interroge souvent des agrégations. Utilisez un stockage d’observabilité dédié ou un backend de traitement analytique en ligne (OLAP), comme ClickHouse ou DuckDB.
• workflows : stocke des snapshots persistants qui doivent être disponibles lors de la reprise d’une exécution. Utilisez une base de données persistante et fiable.
• scores, datasets et experiments : stockent des données d’évaluation moins fréquentes, souvent consultées ultérieurement pour analyse.
• schedules : stocke les définitions des planifications et l’historique des déclenchements. Utilisez un adaptateur qui implémente le domaine des planifications.

Lorsque les domaines ont des besoins opérationnels différents, utilisez le stockage composite afin d’orienter chaque domaine vers le backend adapté.

Démarrer en local

Pour le développement local, utilisez libSQL avec une base de données stockée dans un fichier. Aucun serveur de base de données distinct n’est nécessaire et l’état est conservé entre les redémarrages.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})

Partager la base de données avec Studio

Lorsque vous exécutez mastra dev en parallèle de votre application, utilisez un chemin absolu afin que les deux processus accèdent à la même base de données :

url: 'file:/absolute/path/to/your/project/mastra.db'

Les chemins relatifs comme file:./mastra.db sont résolus à partir du répertoire de travail de chaque processus, lesquels peuvent être différents.

Mastra initialise les structures de stockage requises lors de la première utilisation.

Configurer pour la production

En production, utilisez une base de données persistante et gérée. PostgreSQL constitue un bon choix par défaut pour la plupart des équipes, car il convient à l’état d’exécution transactionnel et est largement proposé en tant que service géré.

Recommandations pour la production :

• Utilisez une base de données gérée avec des sauvegardes, une surveillance et un pool de connexions.
• N’utilisez pas de bases de données locales stockées dans un fichier, comme file:./mastra.db, dans les déploiements de production multiprocessus.
• Orientez les domaines à fort volume, en particulier observability, vers un backend dédié au moyen du stockage composite.
• Configurez des politiques de rétention sur l’adaptateur de stockage ou le stockage composite, puis appelez storage.prune() depuis un planificateur ou une tâche de maintenance.
• Choisissez les fournisseurs selon les domaines utilisés par votre application. Par exemple, les planifications nécessitent un adaptateur qui implémente le domaine schedules.

Portée de la configuration

Le stockage peut être configuré au niveau de l’instance Mastra ou de l’Agent.

Stockage au niveau de l’instance

Le stockage au niveau de l’instance est partagé par les Agents, les Workflows, les fonctions d’observabilité, les Evals, les planifications et les autres fonctionnalités d’exécution enregistrées dans la même instance Mastra.

PostgreSQL

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PostgresStore } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new PostgresStore({
    id: 'mastra-storage',
    connectionString: process.env.DATABASE_URL,
  }),
})

MongoDB

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MongoDBStore } from '@mastra/mongodb'

export const mastra = new Mastra({
  storage: new MongoDBStore({
    id: 'mastra-storage',
    uri: process.env.MONGODB_URI,
    dbName: process.env.MONGODB_DB_NAME,
  }),
})

Utilisez le stockage au niveau de l’instance lorsque la plupart des domaines d’exécution peuvent partager la même base de données.

Stockage au niveau de l’Agent

Le stockage au niveau de l’Agent est configuré dans une instance Memory. Il remplace le stockage au niveau de l’instance uniquement pour les données de mémoire de cet Agent.

src/mastra/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { PostgresStore } from '@mastra/pg'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'Answer customer support questions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new PostgresStore({
      id: 'support-agent-storage',
      connectionString: process.env.SUPPORT_AGENT_DATABASE_URL,
    }),
  }),
})

Utilisez le stockage au niveau de l’Agent lorsqu’un Agent nécessite un périmètre de mémoire isolé ou un backend de mémoire différent.

Stockage composite

MastraCompositeStore oriente les domaines vers différents backends. Utilisez-le lorsqu’une même base de données ne convient pas à tous les domaines.

L’exemple suivant utilise libSQL comme stockage par défaut et oriente l’état des Workflows vers PostgreSQL :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { LibSQLStore } from '@mastra/libsql'
import { WorkflowsPG } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'default-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      workflows: new WorkflowsPG({
        connectionString: process.env.DATABASE_URL,
      }),
    },
  }),
})

Vous pouvez également orienter observability vers un backend analytique dédié. Consultez le guide de démarrage rapide de l’observabilité pour obtenir un exemple propre à l’observabilité.

Fournisseurs pris en charge

La page de chaque fournisseur comprend les instructions d’installation, les paramètres de configuration et des exemples d’utilisation :

• libSQL
• PostgreSQL
• MongoDB
• OracleDB
• Upstash
• Redis
• Cloudflare D1
• Cloudflare KV & Durable Objects
• Convex
• DynamoDB
• LanceDB
• Microsoft SQL Server
• Google Cloud Spanner

astuce

libSQL est la solution la plus rapide pour le développement local, car elle ne nécessite pas l’exécution d’un serveur de base de données distinct.

Étapes suivantes

• Stockage composite
• Rétention du stockage
• Schémas de stockage
• Mémoire
• Stockage de l’observabilité