한 줄 요약: Claude Developer Platform 공식 문서 "Memory tool". 메모리 도구는 Claude가 /memories 디렉터리의 파일을 만들고 읽고 고치고 지워 대화를 넘어 정보를 쌓게 하는 클라이언트 측 도구다. Claude는 파일 작업을 요청할 뿐이고, 실제 저장과 실행은 내 애플리케이션이 한다. 요청의 tools에 {"type": "memory_20250818", "name": "memory"} 한 줄을 넣으면 되고, 도구 자체는 베타 헤더가 필요 없다(SDK 도우미만 beta 네임스페이스에 있음). Claude 4 이후 모든 모델에서 쓸 수 있다. 경로 이탈(path traversal) 막기 같은 보안은 내 애플리케이션 책임이다.
원본 정보#
- 제목: Memory tool
- 발행처: Claude Developer Platform 문서(platform.claude.com)
- 원본 날짜: 문서에 표기 없음. 수집 2026-10-26. 이 페이지의 도구 타입·모델·SDK 사실은 수집일 기준이다(원본 날짜 미상).
- URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool (새 창)
- 참고: raw 파일에는 원문 자체의 머리말(title·url·description)이 출처 블록 아래에 남아 있다.
핵심 주장#
- 대화를 넘는 파일 기반 기억이다. Claude가 메모리 디렉터리의 파일을 만들고 읽고 고치고 지워, 모든 것을 컨텍스트 창에 두지 않고 시간이 지나며 지식을 쌓는다. 처음부터 다 싣지 않고 필요할 때 읽어 오는(just-in-time) 방식이라 긴 세션에서 컨텍스트를 지금 일에 집중시킨다. → 장기 작업 컨텍스트 관리
- 클라이언트 측 도구다. Claude는 파일 작업을 요청만 하고, 내 애플리케이션이 내가 관리하는 저장소에서 실행해
tool_result로 돌려준다./memories는 핸들러가 실제 저장소(사용자별 디렉터리, 데이터베이스 키 등)에 연결하는 접두 경로이고, 메모리는 전부 내 애플리케이션 안에 있다. 도구가 켜져 있으면 Claude는 작업 전에 메모리 디렉터리를 먼저 확인한다. → 장기 작업 컨텍스트 관리 - 설정은 한 줄, 베타 헤더는 필요 없다.
{"type": "memory_20250818", "name": "memory"}가 설정 전부이고(name은 반드시memory), Claude 4 이후 모든 모델에서 쓸 수 있다. Python·C#·TypeScript·Java SDK에 메모리 도우미가 있고, 원본은 "The helper and tool-runner surfaces live in your SDK's beta namespace even though the memory tool itself doesn't require a beta header"라고 쓴다. → 장기 작업 컨텍스트 관리 - 명령은 여섯 가지.
view(디렉터리·파일 보기,view_range),create,str_replace,insert,delete,rename. 핸들러가 각 명령을 구현한다. - 보안은 내 책임이다. 민감 정보(Claude는 보통 쓰기를 거부하지만 더 강한 보장이 필요하면 쓰기 전에 걸러내라), 파일 크기 상한, 오래 안 쓴 파일 삭제, 경로 이탈 막기(
/memories/../../secrets.env같은 경로가 디렉터리 밖에 닿을 수 있으니 모든 명령의 모든 경로를 검증하라). → 장기 작업 컨텍스트 관리 - 컨텍스트 편집·컴팩션과 함께 쓴다. 컨텍스트 편집은 클라이언트에서 특정 도구 결과를 지우고, 컴팩션은 서버에서 대화 전체를 요약한다. 오래 도는 에이전트는 둘 다 쓰고, 요약을 넘어 남아야 할 정보는 메모리에 두라고 권한다. → 장기 작업 컨텍스트 관리
- 여러 세션에 걸친 개발 패턴. 첫 세션(initializer)이 진행 로그·기능 체크리스트·시작 스크립트 참조를 먼저 만들고, 이후 세션은 그 파일을 읽어 시작하며, 세션이 끝나기 전에 진행 로그를 갱신한다. 한 번에 기능 하나, 끝에서 끝까지 확인한 뒤에만 완료로 표시한다. → 장기 작업 컨텍스트 관리
이전 원본과 달라진 점 (시간에 따른 변화)#
- 효과적인 컨텍스트 엔지니어링(2025-09-29)은 메모리 도구가 Sonnet 4.5 출시와 함께 Claude Developer Platform에 공개 베타로 나왔다고 썼다. 이 원본(수집 2026-10-26)은 도구 자체에 베타 헤더가 필요 없고 Claude 4 이후 모든 모델에서 쓸 수 있다고 적으며, 베타 상태 표기를 하지 않는다(SDK 도우미와 tool runner만 beta 네임스페이스). 출시 당시의 기록과 지금 상태의 차이로 보고, 장기 작업 컨텍스트 관리에 지금 상태를 앞세우고 2025년 글 문장은 이력으로 남겼다. 원본은 "정식 출시(GA)"라는 말을 쓰지 않는다.
원본에 없는 것#
- Claude Code의 메모리(CLAUDE.md, 자동 메모리)와의 관계. 이 원본은 API로 앱을 만드는 개발자용이고 Claude Code를 말하지 않는다.
- 요금, 저장 용량 한도 숫자.
원본이 링크만 한 것#
Context editing(도구 결과 지우기), Compaction(서버 측), Handle tool calls(도구 사용 루프), Text editor tool(오류 처리), API and data retention(ZDR), Tool reference, 엔지니어링 글 "Effective harnesses for long-running agents".