Stockage Convex

L'implémentation du stockage Convex fournit une solution de stockage serverless fondée sur Convex, une plateforme de développement TypeScript full-stack avec synchronisation en temps réel et mise en cache automatique.

Observabilité non prise en charge

Le stockage Convex ne prend pas en charge le domaine de l'observabilité. Les traces de MastraStorageExporter ne peuvent pas être conservées dans Convex, et les fonctionnalités d'observabilité de Studio ne fonctionneront pas si Convex est votre seul Provider de stockage. Pour activer l'observabilité, utilisez le stockage composite afin d'acheminer les données d'observabilité vers un Provider pris en charge tel que ClickHouse.

Limite de taille des enregistrements

Convex impose une taille maximale d'enregistrement de 1 Mio. Cette limite peut être dépassée lors du stockage de messages contenant des pièces jointes encodées en base64, telles que des images. Consultez Gérer les pièces jointes volumineuses pour découvrir des solutions de contournement, notamment le téléversement des pièces jointes vers un stockage externe tel que S3, Cloudflare R2 ou le stockage de fichiers Convex.

Installation

npm

npm install @mastra/convex@latest

pnpm

pnpm add @mastra/convex@latest

Yarn

yarn add @mastra/convex@latest

Bun

bun add @mastra/convex@latest

Configuration de Convex

Avant d'utiliser ConvexStore, configurez le schéma Convex et le gestionnaire de stockage dans votre projet Convex. L'exemple de schéma ci-dessous comprend la configuration complète de ConvexStore et ConvexServerCache. Si vous utilisez uniquement ConvexStore, omettez mastraCacheTable et mastraCacheListItemsTable ; si vous utilisez ConvexServerCache, incluez ces tables et créez le gestionnaire de cache.

1. Configurer le schéma Convex

Dans convex/schema.ts :

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

export default defineSchema({
  mastra_threads: mastraThreadsTable,
  mastra_messages: mastraMessagesTable,
  mastra_resources: mastraResourcesTable,
  mastra_workflow_snapshots: mastraWorkflowSnapshotsTable,
  mastra_scorers: mastraScoresTable,
  mastra_observational_memory: mastraObservationalMemoryTable,
  mastra_vector_indexes: mastraVectorIndexesTable,
  mastra_vectors: mastraVectorsTable,
  mastra_cache: mastraCacheTable,
  mastra_cache_list_items: mastraCacheListItemsTable,
  mastra_documents: mastraDocumentsTable,
})

2. Créer le gestionnaire de stockage

Dans convex/mastra/storage.ts :

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

export const handle = mastraStorage

Si vous utilisez ConvexServerCache, créez convex/mastra/cache.ts :

import { mastraCache } from '@mastra/convex/server'

export const handle = mastraCache

3. Déployer sur Convex

npx convex dev
# or for production
npx convex deploy

Utilisation

import { ConvexServerCache, ConvexStore } from '@mastra/convex'

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

const cache = new ConvexServerCache({
  deploymentUrl: process.env.CONVEX_URL!,
  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
})

Paramètres de ConvexStore

deploymentUrl:

string

URL du déploiement Convex (par exemple, https://your-project.convex.cloud)

adminAuthToken:

string

Jeton d'authentification d'administration Convex pour accéder au backend

storageFunction?:

string

= mastra/storage:handle

Chemin de la fonction de mutation du stockage (valeur par défaut : 'mastra/storage:handle')

Paramètres de ConvexServerCache

deploymentUrl:

string

URL du déploiement Convex (par exemple, https://your-project.convex.cloud)

adminAuthToken:

string

Jeton d'authentification d'administration Convex pour accéder au backend

cacheFunction?:

string

= mastra/cache:handle

Chemin de la fonction de mutation du cache pour ConvexServerCache (valeur par défaut : 'mastra/cache:handle')

requestTimeoutMs?:

number

= 30000

Délai d'expiration des requêtes de mutation du cache Convex, en millisecondes. Définissez-le sur 0 pour désactiver le délai d'expiration côté client.

keyPrefix?:

string

= mastra:cache:

Préfixe appliqué aux clés de ConvexServerCache. clear() supprime les lignes dont le préfixe enregistré correspond exactement à cette valeur.

ttlMs?:

number

= 300000

TTL par défaut de ConvexServerCache en millisecondes. Définissez-le sur 0 pour désactiver l'expiration.

Exemples de constructeur

import { ConvexServerCache, 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',
})

// Server cache for durable stream replay and response caching
const cache = new ConvexServerCache({
  deploymentUrl: 'https://your-project.convex.cloud',
  adminAuthToken: 'your-admin-token',
  cacheFunction: 'mastra/cache:handle',
})

Cache serveur

ConvexServerCache implémente avec Convex le contrat de cache serveur de Mastra. Utilisez-le lorsque vous souhaitez un état de cache durable pour des fonctionnalités telles que les flux d'agents durables pouvant être repris, la relecture des flux de workflows ou la mise en cache des réponses.

ConvexServerCache stocke les entrées de liste sous forme de documents Convex distincts. Cela évite d'agrandir une liste de relecture de flux dans un seul document et aide à respecter la limite de taille des enregistrements de Convex.

Chaque valeur scalaire du cache et chaque élément de liste sont stockés dans une ligne Convex et doivent respecter les limites de taille des lignes de Convex. Les listes très volumineuses restent soumises aux limites des requêtes Convex lors de la relecture d'une plage.

Le nettoyage du cache et clear() s'exécutent par lots limités. Un seul appel client peut parcourir jusqu'à 1 000 mutations Convex, chacune traitant jusqu'à 25 éléments de liste. Pendant que clear() nettoie une clé, les lectures de cette clé peuvent renvoyer des résultats vides jusqu'à la fin du nettoyage.

Pour les espaces de noms de cache très volumineux, effectuez le nettoyage progressivement ou utilisez des préfixes plus précis afin d'éviter les opérations de nettoyage trop longues.

Pendant le nettoyage par lots, les métadonnées du cache peuvent temporairement utiliser un état interne deleted. Le passage de nettoyage suivant supprime ces lignes. Évitez d'écrire de nouvelles valeurs avec le même préfixe avant la fin de clear().

clear() supprime uniquement les lignes dont le keyPrefix enregistré correspond exactement au keyPrefix configuré. Elle ne nettoie pas les préfixes imbriqués par correspondance de préfixe de chaîne. Chaque appel à listPush() actualise le TTL de la liste en utilisant le ttlMs configuré du cache.

Utilisez un keyPrefix non vide, sauf si vous souhaitez volontairement que clear() supprime toutes les clés de cache du déploiement. Les lignes de liste expirées sont récupérées progressivement lors des lectures et des écritures. clear() supprime toutes les lignes correspondant au préfixe.

ConvexServerCache convient particulièrement à la relecture durable d'événements de fréquence modérée. Pour les flux de tokens à haute fréquence, privilégiez le regroupement des événements en lots ou un backend de cache à plus faible latence.

ConvexServerCache ne remplace pas un transport pub/sub distribué. Si votre application nécessite une diffusion en direct d'événements entre processus, configurez séparément un backend pub/sub de production.

Remarques supplémentaires

Gestion du schéma

L'implémentation du stockage utilise des tables Convex typées pour chaque domaine Mastra :

Domaine	Table Convex	Rôle
Fils	mastra_threads	Fils de conversation
Messages	mastra_messages	Messages de conversation
Ressources	mastra_resources	Mémoire de travail de l'utilisateur
Mémoire observationnelle	mastra_observational_memory	Générations de mémoire observationnelle
Workflows	mastra_workflow_snapshots	État du workflow
Scorers	mastra_scorers	Données d'évaluation
Cache	mastra_cache	Valeurs, compteurs et métadonnées de listes du cache
Éléments du cache	mastra_cache_list_items	Entrées de liste du cache
Repli	mastra_documents	Tables inconnues

Mémoire observationnelle

ConvexStore prend en charge la mémoire observationnelle. Ajoutez mastraObservationalMemoryTable à votre schéma Convex et redéployez avec npx convex deploy pour l'activer. Les déploiements existants créés avant l'ajout de cette table nécessitent la même mise à jour du schéma.

Architecture

Toutes les tables typées comprennent :

• un champ id pour l'identifiant d'enregistrement de Mastra (distinct de l'identifiant _id généré automatiquement par Convex) ;
• un index by_record_id permettant des recherches efficaces par identifiant Mastra.

Cette conception assure la compatibilité avec le contrat de stockage de Mastra tout en exploitant l'indexation automatique et les capacités en temps réel de Convex.

Variables d'environnement

Définissez ces variables d'environnement pour votre déploiement :

• CONVEX_URL : URL de votre déploiement Convex
• CONVEX_ADMIN_KEY : jeton d'authentification administrateur (à obtenir depuis le tableau de bord Convex)

Ressources associées

• Stockage vectoriel Convex
• Documentation Convex