메모리 도구는 Claude가 메모리 파일 디렉토리를 통해 대화 간에 정보를 저장하고 검색할 수 있게 해줍니다. Claude는 세션 간에 지속되는 파일을 생성, 읽기, 업데이트, 삭제할 수 있어 컨텍스트 창에 모든 것을 유지하지 않고도 시간이 지남에 따라 지식을 구축할 수 있습니다. 메모리 도구는 클라이언트 측에서 작동합니다—사용자가 자신의 인프라를 통해 데이터가 저장되는 위치와 방법을 제어합니다.
메모리 도구는 현재 베타 버전입니다. 이를 활성화하려면 API 요청에서 베타 헤더 context-management-2025-06-27을 사용하세요.이 기능에 대한 피드백을 공유하려면 피드백 양식을 통해 연락해 주세요.

​
사용 사례

  • 여러 에이전트 실행 간에 프로젝트 컨텍스트 유지
  • 과거 상호작용, 결정, 피드백으로부터 학습
  • 시간이 지남에 따라 지식 베이스 구축
  • Claude가 반복되는 워크플로우에서 개선되는 대화 간 학습 활성화

​
작동 방식

활성화되면 Claude는 작업을 시작하기 전에 자동으로 메모리 디렉토리를 확인합니다. Claude는 /memories 디렉토리에서 파일을 생성, 읽기, 업데이트, 삭제하여 작업하면서 학습한 내용을 저장한 다음, 향후 대화에서 해당 메모리를 참조하여 유사한 작업을 더 효과적으로 처리하거나 중단한 지점부터 다시 시작할 수 있습니다. 이것은 클라이언트 측 도구이므로 Claude는 메모리 작업을 수행하기 위해 도구 호출을 하고, 애플리케이션이 해당 작업을 로컬에서 실행합니다. 이를 통해 메모리가 저장되는 위치와 방법을 완전히 제어할 수 있습니다. 보안을 위해 모든 메모리 작업을 /memories 디렉토리로 제한해야 합니다.

​
예시: 메모리 도구 호출 작동 방식

Claude에게 작업 도움을 요청하면 Claude는 자동으로 먼저 메모리 디렉토리를 확인합니다. 일반적인 상호작용은 다음과 같습니다: 1. 사용자 요청: 
"이 고객 서비스 티켓에 응답하는 것을 도와주세요."
2. Claude가 메모리 디렉토리를 확인: 
"고객 서비스 티켓에 응답하는 것을 도와드리겠습니다. 이전 컨텍스트가 있는지 메모리를 확인해보겠습니다."
Claude가 메모리 도구를 호출: 
{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}
3. 애플리케이션이 디렉토리 내용을 반환: 
{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Directory: /memories\n- customer_service_guidelines.xml\n- refund_policies.xml"
}
4. Claude가 관련 파일을 읽음: 
{
  "type": "tool_use",
  "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories/customer_service_guidelines.xml"
  }
}
5. 애플리케이션이 파일 내용을 반환: 
{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- Use empathetic language\n..."
}
6. Claude가 메모리를 사용하여 도움: 
"고객 서비스 가이드라인을 바탕으로 응답을 작성하는 것을 도와드릴 수 있습니다. 티켓 세부사항을 공유해 주세요..."

​
지원되는 모델

메모리 도구는 다음에서 사용할 수 있습니다:
  • Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)

​
시작하기

메모리 도구를 사용하려면:
  1. API 요청에 베타 헤더 context-management-2025-06-27을 포함
  2. 요청에 메모리 도구 추가
  3. 메모리 작업을 위한 클라이언트 측 핸들러 구현
애플리케이션에서 메모리 도구 작업을 처리하려면 각 메모리 명령에 대한 핸들러를 구현해야 합니다. 저희 SDK는 도구 인터페이스를 처리하는 메모리 도구 헬퍼를 제공합니다—BetaAbstractMemoryTool(Python)을 서브클래스화하거나 betaMemoryTool(TypeScript)을 사용하여 자신만의 메모리 백엔드(파일 기반, 데이터베이스, 클라우드 스토리지, 암호화된 파일 등)를 구현할 수 있습니다.작동 예시는 다음을 참조하세요:

​
기본 사용법

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": "타임아웃 오류로 계속 충돌하는 Python 웹 스크래퍼를 작업하고 있습니다. 문제가 있는 함수는 다음과 같습니다:\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\n이것을 디버그하는 것을 도와주세요."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

​
도구 명령

클라이언트 측 구현에서는 다음 메모리 도구 명령을 처리해야 합니다:

​
view

선택적 라인 범위와 함께 디렉토리 내용 또는 파일 내용을 표시: 
{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // 선택사항: 특정 라인 보기
}

​
create

파일 생성 또는 덮어쓰기: 
{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "회의 노트:\n- 프로젝트 일정 논의\n- 다음 단계 정의\n"
}

​
str_replace

파일의 텍스트 교체: 
{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "좋아하는 색상: 파란색",
  "new_str": "좋아하는 색상: 초록색"
}

​
insert

특정 라인에 텍스트 삽입: 
{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- 메모리 도구 문서 검토\n"
}

​
delete

파일 또는 디렉토리 삭제: 
{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

​
rename

파일/디렉토리 이름 변경 또는 이동: 
{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

​
프롬프팅 가이드

메모리 도구가 포함될 때 시스템 프롬프트에 자동으로 다음 지침을 포함합니다: 
중요: 다른 모든 작업을 수행하기 전에 항상 메모리 디렉토리를 확인하세요.
메모리 프로토콜:
1. `memory` 도구의 `view` 명령을 사용하여 이전 진행 상황을 확인하세요.
2. ... (작업 수행) ...
     - 진행하면서 상태 / 진행 상황 / 생각 등을 메모리에 기록하세요.
중단 가정: 컨텍스트 창이 언제든지 재설정될 수 있으므로 메모리 디렉토리에 기록되지 않은 진행 상황을 잃을 위험이 있습니다.
Claude가 어수선한 메모리 파일을 생성하는 것을 관찰하면 다음 지침을 포함할 수 있습니다:
참고: 메모리 폴더를 편집할 때는 항상 내용을 최신 상태로 유지하고 일관성 있고 체계적으로 관리하세요. 더 이상 관련이 없는 파일은 이름을 변경하거나 삭제할 수 있습니다. 필요하지 않은 한 새 파일을 생성하지 마세요.
Claude가 메모리에 무엇을 쓸지 안내할 수도 있습니다. 예: “메모리 시스템에는 <주제>와 관련된 정보만 기록하세요.”

​
보안 고려사항

메모리 저장소를 구현할 때 중요한 보안 고려사항은 다음과 같습니다:

​
민감한 정보

Claude는 일반적으로 메모리 파일에 민감한 정보를 기록하는 것을 거부합니다. 그러나 잠재적으로 민감한 정보를 제거하는 더 엄격한 검증을 구현할 수 있습니다.

​
파일 저장소 크기

메모리 파일 크기를 추적하고 파일이 너무 커지는 것을 방지하는 것을 고려하세요. 메모리 읽기 명령이 반환할 수 있는 최대 문자 수를 추가하고 Claude가 내용을 페이지네이션하도록 하는 것을 고려하세요.

​
메모리 만료

장기간 액세스되지 않은 메모리 파일을 주기적으로 정리하는 것을 고려하세요.

​
경로 순회 보호

악의적인 경로 입력은 /memories 디렉토리 외부의 파일에 액세스하려고 시도할 수 있습니다. 구현에서는 디렉토리 순회 공격을 방지하기 위해 모든 경로를 검증해야 합니다.
다음 보안 조치를 고려하세요:
  • 모든 경로가 /memories로 시작하는지 검증
  • 경로를 정규 형태로 해결하고 메모리 디렉토리 내에 남아있는지 확인
  • ../, ..\\ 또는 기타 순회 패턴을 포함하는 경로 거부
  • URL 인코딩된 순회 시퀀스(%2e%2e%2f) 주의
  • 언어의 내장 경로 보안 유틸리티 사용(예: Python의 pathlib.Path.resolve() 및 relative_to())

​
오류 처리

메모리 도구는 텍스트 편집기 도구와 동일한 오류 처리 패턴을 사용합니다. 일반적인 오류에는 파일을 찾을 수 없음, 권한 오류, 잘못된 경로가 포함됩니다.