Stockage MongoDB

L'implémentation du stockage MongoDB fournit une solution de grande capacité fondée sur les bases de données MongoDB, qui prend en charge le stockage de documents et les opérations vectorielles.

Installation

npm

npm install @mastra/mongodb@latest

pnpm

pnpm add @mastra/mongodb@latest

Yarn

yarn add @mastra/mongodb@latest

Bun

bun add @mastra/mongodb@latest

Utilisation

Assurez-vous de disposer d'une instance MongoDB Atlas Local (avec Docker) ou MongoDB Atlas Cloud avec Atlas Search activé. MongoDB 7.0 ou version ultérieure est recommandé.

import { MongoDBStore } from '@mastra/mongodb'

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

Paramètres

id:

string

Identifiant unique de cette instance de stockage.

uri:

string

Chaîne de connexion MongoDB (par exemple, mongodb+srv://user:password@cluster.mongodb.net)

url?:

string

Obsolète. Utilisez uri à la place. Chaîne de connexion MongoDB (prise en charge pour la rétrocompatibilité).

dbName:

string

Nom de la base de données que le stockage doit utiliser.

options?:

MongoClientOptions

Options du client MongoDB pour une configuration avancée (SSL, pool de connexions, etc.). Consultez les options de connexion

disableInit?:

boolean

Lorsque la valeur est true, l'initialisation automatique (création des collections) est désactivée. Utile pour les pipelines CI/CD dans lesquels vous souhaitez exécuter explicitement les migrations. Vous devez appeler manuellement storage.init() lorsque cette valeur est true.

skipDefaultIndexes?:

boolean

Lorsque la valeur est true, les index par défaut ne sont pas créés pendant l'initialisation. Utile lorsque vous gérez les index séparément ou utilisez uniquement des index personnalisés.

indexes?:

MongoDBIndexConfig[]

Index personnalisés à créer pendant l'initialisation. Chaque index doit préciser une collection, des clés et des options d'index facultatives. Consultez les index

connectorHandler?:

ConnectorHandler

Gestionnaire de connexion personnalisé pour une gestion avancée des connexions. Constitue une alternative à la fourniture directe de uri/dbName.

Avis d'obsolescence

Le paramètre url est obsolète, mais reste pris en charge pour assurer la rétrocompatibilité. Utilisez désormais uri dans tout nouveau code.

Exemples de constructeur

Vous pouvez instancier MongoDBStore de différentes manières :

import { MongoDBStore } from '@mastra/mongodb'

// Basic connection without custom options
const store1 = new MongoDBStore({
  id: 'mongodb-storage-01',
  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
  dbName: 'mastra_storage',
})

// Using connection string with options
const store2 = new MongoDBStore({
  id: 'mongodb-storage-02',
  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
  dbName: 'mastra_storage',
  options: {
    retryWrites: true,
    maxPoolSize: 10,
    serverSelectionTimeoutMS: 5000,
    socketTimeoutMS: 45000,
  },
})

// With custom indexes
const store3 = new MongoDBStore({
  id: 'mongodb-storage-03',
  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
  dbName: 'mastra_storage',
  indexes: [
    { collection: 'mastra_threads', keys: { 'metadata.type': 1 } },
    { collection: 'mastra_messages', keys: { 'metadata.status': 1 }, options: { sparse: true } },
  ],
})

// For CI/CD with explicit initialization
const store4 = new MongoDBStore({
  id: 'mongodb-storage-04',
  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
  dbName: 'mastra_storage',
  disableInit: true, // Disable auto-init
})
await store4.init() // Call init explicitly

Remarques supplémentaires

Gestion des collections

L'implémentation du stockage gère automatiquement la création et la gestion des collections. Elle crée les collections suivantes :

• mastra_workflow_snapshot : stocke l'état du workflow et les données d'exécution
• mastra_evals : stocke les résultats d'évaluation et les métadonnées
• mastra_threads : stocke les fils de conversation
• mastra_messages : stocke les messages individuels
• mastra_traces : stocke les données de télémétrie et de traçage
• mastra_scorers : stocke les données de notation et d'évaluation
• mastra_resources : stocke les données de mémoire de travail des ressources
• mastra_notifications : stocke les enregistrements de la boîte de réception des notifications et les métadonnées de livraison

MongoDBStore expose le stockage des notifications au moyen de getStore('notifications').

Initialisation

Lorsque vous transmettez le stockage à la classe Mastra, init() est appelée automatiquement avant toute opération de stockage :

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

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

const mastra = new Mastra({
  storage, // init() is called automatically
})

Si vous utilisez le stockage directement sans Mastra, vous devez appeler explicitement init() afin de créer les collections :

import { MongoDBStore } from '@mastra/mongodb'

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

// Required when using storage directly
await storage.init()

// Access domain-specific stores via getStore()
const memoryStore = await storage.getStore('memory')
const thread = await memoryStore?.getThreadById({ threadId: '...' })

attention

Si init() n'est pas appelée, les collections ne seront pas créées et les opérations de stockage échoueront silencieusement ou lèveront des erreurs.

Gestion des connexions

La méthode close() ferme la connexion du client MongoDB. Appelez-la lors de l'arrêt de votre application :

import { MongoDBStore } from '@mastra/mongodb'

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

// Use storage...

// Clean up on shutdown
await storage.close()

Capacités de recherche vectorielle

Le stockage MongoDB comprend des capacités de recherche vectorielle intégrées pour les applications d'IA. Pour en savoir plus sur les opérations vectorielles, notamment la création d'index, l'upsert des embeddings, la recherche par similarité et le filtrage des métadonnées, consultez la référence vectorielle de MongoDB.

Exemple d'utilisation

Ajouter une mémoire à un agent

Pour ajouter une mémoire MongoDB à un agent, utilisez la classe Memory et créez une nouvelle clé storage avec MongoDBStore. La configuration prend en charge les instances MongoDB locales et distantes.

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

import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { MongoDBStore } from '@mastra/mongodb'

export const mongodbAgent = new Agent({
  id: 'mongodb-agent',
  name: 'mongodb-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 MongoDBStore({
      id: 'mongodb-storage',
      uri: process.env.MONGODB_URI!,
      dbName: process.env.MONGODB_DB_NAME!,
    }),
    options: {
      generateTitle: true,
    },
  }),
})

Utiliser l'agent

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

src/test-mongodb-agent.ts

import 'dotenv/config'

import { mastra } from './mastra'

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

const agent = mastra.getAgent('mongodbAgent')

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)
}