Claude 메모리 툴 한눈에 이해하기

메모리 툴이란?

Claude의 메모리 툴은 챗봇이 대화 중에 필요한 정보를 직접 파일로 저장하고, 나중에 꺼내 사용할 수 있게 해주는 기능입니다. 대화가 길어지거나 여러 번 이어져도 필요한 정보나 이전 작업 기록을 쉽게 유지하고 확인할 수 있습니다. 저장된 파일은 모두 사용자의 컴퓨터 또는 서버에 남아있어, 완전히 사용자가 관리합니다.

어떤 역할을 하나요?

이 기능을 사용하면 Claude가 프로젝트의 진행상황, 배경지식, 고객 요청 이력, 팀 논의내용 등을 저마다 파일로 기록해둡니다. 다음에 비슷한 상황이 오면 저장해둔 내용을 바로 꺼내서, 더 똑똑하게 도움을 줄 수 있습니다. 예를 들어, 고객 문의에 답변할 때 과거 관련 지침 파일을 바로 찾아보고, 안내에 활용하는 방식입니다.

어떻게 작동하나요?

Claude는 작업을 시작할 때마다 항상 먼저 메모리 디렉터리(예: /memories 폴더)를 확인합니다. 파일 목록을 보고 필요한 정보를 읽어온 뒤, 새로운 내용이나 변화가 생기면 다시 파일로 저장합니다. 실제 파일 생성과 관리는 사용자의 앱 또는 서버가 담당하며, Claude가 요청하는 명령을 받아 처리해줍니다.

지원 모델

이 기능은 Claude Sonnet 4.x와 Opus 4.x 계열 최신 버전에서 사용할 수 있습니다. 베타 단계이므로, 특수 헤더(context-management-2025-06-27)를 API 요청에 추가해야 활성화됩니다.

주요 명령어 소개

메모리 툴은 여러 작업 명령을 지원합니다. 각각의 명령은 아래와 같이 구성됩니다.

{
  "command": "view",          // 파일 또는 폴더 내용 확인
  "path": "/memories"
}
{
  "command": "create",        // 새 파일 생성 또는 기존파일 덮어쓰기
  "path": "/memories/notes.txt",
  "file_text": "회의 내용 정리..."
}
{
  "command": "str_replace",   // 파일 내 특정 문자열 바꾸기
  "old_str": "blue",
  "new_str": "green"
}
{
  "command": "insert",        // 특정 위치에 내용을 추가
  "insert_line": 2,
  "insert_text": "추가할 내용..."
}
{
  "command": "delete",        // 파일 또는 폴더 삭제
  "path": "/memories/old_file.txt"
}
{
  "command": "rename",        // 이름 바꾸기 또는 이동
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

안전하게 사용하는 방법

메모리 툴을 쓸 때 보안이 중요합니다. 다음 지침을 꼭 지켜주세요.

저장 경로가 반드시 /memories 폴더 내여야 하며, 이 범위를 벗어나지 않도록 경로를 확인하세요.
파일 경로 이동이나.., ../ 등 위험한 패턴은 차단하세요.
민감 정보(개인정보 등)는 Claude도 원칙적으로 저장하지 않지만, 별도의 검증 로직을 추가하는 것이 좋습니다.
파일의 크기가 너무 커지지 않게 제한하세요.
오랫동안 사용하지 않은 파일은 자동으로 삭제하는 등 관리 정책을 두세요.

활용 팁

메모리 툴을 활용할 때 Claude가 폴더 및 파일을 항상 깔끔하고 최신 상태로 유지하도록 직접 안내할 수 있습니다. 예를 들어, "지금 주제와 관련 없는 내용은 지우거나 정리해 주세요"와 같이 요청하면 좋습니다. 그리고 남길 내용의 범위를 구체적으로 지정하면 더 효율적입니다.

시작 방법

API를 통해 사용할 때는 베타 헤더와 서명된 메모리 툴 옵션을 추가하세요. Claude의 SDK를 이용하면 Python, TypeScript 등 다양한 언어로 자신만의 파일 관리 방식을 구현할 수 있습니다.

예시 사용법

API를 호출할 때 다음처럼 구성합니다.

curl https://api.anthropic.com/v1/messages 
  --header "x-api-key: $ANTHROPIC_API_KEY" 
  --header "anthropic-version: 2023-06-01" 
  --header "content-type: application/json" 
  --header "anthropic-beta: context-management-2025-06-27" 
  --data '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 2048,
    "messages": [{ "role": "user", "content": "코드를 도와주세요..." }],
    "tools": [{ "type": "memory_20250818", "name": "memory" }]
  }'

실제 활용 예시

고객 응대, 프로젝트 진행 상황 기록, 작업 중단 이후 재개 등 반복적인 업무에 매우 유용합니다. 자주 쓰는 지침이나 체크리스트를 파일로 남겨두고, 필요할 때마다 Claude가 자동으로 참고하기 때문에, 더 일관된 결과를 얻을 수 있습니다.

출처 및 참고 : Memory tool - Claude Docs