레디스 스토리지

Redis 스토리지 구현은 다음을 통해 직접 Redis 연결을 사용하여 고성능 스토리지 솔루션을 제공합니다.node-redis(Node.js의 공식 Redis 클라이언트). 독립형 Redis를 지원하고 사용자 정의 클라이언트 구성을 통해 Redis Sentinel 및 클러스터 배포를 지원합니다.

설치

npm install @mastra/redis

용법

연결 문자열 사용

import { RedisStore } from '@mastra/redis'

const storage = new RedisStore({
  id: 'redis-storage',
  connectionString: 'redis://localhost:6379',
})

await storage.init()

호스트/포트 구성 사용

import { RedisStore } from '@mastra/redis'

const storage = new RedisStore({
  id: 'redis-storage',
  host: 'localhost',
  port: 6379,
  password: 'your-password',
  db: 0,
})

await storage.init()

사전 구성된 클라이언트 사용

Sentinel 또는 Cluster와 같은 고급 구성의 경우 사전 구성된 Redis 클라이언트를 전달할 수 있습니다.

import { RedisStore } from '@mastra/redis'
import { createClient } from 'redis'

const client = createClient({
  url: 'redis://localhost:6379',
  socket: {
    reconnectStrategy: retries => Math.min(retries * 50, 2000),
  },
})

// Connect the client before passing to RedisStore
await client.connect()

const storage = new RedisStore({
  id: 'redis-storage',
  client,
})

매개변수

id:

string

저장소 인스턴스의 고유 식별자입니다.

connectionString?:

string

Redis 연결 URL입니다(예: redis://localhost:6379 또는 redis://:password@localhost:6379).

host?:

string

Redis 호스트 주소입니다.

port?:

number

= 6379

Redis 포트 번호입니다.

password?:

string

인증에 사용할 Redis 비밀번호입니다.

db?:

number

= 0

Redis 데이터베이스 번호입니다.

client?:

RedisClient

고급 설정을 위한 미리 구성된 redis 클라이언트(redis 패키지 제공)입니다.

:::참고 connectionString, host, client 중 하나를 제공해야 합니다. 이 옵션들은 상호 배타적입니다. :::

추가 참고사항

주요 구조

Redis 스토리지 구현은 다음과 같은 주요 패턴을 사용합니다.

• 스레드: mastra_threads:id:{threadId}
• 메시지: mastra_messages:threadId:{threadId}:id:{messageId}
• 메시지 인덱스: msg-idx:{messageId}(빠른 조회용)
• 스레드 메시지 정렬 집합: thread:{threadId}:messages
• Workflow 스냅샷: mastra_workflow_snapshot:namespace:{ns}:workflow_name:{name}:run_id:{id}
• 점수: mastra_scorers:id:{scoreId}
• 리소스: mastra_resources:{resourceId}

레디스 센티넬

Redis Sentinel을 사용한 고가용성 배포를 위해 사용자 지정 클라이언트를 만듭니다.

import { RedisStore } from '@mastra/redis'
import { createClient } from 'redis'

const client = createClient({
  url: 'redis://sentinel-host:26379',
  // Configure sentinel options as needed for your setup
})

await client.connect()

const storage = new RedisStore({
  id: 'redis-sentinel-storage',
  client,
})

레디스 클러스터

Redis 클러스터 배포의 경우 클러스터 클라이언트를 사용합니다.

import { RedisStore } from '@mastra/redis'
import { createCluster } from 'redis'

const cluster = createCluster({
  rootNodes: [
    { url: 'redis://node-1:6379' },
    { url: 'redis://node-2:6379' },
    { url: 'redis://node-3:6379' },
  ],
})

await cluster.connect()

const storage = new RedisStore({
  id: 'redis-cluster-storage',
  client: cluster,
})

기본 클라이언트에 액세스

사용자 지정 작업을 위해 기본 Redis 클라이언트에 액세스할 수 있습니다.

const storage = new RedisStore({
  id: 'redis-storage',
  connectionString: 'redis://localhost:6379',
})

await storage.init()

const client = storage.getClient()

// Custom Redis operations
await client.set('custom-key', 'value')
const value = await client.get('custom-key')

연결 닫기

애플리케이션을 종료할 때 Redis 연결을 닫습니다.

await storage.close()

사용예

Agent에 Memory 추가

src/mastra/agents/redis-agent.ts

import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { RedisStore } from '@mastra/redis'

export const redisAgent = new Agent({
  id: 'redis-agent',
  name: 'Redis 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 RedisStore({
      id: 'redis-agent-storage',
      connectionString: process.env.REDIS_URL!,
    }),
    options: {
      lastMessages: 10,
    },
  }),
})

Agent 사용

src/test-redis-agent.ts

import 'dotenv/config'

import { mastra } from './mastra'

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

const agent = mastra.getAgent('redisAgent')

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,
  },
})

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

Mastra 인스턴스와 함께 사용

import { Mastra } from '@mastra/core'
import { RedisStore } from '@mastra/redis'

const storage = new RedisStore({
  id: 'mastra-storage',
  host: 'localhost',
  port: 6379,
})

const mastra = new Mastra({
  storage, // init() called automatically
})

Mastra 없이 직접 저장소를 사용하는 경우init() explicitly:

import { RedisStore } from '@mastra/redis'

const storage = new RedisStore({
  id: 'redis-storage',
  host: 'localhost',
  port: 6379,
})

await storage.init()

// Access domain-specific stores via getStore()
const memoryStore = await storage.getStore('memory')
const thread = await memoryStore?.getThreadById({ threadId: '...' })