Convex 存储

Convex 存储实现使用 Convex 提供 serverless 存储方案。Convex 是一个具有实时同步和自动缓存功能的全栈 TypeScript 开发平台。

不支持 Observability

Convex 存储不支持 observability 域。来自 MastraStorageExporter 的 Trace 无法持久化到 Convex，并且仅将 Convex 作为存储 Provider 时，Studio 的 observability 功能无法使用。若要启用 observability，请使用组合存储将 observability 数据路由到 ClickHouse 等受支持的 Provider。

记录大小限制

Convex 强制实施 1 MiB 的最大记录大小。存储带有图片等 base64 编码附件的消息时可能超出此限制。请参阅处理大型附件，了解包括将附件上传至 S3、Cloudflare R2 或 Convex file storage 等外部存储在内的解决方法。

安装

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 project 中设置 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 deployment URL（例如 https://your-project.convex.cloud）

adminAuthToken:

string

用于后端访问的 Convex admin 身份验证令牌

storageFunction?:

string

= mastra/storage:handle

storage mutation function 的路径（默认值：'mastra/storage:handle'）

ConvexServerCache 参数

deploymentUrl:

string

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

adminAuthToken:

string

用于后端访问的 Convex admin 身份验证令牌

cacheFunction?:

string

= mastra/cache:handle

ConvexServerCache 的 cache mutation function 路径（默认值：'mastra/cache:handle'）

requestTimeoutMs?:

number

= 30000

Convex cache mutation 请求的超时时间，单位为毫秒。设置为 0 可禁用 client-side 超时。

keyPrefix?:

string

= mastra:cache:

应用于 ConvexServerCache 键的前缀。clear() 会移除已存储前缀与此值完全匹配的行。

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 streams、Workflow stream replay 或 response caching 等功能保留持久的 cache state 时，请使用它。

ConvexServerCache 将 list entry 作为独立的 Convex document 存储。这样可避免在一个 document 内增大 stream replay list，并有助于保持在 Convex 的 record size limit 内。

每个 scalar cache value 和每个 list item 均存储为一行 Convex 数据，并且必须保持在 Convex 的行大小限制内。回放范围时，非常大的 list 仍受 Convex query limit 限制。

cache cleanup 和 clear() 会在有边界的 batch 中运行。单个 client call 最多可循环执行 1,000 个 Convex mutation，每个 mutation 最多处理 25 个 list item。当 clear() 正在清理某个键时，该键的读取可能返回空结果，直至清理完成。

对于非常大的 cache namespace，请逐步清理或使用更窄的前缀，以避免长时间运行的 cleanup operation。

在批量清理期间，cache metadata 可暂时使用内部 deleted state。下一次 cleanup pass 会移除这些行。在 clear() 完成之前，避免使用相同前缀写入新值。

clear() 仅移除已存储 keyPrefix 与配置的 keyPrefix 完全匹配的行。它不会通过字符串前缀匹配清除嵌套前缀。每次 listPush() 都会使用 cache 配置的 ttlMs 刷新 list TTL。

请使用非空 keyPrefix，除非确实希望 clear() 移除 deployment 中的每个 cache key。过期的 list row 会在读写期间逐步回收。clear() 会移除该前缀的所有行。

ConvexServerCache 最适用于中等频率事件的持久化 replay。对于高频 token stream，优先考虑批量处理事件或使用低延迟 cache backend。

ConvexServerCache 不能替代分布式 pub/sub transport。如果应用需要实时跨进程 event delivery，请另行配置生产 pub/sub backend。

补充说明

Schema 管理

该存储实现为每个 Mastra 域使用类型化的 Convex 表：

域	Convex 表	用途
Threads	mastra_threads	对话线程
Messages	mastra_messages	聊天消息
Resources	mastra_resources	用户工作记忆
Observational Memory	mastra_observational_memory	Observational Memory 生成记录
Workflows	mastra_workflow_snapshots	Workflow 状态
Scorers	mastra_scorers	评估数据
Cache	mastra_cache	Cache 值、计数器和列表元数据
Cache Items	mastra_cache_list_items	Cache 列表条目
Fallback	mastra_documents	未知表

Observational memory

ConvexStore 支持 observational memory。将 mastraObservationalMemoryTable 添加到 Convex schema，并使用 npx convex deploy 重新部署以启用它。在添加此表之前创建的现有 deployment 也需要进行相同的 schema 更新。

架构

所有类型化表均包含：

• 用于 Mastra 记录 ID 的 id field（不同于 Convex 自动生成的 _id）
• 用于按 Mastra ID 高效查找的 by_record_id index

该设计在利用 Convex 自动索引和实时能力的同时，确保兼容 Mastra 的 storage contract。

环境变量

为 deployment 设置以下环境变量：

• CONVEX_URL：你的 Convex deployment URL
• CONVEX_ADMIN_KEY：admin 身份验证令牌（从 Convex dashboard 获取）

相关内容

• Convex Vector Store
• Convex 文档