Convex 儲存
Convex 儲存實作使用 Convex 提供 serverless 儲存方案。Convex 是支援即時同步及自動 caching 的 full-stack TypeScript 開發平台。
Convex 強制實施 1 MiB 的記錄大小上限。儲存包含圖片等 base64 編碼附件的訊息時，可能會超出此限制。請參閱處理大型附件，了解包括將附件上載至 S3、Cloudflare R2 等外部儲存空間或 Convex 檔案儲存空間在內的解決方法。
安裝安裝 的直接連結
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/convex@latest
pnpm add @mastra/convex@latest
yarn add @mastra/convex@latest
bun add @mastra/convex@latest
設定 Convex設定 Convex 的直接連結
使用 ConvexStore 前，請在 Convex 項目中設定 Convex schema 及 storage handler。
以下 schema 範例包含完整的 ConvexStore 及 ConvexServerCache 設定。如只使用 ConvexStore，請省略 mastraCacheTable 及 mastraCacheListItemsTable；如使用 ConvexServerCache，請加入這些資料表並建立 cache handler。
1. 設定 Convex Schema1. 設定 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 Handler2. 建立 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. 部署至 Convex3. 部署至 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 參數ConvexStore 參數 的直接連結
deploymentUrl:
adminAuthToken:
storageFunction?:
ConvexServerCache 參數ConvexServerCache 參數 的直接連結
deploymentUrl:
adminAuthToken:
cacheFunction?:
requestTimeoutMs?:
keyPrefix?:
ttlMs?:
Constructor 範例Constructor 範例 的直接連結
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 cacheServer 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 管理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 memoryObservational memory 的直接連結
ConvexStore 支援 observational memory。請將 mastraObservationalMemoryTable 加至 Convex schema，並以 npx convex deploy 重新部署以啟用此功能。在加入此資料表前建立的現有部署亦需要進行相同的 schema 更新。
架構架構 的直接連結
所有具類型的資料表均包括：
- 用作 Mastra record ID 的
id欄位（有別於 Convex 自動產生的_id） by_record_idindex，用於按 Mastra ID 高效 lookup
這項設計使用 Convex 的自動 indexing 及即時功能，同時確保與 Mastra storage contract 相容。
環境變數環境變數 的直接連結
為你的部署設定以下環境變數：
CONVEX_URL：你的 Convex 部署 URLCONVEX_ADMIN_KEY：Admin authentication token（從 Convex dashboard 取得）