메모리 도구

메모리 도구를 사용하면 Claude가 메모리 파일 디렉터리에서 대화 간에 정보를 저장하고 검색할 수 있습니다. Claude는 세션 간에 유지되는 파일을 생성, 읽기, 업데이트, 삭제할 수 있으며, 모든 것을 컨텍스트 윈도우에 유지하지 않고도 시간이 지남에 따라 지식을 축적할 수 있습니다.

메모리는 적시(just-in-time) 컨텍스트 검색을 지원합니다. 모든 관련 정보를 미리 로드하는 대신, 에이전트는 학습한 내용을 메모리 파일에 기록하고 필요할 때 다시 읽어옵니다. 이렇게 하면 활성 컨텍스트가 현재 작업에 집중되며, 이는 컨텍스트 윈도우를 압도할 수 있는 장기 실행 세션에서 중요합니다. 더 넓은 패턴에 대해서는 효과적인 컨텍스트 엔지니어링을 참조하세요.

메모리 도구는 클라이언트 측에서 작동합니다. Claude가 파일 작업을 요청하면 애플리케이션이 이를 실행합니다. 자체 인프라를 통해 데이터가 저장되는 위치와 방법을 제어할 수 있습니다.



사용 사례

• 여러 에이전트 세션에 걸쳐 프로젝트 컨텍스트 유지
• 과거 상호작용, 결정, 피드백에서 얻은 교훈을 새로운 작업에 적용
• 시간이 지남에 따라 지식 베이스 구축



작동 방식

메모리 도구가 활성화되면 Claude는 작업을 시작하기 전에 자동으로 메모리 디렉터리를 확인합니다. 작업하는 동안 Claude는 학습한 내용을 /memories 아래의 파일에 저장하고 이후 대화에서 다시 읽어 이전 작업을 계속합니다.

메모리 도구는 클라이언트 측이기 때문에 Claude는 메모리 작업을 요청만 합니다. 애플리케이션은 사용자가 제어하는 스토리지에 대해 각 요청을 실행하고 결과를 tool_result 블록으로 반환합니다(도구 호출 처리 참조). /memories 경로는 핸들러가 사용자별 디렉터리나 데이터베이스의 키와 같은 실제 스토리지에 매핑하는 접두사입니다. 메모리는 전적으로 애플리케이션에 존재합니다. 이후 대화가 동일한 tools 항목을 보내고 핸들러가 동일한 저장소를 제공하면 동일한 메모리에서 계속됩니다. 보안을 위해 모든 메모리 작업을 /memories 디렉터리로 제한하세요(경로 탐색 보호 참조).



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

일반적인 상호작용은 다음과 같습니다:

1. 사용자 요청:

"Help me respond to this customer service ticket."

2. Claude가 메모리 디렉터리를 확인합니다:

"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."

Claude가 메모리 도구를 호출합니다:

{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}

3. 애플리케이션이 디렉터리 내용을 반환합니다:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/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": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Always address customers by their first name\n     4\t- Use empathetic language\n..."
}

6. Claude가 메모리를 사용하여 도움을 줍니다:

"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."

메모리 도구는 모든 Claude 4 이상 모델에서 사용할 수 있습니다. Anthropic에서 제공하는 도구의 전체 목록은 도구 참조를 참조하세요.



시작하기

메모리 도구는 Messages API에서 정식으로 제공됩니다. 베타 헤더가 필요하지 않습니다. 사용하려면 두 단계가 필요합니다:

1. 요청에 메모리 도구를 추가합니다. tools 항목 {"type": "memory_20250818", "name": "memory"}가 전체 구성입니다. name은 반드시 memory여야 하며, Anthropic에서 제공하는 도구에는 입력 스키마를 정의하지 않습니다.
2. 각 메모리 명령에 대한 클라이언트 측 핸들러를 구현합니다. 핸들러는 /memories 외부의 경로를 거부해야 하므로, 작성하기 전에 경로 탐색 보호를 읽어보세요.



기본 사용법

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "Help me respond to this customer service ticket.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)



메모리 핸들러 구현

이전과 같은 요청에 대한 Claude의 응답은 view /memories와 같은 메모리 작업을 요청하는 tool_use 블록으로 끝납니다. 애플리케이션은 작업을 실행하고 결과를 tool_result 블록으로 반환한 다음, Claude가 계속할 수 있도록 대화를 다시 보냅니다. 이것이 표준 도구 사용 루프입니다.

네 개의 SDK가 도구 인터페이스와 루프를 처리하는 메모리 도구 헬퍼를 제공합니다. BetaAbstractMemoryTool을 서브클래싱하거나(Python 및 C#), betaMemoryTool을 사용하거나(TypeScript), BetaMemoryToolHandler를 구현하여(Java) 디스크의 파일, 데이터베이스, 클라우드 스토리지 또는 암호화된 파일과 같은 자체 스토리지로 메모리를 지원할 수 있습니다. Python과 TypeScript는 바로 사용할 수 있는 로컬 파일시스템 구현인 BetaLocalFilesystemMemoryTool도 제공합니다. 메모리 도구 자체는 정식으로 제공되지만 헬퍼와 도구 실행기 인터페이스는 각 SDK의 베타 네임스페이스에 있습니다. Go와 Ruby SDK에는 메모리 헬퍼가 없으므로 해당 예제는 도구 사용 루프를 직접 실행하며, PHP는 핸들러 클로저를 일반 BetaRunnableTool로 래핑합니다. 세 가지 모두 자체 스토리지로 교체해야 하는 인메모리 저장소를 사용합니다.

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Remember that customer Acme Corp prefers email follow-ups.",
        }
    ],
    tools=[memory],
)

final_message = runner.until_done()
print(final_message.content)

Go, PHP, Ruby 예제의 인메모리 저장소는 예제를 독립적으로 유지합니다. 각각은 tool_use 블록의 input에 있는 command 필드에 따라 분기하고 도구 명령에 설명된 문자열을 반환합니다. 프로덕션 핸들러에는 이러한 데모 저장소가 생략한 경로 검증도 필요합니다. SDK 자체의 완전한 예제는 다음을 참조하세요:

• Python: examples/memory/basic.py
• TypeScript: examples/tools-helpers-memory.ts
• C#: MemoryToolExample
• Java: BetaMemoryToolExample.java



도구 명령

클라이언트 측 구현은 다음 명령을 처리해야 합니다. 이 사양은 권장되는 동작과 반환 문자열을 설명합니다. Claude는 도구 결과에 포함된 텍스트를 그대로 읽으므로, 애플리케이션에 필요하다면 다른 문자열을 반환할 수 있습니다.



view

디렉터리 내용 또는 선택적 줄 범위와 함께 파일 내용을 표시합니다:

{
  "command": "view",
  "path": "/memories/notes.txt",
  "view_range": [1, 10]
}

view_range는 선택 사항이며 텍스트 파일 보기에 적용됩니다. [start_line, end_line]은 해당 줄을 반환하고, [start_line, -1]은 start_line부터 파일 끝까지 모든 내용을 반환합니다.



반환 값

디렉터리의 경우: 파일과 디렉터리를 크기와 함께 보여주는 목록을 반환합니다:

Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}\t{path}
{size}\t{path}/{filename1}
{size}\t{path}/{filename2}

• 최대 2단계 깊이까지 파일을 나열합니다
• 사람이 읽기 쉬운 크기를 표시합니다(예: 5.5K, 1.2M)
• 숨겨진 항목(.으로 시작하는 파일)과 node_modules를 제외합니다
• 크기와 경로 사이에 탭 문자를 사용합니다

빈 저장소에서 /memories에 대한 첫 번째 view는 오류가 아닙니다. SDK의 로컬 파일시스템 메모리 도구(BetaLocalFilesystemMemoryTool)는 Claude의 첫 번째 호출 전에 메모리 루트를 생성하고, 목록 헤더 다음에 빈 디렉터리 자체에 대한 크기와 경로 한 줄을 반환합니다.

파일의 경우: 헤더와 줄 번호와 함께 파일 내용을 반환합니다:

Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}

줄 번호 형식:

• 너비: 6자, 공백 패딩으로 오른쪽 정렬
• 구분자: 줄 번호와 내용 사이의 탭 문자
• 인덱싱: 1부터 시작(첫 번째 줄이 1번 줄)
• 줄 제한: 999,999줄을 초과하는 파일은 오류를 반환해야 합니다: "File {path} exceeds maximum line limit of 999,999 lines."

출력 예시:

Here's the content of /memories/notes.txt with line numbers:
     1	Hello World
     2	This is line two
    10	Line ten
   100	Line one hundred

Claude의 도구 설명에는 view가 이미지 파일(.jpg, .jpeg, .png)을 표시하고 16,000자를 초과하는 파일의 텍스트 보기를 잘라낸다고도 명시되어 있습니다. 이미지 경로에 대한 view 호출과 긴 파일에 대한 후속 범위 지정 보기를 예상하세요.



오류 처리

• 파일 또는 디렉터리가 존재하지 않음: "The path {path} does not exist. Please provide a valid path."



create

새 파일을 생성합니다:

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}



반환 값

• 성공: "File created successfully at: {path}"



오류 처리

• 파일이 이미 존재함: "Error: File {path} already exists"

Claude의 도구 설명에는 create가 파일을 "생성하거나 덮어쓴다"고 명시되어 있으므로, 이미 존재하는 경로에 대한 create 호출을 예상하세요. 오류를 반환하는 것이 참조 동작이며, 대신 덮어쓰는 것도 유효한 구현 선택입니다.



str_replace

파일의 텍스트를 교체합니다:

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

new_str은 str_replace에서 선택 사항입니다. 생략하면 old_str이 대체 없이 삭제됩니다.



반환 값

• 성공: "The memory file has been edited." 다음에 줄 번호가 포함된 편집된 파일의 일부



오류 처리

• 파일이 존재하지 않음: "Error: The path {path} does not exist. Please provide a valid path."
• 텍스트를 찾을 수 없음: "No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."
• 중복 텍스트: old_str이 여러 번 나타나는 경우 다음을 반환합니다: "No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"



디렉터리 처리

경로가 디렉터리인 경우 "파일이 존재하지 않음" 오류를 반환합니다.



insert

특정 줄에 텍스트를 삽입합니다:

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Review memory tool documentation\n"
}

insert_text는 insert_line 줄 뒤에 삽입되며, 0은 파일의 시작 부분에 삽입합니다.



반환 값

• 성공: "The file {path} has been edited."



오류 처리

• 파일이 존재하지 않음: "Error: The path {path} does not exist"
• 잘못된 줄 번호: "Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"



디렉터리 처리

경로가 디렉터리인 경우 "파일이 존재하지 않음" 오류를 반환합니다.



delete

파일 또는 디렉터리를 삭제합니다:

{
  "command": "delete",
  "path": "/memories/old_file.txt"
}



반환 값

• 성공: "Successfully deleted {path}"



오류 처리

• 파일 또는 디렉터리가 존재하지 않음: "Error: The path {path} does not exist"



디렉터리 처리

디렉터리와 모든 내용을 재귀적으로 삭제합니다. 도구 설명은 Claude에게 /memories 디렉터리 자체를 삭제할 수 없다고 알려주므로, 경로가 메모리 루트인 delete는 거부하세요.



rename

파일 또는 디렉터리의 이름을 변경하거나 이동합니다:

{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}



반환 값

• 성공: "Successfully renamed {old_path} to {new_path}"



오류 처리

• 원본이 존재하지 않음: "Error: The path {old_path} does not exist"
• 대상이 이미 존재함: 오류를 반환합니다(덮어쓰지 않음): "Error: The destination {new_path} already exists"



디렉터리 처리

디렉터리의 이름을 변경합니다. 도구 설명은 Claude에게 /memories 디렉터리 자체의 이름을 변경할 수 없다고 알려주므로, old_path가 메모리 루트인 rename은 거부하세요.



프롬프트 가이드

요청의 tools에 메모리 도구가 있으면 API가 자동으로 이 지침을 시스템 프롬프트에 추가합니다. 직접 보낼 필요가 없습니다:

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
   - As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.

Claude의 도구 설명에는 이미 메모리 디렉터리를 정리된 상태로 유지하라고 명시되어 있으므로, 해당 지침을 반복할 필요가 없습니다. Claude가 여전히 어수선한 메모리 파일을 생성한다면 프롬프트에서 이를 강화할 수 있습니다:

Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.

Claude가 메모리에 작성하는 내용을 안내할 수도 있습니다. 예: "메모리 시스템에는 <topic>과 관련된 정보만 기록하세요."



보안 고려 사항

애플리케이션은 Claude가 요청하는 모든 파일 작업을 실행하므로, 다음 안전장치는 사용자의 책임입니다:



민감한 정보

Claude는 일반적으로 민감한 정보를 메모리 파일에 쓰는 것을 거부합니다. 더 강력한 보장을 위해 핸들러가 파일을 쓰기 전에 민감한 데이터를 제거하는 검증을 추가하세요.



파일 저장 크기

메모리 파일 크기를 추적하고 파일이 커질 수 있는 한도를 설정하세요. view 명령이 반환하는 문자 수를 제한하고, Claude가 view_range로 나머지를 페이지 단위로 탐색하도록 하는 것을 고려하세요.



메모리 만료

오랫동안 접근되지 않은 메모리 파일을 주기적으로 삭제하세요.



경로 탐색 보호

다음 안전장치를 고려하세요:

• 모든 경로가 /memories로 시작하는지 검증
• 경로를 정규 형식으로 해석하고 메모리 디렉터리 내에 유지되는지 확인
• ../, ..\\ 또는 기타 탐색 패턴과 같은 시퀀스가 포함된 경로 거부
• URL 인코딩된 탐색 시퀀스(%2e%2e%2f) 주의
• 사용 중인 언어의 내장 경로 보안 유틸리티 사용(예: Python의 pathlib.Path.resolve() 및 relative_to())



오류 처리

메모리 도구는 텍스트 편집기 도구와 유사한 오류 처리 패턴을 사용합니다. 각 명령의 오류 메시지는 도구 명령에 나열되어 있습니다. Claude에게 오류를 반환하려면 도구 결과에서 is_error를 true로 설정하고 메시지를 content에 넣으세요:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Error: The path /memories/notes.txt does not exist",
  "is_error": true
}



컨텍스트 편집 통합

메모리 도구는 컨텍스트 편집과 함께 사용하여 장기 실행 대화를 관리할 수 있습니다. 자세한 내용은 컨텍스트 편집을 참조하세요.



컴팩션과 함께 사용

메모리 도구는 서버 측에서 이전 대화 컨텍스트를 요약하는 컴팩션과도 함께 사용할 수 있습니다. 컨텍스트 편집은 클라이언트에서 특정 도구 결과를 지웁니다. 컴팩션은 대화가 컨텍스트 윈도우 한도에 가까워지면 서버에서 전체 대화를 자동으로 요약합니다.

장기 실행 에이전트의 경우 둘 다 사용하는 것을 고려하세요. 컴팩션은 클라이언트 측 관리 없이 활성 컨텍스트를 작게 유지하고, 메모리는 요약 후에도 유지되어야 하는 정보를 보존합니다.



다중 세션 소프트웨어 개발 패턴

여러 에이전트 세션에 걸친 소프트웨어 프로젝트의 경우, 작업이 진행됨에 따라 임시로 작성하는 대신 메모리 파일을 의도적으로 설정하세요. 다음 패턴은 메모리를 복구 메커니즘으로 전환합니다. 각 새 세션은 마지막 세션이 기록한 상태에서 재개됩니다.



패턴 작동 방식

1. 초기화 세션: 첫 번째 세션은 실질적인 작업이 시작되기 전에 메모리 파일을 설정합니다. 여기에는 진행 로그(완료된 작업과 다음 작업 추적), 기능 체크리스트(작업 범위 정의), 프로젝트에 필요한 시작 또는 초기화 스크립트에 대한 참조가 포함됩니다.

2. 후속 세션: 각 새 세션은 해당 메모리 파일을 읽는 것으로 시작합니다. 이렇게 하면 코드 베이스를 다시 탐색하거나 이전 결정을 되짚지 않고도 프로젝트 상태가 복원됩니다.

3. 세션 종료 업데이트: 세션이 끝나기 전에 완료된 작업과 남은 작업으로 진행 로그를 업데이트합니다. 이렇게 하면 다음 세션이 정확한 시작점을 갖게 됩니다.



핵심 원칙

한 번에 하나의 기능만 작업하세요. 코드가 작성되었을 때가 아니라 엔드투엔드 검증으로 작동이 확인된 후에만 기능을 완료로 표시하세요. 이렇게 하면 세션 간에 진행 로그가 정확하게 유지됩니다.



다음 단계