> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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**:

```bash
npm install @mastra/mongodb@latest
```

**pnpm**:

```bash
pnpm add @mastra/mongodb@latest
```

**Yarn**:

```bash
yarn add @mastra/mongodb@latest
```

**Bun**:

```bash
bun add @mastra/mongodb@latest
```

## Utilisation

Assurez-vous de disposer d'une instance [MongoDB Atlas Local (avec Docker)](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) ou [MongoDB Atlas Cloud](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-getting-started/) avec Atlas Search activé. MongoDB 7.0 ou version ultérieure est recommandé.

```typescript
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 :

```ts
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 :

```typescript
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 :

```typescript
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 :

```typescript
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](https://mastra.zisheng.pro/fr/reference/vectors/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.

```typescript
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.

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