목차
Claude 가이드 - 이 글은 시리즈의 일부입니다.
이 글은 Claude API 공식 문서의 Memory tool 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool 마지막 확인: 2026-05-27
1. 한 줄 요약 #
메모리 도구는 Claude가 대화 사이에 배운 내용을 작은 파일로 적어두고, 다음에 다시 꺼내 쓰는 메모장입니다.
2. 무엇이고 왜 좋을까 #
단골 카페 사장님이 “오늘도 아메리카노 따뜻하게요?“라고 먼저 물어보는 것과 같습니다.
Claude는 원래 대화가 끝나면 모든 걸 잊습니다. 새로 대화를 시작하면 “처음 뵙겠습니다” 상태로 돌아갑니다. 그래서 같은 자료, 같은 취향, 같은 규칙을 매번 다시 알려줘야 했죠.
메모리 도구는 이걸 해결합니다. Claude가 “이건 다음에도 필요하겠다” 싶은 내용을 /memories 라는 폴더에 작은 파일로 저장해두고, 다음 대화가 시작될 때 자동으로 그 폴더를 먼저 들여다봅니다.
핵심 수치 하나만 기억하세요. Claude는 새 대화를 시작할 때마다 자동으로 메모리 폴더를 가장 먼저 확인합니다. 따로 “예전 메모 좀 봐줘"라고 부탁하지 않아도 됩니다.
3. 이런 상황에서 써요 #
상황 1: 매번 자기소개를 다시 하지 않아도 되는 학생 #
대학원생인 A는 매일 Claude와 논문을 함께 읽습니다. 그런데 매번 “저는 분자생물학 전공이고, 학부 때 통계는 한 학기만 들었어요"부터 다시 설명해야 했죠.
메모리 도구를 켜두면 Claude가 첫 대화에서 들은 전공·배경·관심 분야를 메모장에 적어둡니다. 다음 날 새로 시작해도 “지난번에 단백질 구조 쪽 관심 있다고 하셨는데, 이번 논문도 그쪽이네요"라고 먼저 짚어줍니다. 매일 5분씩 자기소개에 쓰던 시간이 사라집니다.
상황 2: 회사 매뉴얼을 외워두는 챗봇 #
고객 문의를 처리하는 B씨의 회사에는 환불 정책, 응대 가이드라인, 자주 묻는 질문 모음이 있습니다. 메모리 도구가 없을 때는 매 대화마다 이 자료를 처음부터 다시 첨부했습니다.
이제는 한 번만 메모리에 정리해두면 됩니다. 새 문의가 들어와도 Claude는 먼저 메모장을 펼쳐 “환불 정책 파일에 따르면 7일 이내는 무조건 가능하네요"라고 스스로 참고해서 답합니다. 직원이 매번 같은 첨부파일을 끌어올 필요가 없습니다.
상황 3: 긴 책 한 권을 천천히 읽는 일반 독자 #
C씨는 두꺼운 역사책을 한 달에 걸쳐 Claude와 함께 읽고 있습니다. 1장에서 등장한 인물이 5장에서 다시 나오는데, 매번 “그 사람 누구였더라?“가 반복됐죠.
메모리 도구를 쓰면 Claude가 책을 읽어가면서 “1장에서 등장한 인물 정리”, “지금까지 나온 주요 사건” 같은 메모를 폴더에 차곡차곡 쌓습니다. 일주일 뒤에 다시 책을 펼쳐도 Claude는 그 메모를 먼저 읽고 “지난번까지 3장 중반이었고, 주인공은 이런 갈등에 빠져 있었죠"라고 자연스럽게 이어줍니다.
4. 가볍게 시작하기 #
💻 개발 경험 있으신가요? 아래 코드는 Python(파이썬, 컴퓨터에게 일을 시킬 때 쓰는 언어) 기준 가장 짧은 예시입니다. 비개발자라면 “이런 식으로 켜는구나” 정도로 보고 넘어가셔도 좋습니다. 메모리 도구는 한 줄 추가로 켜집니다.
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-4-7",
max_tokens=2048,
# ↓ 이 한 줄이 메모리 기능을 켭니다
tools=[{"type": "memory_20250818", "name": "memory"}],
messages=[{
"role": "user",
"content": "제가 작업 중인 프로젝트 진행 상황을 도와주세요."
}],
)
print(message)tools 칸에 메모리 도구를 등록하기만 하면 Claude가 알아서 “어, 메모장이 있네?” 하고 새 대화 시작 시 폴더를 먼저 들여다봅니다. 단, 실제로 파일을 저장하고 읽어오는 일은 사용자의 컴퓨터(또는 서버) 쪽에서 처리해야 합니다. 이걸 “클라이언트 측 도구"라고 부르는데, 쉽게 말해 “메모장 자체는 내 책상 위에 둔다"는 뜻입니다. 공식 예제(examples/memory/basic.py)를 가져다 쓰면 가장 빠릅니다.
5. 흔한 오해와 함정 #
⚠️ 함정 1: “한 번만 켜두면 알아서 다 기억해주겠지?” #
메모리 도구는 자동으로 모든 걸 적어주는 마법이 아닙니다. Claude가 “이건 다음에도 쓸 만하다"고 판단할 때 메모장에 적어둡니다. 처음 켰을 때는 폴더가 텅 비어 있는 게 정상이에요. 몇 번 대화하면서 자연스럽게 쌓입니다. “왜 아무것도 안 적혔지?” 싶으면 “이 내용은 메모에 남겨주세요"라고 한 번 부탁해보세요.
⚠️ 함정 2: “내 비밀번호도 알아서 기억해주려나?” #
❌ 카드 번호, 비밀번호, 주민등록번호 같은 민감 정보를 적어두는 건 위험합니다.
✅ Claude는 보통 이런 정보를 메모에 쓰는 걸 거부하지만, 메모장은 결국 컴퓨터에 저장되는 파일이라서 누가 접근할 수도 있습니다. 메모리 폴더는 “잊혀도 괜찮은 메모"만 두는 곳이라고 생각하세요. 중요한 정보는 따로 안전한 곳에 보관해야 합니다.
⚠️ 함정 3: “메모가 쌓이다 보면 너무 어수선해지지 않을까?” #
맞습니다. Claude가 새 파일을 자꾸 만들면 폴더가 금방 어수선해집니다. 이럴 때는 “메모장을 항상 깔끔하게 정리해주세요. 필요 없는 파일은 지우거나 이름을 바꿔주세요"라는 한 줄 안내를 시스템 프롬프트에 넣어두세요. Claude가 알아서 정리정돈을 합니다. 가끔은 직접 폴더를 열어 오래된 파일을 삭제해주는 것도 좋습니다.
6. 한 단계 더 (관심 있는 분만) #
🎯 여기까지 오신 분 환영합니다. 이 섹션은 더 깊이 알고 싶은 분을 위한 보너스입니다. 본문만 읽으셔도 충분합니다.
메모리 도구는 비슷한 자매 기능과 짝을 지어 쓰면 더 강해집니다. 짧게 비교해드릴게요.
| 기능 | 무엇을 하는가 | 언제 좋은가 |
|---|---|---|
| 메모리 도구 | 대화가 끝나도 남는 메모장 | 다음 대화에서도 정보를 이어가고 싶을 때 |
| 프롬프트 캐시 | 같은 대화 안에서 같은 자료 재사용 | 한 대화에서 긴 자료를 여러 번 참고할 때 |
| 컴팩션(Compaction) | 길어진 대화를 요약해 압축 | 대화가 너무 길어져 끊길 위험이 있을 때 |
특히 긴 작업을 여러 날에 걸쳐 할 때는 메모리 + 컴팩션 조합이 든든합니다. 컴팩션은 한 대화가 너무 길어지면 자동으로 요약해주고, 메모리는 그 요약마저 잊지 않도록 따로 적어둡니다. 마치 회의록을 정리해서 캐비닛에 넣어두는 것과 같습니다.
또 하나, 메모리 도구를 켤 때 Claude는 자동으로 “어떤 일을 시작하기 전에 항상 메모장을 먼저 보세요"라는 안내를 받습니다. 그래서 새 대화 첫 마디부터 Claude가 폴더를 열어보는 모습을 볼 수 있어요. 이게 어색하지 않고, 오히려 “아, 진짜로 기억하고 있구나"라는 신호입니다.
7. 한 마디 #
처음엔 “메모장? 그게 뭐 그렇게 대단해?” 싶을 수 있습니다. 그런데 막상 며칠 써보면 “어, Claude가 나를 알아본다"는 느낌이 들기 시작합니다. 같은 설명을 다시 하지 않아도 되고, 어제 멈춘 자리에서 자연스럽게 이어집니다.
혹시 잘 안 되더라도 너무 걱정하지 마세요. 대부분은 함정 1~3 중 하나입니다 — 폴더가 비어 있어서, 민감 정보라 거절당해서, 또는 메모가 쌓이다 정리가 필요해서. 한 줄씩 점검해보면 금방 풀립니다.
다음 글에서는 Claude 가이드 #18 — Bash 도구를 소개합니다. Claude가 컴퓨터 명령어를 직접 실행해서 일을 처리하게 해주는 도구예요. 메모리 도구와 짝을 이루면 “어제 하던 작업, 이어서 해줘"가 진짜 가능해집니다. 천천히 함께 가요.
Claude API 공식 문서를 한국어로 풀어쓴 시리즈입니다. 원문 정확성이 가장 우선, 의역과 친근함은 그 위에서.
