MongoDB storage provides flexible schema-less document storage for Mastra with native support for nested data structures.
Installation
npm install @mastra/mongodb
Configuration
Import MongoDBStore
import { MongoDBStore } from '@mastra/mongodb';
Create storage instance
const storage = new MongoDBStore({
id: 'my-storage',
uri: process.env.MONGODB_URI!,
});
Configure Mastra
import { Mastra } from '@mastra/core';
const mastra = new Mastra({
storage,
});
Configuration Options
Unique identifier for the storage instance
MongoDB connection URI (e.g., mongodb://localhost:27017 or mongodb+srv://...)
Name of the MongoDB database to use
Disable automatic collection and index creation
Usage Examples
Basic Configuration
import { MongoDBStore } from '@mastra/mongodb';
import { Mastra } from '@mastra/core';
const storage = new MongoDBStore({
id: 'storage',
uri: process.env.MONGODB_URI!,
databaseName: 'mastra_prod',
});
const mastra = new Mastra({
storage,
});
Access Storage Domains
const storage = new MongoDBStore({
id: 'storage',
uri: process.env.MONGODB_URI!,
});
// Access memory domain
const memory = await storage.getStore('memory');
await memory?.saveThread({ thread });
// Access workflows domain
const workflows = await storage.getStore('workflows');
await workflows?.persistWorkflowSnapshot({
workflowName: 'my-workflow',
runId: 'run-123',
snapshot,
});
MongoDB Atlas
const storage = new MongoDBStore({
id: 'atlas-storage',
uri: `mongodb+srv://${process.env.ATLAS_USER}:${process.env.ATLAS_PASSWORD}@${process.env.ATLAS_CLUSTER}.mongodb.net/?retryWrites=true&w=majority`,
databaseName: 'mastra',
});
Local Development
const storage = new MongoDBStore({
id: 'dev-storage',
uri: 'mongodb://localhost:27017',
databaseName: 'mastra_dev',
});
Storage Domains
MongoDB storage supports all Mastra domains:
memory - Thread-based conversation persistenceworkflows - Workflow execution snapshotsobservability - Telemetry and loggingagents - Agent configurationsmcpClients - MCP client configurationsmcpServers - MCP server configurationsblobs - Binary large object storage
Vector Store Support
MongoDB also provides vector search capabilities:
import { MongoDBVector } from '@mastra/mongodb';
const vectorStore = new MongoDBVector({
id: 'vectors',
uri: process.env.MONGODB_URI!,
databaseName: 'mastra',
});
const mastra = new Mastra({
vectors: {
embeddings: vectorStore,
},
});
Best Practices
Connection String Security
Store MongoDB credentials in environment variables:uri: process.env.MONGODB_URI!
Database Naming
Use descriptive database names per environment:databaseName: `mastra_${process.env.NODE_ENV}`
Atlas Deployment
Use MongoDB Atlas for production deployments with automatic backups and scaling.
Indexes
MongoDB automatically creates indexes for common query patterns.
Connection Pooling
MongoDB driver automatically manages connection pooling. For high-traffic applications:
const storage = new MongoDBStore({
id: 'storage',
uri: `${process.env.MONGODB_URI}?maxPoolSize=50&minPoolSize=10`,
databaseName: 'mastra',
});
Write Concerns
Adjust write concerns in connection string for durability vs performance:
// High durability (default)
uri: `${process.env.MONGODB_URI}?w=majority`
// Higher performance (less durable)
uri: `${process.env.MONGODB_URI}?w=1`
MongoDB Vector
MongoDB Atlas Vector Search
PostgreSQL Storage
Alternative SQL storage option
MongoDB Docs
Official MongoDB documentation
MongoDB Atlas
Fully managed MongoDB service