메모리 도구

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

메모리는 적시 컨텍스트 검색을 지원합니다. 에이전트는 모든 관련 정보를 미리 로드하는 대신, 학습한 내용을 메모리 파일에 기록하고 필요할 때 다시 읽어옵니다. 이렇게 하면 활성 컨텍스트가 현재 작업에 집중된 상태로 유지되며, 이는 그렇지 않으면 컨텍스트 윈도우를 초과하게 될 장기 실행 세션에서 중요합니다. 더 넓은 패턴에 대해서는 Effective context engineering을 참조하세요.

메모리 도구는 클라이언트 측에서 작동합니다. 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-4-8",
    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-4-8",
    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"
}

str_replace에서 new_str은 선택 사항입니다. 생략하면 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. 세션 종료 업데이트: 세션이 끝나기 전에 완료된 작업과 남은 작업으로 진행 로그를 업데이트합니다. 이렇게 하면 다음 세션이 정확한 시작점을 갖게 됩니다.



핵심 원칙

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



다음 단계