에이전트를 만들다 보면 매번 같은 걸 다시 알려주는 게 슬슬 지친다. "나는 타입스크립트 쓰고, 들여쓰기는 2칸, 커밋 메시지는 한글로"를 대화가 바뀔 때마다 반복하는 거다. LLM은 기본적으로 세션이 끝나면 다 잊는다. 컨텍스트 윈도우 안에 있던 내용은 대화가 끝나는 순간 증발한다.
프롬프트에 매번 프로필을 통째로 끼워 넣는 방법도 있긴 한데, 늘어날수록 토큰이 아깝고 관리도 번거롭다. 그래서 Claude의 memory 도구를 붙였다.
기억을 파일로 남긴다
memory는 Claude가 /memories 디렉토리에 파일을 읽고 쓰게 해주는 도구다. 핵심은 저장 위치가 내 쪽이라는 점이다. Claude는 "이 파일 만들어줘", "여기 한 줄 바꿔줘" 같은 명령만 내리고, 실제 파일 조작은 내가 구현한다. 그래서 대화가 끝나도 파일은 내 디스크(혹은 DB)에 그대로 남는다.
tools 배열에 선언만 하면 된다. 도구 실행 결과를 다시 넘겨주는 흐름은 여느 tool use와 똑같다.
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
const response = await client.beta.messages.create({
model: 'claude-sonnet-5',
max_tokens: 2048,
betas: ['context-management-2025-06-27'],
tools: [{ type: 'memory_20250818', name: 'memory' }],
messages: [
{ role: 'user', content: '나 이제부터 커밋 메시지는 한글로 써. 기억해둬.' },
],
});
// Claude가 memory 도구로 { command: 'create', path: '/memories/user.md', ... } 요청
// → 내가 실제 파일에 써주고 결과를 tool_result로 되돌려준다
Claude가 내리는 명령은 view, create, str_replace, insert, delete, rename 정도다. 각 명령에 맞춰 파일을 조작하는 핸들러만 짜두면, 다음 대화에서 Claude가 알아서 /memories를 먼저 훑어보고 필요한 맥락을 꺼내 쓴다.
실전 팁
- 경로를 가둬라.
path가 항상/memories아래인지 꼭 검증하자. 안 그러면 경로 조작으로 엉뚱한 파일을 건드릴 수 있다. - 사용자별로 격리하자. 멀티 유저라면 유저마다 memory 디렉토리를 분리해야 남의 기억이 섞이지 않는다.
- 컨텍스트 편집과 궁합이 좋다. 긴 대화에서 오래된 도구 결과를 잘라내도, 중요한 건 memory에 적어두면 살아남는다.
매번 프로필을 붙여넣던 걸 파일 몇 개로 옮기니, 두 번째 대화부터는 "아까 말한 그대로"가 그냥 됐다. 사람한테 메모장 하나 쥐여준 것뿐인데 말이다.