본문 바로가기
삵
AI

메모리 툴로 Claude 에이전트 오래 돌리기

포포스트맨·2026년 11월 22일·조회 0

에이전트를 한두 턴이 아니라 수십, 수백 턴 돌리다 보면 늘 같은 벽에 부딪힌다. tool 결과가 대화 기록에 계속 쌓이고, 매 요청마다 그 기록을 통째로 다시 모델에 보내기 때문에 입력 토큰이 턴마다 불어난다. 긴 리서치 작업이나 코드베이스 수정 같은 걸 자동으로 맡기면 어느 순간 컨텍스트 창이 꽉 차서 요청이 거부되거나, 거부는 안 되더라도 청구서가 가파르게 올라간다.

이 문제를 Anthropic이 공식으로 푸는 두 축이 메모리 툴과 컨텍스트 편집이다. 메모리 툴은 Claude가 /memories 디렉터리에 파일을 만들고 읽어서 중요한 상태를 대화 밖에 보관하게 해 준다. 컨텍스트 편집(clear_tool_uses_20250919)은 오래된 tool 결과를 서버에서 자동으로 비워 입력 토큰을 다시 줄여 준다. 오래 도는 에이전트라면 이 둘을 같이 켜는 게 정답이다.

메모리 툴이 하는 일

메모리 툴은 Claude에게 파일 시스템 비슷한 저장소를 쥐여 주는 도구다. 핵심은 클라이언트 측에서 동작한다는 점이다. 모델은 "이 파일을 읽어라", "이 내용으로 파일을 만들어라" 하고 요청만 하고, 실제 저장과 읽기는 내 애플리케이션이 실행한다. 저장 위치는 디스크든 데이터베이스든 S3든 내가 정한다. /memories는 실제 저장소에 매핑하는 경로 접두어일 뿐이다.

왜 굳이 이렇게 하냐면, 모든 정보를 컨텍스트에 이고 가는 대신 필요할 때만 꺼내 읽는 방식(just-in-time)을 쓰기 위해서다. 긴 작업 중에 알아낸 사실, 진행 상황, 다음 할 일을 메모리 파일에 적어 두면 대화 기록이 초기화돼도 다음 세션이 그 파일을 읽고 이어서 일한다.

요청에 넣는 설정은 이게 전부다. 입력 스키마를 따로 정의하지 않는다.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 2048,
    "messages": [
      {"role": "user", "content": "이 고객 문의에 답장하는 걸 도와줘."}
    ],
    "tools": [{"type": "memory_20250818", "name": "memory"}]
  }'

메모리 툴을 켜면 API가 시스템 프롬프트에 "작업 전에 항상 메모리 디렉터리부터 확인하라"는 지침을 자동으로 붙인다. 그래서 첫 응답은 대개 view /memories tool 호출로 시작한다.

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

이 호출을 받으면 내 핸들러가 실제 디렉터리를 뒤져서 tool_result로 돌려준다. 빈 저장소에서의 첫 view /memories는 에러가 아니다.

{
  "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\n2.0K\t/memories/progress.md"
}

핸들러가 처리해야 하는 명령은 여섯 가지다. view(디렉터리 목록 또는 파일 내용), create(파일 생성 또는 덮어쓰기), str_replace(문자열 치환), insert(특정 줄에 삽입), delete(삭제), rename(이름 변경 또는 이동). 각 명령이 돌려줘야 하는 성공/에러 문자열은 공식 문서에 그대로 정의돼 있고, Claude는 그 문자열을 그냥 텍스트로 읽으니 내 상황에 맞게 바꿔도 된다.

직접 여섯 개를 다 구현하기 번거로우면 SDK가 돕는다. Python과 TypeScript에는 로컬 디스크에 바로 붙는 구현체 BetaLocalFilesystemMemoryTool과 tool-use 루프를 대신 돌려 주는 러너가 들어 있다.

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": "Acme Corp 고객은 이메일 후속 연락을 선호한다는 걸 기억해 둬."}],
    tools=[memory],
)

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

메모리 툴 자체는 beta 헤더가 필요 없지만, SDK 헬퍼와 러너는 beta 네임스페이스(client.beta.messages)에 산다는 점만 기억하면 된다.

직접 핸들러를 짠다면 보안 구멍 하나를 반드시 막아야 한다. /memories/../../secrets.env 같은 경로가 오면 메모리 디렉터리 밖 파일에 손이 닿는다. 모든 명령에서 경로가 /memories로 시작하는지 검증하고, canonical 경로로 변환해 디렉터리 안에 머무는지 확인하라. Python이면 pathlib.Path.resolve()와 relative_to()로 거른다. SDK가 주는 인메모리 예제 저장소에는 이 검증이 빠져 있으니 운영에 그대로 쓰면 안 된다.

컨텍스트 편집으로 오래된 tool 결과 비우기

메모리를 붙여도 대화 기록 자체는 계속 쌓인다. tool을 한 번 쓸 때마다 호출과 결과가 기록에 남고, 매 요청에서 그걸 다시 보낸다. 컨텍스트 편집은 이 오래된 tool 결과를 서버에서 플레이스홀더로 치환해 입력 토큰을 깎는다. 내 클라이언트가 들고 있는 원본 기록은 손대지 않고, 모델에 들어가기 직전의 프롬프트만 정리하는 방식이다.

켜려면 beta 헤더 anthropic-beta: context-management-2025-06-27와 context_management 파라미터를 넣는다.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: context-management-2025-06-27" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4096,
    "messages": [ ... ],
    "tools": [ ... ],
    "context_management": {
      "edits": [{"type": "clear_tool_uses_20250919"}]
    }
  }'

기본값만으로도 돈다. 입력 토큰이 10만을 넘으면(trigger 기본값 input_tokens: 100000) 작동하고, 가장 최근 tool 사용 3쌍(keep 기본값 tool_uses: 3)은 남기고 그 앞의 결과를 비운다. 기본은 결과만 지우고 tool 호출 입력은 남긴다. 호출 입력까지 지우려면 clear_tool_inputs: true를 준다.

실제로는 기본 트리거 10만 토큰이 너무 늦게 걸릴 때가 많다. 더 공격적으로 비우려면 트리거를 낮추고, 유지할 쌍 수와 최소 삭제량을 직접 잡는다.

"context_management": {
  "edits": [{
    "type": "clear_tool_uses_20250919",
    "trigger": {"type": "input_tokens", "value": 30000},
    "keep": {"type": "tool_uses", "value": 3},
    "clear_at_least": {"type": "input_tokens", "value": 5000},
    "exclude_tools": ["web_search"]
  }]
}

여기서 clear_at_least가 실전 포인트다. 컨텍스트를 건드리면 프롬프트 캐시가 그 지점부터 무효가 된다. 조금씩 자주 비우면 캐시를 매번 날려 오히려 손해다. 한 번 비울 때 최소 5천 토큰처럼 의미 있는 덩어리로 비우게 묶어 캐시 무효화 비용을 상쇄한다. exclude_tools는 비우면 안 되는 tool 결과를 지정한다. 예를 들어 다시 호출하기 비싼 검색 결과를 남기고 싶을 때 쓴다.

응답에는 무엇을 비웠는지 돌아온다.

{
  "context_management": {
    "applied_edits": [{
      "type": "clear_tool_uses_20250919",
      "cleared_tool_uses": 8,
      "cleared_input_tokens": 50000
    }]
  }
}

실행 전에 효과를 미리 보고 싶으면 토큰 카운팅 엔드포인트에 같은 context_management를 넣어 본다. original_input_tokens와 비우기 후 input_tokens를 비교하면 이 설정으로 요청당 얼마나 줄어드는지 환경에 맞게 확인할 수 있다.

response = client.beta.messages.count_tokens(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": "Continue..."}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{
        "type": "clear_tool_uses_20250919",
        "trigger": {"type": "input_tokens", "value": 30000},
        "keep": {"type": "tool_uses", "value": 5},
    }]},
)
print(response.context_management.original_input_tokens)
print(response.input_tokens)

둘을 같이 켜야 작업이 안 끊긴다

컨텍스트 편집만 켜면 함정이 하나 있다. 오래된 tool 결과를 비우면 거기 담겼던 정보도 같이 사라진다. 리서치 중간 결과나 파일 내용을 뒤에서 다시 참조해야 하는데 이미 비워졌다면 작업이 어긋난다.

그래서 메모리 툴과 짝지어 쓴다. Claude는 tool 결과가 비워지기 전에 중요한 내용을 메모리 파일에 적어 둘 수 있고, 나중에 필요하면 view로 다시 읽는다. 비워지는 건 대화 기록 속 결과고, 핵심 사실은 /memories에 남는다. 요청 하나에 두 기능을 같이 넣으면 된다.

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "..."}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

여러 세션에 걸치는 코드 작업이라면 메모리 파일을 즉흥적으로 만들지 말고 처음부터 구조를 잡아 두는 편이 안정적이다. 첫 세션에서 진행 로그(한 일과 다음 할 일), 기능 체크리스트, 초기화 스크립트 참조를 메모리에 세팅한다. 이후 세션은 그 파일을 읽고 바로 이어서 일하고, 세션을 끝내기 전에 진행 로그를 갱신한다. 기능은 코드를 다 썼을 때가 아니라 끝까지 검증됐을 때만 완료로 표시해야 진행 로그가 세션 사이에서 정확하게 유지된다.

컨텍스트 편집이 클라이언트 측에서 특정 tool 결과를 비우는 방식이라면, 서버 측에서 대화 전체를 요약으로 압축하는 compaction이라는 선택지도 있다. 컨텍스트 창 한계에 다가가면 서버가 알아서 오래된 맥락을 요약한다. 긴 에이전트에서는 compaction으로 활성 컨텍스트를 작게 유지하고, 요약을 넘어 반드시 살아남아야 하는 정보는 메모리에 박아 두는 조합도 쓸 수 있다.

모델은 모든 Claude 4 이상에서 메모리 툴과 컨텍스트 편집을 쓸 수 있다. 비용에 민감한 오래 도는 작업이라면 예제의 claude-opus-5-5 대신 더 저렴한 모델로 바꿔 보고, 위 토큰 카운팅으로 요청당 입력 토큰이 실제로 어떻게 줄어드는지부터 재 보는 걸 권한다. 모델 ID와 버전 번호는 계정에서 쓸 수 있는 최신 목록에 따라 다를 수 있다.

자주 묻는 질문

메모리 툴을 쓰려면 beta 헤더가 필요한가.

메모리 툴 자체는 beta 헤더가 필요 없다. 요청의 tools에 {"type": "memory_20250818", "name": "memory"}만 넣으면 된다. 다만 Python이나 TypeScript SDK의 메모리 헬퍼와 tool 러너는 client.beta.messages 네임스페이스에 있다. 컨텍스트 편집을 같이 켤 때는 anthropic-beta: context-management-2025-06-27 헤더가 필요하다.

메모리 데이터는 어디에 저장되나.

메모리 툴은 클라이언트 측에서 동작한다. Claude는 파일 명령만 요청하고 실제 저장과 읽기는 내 애플리케이션이 실행한다. /memories는 실제 저장소에 매핑하는 경로 접두어이고, 디스크, 데이터베이스, 클라우드 스토리지 등 내가 정한 곳에 둔다. 다음 세션이 같은 tools 설정으로 같은 저장소를 가리키면 이전 메모리를 그대로 이어받는다.

컨텍스트 편집은 기본값으로 언제 작동하나.

clear_tool_uses_20250919의 기본 트리거는 input_tokens 100000이다. 입력 토큰이 10만을 넘으면 작동해 가장 최근 tool 사용 3쌍(keep 기본값 tool_uses 3)을 남기고 그 앞의 tool 결과를 비운다. 기본은 결과만 비우고 tool 호출 입력은 남긴다. trigger, keep, clear_at_least, exclude_tools, clear_tool_inputs로 동작을 조정한다.

tool 결과를 비우면 중요한 정보가 사라지지 않나.

그래서 메모리 툴과 같이 쓴다. Claude는 tool 결과가 비워지기 전에 핵심 내용을 /memories 파일에 저장할 수 있고, 나중에 view로 다시 읽는다. 비워지는 것은 대화 기록 속 tool 결과이고, 저장해 둔 사실은 메모리에 남아 긴 작업이 끊기지 않는다.

컨텍스트를 자주 비우면 캐시 때문에 손해 아닌가.

맞다. 컨텍스트를 건드리면 프롬프트 캐시가 그 지점부터 무효가 된다. 조금씩 자주 비우면 캐시를 반복해서 날려 오히려 비싸진다. clear_at_least로 한 번 비울 때 최소 토큰량을 지정해 의미 있는 덩어리로 묶어 비우면 캐시 무효화 비용을 상쇄할 수 있다.

관련 글

댓글 0

로그인 후 댓글을 남길 수 있습니다.

아직 댓글이 없습니다.