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

# Convex 儲存

Convex 儲存實作使用 [Convex](https://convex.dev) 提供 serverless 儲存方案。Convex 是支援即時同步及自動 caching 的 full-stack TypeScript 開發平台。

> **不支援可觀測性:** Convex 儲存**不支援 observability domain**。來自 `MastraStorageExporter` 的 Trace 無法持久保存至 Convex，而當 Convex 是你唯一的 storage provider 時，[Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview) 的可觀測性功能亦無法運作。如要啟用可觀測性，請使用[複合儲存](https://mastra.zisheng.pro/zh-HK/reference/storage/composite)，將可觀測性資料路由至 ClickHouse 等受支援的 Provider。

> **記錄大小限制:** Convex 強制實施 **1 MiB 的記錄大小上限**。儲存包含圖片等 base64 編碼附件的訊息時，可能會超出此限制。請參閱[處理大型附件](https://mastra.zisheng.pro/zh-HK/docs/memory/memory-processors)，了解包括將附件上載至 S3、Cloudflare R2 等外部儲存空間或 [Convex 檔案儲存空間](https://docs.convex.dev/file-storage)在內的解決方法。

## 安裝

**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 admin authentication 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 admin authentication token

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

**requestTimeoutMs** (`number`): Convex cache mutation request 的 timeout（毫秒）。設為 0 可停用 client-side timeout。 (Default: `30000`)

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

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

## Constructor 範例

```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 或 response caching 等功能提供持久 cache 狀態，請使用此功能。

`ConvexServerCache` 會將 list entry 儲存為獨立的 Convex document。這樣可避免 stream replay list 在單一 document 內持續增長，並有助維持在 Convex 的記錄大小限制內。

每個 scalar cache value 及每個 list item 均儲存為一個 Convex row，並且必須符合 Convex 的 row-size limit。replay 某個範圍時，非常大型的 list 仍受 Convex query limit 約束。

cache 清理及 `clear()` 會以有界 batch 執行。單次 client call 最多可以循環執行 1,000 個 Convex mutation，而每個 mutation 最多處理 25 個 list item。`clear()` 正在清理某個 key 時，該 key 的 read 可能會傳回空結果，直至清理完成。

對於非常大型的 cache namespace，請逐步清除，或使用更精確的前綴，以免清理操作耗時過長。

進行 batch 清理期間，cache metadata 可能會暫時使用內部 `deleted` 狀態。下一輪清理會移除這些資料列。`clear()` 完成前，請避免以相同前綴寫入新值。

`clear()` 只會移除已儲存 `keyPrefix` 與設定的 `keyPrefix` 完全相符的資料列，不會透過字串前綴比對來清除巢狀前綴。每次呼叫 `listPush()` 都會使用 cache 設定的 `ttlMs` 重新整理 list TTL。

除非你有意讓 `clear()` 移除部署中的每個 cache key，否則請使用非空白的 `keyPrefix`。已到期的 list row 會在 read 及 write 期間逐步回收。`clear()` 會移除該前綴的所有資料列。

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

`ConvexServerCache` 不會取代分散式 pub/sub transport。如你的應用程式需要跨 process 即時傳送 event，請另行設定生產環境 pub/sub backend。

## 補充說明

### Schema 管理

儲存實作為每個 Mastra domain 使用具類型的 Convex 資料表：

| Domain               | Convex 資料表                    | 用途                                  |
| -------------------- | ----------------------------- | ----------------------------------- |
| Thread               | `mastra_threads`              | 對話 thread                           |
| 訊息                   | `mastra_messages`             | 對話訊息                                |
| Resource             | `mastra_resources`            | 使用者 working memory                  |
| Observational Memory | `mastra_observational_memory` | Observational memory generation     |
| Workflow             | `mastra_workflow_snapshots`   | Workflow 狀態                         |
| Scorer               | `mastra_scorers`              | 評估資料                                |
| Cache                | `mastra_cache`                | Cache value、counter 及 list metadata |
| Cache 項目             | `mastra_cache_list_items`     | Cache list entry                    |
| Fallback             | `mastra_documents`            | 未知資料表                               |

### Observational memory

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

### 架構

所有具類型的資料表均包括：

- 用作 Mastra record ID 的 `id` 欄位（有別於 Convex 自動產生的 `_id`）
- `by_record_id` index，用於按 Mastra ID 高效 lookup

這項設計使用 Convex 的自動 indexing 及即時功能，同時確保與 Mastra storage contract 相容。

### 環境變數

為你的部署設定以下環境變數：

- `CONVEX_URL`：你的 Convex 部署 URL
- `CONVEX_ADMIN_KEY`：Admin authentication token（從 Convex dashboard 取得）

## 相關內容

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