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

# Convex 儲存空間

Convex 儲存空間實作採用 [Convex](https://convex.dev)，提供 serverless 儲存解決方案。Convex 是具備即時同步與自動快取功能的全端 TypeScript 開發平台。

> **不支援可觀測性:** Convex 儲存空間**不支援 observability domain**。`MastraStorageExporter` 的 Trace 無法持久化至 Convex；若 Convex 是唯一的儲存 Provider，[Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/overview) 的可觀測性功能也無法運作。若要啟用可觀測性，請使用[複合儲存空間](https://mastra.zisheng.pro/zh-TW/reference/storage/composite)，將可觀測性資料路由至 ClickHouse 等受支援的 Provider。

> **記錄大小限制:** Convex 規定**每筆記錄最大為 1 MiB**。儲存包含圖片等 base64 編碼附件的訊息時，可能超過此限制。如需包含將附件上傳至 S3、Cloudflare R2 或 [Convex 檔案儲存空間](https://docs.convex.dev/file-storage)等外部儲存空間的替代做法，請參閱[處理大型附件](https://mastra.zisheng.pro/zh-TW/docs/memory/memory-processors)。

## 安裝

**npm**:

```bash
npm install @mastra/convex@latest
```

**pnpm**:

```bash
pnpm add @mastra/convex@latest
```

**Yarn**:

```bash
yarn add @mastra/convex@latest
```

**Bun**:

```bash
bun add @mastra/convex@latest
```

## Convex 設定

使用 `ConvexStore` 前，請在 Convex 專案中設定 Convex schema 與 storage handler。 下列 schema 範例包含完整的 `ConvexStore` 與 `ConvexServerCache` 設定。若只使用 `ConvexStore`，請省略 `mastraCacheTable` 與 `mastraCacheListItemsTable`；若使用 `ConvexServerCache`，請納入這些資料表並建立 cache handler。

### 1. 設定 Convex schema

在 `convex/schema.ts` 中：

```typescript
import { defineSchema } from 'convex/server'
import {
  mastraThreadsTable,
  mastraMessagesTable,
  mastraResourcesTable,
  mastraWorkflowSnapshotsTable,
  mastraScoresTable,
  mastraObservationalMemoryTable,
  mastraVectorIndexesTable,
  mastraVectorsTable,
  mastraCacheTable,
  mastraCacheListItemsTable,
  mastraDocumentsTable,
} from '@mastra/convex/schema'

export default defineSchema({
  mastra_threads: mastraThreadsTable,
  mastra_messages: mastraMessagesTable,
  mastra_resources: mastraResourcesTable,
  mastra_workflow_snapshots: mastraWorkflowSnapshotsTable,
  mastra_scorers: mastraScoresTable,
  mastra_observational_memory: mastraObservationalMemoryTable,
  mastra_vector_indexes: mastraVectorIndexesTable,
  mastra_vectors: mastraVectorsTable,
  mastra_cache: mastraCacheTable,
  mastra_cache_list_items: mastraCacheListItemsTable,
  mastra_documents: mastraDocumentsTable,
})
```

### 2. 建立 storage handler

在 `convex/mastra/storage.ts` 中：

```typescript
import { mastraStorage } from '@mastra/convex/server'

export const handle = mastraStorage
```

若使用 `ConvexServerCache`，請建立 `convex/mastra/cache.ts`：

```typescript
import { mastraCache } from '@mastra/convex/server'

export const handle = mastraCache
```

### 3. 部署至 Convex

```bash
npx convex dev
# or for production
npx convex deploy
```

## 使用方式

```typescript
import { ConvexServerCache, ConvexStore } from '@mastra/convex'

const storage = new ConvexStore({
  id: 'convex-storage',
  deploymentUrl: process.env.CONVEX_URL!,
  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
})

const cache = new ConvexServerCache({
  deploymentUrl: process.env.CONVEX_URL!,
  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
})
```

## ConvexStore 參數

**deploymentUrl** (`string`): Convex 部署 URL（例如 https\://your-project.convex.cloud）

**adminAuthToken** (`string`): 用於存取 backend 的 Convex 管理員驗證 token

**storageFunction** (`string`): Storage mutation function 的路徑（預設：'mastra/storage:handle'） (Default: `mastra/storage:handle`)

## ConvexServerCache 參數

**deploymentUrl** (`string`): Convex 部署 URL（例如 https\://your-project.convex.cloud）

**adminAuthToken** (`string`): 用於存取 backend 的 Convex 管理員驗證 token

**cacheFunction** (`string`): ConvexServerCache cache mutation function 的路徑（預設：'mastra/cache:handle'） (Default: `mastra/cache:handle`)

**requestTimeoutMs** (`number`): Convex cache mutation 請求的逾時時間（毫秒）。設為 0 可停用 client 端逾時。 (Default: `30000`)

**keyPrefix** (`string`): 套用至 ConvexServerCache key 的 prefix。clear() 會移除已儲存 prefix 與此值完全相符的資料列。 (Default: `mastra:cache:`)

**ttlMs** (`number`): ConvexServerCache 的預設 TTL（毫秒）。設為 0 可停用到期機制。 (Default: `300000`)

## 建構函式範例

```ts
import { ConvexServerCache, ConvexStore } from '@mastra/convex'

// Basic configuration
const store = new ConvexStore({
  id: 'convex-storage',
  deploymentUrl: 'https://your-project.convex.cloud',
  adminAuthToken: 'your-admin-token',
})

// With custom storage function path
const storeCustom = new ConvexStore({
  id: 'convex-storage',
  deploymentUrl: 'https://your-project.convex.cloud',
  adminAuthToken: 'your-admin-token',
  storageFunction: 'custom/path:handler',
})

// Server cache for durable stream replay and response caching
const cache = new ConvexServerCache({
  deploymentUrl: 'https://your-project.convex.cloud',
  adminAuthToken: 'your-admin-token',
  cacheFunction: 'mastra/cache:handle',
})
```

## Server cache

`ConvexServerCache` 透過 Convex 實作 Mastra 的 server cache contract。若要為可繼續的 durable Agent stream、Workflow stream replay 或回應快取等功能提供持久 cache 狀態，請使用此類別。

`ConvexServerCache` 會將 list entry 儲存為個別 Convex 文件。如此可避免 stream replay list 在單一文件內持續增長，也有助於維持在 Convex 的記錄大小限制內。

每個純量 cache 值與 list item 都會儲存為一個 Convex 資料列，且必須符合 Convex 的資料列大小限制。replay 某個範圍時，極大型 list 仍受 Convex 查詢限制約束。

Cache 清理與 `clear()` 會以有界批次執行。單次 client 呼叫最多可迴圈處理 1,000 次 Convex mutation，而每次 mutation 最多處理 25 個 list item。`clear()` 清理某個 key 時，在清理完成前讀取該 key 可能會傳回空結果。

對於非常大的 cache namespace，請逐步清除或使用範圍較窄的 prefix，以避免長時間執行的清理操作。

批次清理期間，cache metadata 可能暫時使用內部 `deleted` 狀態。下一輪清理會移除這些資料列。在 `clear()` 完成前，請避免寫入具有相同 prefix 的新值。

`clear()` 只會移除已儲存 `keyPrefix` 與設定的 `keyPrefix` 完全相符的資料列。它不會以字串 prefix 比對方式清除巢狀 prefix。每次 `listPush()` 都會使用 cache 設定的 `ttlMs` 重新整理 list TTL。

除非刻意要讓 `clear()` 移除部署中的每個 cache key，否則請使用非空白的 `keyPrefix`。已到期的 list 資料列會在讀寫期間逐步回收。`clear()` 會移除該 prefix 的所有資料列。

`ConvexServerCache` 最適合中等頻率事件的持久 replay。對於高頻 token stream，建議將事件批次處理，或使用延遲較低的 cache backend。

`ConvexServerCache` 無法取代分散式 pub/sub transport。若應用程式需要即時的跨處理程序事件傳遞，請另行設定正式環境 pub/sub backend。

## 其他注意事項

### Schema 管理

儲存空間實作會為各 Mastra domain 使用有型別的 Convex 資料表：

| Domain               | Convex 資料表                    | 用途                              |
| -------------------- | ----------------------------- | ------------------------------- |
| Thread               | `mastra_threads`              | 對話 thread                       |
| 訊息                   | `mastra_messages`             | 聊天訊息                            |
| 資源                   | `mastra_resources`            | 使用者 working memory              |
| Observational Memory | `mastra_observational_memory` | Observational memory 產生內容       |
| Workflow             | `mastra_workflow_snapshots`   | Workflow 狀態                     |
| Scorer               | `mastra_scorers`              | 評估資料                            |
| Cache                | `mastra_cache`                | Cache 值、counter 與 list metadata |
| Cache 項目             | `mastra_cache_list_items`     | Cache list entry                |
| Fallback             | `mastra_documents`            | 未知資料表                           |

### Observational memory

`ConvexStore` 支援 [observational memory](https://mastra.zisheng.pro/zh-TW/docs/memory/observational-memory)。請將 `mastraObservationalMemoryTable` 新增至 Convex schema，並使用 `npx convex deploy` 重新部署以啟用此功能。在新增此資料表前建立的現有部署也需要進行相同的 schema 更新。

### 架構

所有有型別的資料表都包括：

- 用於 Mastra 記錄 ID 的 `id` 欄位（不同於 Convex 自動產生的 `_id`）
- `by_record_id` 索引，可依 Mastra ID 高效查詢

此設計在使用 Convex 自動索引與即時功能的同時，也確保與 Mastra 的儲存 contract 相容。

### 環境變數

請為部署設定下列環境變數：

- `CONVEX_URL`：Convex 部署 URL
- `CONVEX_ADMIN_KEY`：管理員驗證 token（從 Convex dashboard 取得）

## 相關內容

- [Convex Vector Store](https://mastra.zisheng.pro/zh-TW/reference/vectors/convex)
- [Convex 說明文件](https://docs.convex.dev/)