에이전트 메모리

에이전트 메모리 (Memory)

메모리는 에이전트가 정보를 저장하고 나중에 꺼내 쓰는 능력입니다. 메모리가 없으면 매 대화가 처음부터 시작되지만, 메모리가 있으면 시간이 지나며 문맥을 쌓고 이전 상호작용을 회상해 사용자에게 맞춰 적응합니다. AI SDK로 메모리를 넣는 방법은 세 가지로, 각기 '구현 노력·유연성·provider 종속(Lock-in)' 트레이드오프가 다릅니다.

출처: 공식문서

본문

세 가지 접근 비교

접근 노력 유연성 Provider 종속
Provider 정의 도구 낮음 중간 있음
메모리 Provider 낮음 낮음 메모리 provider에 따라 다름
커스텀 도구 높음 높음 없음

Provider 정의 도구 (Provider-Defined Tools)

provider가 도구의 inputSchema와 description을 지정하고, 우리가 execute 함수만 제공하는 방식입니다. 모델이 이 도구를 쓰도록 학습되어 커스텀 도구보다 성능이 좋을 수 있습니다.

예: Anthropic Memory Tool은 Claude에 /memories 디렉터리를 관리하는 구조화 인터페이스를 줍니다. Claude는 작업 전 메모리를 읽고, 작업하며 파일을 만들고·갱신하고, 이후 대화에서 참조합니다. 도구는 view, create, str_replace, insert, delete, rename 같은 구조화 커맨드(command)를 받고, 각각 /memories에 스코프된 path를 가집니다. execute에서 이를 파일시스템·DB 등 우리 저장소에 매핑합니다.

import { anthropic } from '@ai-sdk/anthropic';
import { ToolLoopAgent } from 'ai';
const memory = anthropic.tools.memory_20250818({
  execute: async action => {
    // action은 command, path 등을 담음 — 저장소 구현
    return 'result';
  },
});
const agent = new ToolLoopAgent({
  model: 'anthropic/claude-haiku-4.5', tools: { memory },
});
const result = await agent.generate({
  prompt: 'Remember that my favorite editor is Neovim',
});

최소 구현 노력으로 메모리를 원하고 이미 Anthropic 모델을 쓴다면 이 방식이 적합합니다. 단, 이 도구는 Claude에서만 동작하므로 provider 종속이 생깁니다.

메모리 Provider (Memory Providers)

메모리가 내장된 provider를 쓰는 방식입니다. 외부 메모리 서비스를 감싸 AI SDK 표준 인터페이스로 노출하며, 저장·검색·주입이 투명하게 일어나고 우리가 도구를 정의할 필요가 없습니다. 대표 예: Letta(지속 장기 메모리, @letta-ai/vercel-ai-sdk-provider), Mem0, Supermemory, Hindsight, MongoDB 등. Letta는 Letta 플랫폼(클라우드·셀프호스팅)에 에이전트를 만들어 메모리를 설정하고, AI SDK provider로 상호작용하며 런타임이 메모리 관리(코어·아카이브·회상)를 처리합니다. MongoDB 메모리는 isLoopFinished()로 자연스러운 종료까지 에이전트를 돌릴 수 있고(memory 도구가 최종 응답 전 읽기·쓰기를 해야 할 때 유용), 세션 메모리는 tool-driven(LLM이 읽기·쓰기 결정, 프로토타입용)과 hook-driven(prepareCall+onEnd 훅으로 매 턴 영속화, 프로덕션 권장) 두 모드를 지원합니다. 단점: provider가 메모리 동작을 통제해 무엇이 저장되고 어떻게 검색되는지 가시성이 낮고, 외부 서비스 의존성이 생깁니다.

pnpm add @letta-ai/vercel-ai-sdk-provider

import { lettaCloud } from '@letta-ai/vercel-ai-sdk-provider';
import { ToolLoopAgent } from 'ai';
const agent = new ToolLoopAgent({
  model: lettaCloud(),
  providerOptions: { letta: { agent: { id: 'your-agent-id' } } },
});
const result = await agent.generate({ prompt: 'Remember that my favorite editor is Neovim' });

커스텀 도구 (Custom Tool)

메모리 도구를 처음부터 직접 만드는 가장 유연한 접근입니다. 저장 형식·인터페이스·검색 로직을 모두 통제하고, provider 종속도 외부 의존성도 없습니다. 다만 가장 많은 초기 작업이 필요합니다. 두 가지 일반 패턴이 있습니다.

  • 구조화 액션: view/create/update/search 같은 명시적 연산을 정의하고 구조화 입력을 직접 처리. 모든 연산을 통제하므로 기본적으로 안전.
  • Bash 기반: 모델에게 샌드박스 bash 환경을 줘 cat/grep/sed/echo 같은 셸 커맨드로 유연하게 메모리에 접근. 강력하지만 안전을 위해 커맨드 검증이 필요.

bash 백엔드·AST 기반 커맨드 검증·파일시스템 영속화를 갖춘 커스텀 메모리 도구 전체 구현은 Build a Custom Memory Tool 레시피를 참고합니다.

더 알아보기