메모리 도구

애플리케이션에서 메모리 도구의 파일 작업을 구현하여 Claude가 대화 간에 정보를 저장하고 검색할 수 있도록 합니다.

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

메모리는 적시(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 제공 도구의 전체 목록은 도구 레퍼런스를 참조하세요.

시작하기

메모리 도구 사용은 두 단계로 이루어집니다:

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

기본 사용법

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-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도 함께 제공합니다. 메모리 도구 자체는 베타 헤더가 필요하지 않지만, 헬퍼와 "tool runner"(도구 러너) 인터페이스는 각 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-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"
}

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가 자동으로 이 지침을 "system prompt"(시스템 프롬프트)에 추가합니다. 직접 전송할 필요가 없습니다:

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가 메모리에 무엇을 기록할지 안내할 수도 있습니다. 예: "Only write down information relevant to <topic> in your memory system."

보안 고려 사항

애플리케이션은 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
}

컨텍스트 편집 통합

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

컴팩션과 함께 사용

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

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

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

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

패턴 작동 방식

초기화 세션: 첫 번째 세션은 실질적인 작업이 시작되기 전에 메모리 파일을 설정합니다. 여기에는 진행 로그(완료된 작업과 다음 작업 추적), 기능 체크리스트(작업 범위 정의), 프로젝트에 필요한 시작 또는 초기화 스크립트에 대한 참조가 포함됩니다.
후속 세션: 각 새 세션은 해당 메모리 파일을 읽는 것으로 시작합니다. 이를 통해 코드베이스를 다시 탐색하거나 이전 결정을 되짚지 않고도 프로젝트 상태를 복원합니다.
세션 종료 시 업데이트: 세션이 끝나기 전에 완료된 작업과 남은 작업으로 진행 로그를 업데이트합니다. 이를 통해 다음 세션이 정확한 시작점을 갖도록 보장합니다.

핵심 원칙

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

다음 단계

Bash 도구

지속적인 bash 세션에서 셸 명령을 실행합니다.

컨텍스트 편집

컨텍스트 편집으로 대화 컨텍스트가 커짐에 따라 자동으로 관리합니다.

컴팩션

컨텍스트 윈도우 한도에 가까워지는 긴 대화를 관리하기 위한 서버 측 컨텍스트 컴팩션입니다.

도구 레퍼런스

Anthropic 제공 도구 디렉터리 및 선택적 도구 정의 속성에 대한 레퍼런스입니다.

사용 사례

작동 방식

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

시작하기

기본 사용법

메모리 핸들러 구현

도구 명령

view

반환 값

오류 처리

create

반환 값

오류 처리

str_replace

반환 값

오류 처리

디렉터리 처리

insert

반환 값

오류 처리

디렉터리 처리

delete

반환 값

오류 처리

디렉터리 처리

rename

반환 값

오류 처리

디렉터리 처리

프롬프트 가이드

보안 고려 사항

민감한 정보

파일 저장 크기

메모리 만료

경로 탐색 보호

오류 처리

컨텍스트 편집 통합

컴팩션과 함께 사용

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

패턴 작동 방식

핵심 원칙

다음 단계

사용 사례

작동 방식

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

시작하기

기본 사용법

메모리 핸들러 구현

도구 명령

view

반환 값

오류 처리

create

반환 값

오류 처리

str_replace

반환 값

오류 처리

디렉터리 처리

insert

반환 값

오류 처리

디렉터리 처리

delete

반환 값

오류 처리

디렉터리 처리

rename

반환 값

오류 처리

디렉터리 처리

프롬프트 가이드

보안 고려 사항

민감한 정보

파일 저장 크기

메모리 만료

경로 탐색 보호

오류 처리

컨텍스트 편집 통합

컴팩션과 함께 사용

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

패턴 작동 방식

핵심 원칙

다음 단계