Stockage Upstash

L’implémentation du stockage Upstash fournit une solution de stockage adaptée au serverless qui utilise le stockage clé-valeur compatible Redis d’Upstash.

Tarification

Lorsque vous utilisez Mastra avec Upstash, le modèle de paiement à l’usage peut engendrer des coûts imprévus en raison du grand nombre de commandes Redis générées pendant les conversations des Agents. Nous vous recommandons vivement d’utiliser une formule à prix fixe afin de garantir des coûts prévisibles. Pour plus de détails, consultez la tarification d’Upstash et, pour le contexte, l’issue GitHub nº 5850.

Observabilité non prise en charge

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

Installation

npm

npm install @mastra/upstash@latest

pnpm

pnpm add @mastra/upstash@latest

Yarn

yarn add @mastra/upstash@latest

Bun

bun add @mastra/upstash@latest

Utilisation

import { UpstashStore } from '@mastra/upstash'

const storage = new UpstashStore({
  id: 'upstash-storage',
  url: process.env.UPSTASH_URL,
  token: process.env.UPSTASH_TOKEN,
})

Paramètres

url:

string

URL Redis d’Upstash

token:

string

Token d’authentification Redis d’Upstash

prefix?:

string

= mastra:

Préfixe de clé pour tous les éléments stockés

Remarques supplémentaires

Structure des clés

L’implémentation du stockage Upstash utilise une structure clé-valeur :

• Clés des fils : {prefix}thread:{threadId}
• Clés des messages : {prefix}message:{messageId}
• Clés des métadonnées : {prefix}metadata:{entityId}

Avantages du serverless

Le stockage Upstash convient particulièrement bien aux déploiements serverless :

• Aucune gestion des connexions nécessaire
• Tarification par requête
• Options de réplication globale
• Compatibilité avec l’Edge

Persistance des données

Upstash fournit :

• Persistance automatique des données
• Récupération à un instant donné
• Options de réplication interrégionale

Considérations relatives aux performances

Pour des performances optimales :

• Utilisez des préfixes de clés appropriés pour organiser les données
• Surveillez l’utilisation de la mémoire Redis
• Envisagez des politiques d’expiration des données si nécessaire

Exemple d’utilisation

Ajouter une mémoire à un Agent

Pour ajouter une mémoire Upstash à un Agent, utilisez la classe Memory, puis créez une nouvelle clé storage avec UpstashStore et une nouvelle clé vector avec UpstashVector. La configuration peut pointer vers un service distant ou une installation locale.

src/mastra/agents/example-upstash-agent.ts

import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { UpstashStore } from '@mastra/upstash'

export const upstashAgent = new Agent({
  id: 'upstash-agent',
  name: 'Upstash Agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new UpstashStore({
      id: 'upstash-agent-storage',
      url: process.env.UPSTASH_REDIS_REST_URL!,
      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
    }),
    options: {
      generateTitle: true, // Explicitly enable automatic title generation
    },
  }),
})

Utiliser l’Agent

Utilisez memoryOptions pour définir la portée du rappel pour cette requête. Définissez lastMessages: 5 afin de limiter le rappel fondé sur la récence, puis utilisez semanticRecall pour récupérer les topK: 3 messages les plus pertinents, en incluant messageRange: 2 messages voisins afin de fournir du contexte autour de chaque correspondance.

src/test-upstash-agent.ts

import 'dotenv/config'

import { mastra } from './mastra'

const threadId = '123'
const resourceId = 'user-456'

const agent = mastra.getAgent('upstashAgent')

const message = await agent.stream('My name is Mastra', {
  memory: {
    thread: threadId,
    resource: resourceId,
  },
})

await message.textStream.pipeTo(new WritableStream())

const stream = await agent.stream("What's my name?", {
  memory: {
    thread: threadId,
    resource: resourceId,
  },
  memoryOptions: {
    lastMessages: 5,
    semanticRecall: {
      topK: 3,
      messageRange: 2,
    },
  },
})

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}