Convex 儲存空間

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

不支援可觀測性

Convex 儲存空間不支援 observability domain。MastraStorageExporter 的 Trace 無法持久化至 Convex；若 Convex 是唯一的儲存 Provider，Studio 的可觀測性功能也無法運作。若要啟用可觀測性，請使用複合儲存空間，將可觀測性資料路由至 ClickHouse 等受支援的 Provider。

記錄大小限制

Convex 規定每筆記錄最大為 1 MiB。儲存包含圖片等 base64 編碼附件的訊息時，可能超過此限制。如需包含將附件上傳至 S3、Cloudflare R2 或 Convex 檔案儲存空間等外部儲存空間的替代做法，請參閱處理大型附件。

安裝

npm

npm install @mastra/convex@latest

pnpm

pnpm add @mastra/convex@latest

Yarn

yarn add @mastra/convex@latest

Bun

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 中：

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 中：

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

export const handle = mastraStorage

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

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

export const handle = mastraCache

3. 部署至 Convex

npx convex dev
# or for production
npx convex deploy

使用方式

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

= mastra/storage:handle

Storage mutation function 的路徑（預設：'mastra/storage:handle'）

ConvexServerCache 參數

deploymentUrl:

string

Convex 部署 URL（例如 https://your-project.convex.cloud）

adminAuthToken:

string

用於存取 backend 的 Convex 管理員驗證 token

cacheFunction?:

string

= mastra/cache:handle

ConvexServerCache cache mutation function 的路徑（預設：'mastra/cache:handle'）

requestTimeoutMs?:

number

= 30000

Convex cache mutation 請求的逾時時間（毫秒）。設為 0 可停用 client 端逾時。

keyPrefix?:

string

= mastra:cache:

套用至 ConvexServerCache key 的 prefix。clear() 會移除已儲存 prefix 與此值完全相符的資料列。

ttlMs?:

number

= 300000

ConvexServerCache 的預設 TTL（毫秒）。設為 0 可停用到期機制。

建構函式範例

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。請將 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
• Convex 說明文件