Mastra 메모리 개요

메모리는 에이전트가 사용할 수 있는 컨텍스트를 관리하는 방법으로, 모든 채팅 메시지를 컨텍스트 윈도우로 압축한 것입니다.

컨텍스트 윈도우

컨텍스트 윈도우는 특정 시점에 언어 모델이 볼 수 있는 총 정보입니다.

Mastra에서 컨텍스트는 세 부분으로 나뉩니다: 시스템 지침과 사용자에 대한 정보(작업 메모리), 최근 메시지(메시지 기록), 그리고 사용자의 쿼리와 관련된 오래된 메시지(의미적 회상, semantic recall).

작업 메모리는 다양한 범위에서 지속될 수 있습니다 - 대화 스레드별(기본값) 또는 동일한 사용자의 모든 스레드에 걸쳐(리소스 범위), 대화 간에 컨텍스트를 기억하는 지속적인 사용자 프로필을 가능하게 합니다.

또한 컨텍스트가 너무 길 경우 컨텍스트를 줄이거나 정보를 제거하는 메모리 프로세서를 제공합니다.

빠른 시작

메모리가 작동하는 모습을 보는 가장 빠른 방법은 내장된 개발 플레이그라운드를 사용하는 것입니다.

아직 하지 않았다면, 메인 시작하기 가이드에 따라 새 Mastra 프로젝트를 생성하세요.

메모리 패키지를 설치합니다:

npm install @mastra/memory@latest

에이전트를 생성하고 Memory 인스턴스를 연결합니다:

src/mastra/agents/index.ts:

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { openai } from "@ai-sdk/openai";
import { LibSQLStore } from "@mastra/libsql";
 
// 지속성을 위해 LibSQLStore로 메모리 초기화
const memory = new Memory({
  storage: new LibSQLStore({
    url: "file:../mastra.db", // 또는 데이터베이스 URL
  }),
});
 
export const myMemoryAgent = new Agent({
  name: "MemoryAgent",
  instructions: "...",
  model: openai("gpt-4o"),
  memory,
});

개발 서버를 시작합니다:

npm run dev

플레이그라운드(http://localhost:4111)를 열고 MemoryAgent를 선택합니다:

몇 개의 메시지를 보내고 에이전트가 대화 간에 정보를 기억하는 것을 확인해보세요:

➡️ 사용자: 내가 좋아하는 색깔은 파란색이야.

⬅️ 에이전트: 알겠습니다! 당신이 좋아하는 색깔이 파란색이라는 걸 기억하겠습니다.

➡️ 사용자: 내가 좋아하는 색깔이 뭐야?

⬅️ 에이전트: 당신이 좋아하는 색깔은 파란색입니다.

메모리 스레드

Mastra는 메모리를 스레드로 구성하며, 이는 두 개의 식별자를 사용하여 특정 대화 기록을 식별하는 레코드입니다:

threadId: 전역적으로 고유한 대화 ID (예: support_123). 스레드 ID는 모든 리소스에서 고유해야 합니다.
resourceId: 각 스레드를 소유하는 사용자 또는 엔티티 ID (예: user_123, org_456).

resourceId는 리소스 범위 작업 메모리에 특히 중요하며, 동일한 사용자의 모든 대화 스레드에서 메모리가 지속되도록 합니다.

const response = await myMemoryAgent.stream("안녕하세요, 제 이름은 Alice입니다.", {
  resourceId: "user_alice",
  threadId: "conversation_123",
});

중요: 이러한 ID가 없으면 메모리가 올바르게 구성되어 있어도 에이전트가 메모리를 사용하지 않습니다. 플레이그라운드는 이를 자동으로 처리하지만, 애플리케이션에서 메모리를 사용할 때는 직접 ID를 추가해야 합니다.

스레드 ID 고유성: 각 스레드 ID는 모든 리소스에서 전역적으로 고유해야 합니다. 스레드는 이를 생성한 리소스와 영구적으로 연결됩니다. 서로 다른 리소스에 대해 유사한 스레드 이름이 필요한 경우(예: 여러 사용자를 위한 "general" 스레드), 스레드 ID에 리소스 ID를 포함하세요: ${resourceId}-general 또는 user_alice_general.

스레드 제목 생성

Mastra는 사용자의 첫 번째 메시지를 기반으로 대화 스레드에 대한 의미 있는 제목을 자동으로 생성할 수 있습니다. 이는 애플리케이션 UI에서 대화를 정리하고 식별하는 데 도움이 됩니다.

const memory = new Memory({
  options: {
    threads: {
      generateTitle: true, // 자동 제목 생성 활성화
    },
  },
});

기본적으로 제목 생성은 에이전트와 동일한 모델과 기본 지침을 사용합니다. 사용자 정의나 비용 최적화를 위해 제목 생성 전용으로 다른 모델을 지정하거나 사용자 정의 지침을 제공할 수 있습니다:

const memory = new Memory({
  options: {
    threads: {
      generateTitle: {
        model: openai("gpt-4.1-nano"), // 제목용으로 더 저렴한 모델 사용
        instructions: "첫 번째 사용자 메시지를 기반으로 이 대화의 간결한 제목을 생성하세요.",
      },
    },
  },
});

제목 생성은 에이전트가 응답한 후 비동기적으로 발생하므로 응답 시간에 영향을 주지 않습니다. 더 자세한 내용과 예제는 전체 구성 참조를 확인하세요.

대화 기록

기본적으로 Memory 인스턴스는 각 새 요청에서 현재 Memory 스레드의 마지막 10개 메시지를 포함합니다. 이는 에이전트에게 즉각적인 대화 컨텍스트를 제공합니다.

const memory = new Memory({
  options: {
    lastMessages: 10,
  },
});

중요: 각 에이전트 호출에서는 가장 새로운 사용자 메시지만 보내세요. Mastra가 필요한 기록을 검색하고 주입하는 것을 처리합니다. 전체 기록을 직접 보내면 중복이 발생합니다. useChat 프론트엔드 훅을 사용할 때 이를 처리하는 방법은 AI SDK 메모리 예제를 참조하세요.

저장소 구성

대화 기록은 메시지를 저장하기 위해 저장소 어댑터에 의존합니다. 기본적으로 메인 Mastra 인스턴스에 제공된 동일한 저장소를 사용합니다.

Memory 인스턴스나 Mastra 객체 모두 저장소 제공업체를 지정하지 않으면, Mastra는 애플리케이션 재시작이나 배포 간에 메모리 데이터를 지속하지 않습니다. 로컬 테스팅을 넘어선 모든 배포에서는 Mastra에서 또는 new Memory() 내에서 직접 자체 저장소 구성을 제공해야 합니다.

Mastra 인스턴스에 저장소가 제공되면 에이전트에 연결된 모든 Memory에서 자동으로 사용됩니다. 이 경우 에이전트별 재정의를 원하지 않는 한 new Memory()에 저장소를 전달할 필요가 없습니다.

import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { LibSQLStore } from "@mastra/libsql";
 
const agent = new Agent({
  memory: new Memory({
    storage: new LibSQLStore({
      url: "file:./local.db",
    }),
  }),
});

저장소 코드 예제:

검색된 메시지 보기

Mastra 배포에서 추적이 활성화되고 메모리가 lastMessages 및/또는 semanticRecall로 구성된 경우, 에이전트의 추적 출력은 컨텍스트를 위해 검색된 모든 메시지를 보여줍니다. - 최근 대화 기록과 의미적 회상(semantic recall)을 통해 회상된 메시지 모두 포함.

이는 디버깅, 에이전트 결정 이해, 그리고 에이전트가 각 요청에 대해 올바른 정보를 검색하고 있는지 확인하는 데 도움이 됩니다.

추적 활성화 및 구성에 대한 자세한 내용은 추적을 참조하세요.

다음 단계

이제 핵심 개념을 이해했으므로, Mastra 에이전트에 RAG 메모리를 추가하는 방법을 배우기 위해 의미적 회상(semantic recall)으로 계속 진행하세요.

또는 사용 가능한 옵션에 대한 구성 참조를 방문하거나 사용 예제를 둘러볼 수 있습니다.

2025년 7월 26일 기준 번역
by dongne.lab@gmail.com

메모리(Memory) 개요