Convex存储

🌐 Convex Storage

Convex 存储实现提供了一种无服务器存储解决方案，使用 Convex，这是一个具备实时同步和自动缓存功能的全栈 TypeScript 开发平台。

🌐 The Convex storage implementation provides a serverless storage solution using Convex, a full-stack TypeScript development platform with real-time sync and automatic caching.

Observability Not Supported

Convex storage does not support the observability domain. Traces from the DefaultExporter cannot be persisted to Convex, and Mastra Studio's observability features won't work with Convex as your only storage provider. To enable observability, use composite storage to route observability data to a supported provider like ClickHouse or PostgreSQL.

Record Size Limit

Convex enforces a 1 MiB maximum record size. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See Handling large attachments for workarounds including uploading attachments to external storage like S3, Cloudflare R2, or Convex file storage.

安装

🌐 Installation

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配置

🌐 Convex Setup

在使用 ConvexStore 之前，你需要在你的 Convex 项目中设置 Convex 模式和存储处理器。

🌐 Before using ConvexStore, you need to set up the Convex schema and storage handler in your Convex project.

1. 设置 Convex 架构

🌐 1. Set up Convex Schema

在 convex/schema.ts 中：

🌐 In convex/schema.ts:

import { defineSchema } from 'convex/server';
import {
  mastraThreadsTable,
  mastraMessagesTable,
  mastraResourcesTable,
  mastraWorkflowSnapshotsTable,
  mastraScoresTable,
  mastraVectorIndexesTable,
  mastraVectorsTable,
  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_vector_indexes: mastraVectorIndexesTable,
  mastra_vectors: mastraVectorsTable,
  mastra_documents: mastraDocumentsTable,
});

2. 创建存储处理器

🌐 2. Create the Storage Handler

在 convex/mastra/storage.ts 中：

🌐 In convex/mastra/storage.ts:

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

export const handle = mastraStorage;

3. 部署到 Convex

🌐 3. Deploy to Convex

npx convex dev
# or for production
npx convex deploy

用法

🌐 Usage

import { ConvexStore } from "@mastra/convex";

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

参数

🌐 Parameters

deploymentUrl:

string

Convex deployment URL (e.g., https://your-project.convex.cloud)

adminAuthToken:

string

Convex admin authentication token for backend access

storageFunction?:

string

= mastra/storage:handle

Path to the storage mutation function (default: 'mastra/storage:handle')

构造函数示例

🌐 Constructor Examples

import { 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",
});

附加说明

🌐 Additional Notes

模式管理

🌐 Schema Management

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

🌐 The storage implementation uses typed Convex tables for each Mastra domain:

域	Convex表	目的
线程	mastra_threads	会话线程
消息	mastra_messages	聊天消息
资源	mastra_resources	用户工作内存
工作流	mastra_workflow_snapshots	工作流状态
评分器	mastra_scorers	评估数据
回退	mastra_documents	未知表格

架构

🌐 Architecture

所有已键入的表格包括：

🌐 All typed tables include:

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

该设计确保与Mastra的存储合约兼容，同时利用Convex的自动索引和实时功能。

🌐 This design ensures compatibility with Mastra's storage contract while leveraging Convex's automatic indexing and real-time capabilities.

环境变量

🌐 Environment Variables

为你的部署设置这些环境变量：

🌐 Set these environment variables for your deployment:

• CONVEX_URL – 你的 Convex 部署 URL
• CONVEX_ADMIN_KEY – 管理员认证令牌（从 Convex 仪表板获取）

相关

🌐 Related

• Convex向量存储
• Convex 文档