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

# 몽고DB 스토리지

MongoDB 스토리지 구현은 문서 스토리지와 벡터 작업을 모두 지원하는 MongoDB 데이터베이스를 사용하여 대용량 스토리지 솔루션을 제공합니다.

## 설치

**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
```

## 용법

Atlas Search가 활성화된 [MongoDB Atlas Local(Docker 사용)](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) 또는 [MongoDB Atlas Cloud](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-getting-started/) 인스턴스가 있는지 확인하세요. MongoDB 7.0 이상을 권장합니다.

```typescript
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`를 인스턴스화할 수 있습니다.

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

## 추가 참고사항

### 컬렉션 관리

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

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

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

### 초기화

스토리지를 Mastra 클래스에 전달하면 스토리지 작업 전에 `init()`이 자동으로 호출됩니다.

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

Mastra 없이 스토어를 직접 사용하는 경우 컬렉션을 생성하려면 `init()`을 명시적으로 호출해야 합니다.

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

> **경고:** `init()`을 호출하지 않으면 컬렉션이 생성되지 않으며 스토리지 작업이 아무 알림 없이 실패하거나 오류를 발생시킵니다.

### 연결 관리

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

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

## 벡터 검색 기능

MongoDB 스토리지에는 AI 애플리케이션을 위한 내장 벡터 검색 기능이 포함되어 있습니다. 인덱스 생성, 임베딩 업데이트, 유사성 검색, 메타데이터 필터링을 포함한 자세한 벡터 작업은 다음을 참조하세요.[MongoDB vector reference](https://mastra.zisheng.pro/ko/reference/vectors/mongodb).

## 사용예

### Agent에 Memory 추가

Agent에 MongoDB Memory를 추가하려면 `Memory` 클래스를 사용하고 `MongoDBStore`를 사용하는 새 `storage` 키를 생성하세요. 이 구성은 로컬 및 원격 MongoDB 인스턴스를 모두 지원합니다.

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

### Agent 사용

`memoryOptions`를 사용하여 이 요청의 회상 범위를 지정하세요. `lastMessages: 5`를 설정하여 최신 메시지 기반 회상을 제한하고, `semanticRecall`을 사용하여 가장 관련성이 높은 `topK: 3`개의 메시지를 가져오세요. 각 일치 항목 주변의 컨텍스트를 제공하도록 인접 메시지 `messageRange: 2`개도 포함됩니다.

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