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

# Convex 存储

Convex 存储实现使用 [Convex](https://convex.dev) 提供 serverless 存储方案。Convex 是一个具有实时同步和自动缓存功能的全栈 TypeScript 开发平台。

> **不支持 Observability:** Convex 存储**不支持 observability 域**。来自 `MastraStorageExporter` 的 Trace 无法持久化到 Convex，并且仅将 Convex 作为存储 Provider 时，[Studio](https://mastra.zisheng.pro/docs/studio/overview) 的 observability 功能无法使用。若要启用 observability，请使用[组合存储](https://mastra.zisheng.pro/reference/storage/composite)将 observability 数据路由到 ClickHouse 等受支持的 Provider。

> **记录大小限制:** Convex 强制实施 **1 MiB 的最大记录大小**。存储带有图片等 base64 编码附件的消息时可能超出此限制。请参阅[处理大型附件](https://mastra.zisheng.pro/docs/memory/memory-processors)，了解包括将附件上传至 S3、Cloudflare R2 或 [Convex file storage](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 project 中设置 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 deployment URL（例如 https\://your-project.convex.cloud）

**adminAuthToken** (`string`): 用于后端访问的 Convex admin 身份验证令牌

**storageFunction** (`string`): storage mutation function 的路径（默认值：'mastra/storage:handle'） (Default: `mastra/storage:handle`)

## ConvexServerCache 参数

**deploymentUrl** (`string`): Convex deployment URL（例如 https\://your-project.convex.cloud）

**adminAuthToken** (`string`): 用于后端访问的 Convex admin 身份验证令牌

**cacheFunction** (`string`): ConvexServerCache 的 cache mutation function 路径（默认值：'mastra/cache:handle'） (Default: `mastra/cache:handle`)

**requestTimeoutMs** (`number`): Convex cache mutation 请求的超时时间，单位为毫秒。设置为 0 可禁用 client-side 超时。 (Default: `30000`)

**keyPrefix** (`string`): 应用于 ConvexServerCache 键的前缀。clear() 会移除已存储前缀与此值完全匹配的行。 (Default: `mastra:cache:`)

**ttlMs** (`number`): 默认 ConvexServerCache TTL，单位为毫秒。设置为 0 可禁用过期。 (Default: `300000`)

## 构造函数示例

```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 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](https://mastra.zisheng.pro/docs/memory/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](https://mastra.zisheng.pro/reference/vectors/convex)
- [Convex 文档](https://docs.convex.dev/)