MongoDB 存储

MongoDB 存储实现使用 MongoDB 数据库提供高容量存储解决方案，同时支持文档存储和向量操作。

安装

npm

npm install @mastra/mongodb@latest

pnpm

pnpm add @mastra/mongodb@latest

Yarn

yarn add @mastra/mongodb@latest

Bun

bun add @mastra/mongodb@latest

使用方法

请确保你拥有已启用 Atlas Search 的 MongoDB Atlas Local（通过 Docker） 或 MongoDB Atlas Cloud 实例。建议使用 MongoDB 7.0+。

import { MongoDBStore } from '@mastra/mongodb'

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

参数

id:

string

此 storage 实例的唯一标识符。

uri:

string

MongoDB 连接字符串（例如 mongodb+srv://user:password@cluster.mongodb.net）。

url?:

string

已弃用。请改用 uri。MongoDB 连接字符串（为向后兼容而支持）。

dbName:

string

storage 要使用的数据库名称。

options?:

MongoClientOptions

用于高级配置的 MongoDB client 选项（SSL、连接池等）。请参阅连接选项。

disableInit?:

boolean

为 true 时，将禁用自动初始化（创建 collection）。适用于需要显式运行 migration 的 CI/CD pipeline。此值为 true 时，你必须手动调用 storage.init()。

skipDefaultIndexes?:

boolean

为 true 时，初始化期间不会创建默认 index。适用于单独管理 index 或仅使用自定义 index 的情况。

indexes?:

MongoDBIndexConfig[]

初始化期间要创建的自定义 index。每个 index 必须指定 collection、keys 和可选的 index 选项。请参阅index。

connectorHandler?:

ConnectorHandler

用于高级连接管理的自定义连接处理程序。可替代直接提供 uri/dbName。

弃用通知

url 参数已弃用，但仍为向后兼容而受支持。请在所有新代码中改用 uri。

构造函数示例

你可以通过以下方式实例化 MongoDBStore：

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

其他说明

Collection 管理

storage 实现会自动处理 collection 的创建和管理。它会创建以下 collection：

• mastra_workflow_snapshot：存储 workflow 状态和执行数据
• mastra_evals：存储评估结果和元数据
• mastra_threads：存储对话 thread
• mastra_messages：存储单条 message
• mastra_traces：存储 telemetry 和 tracing 数据
• mastra_scorers：存储评分和评估数据
• mastra_resources：存储 resource working memory 数据
• mastra_notifications：存储通知收件箱记录和投递元数据

MongoDBStore 通过 getStore('notifications') 提供通知存储。

初始化

将 storage 传递给 Mastra class 时，任何 storage 操作前都会自动调用 init()：

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

如果不通过 Mastra 直接使用 storage，则必须显式调用 init() 以创建 collection：

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: '...' })

注意

如果未调用 init()，将不会创建 collection，storage 操作会静默失败或抛出错误。

连接管理

close() 方法会关闭 MongoDB client 连接。关闭应用程序时请调用它：

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

向量搜索功能

MongoDB storage 包含面向 AI 应用程序的内置向量搜索功能。有关 index 创建、upsert embedding、相似度搜索和元数据过滤等详细向量操作，请参阅 MongoDB vector 参考。

使用示例

向 agent 添加 memory

要向 agent 添加 MongoDB memory，请使用 Memory class 并通过 MongoDBStore 创建新的 storage key。该配置同时支持本地和远程 MongoDB 实例。

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

使用 agent

使用 memoryOptions 限定此请求的 recall 范围。设置 lastMessages: 5 以限制基于近期性的 recall，并使用 semanticRecall 获取最相关的 topK: 3 条 message，其中包含每个匹配项周围作为上下文的 messageRange: 2 条相邻 message。

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