몽고DB 스토리지

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

이 스토리지 인스턴스의 고유 식별자입니다.

uri:

string

MongoDB 연결 문자열(예: mongodb+srv://user:password@cluster.mongodb.net)

url?:

string

더 이상 권장되지 않습니다. 대신 uri를 사용하세요. MongoDB 연결 문자열이며 이전 버전과의 호환성을 위해 지원됩니다.

dbName:

string

스토리지에서 사용할 데이터베이스의 이름입니다.

options?:

MongoClientOptions

고급 구성을 위한 MongoDB 클라이언트 옵션입니다(SSL, 연결 풀링 등). 연결 옵션을 참조하세요.

disableInit?:

boolean

true이면 자동 초기화(컬렉션 생성)가 비활성화됩니다. 마이그레이션을 명시적으로 실행하려는 CI/CD 파이프라인에 유용합니다. true로 설정하면 storage.init()을 수동으로 호출해야 합니다.

skipDefaultIndexes?:

boolean

true이면 초기화 중에 기본 인덱스를 생성하지 않습니다. 인덱스를 별도로 관리하거나 사용자 지정 인덱스만 사용할 때 유용합니다.

indexes?:

MongoDBIndexConfig[]

초기화 중에 생성할 사용자 지정 인덱스입니다. 각 인덱스에는 컬렉션, 키, 선택적 인덱스 옵션을 지정해야 합니다. 인덱스를 참조하세요.

connectorHandler?:

ConnectorHandler

고급 연결 관리를 위한 사용자 지정 연결 핸들러입니다. uri/dbName을 직접 제공하는 방식의 대안입니다.

:::note[지원 중단 알림] 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

추가 참고사항

컬렉션 관리

저장소 구현은 컬렉션 생성 및 관리를 자동으로 처리합니다. 다음 컬렉션을 생성합니다.

• mastra_workflow_snapshot: Workflow 상태 및 실행 데이터를 저장합니다.
• mastra_evals: 평가 결과 및 메타데이터를 저장합니다.
• mastra_threads: 대화 스레드를 저장합니다.
• mastra_messages: 개별 메시지를 저장합니다.
• mastra_traces: 원격 측정 및 추적 데이터를 저장합니다.
• mastra_scorers: 점수 및 평가 데이터를 저장합니다.
• mastra_resources: 자원 작업 Memory 데이터를 저장합니다.
• mastra_notifications: 알림 받은 편지함 기록 및 전달 메타데이터를 저장합니다.

MongoDBStore다음을 통해 알림 저장소를 노출합니다.getStore('notifications').

초기화

스토리지를 Mastra 클래스에 전달하면 스토리지 작업 전에 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 없이 스토어를 직접 사용하는 경우 컬렉션을 생성하려면 init()을 명시적으로 호출해야 합니다.

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()을 호출하지 않으면 컬렉션이 생성되지 않으며 스토리지 작업이 아무 알림 없이 실패하거나 오류를 발생시킵니다.

연결 관리

close() 메서드는 MongoDB 클라이언트 연결을 닫습니다. 애플리케이션을 종료할 때 호출하세요.

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 스토리지에는 AI 애플리케이션을 위한 내장 벡터 검색 기능이 포함되어 있습니다. 인덱스 생성, 임베딩 업데이트, 유사성 검색, 메타데이터 필터링을 포함한 자세한 벡터 작업은 다음을 참조하세요.MongoDB vector reference.

사용예

Agent에 Memory 추가

Agent에 MongoDB Memory를 추가하려면 Memory 클래스를 사용하고 MongoDBStore를 사용하는 새 storage 키를 생성하세요. 이 구성은 로컬 및 원격 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를 사용하여 이 요청의 회상 범위를 지정하세요. lastMessages: 5를 설정하여 최신 메시지 기반 회상을 제한하고, semanticRecall을 사용하여 가장 관련성이 높은 topK: 3개의 메시지를 가져오세요. 각 일치 항목 주변의 컨텍스트를 제공하도록 인접 메시지 messageRange: 2개도 포함됩니다.

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