메시지 기록

메시지 기록은 가장 기본적이고 중요한 기억의 형태입니다. 이는 LLM에게 컨텍스트 창에서 최근 메시지 보기를 제공하여 Agent가 이전 교환을 참조하고 일관되게 응답할 수 있도록 합니다.

메시지 기록을 검색하여 UI에 과거 대화를 표시할 수도 있습니다.

정보

각 메시지는 스레드(대화)와 리소스(연결된 사용자 또는 엔터티)에 속합니다. 자세한 내용은 스레드와 리소스를 참조하세요.

경고

클라이언트 애플리케이션에서 Memory를 사용할 때는 전체 대화 기록이 아니라 클라이언트의 새 메시지만 전달하세요. Mastra가 저장소에서 메시지를 로드하기 때문에 전체 기록을 보내는 것은 중복되며 클라이언트 측 타임스탬프가 저장된 타임스탬프와 충돌할 때 메시지 순서 버그가 발생할 수 있습니다.

AI SDK 예시는 Mastra Memory 사용하기를 참조하세요.

스레드 및 리소스

Mastra는 두 가지 식별자를 사용하여 대화를 구성합니다.

• 실: 일련의 메시지가 포함된 대화 세션입니다.
• 의지: 사용자, 조직, 프로젝트 또는 애플리케이션의 다른 도메인 엔터티와 같이 스레드를 소유하는 엔터티입니다.

Studio는 스레드 및 리소스 ID를 자동으로 생성합니다. 직접 stream() 또는 generate()를 호출할 때는 이러한 식별자를 명시적으로 제공하세요.

시작하기

데이터베이스용 스토리지 어댑터와 함께 Mastra Memory 모듈을 설치하세요. 아래 예시에서는 데이터를 로컬 mastra.db 파일에 저장하는 @mastra/libsql을 사용합니다.

npm

npm install @mastra/memory@latest @mastra/libsql@latest

pnpm

pnpm add @mastra/memory@latest @mastra/libsql@latest

Yarn

yarn add @mastra/memory@latest @mastra/libsql@latest

Bun

bun add @mastra/memory@latest @mastra/libsql@latest

메시지 기록에는 대화를 유지하기 위한 스토리지 어댑터가 필요합니다. 아직 구성하지 않은 경우 Mastra 인스턴스에 스토리지를 구성합니다.

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

Agent에서 Memory 인스턴스를 생성하세요.

src/mastra/agents/test-agent.ts

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

export const agent = new Agent({
  id: 'test-agent',
  memory: new Memory({
    options: {
      lastMessages: 10,
    },
  }),
})

Agent를 호출하면 메시지가 데이터베이스에 자동으로 저장됩니다. threadId, resourceId 및 선택적 metadata를 지정할 수 있습니다.

.generate()

await agent.generate('Hello', {
  memory: {
    thread: {
      id: 'thread-123',
      title: 'Support conversation',
      metadata: { category: 'billing' },
    },
    resource: 'user-456',
  },
})

.stream()

await agent.stream('Hello', {
  memory: {
    thread: {
      id: 'thread-123',
      title: 'Support conversation',
      metadata: { category: 'billing' },
    },
    resource: 'user-456',
  },
})

정보

agent.generate() 또는 agent.stream()을 호출하면 스레드와 메시지가 자동으로 생성되지만, createThread() 및 saveMessages()를 사용하여 직접 생성할 수도 있습니다.

이 기록은 두 가지 방법으로 사용할 수 있습니다.

• 자동 포함: Mastra는 최근 메시지를 자동으로 가져와 컨텍스트 창에 포함합니다. 기본적으로 최근 메시지 10개가 포함되어 Agent가 대화를 이어갈 수 있습니다. 이 수는 lastMessages로 조정할 수 있지만 대부분의 경우 신경 쓰지 않아도 됩니다.
• 수동 쿼리: 더 세밀하게 제어하려면 recall() 함수를 사용하여 스레드와 메시지를 직접 쿼리하세요. 컨텍스트 창에 포함할 Memory를 정확히 선택하거나 UI에 대화 기록을 렌더링할 메시지를 가져올 수 있습니다.

팁

Memory가 활성화되면 Studio는 메시지 기록을 사용하여 채팅 사이드바에 이전 대화를 표시합니다.

스레드 제목 생성

generateTitle을 활성화하면 Mastra가 대화 내용에서 설명적인 스레드 제목을 자동으로 생성할 수 있습니다. 스레드 목록이나 사이드바에 대화 제목을 표시하는 채팅 인터페이스를 만들 때 이 옵션을 사용하세요.

src/mastra/agents/support-agent.ts

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

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({
    options: {
      generateTitle: true,
    },
  }),
})

제목 생성은 Agent가 응답한 후 비동기적으로 실행되며 응답 시간에는 영향을 주지 않습니다.

비용이나 동작을 최적화하려면 더 작은 model과 사용자 지정 instructions를 제공하세요.

src/mastra/agents/support-agent.ts

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

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({
    options: {
      generateTitle: {
        model: 'openai/gpt-5-mini',
        instructions: 'Generate a one-word title.',
      },
    },
  }),
})

Memory 액세스

스레드와 메시지를 쿼리, 복제 또는 삭제하는 Memory 기능에 접근하려면 Agent에서 getMemory()를 호출하세요.

const agent = mastra.getAgentById('test-agent')
const memory = await agent.getMemory()

Memory 인스턴스를 통해 스레드 목록 조회, 메시지 회상, 대화 복제 등의 함수에 접근할 수 있습니다.

쿼리 중

UI에 대화 기록을 표시하거나 사용자 지정 Memory 검색 논리를 위해 스레드와 메시지를 가져오려면 이러한 메서드를 사용하세요.

경고

Memory 시스템은 액세스 제어를 시행하지 않습니다. 쿼리를 실행하기 전에 애플리케이션 로직에서 현재 사용자에게 액세스 권한이 있는지 확인하세요.resourceId being queried.

스레드

리소스의 스레드를 가져오려면 listThreads()를 사용하세요.

const result = await memory.listThreads({
  filter: { resourceId: 'user-123' },
  perPage: false,
})

스레드를 통해 페이지를 매깁니다.

const result = await memory.listThreads({
  filter: { resourceId: 'user-123' },
  page: 0,
  perPage: 10,
})

console.log(result.threads) // thread objects
console.log(result.hasMore) // more pages available?

메타데이터로 필터링하고 정렬 순서를 제어할 수도 있습니다.

const result = await memory.listThreads({
  filter: {
    resourceId: 'user-123',
    metadata: { status: 'active' },
  },
  orderBy: { field: 'createdAt', direction: 'DESC' },
})

ID로 단일 스레드를 가져오려면 다음을 사용하세요.getThreadById():

const thread = await memory.getThreadById({ threadId: 'thread-123' })

메시지

스레드가 있으면 recall()을 사용하여 메시지를 가져오세요. 페이지네이션, 날짜 필터링 및 의미 검색을 지원합니다. 기본 회수는 스레드의 모든 메시지를 반환합니다.

const { messages } = await memory.recall({
  threadId: 'thread-123',
  perPage: false,
})

메시지 페이지 매기기:

const { messages } = await memory.recall({
  threadId: 'thread-123',
  page: 0,
  perPage: 50,
})

날짜 범위별로 필터링:

const { messages } = await memory.recall({
  threadId: 'thread-123',
  filter: {
    dateRange: {
      start: new Date('2025-01-01'),
      end: new Date('2025-06-01'),
    },
  },
})

얕은 메시지 메타데이터로 필터링:

const { messages } = await memory.recall({
  threadId: 'thread-123',
  filter: {
    metadata: {
      category: 'billing',
      escalated: true,
      priority: 2,
      archivedAt: null,
    },
  },
})

메타데이터 필터는 string, 유한한 number, boolean, null과 같은 얕은 스칼라 값만 일치시킵니다. 지정된 모든 메타데이터 키에는 AND 의미 체계가 적용됩니다. null 필터는 명시적인 null 값에만 일치합니다. 존재하지 않는 메타데이터 키는 일치하지 않습니다. 메타데이터 키는 문자나 밑줄로 시작해야 하며 영숫자와 밑줄만 포함할 수 있습니다. 길이는 128자 이하여야 하며 __proto__, constructor, prototype 같은 예약된 프로토타입 키는 사용할 수 없습니다. 성능은 스토리지 백엔드에 따라 다릅니다. 일부 백엔드는 필터의 일부를 데이터베이스로 푸시할 수 있지만, 다른 백엔드는 스레드, 리소스, 날짜 제약 조건을 적용한 후 페이지 매김 전에 후보 메시지를 검색합니다. ID로 단일 메시지를 가져옵니다.

const { messages } = await memory.recall({
  threadId: 'thread-123',
  include: [{ id: 'msg-123' }],
})

주변 컨텍스트와 함께 ID별로 여러 메시지를 가져옵니다.

const { messages } = await memory.recall({
  threadId: 'thread-123',
  include: [
    { id: 'msg-123' },
    {
      id: 'msg-456',
      withPreviousMessages: 3,
      withNextMessages: 1,
    },
  ],
})

의미 검색을 사용하는 경우(설정 방법은 의미 회상 참조):

const { messages } = await memory.recall({
  threadId: 'thread-123',
  vectorSearchString: 'project deadline discussion',
  threadConfig: {
    semanticRecall: true,
  },
})

UI 형식

메시지 쿼리는 MastraDBMessage[] 형식을 반환합니다. 프런트엔드에 메시지를 표시하려면 UI 라이브러리가 요구하는 형식으로 변환해야 할 수 있습니다. 예를 들어 toAISdkV5Messages는 메시지를 AI SDK UI 형식으로 변환합니다.

스레드 복제

스레드 복제는 해당 메시지와 함께 기존 스레드의 복사본을 만듭니다. 이는 잠재적으로 파괴적인 작업 전에 대화를 분기하거나 체크포인트를 생성하거나 대화의 변형을 테스트하는 데 유용합니다.

const { thread, clonedMessages } = await memory.cloneThread({
  sourceThreadId: 'thread-123',
  title: 'Branched conversation',
})

복제되는 메시지를 필터링(개수 또는 날짜 범위 기준)하고, 사용자 정의 스레드 ID를 지정하고, 유틸리티 방법을 사용하여 복제 관계를 검사할 수 있습니다.

전체 API는 cloneThread() 및 복제 유틸리티를 참조하세요.

메시지 삭제

스레드에서 메시지를 제거하려면 deleteMessages()를 사용하세요. 메시지 ID로 삭제하거나 스레드의 모든 메시지를 지울 수 있습니다.