스토리지 개요

스토리지는 Mastra 런타임의 지속성 계층입니다. 프로세스가 다시 시작된 후에도 Memory, Workflow 상태, Observability 데이터, 평가 결과, 일정 및 장기 실행 Agent 상태를 유지합니다.

저장 능력:

• Memory: 메시지 기록, 스레드, 리소스 및 작업 Memory입니다.
• Workflow: 일시 중단 및 재개된 Workflow 실행을 위한 내구성 있는 스냅샷입니다.
• Observability: 추적, 범위, 측정항목, 로그, 피드백입니다.
• 평가: 점수, 데이터 세트, 실험, 평가 결과입니다.
• 장기 실행 Agent: 백그라운드 작업, 일정, 목표 및 스레드 상태입니다.

스토리지를 구성해야 하는 경우

상태가 다시 시작 후에도 유지되어야 하거나 프로세스 간에 공유되어야 하는 경우 영구 스토리지 어댑터를 구성합니다. 영구 저장소는 또한 세션 전반에 걸쳐 Studio에서 상태를 계속 표시합니다. 기본 Memory 내 저장소는 테스트 및 짧은 로컬 실험에 유용하지만 프로세스가 종료되면 데이터가 손실됩니다.

애플리케이션에 다음 동작이 필요할 때 스토리지를 사용하세요.

• Agent은 과거 메시지나 사용자 사실을 기억합니다.
• 다시 시작한 후 Workflow가 일시 중지되고 다시 시작됩니다.
• 분석을 위해 추적, 지표, 로그, 점수 또는 피드백을 계속 사용할 수 있습니다.
• 일정과 백그라운드 작업은 배포 전반에 걸쳐 계속됩니다.
• 여러 런타임 프로세스가 동일한 상태를 읽고 씁니다.

스토리지 작동 방식

Mastra 스토리지는 도메인으로 구성됩니다. 도메인은 한 유형의 런타임 데이터를 소유하며, 스토리지 어댑터는 하나 이상의 도메인을 구현합니다.

도메인	저장하는 데이터
memory	스레드, 메시지, 리소스, 작업 Memory 및 기타 Agent Memory 상태입니다.
workflows	실행을 일시 중단하고 재개하는 데 사용되는 Workflow 스냅샷입니다.
observability	Trace, 스팬, 메트릭, 로그 및 피드백입니다.
scores	Eval 점수 레코드입니다.
datasets	Evals 및 실험에 사용되는 데이터세트 레코드와 데이터세트 항목입니다.
experiments	실험 실행 및 항목별 실험 결과입니다.
backgroundTasks	백그라운드 작업 레코드 및 실행 상태입니다.
schedules	일정 정의 및 트리거 기록입니다.
threadState	영구적인 작업, 목표 및 스레드 상태입니다.
어댑터 지원은 도메인에 따라 다릅니다. 전체 도메인 목록과 기본 제공 스키마는 다음을 참조하세요.storage overview reference.

데이터 형태에 따라 백엔드 선택

다양한 도메인은 다양한 종류의 데이터를 작성하고 쿼리합니다. 도메인의 액세스 패턴에 따라 백엔드를 선택하세요.

• memory: 기억된 모든 Agent 호출에서 행을 읽고 씁니다. libSQL, PostgreSQL 또는 MongoDB와 같은 트랜잭션 데이터베이스를 사용하세요.
• observability: 대량의 원격 측정 데이터를 작성하고 집계를 자주 쿼리합니다. 전용 Observability 저장소나 ClickHouse 또는 DuckDB와 같은 온라인 분석 처리(OLAP) 백엔드를 사용하세요.
• workflows: 실행을 재개할 때 사용할 수 있어야 하는 내구성 있는 스냅샷을 저장합니다. 안정적인 영구 데이터베이스를 사용하세요.
• scores, datasets, experiments: 나중에 분석하기 위해 읽는 경우가 많은 저빈도 평가 데이터를 저장합니다.
• schedules: 일정 정의와 실행 이력을 저장합니다. 일정 도메인을 구현하는 어댑터를 사용하세요. 도메인별 운영 요구 사항이 다르면 복합 스토리지를 사용하여 각 도메인을 적합한 백엔드로 라우팅하세요.

로컬에서 시작하기

로컬 개발의 경우 파일 지원 데이터베이스와 함께 libSQL을 사용하십시오. 별도의 데이터베이스 서버가 필요하지 않으며 다시 시작하는 동안 상태를 유지합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})

:::tip[Studio와 데이터베이스 공유하기]

애플리케이션과 함께 mastra dev를 실행할 때는 두 프로세스가 동일한 데이터베이스에 접근하도록 절대 경로를 사용하세요.

url: 'file:/absolute/path/to/your/project/mastra.db'

file:./mastra.db 같은 상대 경로는 각 프로세스의 작업 디렉터리를 기준으로 해석되며, 이 디렉터리는 서로 다를 수 있습니다. :::

Mastra는 처음 사용할 때 필요한 저장 구조를 초기화합니다.

프로덕션을 위한 구성

프로덕션의 경우 영구 관리형 데이터베이스를 사용합니다. PostgreSQL은 트랜잭션 런타임 상태에 적합하고 관리형 서비스로 널리 사용 가능하므로 대부분의 팀에 좋은 기본값입니다.

생산 지침:

• 백업, 모니터링, 연결 풀링이 포함된 관리형 데이터베이스를 사용하세요.
• file:./mastra.db 같은 로컬 파일 데이터베이스는 다중 프로세스 프로덕션 배포에서 사용하지 마세요.
• 특히 대용량 observability 도메인은 복합 스토리지를 사용하여 전용 백엔드로 라우팅하세요.
• 스토리지 어댑터 또는 복합 저장소에 보존 정책을 구성한 다음, 스케줄러나 유지 관리 작업에서 storage.prune()을 호출하세요.
• 애플리케이션이 사용하는 도메인을 기준으로 Provider를 선택하세요. 예를 들어 일정에는 schedules 도메인을 구현하는 어댑터가 필요합니다.

구성 범위

스토리지는 Mastra 인스턴스 수준 또는 Agent 수준에서 구성할 수 있습니다.

인스턴스 수준 스토리지

인스턴스 수준 스토리지는 동일한 Mastra 인스턴스에 등록된 Agent, Workflow, Observability, 평가, 일정 및 기타 런타임 기능에 의해 공유됩니다.

PostgreSQL

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PostgresStore } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new PostgresStore({
    id: 'mastra-storage',
    connectionString: process.env.DATABASE_URL,
  }),
})

MongoDB

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MongoDBStore } from '@mastra/mongodb'

export const mastra = new Mastra({
  storage: new MongoDBStore({
    id: 'mastra-storage',
    uri: process.env.MONGODB_URI,
    dbName: process.env.MONGODB_DB_NAME,
  }),
})

대부분의 런타임 도메인이 동일한 데이터베이스를 공유할 수 있는 경우 인스턴스 수준 스토리지를 사용하십시오.

Agent 수준 스토리지

Agent 수준 스토리지는 Memory 인스턴스에 구성됩니다. 해당 Agent의 Memory 데이터에 대해서만 인스턴스 수준 스토리지를 재정의합니다.

src/mastra/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { PostgresStore } from '@mastra/pg'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'Answer customer support questions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new PostgresStore({
      id: 'support-agent-storage',
      connectionString: process.env.SUPPORT_AGENT_DATABASE_URL,
    }),
  }),
})

Agent에 격리된 Memory 경계나 다른 Memory 백엔드가 필요한 경우 Agent 수준 스토리지를 사용하세요.

복합 스토리지

MastraCompositeStore도메인을 다른 백엔드로 라우팅합니다. 하나의 데이터베이스가 모든 도메인에 적합하지 않을 때 사용하세요.

다음 예에서는 libSQL을 기본 저장소로 사용하고 Workflow 상태를 PostgreSQL로 라우팅합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { LibSQLStore } from '@mastra/libsql'
import { WorkflowsPG } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'default-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      workflows: new WorkflowsPG({
        connectionString: process.env.DATABASE_URL,
      }),
    },
  }),
})

observability를 전용 분석 백엔드로 라우팅할 수도 있습니다. Observability 관련 예제는 Observability 빠른 시작을 참조하세요.

지원되는 Provider

각 공급자 페이지에는 설치 지침, 구성 매개변수 및 사용 예가 포함되어 있습니다.

• libSQL
• 포스트그레SQL
• 몽고DB
• 오라클DB
• 업스태시
• 레디스
• 클라우드플레어 D1
• Cloudflare KV 및 내구성 개체
• 볼록한
• DynamoDB
• 랜스DB
• 마이크로소프트 SQL 서버
• 구글 클라우드 스패너

팁

libSQL은 별도의 데이터베이스 서버를 실행할 필요가 없기 때문에 로컬 개발을 위한 가장 빠른 경로입니다.

다음 단계

• 복합 스토리지
• 보관 유지
• 스토리지 스키마
• Memory
• 관측 가능성 저장소