핵심 요약
Claude Memory Tool은 Claude가 /memories 디렉터리에 정보를 저장하고 다시 읽어, 여러 대화와 세션을 넘나들며 작업 맥락을 유지하게 해주는 도구입니다.
핵심은 "모든 정보를 한 번에 컨텍스트에 넣는 것"이 아니라, 필요할 때 기억을 찾아오는 방식으로 긴 작업을 안정적으로 이어가는 것입니다.
Memory Tool은 무엇인가
Memory Tool은 Claude가 파일을 만들고, 읽고, 수정하고, 삭제하면서 정보를 장기적으로 보관할 수 있게 하는 기능입니다.
예를 들어 고객 응대 규칙, 프로젝트 진행 상황, 반복 업무에서 배운 선호사항 등을 /memories 아래에 저장해두면, 다음 대화에서 Claude가 이를 다시 확인하고 이어서 작업할 수 있습니다.
쉽게 말해 컨텍스트 창이 "작업대"라면, Memory Tool은 "서랍장"입니다. 지금 필요한 자료만 꺼내 작업대에 올리고, 나머지는 서랍에 보관합니다.
왜 필요한가: 긴 작업에서 컨텍스트를 아끼는 방법
LLM은 한 번에 볼 수 있는 정보량, 즉 컨텍스트 창에 제한이 있습니다.
긴 프로젝트에서 모든 문서, 결정 사항, 코드 설명, 이전 대화를 계속 넣으면 금방 공간이 부족해집니다.
Memory Tool은 중요한 정보를 파일로 저장해두고, Claude가 필요할 때만 다시 읽게 만듭니다.
이 방식은 장기 프로젝트, 반복 업무, 여러 세션에 걸친 소프트웨어 개발에 특히 유용합니다.
작동 방식: Claude가 기억을 직접 요청하고 앱이 실행한다
Memory Tool은 서버에 자동으로 저장되는 기능이 아닙니다.
Claude가 "이 파일을 보여줘", "이 내용을 저장해줘" 같은 도구 호출을 하면, 실제 파일 저장과 읽기는 사용자의 애플리케이션이 처리합니다.
즉 저장 위치, 보안 방식, 백엔드 구조는 개발자가 직접 통제합니다.
파일 시스템, 데이터베이스, 클라우드 스토리지, 암호화 저장소 등 원하는 방식으로 구현할 수 있습니다.
기본 흐름: 먼저 기억을 보고, 관련 파일을 읽는다
Memory Tool이 활성화되면 Claude는 작업을 시작하기 전에 보통 /memories 디렉터리를 먼저 확인합니다.
예를 들어 사용자가 "고객 서비스 티켓 답변을 도와줘"라고 하면, Claude는 먼저 기억 저장소를 살펴보고 고객 응대 가이드나 환불 정책 같은 관련 파일을 찾습니다.
그다음 필요한 파일 내용을 읽고, 현재 요청에 맞게 답변을 작성합니다.
이 흐름 덕분에 Claude는 매번 처음부터 설명을 요구하지 않고도 이전 맥락을 활용할 수 있습니다.
사용 시작: 도구 추가와 클라이언트 핸들러 구현
Memory Tool을 쓰려면 요청에 memory 도구를 추가해야 합니다.
또한 애플리케이션 쪽에서 view, create, str_replace, insert, delete, rename 같은 명령을 실제로 처리하는 핸들러를 만들어야 합니다.
Python SDK에서는 BetaAbstractMemoryTool을 상속해 구현할 수 있고, TypeScript에서는 betaMemoryTool을 사용할 수 있습니다.
예시는 다음과 같은 형태입니다.
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-4-7",
max_tokens=2048,
messages=[
{
"role": "user",
"content": "Python 웹 스크래퍼의 timeout 오류를 디버깅해줘.",
}
],
tools=[{"type": "memory_20250818", "name": "memory"}],
)주요 명령: view, create, replace, insert
view는 디렉터리 목록이나 파일 내용을 보여주는 명령입니다.
디렉터리를 볼 때는 파일 크기와 경로를 함께 보여주고, 파일을 볼 때는 줄 번호를 붙여 반환하는 것이 권장됩니다.
create는 새 파일을 만듭니다. 이미 같은 파일이 있으면 덮어쓰지 않고 오류를 반환하는 방식이 안전합니다.
str_replace는 파일 안의 특정 문자열을 다른 문자열로 바꿉니다. 단, 바꿀 문자열이 여러 번 등장하면 어느 위치를 바꿔야 할지 모호하므로 오류를 내는 것이 좋습니다.
insert는 지정한 줄에 텍스트를 삽입합니다. 진행 로그에 새 작업 내역을 추가할 때 유용합니다.
주요 명령: delete와 rename
delete는 파일이나 디렉터리를 삭제합니다.
디렉터리를 삭제할 경우 그 안의 내용까지 재귀적으로 삭제할 수 있으므로, 구현 시 매우 신중해야 합니다.
rename은 파일이나 디렉터리 이름을 바꾸거나 위치를 옮깁니다.
목적지가 이미 존재하면 덮어쓰지 않고 오류를 반환하는 것이 권장됩니다.
이 원칙은 기억 저장소가 우발적으로 손상되는 일을 줄여줍니다.
프롬프트 설계: 기억은 자동으로 정리되게 유도해야 한다
Memory Tool을 활성화하면 Claude에게 "작업 전 항상 memory 디렉터리를 확인하라"는 취지의 지시가 포함됩니다.
또한 작업 중간에도 중요한 진행 상황, 결정, 다음 할 일을 memory에 기록하도록 유도할 수 있습니다.
하지만 방치하면 기억 파일이 지저분해질 수 있습니다.
그래서 "불필요한 파일은 만들지 말고, 기존 파일을 최신 상태로 유지하라"는 지시를 추가하는 것이 좋습니다.
예를 들어 특정 프로젝트에서는 "이 프로젝트의 설계 결정과 진행 상황만 memory에 기록하라"고 범위를 정해주는 편이 효과적입니다.
보안: /memories 밖으로 절대 나가지 못하게 하라
Memory Tool 구현에서 가장 중요한 보안 원칙은 모든 경로를 /memories 안으로 제한하는 것입니다.
악의적인 입력은 ../ 같은 경로 이동 패턴을 사용해 외부 파일에 접근하려 할 수 있습니다.
따라서 모든 경로가 /memories로 시작하는지 확인하고, 실제 경로를 정규화한 뒤에도 여전히 허용된 디렉터리 안에 있는지 검증해야 합니다.
URL 인코딩된 우회 패턴이나 운영체제별 경로 구분자도 주의해야 합니다.
Memory Tool은 "기억"이지만, 잘못 구현하면 파일 시스템 접근 도구가 될 수 있습니다.
민감 정보와 저장 용량 관리
Claude는 보통 민감 정보를 기억 파일에 저장하려 하지 않지만, 애플리케이션 차원의 검증이 필요합니다.
개인정보, 인증 토큰, 결제 정보, 의료 정보 등은 저장 전에 차단하거나 마스킹하는 정책을 둘 수 있습니다.
또한 기억 파일이 너무 커지지 않게 크기 제한을 두는 것이 좋습니다.
읽기 명령이 한 번에 반환할 수 있는 문자 수를 제한하고, Claude가 필요한 부분을 나누어 읽게 하면 컨텍스트 낭비를 줄일 수 있습니다.
오래 접근하지 않은 memory 파일을 주기적으로 정리하는 만료 정책도 도움이 됩니다.
Context Editing과 Compaction과의 조합
Memory Tool은 긴 대화 관리 기능과 함께 쓰면 더 강력해집니다.
Context Editing은 클라이언트 쪽에서 특정 도구 결과나 오래된 정보를 정리해 현재 컨텍스트를 가볍게 유지하는 방식입니다.
Compaction은 서버 쪽에서 오래된 대화 내용을 요약해 컨텍스트 한계를 넘지 않게 돕는 방식입니다.
Memory Tool은 이 둘과 다르게 중요한 정보를 세션 밖에 보존합니다.
따라서 장기 작업에서는 Compaction으로 대화를 압축하고, Memory Tool로 핵심 상태를 별도로 저장하는 조합이 안정적입니다.
장기 소프트웨어 개발에서의 패턴
긴 개발 프로젝트에서는 memory를 즉흥적으로 쓰기보다 처음부터 구조화하는 것이 좋습니다.
첫 세션에서 진행 로그, 기능 체크리스트, 실행 스크립트나 초기화 절차를 memory에 만들어둡니다.
다음 세션은 이 파일들을 먼저 읽고, 이전 상태를 빠르게 복구합니다.
세션이 끝나기 전에는 무엇을 완료했는지, 무엇이 남았는지, 다음에 어디서 시작해야 하는지를 업데이트합니다.
특히 기능은 코드 작성만으로 완료 처리하지 말고, 끝까지 검증된 뒤에만 완료로 표시해야 합니다.
그래야 다음 세션의 Claude가 잘못된 진행 상태를 믿고 엉뚱한 방향으로 가지 않습니다.
인사이트
Memory Tool의 본질은 Claude에게 "완벽한 기억력"을 주는 것이 아니라, 필요한 정보를 잘 꺼내 쓰는 작업 구조를 만드는 것입니다.
좋은 memory는 많을수록 좋은 것이 아니라, 최신이고 짧고 믿을 수 있을수록 좋습니다.
실제로 도입할 때는 /memories/progress.md, /memories/decisions.md, /memories/checklist.md처럼 역할이 분명한 파일 몇 개부터 시작하는 것이 가장 안전합니다.
출처 및 참고 : Memory tool - Claude API Docs
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.