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

# MongoDB 儲存空間

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 pipeline。此項設為 true 時，你必須手動呼叫 storage.init()。

**skipDefaultIndexes** (`boolean`): 設為 true 時，初始化期間不會建立預設索引。適用於另行管理索引或只使用自訂索引的情況。

**indexes** (`MongoDBIndexConfig[]`): 初始化期間要建立的自訂索引。每個索引必須指定集合、鍵及可選的索引選項。請參閱索引

**connectorHandler** (`ConnectorHandler`): 用於進階連線管理的自訂連線處理器，可取代直接提供 uri/dbName。

> **棄用通知:** `url` 參數已棄用，但為向後兼容仍然支援。所有新程式碼請改用 `uri`。

## Constructor 範例

你可以透過以下方式建立 `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`：儲存評估結果及 metadata
- `mastra_threads`：儲存對話 thread
- `mastra_messages`：儲存個別訊息
- `mastra_traces`：儲存遙測及 tracing 資料
- `mastra_scorers`：儲存評分及評估資料
- `mastra_resources`：儲存資源的 working memory 資料
- `mastra_notifications`：儲存通知收件箱記錄及傳送 metadata

`MongoDBStore` 透過 `getStore('notifications')` 提供通知儲存空間。

### 初始化

將儲存空間傳入 Mastra class 時，系統會在任何儲存操作前自動呼叫 `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 應用程式的向量搜尋功能。有關建立索引、upsert embedding、相似度搜尋及 metadata 篩選等詳細向量操作，請參閱 [MongoDB 向量參考](https://mastra.zisheng.pro/zh-HK/reference/vectors/mongodb)。

## 用法範例

### 為 Agent 加入 memory

要為 Agent 加入 MongoDB memory，請使用 `Memory` class，並透過 `MongoDBStore` 建立新的 `storage` key。此設定同時支援本機及遠端 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` 限定此要求的 recall 範圍。設定 `lastMessages: 5` 以限制按最近時間進行的 recall，並使用 `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)
}
```