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

# 볼록한 저장

Convex 스토리지 구현은 다음을 사용하여 서버리스 스토리지 솔루션을 제공합니다.[Convex](https://convex.dev), 실시간 동기화 및 자동 캐싱 기능을 갖춘 풀 스택 TypeScript 개발 플랫폼입니다.

:::warning\[관측성이 지원되지 않음]

Convex 스토리지는 **Observability 도메인을 지원하지 않습니다**. `MastraStorageExporter`의 Trace를 Convex에 유지할 수 없으며, Convex를 유일한 스토리지 Provider로 사용하는 경우 [Studio의](https://mastra.zisheng.pro/ko/docs/studio/overview) Observability 기능이 작동하지 않습니다. Observability을 활성화하려면 [복합 스토리지](https://mastra.zisheng.pro/ko/reference/storage/composite)를 사용하여 Observability 데이터를 ClickHouse와 같이 지원되는 Provider로 라우팅하세요. :::

:::warning\[레코드 크기 제한] Convex의 **최대 레코드 크기는 1 MiB입니다**. 이미지와 같이 base64로 인코딩된 첨부 파일이 포함된 메시지를 저장하면 이 제한을 초과할 수 있습니다. 첨부 파일을 S3, Cloudflare R2 또는 [Convex 파일 스토리지](https://docs.convex.dev/file-storage)와 같은 외부 스토리지에 업로드하는 방법을 비롯한 해결 방법은 [대용량 첨부 파일 처리](https://mastra.zisheng.pro/ko/docs/memory/memory-processors)를 참조하세요. :::

## 설치

**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
```

## 볼록한 설정

`ConvexStore`를 사용하기 전에 Convex 프로젝트에서 Convex 스키마와 스토리지 핸들러를 설정하세요. 아래 스키마 예제에는 전체 `ConvexStore` 및 `ConvexServerCache` 설정이 포함되어 있습니다. `ConvexStore`만 사용하는 경우 `mastraCacheTable`과 `mastraCacheListItemsTable`을 생략하고, `ConvexServerCache`를 사용하는 경우에는 해당 테이블을 포함하고 캐시 핸들러를 생성하세요.

### 1. 볼록 스키마 설정

\~ 안에`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. 스토리지 핸들러 생성

\~ 안에`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 배포 URL(예: https\://your-project.convex.cloud)

**adminAuthToken** (`string`): 백엔드 액세스를 위한 Convex 관리자 인증 토큰

**storageFunction** (`string`): 스토리지 변경 함수의 경로(기본값: 'mastra/storage:handle') (Default: `mastra/storage:handle`)

## ConvexServerCache 매개변수

**deploymentUrl** (`string`): Convex 배포 URL(예: https\://your-project.convex.cloud)

**adminAuthToken** (`string`): 백엔드 액세스를 위한 Convex 관리자 인증 토큰

**cacheFunction** (`string`): ConvexServerCache의 캐시 변경 함수 경로(기본값: 'mastra/cache:handle') (Default: `mastra/cache:handle`)

**requestTimeoutMs** (`number`): Convex 캐시 변경 요청의 제한 시간(밀리초)입니다. 클라이언트 측 제한 시간을 비활성화하려면 0으로 설정하세요. (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',
})
```

## 서버 캐시

`ConvexServerCache`Convex와 Mastra의 서버 캐시 계약을 구현합니다. 재개 가능한 내구성 Agent 스트림, Workflow 스트림 재생 또는 응답 캐싱과 같은 기능에 대해 내구성 있는 캐시 상태를 원할 때 사용합니다.

`ConvexServerCache`목록 항목을 별도의 Convex 문서로 저장합니다. 이렇게 하면 하나의 문서 내에서 스트림 재생 목록이 커지는 것을 방지하고 Convex의 레코드 크기 제한 내에서 유지하는 데 도움이 됩니다.

각 스칼라 캐시 값과 각 목록 항목은 하나의 Convex 행으로 저장되며 Convex의 행 크기 제한 내에 있어야 합니다. 범위를 재생할 때 매우 큰 목록은 여전히 ​​Convex 쿼리 제한으로 제한됩니다.

캐시 정리와 `clear()`는 제한된 배치 단위로 실행됩니다. 단일 클라이언트 호출은 최대 1,000개의 Convex 변경 작업을 순회할 수 있으며, 각 변경 작업은 최대 25개의 목록 항목을 처리합니다. `clear()`가 키를 정리하는 동안에는 정리가 끝날 때까지 해당 키에 대한 읽기 결과가 비어 있을 수 있습니다. 매우 큰 캐시 네임스페이스의 경우 점진적으로 지우거나 더 좁은 접두사를 사용하여 장기 실행 정리 작업을 방지합니다.

배치 정리 중에는 캐시 메타데이터가 일시적으로 내부 `deleted` 상태가 됩니다. 다음 정리 단계에서 해당 행을 제거합니다. `clear()`가 끝날 때까지 동일한 접두사로 새 값을 쓰지 마세요. `clear()`는 저장된 `keyPrefix`가 구성된 `keyPrefix`와 정확히 일치하는 행만 제거합니다. 문자열 접두사 일치 방식으로 중첩 접두사를 지우지는 않습니다. 각 `listPush()`는 캐시에 구성된 `ttlMs`를 사용하여 목록 TTL을 갱신합니다. `clear()`가 배포의 모든 캐시 키를 제거하도록 의도한 경우가 아니라면 비어 있지 않은 `keyPrefix`를 사용하세요. 만료된 목록 행은 읽기 및 쓰기 과정에서 점진적으로 회수됩니다. `clear()`는 해당 접두사의 모든 행을 제거합니다. `ConvexServerCache`중간 빈도 이벤트의 내구성 있는 재생에 가장 적합합니다. 빈도가 높은 토큰 스트림의 경우 이벤트를 일괄 처리하거나 지연 시간이 짧은 캐시 백엔드를 사용하는 것이 좋습니다.

`ConvexServerCache`분산 pub/sub 전송을 대체하지 않습니다. 앱에 실시간 크로스 프로세스 이벤트 전달이 필요한 경우 프로덕션 게시/구독 백엔드를 별도로 구성하세요.

## 추가 참고사항

### 스키마 관리

스토리지 구현에서는 각 Mastra 도메인에 대해 유형이 지정된 Convex 테이블을 사용합니다.

| 도메인       | Convex 테이블                    | 목적                  |
| --------- | ----------------------------- | ------------------- |
| 스레드       | `mastra_threads`              | 대화 스레드              |
| 메시지       | `mastra_messages`             | 채팅 메시지              |
| 리소스       | `mastra_resources`            | 사용자 작업 Memory       |
| 관찰 Memory | `mastra_observational_memory` | 관찰 Memory 생성 결과     |
| Workflow  | `mastra_workflow_snapshots`   | Workflow 상태         |
| 채점기       | `mastra_scorers`              | 평가 데이터              |
| 캐시        | `mastra_cache`                | 캐시 값, 카운터, 목록 메타데이터 |
| 캐시 항목     | `mastra_cache_list_items`     | 캐시 목록 항목            |
| 대체 항목     | `mastra_documents`            | 알 수 없는 테이블          |

### 관찰 기억

`ConvexStore`는 [관찰 Memory](https://mastra.zisheng.pro/ko/docs/memory/observational-memory)를 지원합니다. Convex 스키마에 `mastraObservationalMemoryTable`을 추가하고 `npx convex deploy`로 다시 배포하여 활성화하세요. 이 테이블이 추가되기 전에 생성된 기존 배포에도 동일한 스키마 업데이트가 필요합니다.

### 건축학

모든 유형의 테이블에는 다음이 포함됩니다.

- Mastra 레코드 ID를 위한 `id` 필드(Convex가 자동 생성하는 `_id`와 별개)
- Mastra ID로 효율적으로 조회하기 위한 `by_record_id` 인덱스 이 디자인은 Convex의 자동 인덱싱 및 실시간 기능을 사용하면서 Mastra의 스토리지 계약과의 호환성을 보장합니다.

### 환경변수

배포에 대해 다음 환경 변수를 설정합니다.

- `CONVEX_URL`: Convex 배포 URL
- `CONVEX_ADMIN_KEY`: 관리자 인증 토큰(Convex 대시보드에서 가져오기)

## 관련된

- [볼록 벡터 저장소](https://mastra.zisheng.pro/ko/reference/vectors/convex)
- [볼록 문서](https://docs.convex.dev/)