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

# 업스태시 스토리지

Upstash 스토리지 구현은 Upstash의 Redis 호환 키-값 저장소를 사용하여 서버리스 친화적인 스토리지 솔루션을 제공합니다.

:::warning\[가격]

Upstash와 함께 Mastra를 사용할 때 종량제 요금제는 Agent 대화 중 생성되는 Redis 명령이 많아 예기치 않은 고비용을 초래할 수 있습니다. 예측 가능한 비용을 위해 **고정 요금제**를 권장합니다. 자세한 내용은 [Upstash 요금](https://upstash.com/pricing/redis)을, 관련 배경은 [GitHub 이슈 #5850](https://github.com/mastra-ai/mastra/issues/5850)을 참조하세요. :::

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

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

## 설치

**npm**:

```bash
npm install @mastra/upstash@latest
```

**pnpm**:

```bash
pnpm add @mastra/upstash@latest
```

**Yarn**:

```bash
yarn add @mastra/upstash@latest
```

**Bun**:

```bash
bun add @mastra/upstash@latest
```

## 용법

```typescript
import { UpstashStore } from '@mastra/upstash'

const storage = new UpstashStore({
  id: 'upstash-storage',
  url: process.env.UPSTASH_URL,
  token: process.env.UPSTASH_TOKEN,
})
```

## 매개변수

**url** (`string`): Upstash Redis URL

**token** (`string`): Upstash Redis 인증 토큰

**prefix** (`string`): 저장되는 모든 항목의 키 접두사 (Default: `mastra:`)

## 추가 참고사항

### 주요 구조

Upstash 스토리지 구현은 키-값 구조를 사용합니다.

- 스레드 키:`{prefix}thread:{threadId}`
- 메시지 키:`{prefix}message:{messageId}`
- 메타데이터 키:`{prefix}metadata:{entityId}`

### 서버리스 이점

Upstash 스토리지는 특히 서버리스 배포에 적합합니다.

- 연결 관리가 필요하지 않습니다
- 요청당 지불 가격
- 글로벌 복제 옵션
- 엣지 호환

### 데이터 지속성

Upstash는 다음을 제공합니다.

- 자동 데이터 지속성
- 특정 시점 복구
- 지역 간 복제 옵션

### 성능 고려 사항

최적의 성능을 위해서는:

- 적절한 키 접두사를 사용하여 데이터 구성
- Redis Memory 사용량 모니터링
- 필요한 경우 데이터 만료 정책을 고려하세요.

## 사용예

### Agent에 Memory 추가

Agent에 Upstash Memory를 추가하려면 `Memory` 클래스를 사용하고, `UpstashStore`를 사용하는 새 `storage` 키와 `UpstashVector`를 사용하는 새 `vector` 키를 생성하세요. 구성은 원격 서비스나 로컬 설정 중 하나를 가리킬 수 있습니다.

```typescript
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { UpstashStore } from '@mastra/upstash'

export const upstashAgent = new Agent({
  id: 'upstash-agent',
  name: 'Upstash Agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new UpstashStore({
      id: 'upstash-agent-storage',
      url: process.env.UPSTASH_REDIS_REST_URL!,
      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
    }),
    options: {
      generateTitle: true, // Explicitly enable automatic title generation
    },
  }),
})
```

### Agent 사용

`memoryOptions`를 사용하여 이 요청의 회상 범위를 지정하세요. `lastMessages: 5`를 설정하여 최근성 기반 회상을 제한하고, `semanticRecall`을 사용하여 가장 관련성 높은 메시지를 `topK: 3`개 가져오세요. 각 일치 항목 주변의 컨텍스트를 위해 인접 메시지 `messageRange: 2`개도 포함합니다.

```typescript
import 'dotenv/config'

import { mastra } from './mastra'

const threadId = '123'
const resourceId = 'user-456'

const agent = mastra.getAgent('upstashAgent')

const message = await agent.stream('My name is Mastra', {
  memory: {
    thread: threadId,
    resource: resourceId,
  },
})

await message.textStream.pipeTo(new WritableStream())

const stream = await agent.stream("What's my name?", {
  memory: {
    thread: threadId,
    resource: resourceId,
  },
  memoryOptions: {
    lastMessages: 5,
    semanticRecall: {
      topK: 3,
      messageRange: 2,
    },
  },
})

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}
```