본문으로 건너뛰기

관리형 에이전트 메모리 스토어

고급
What you'll learn
  • 메모리 스토어란 무엇인지 — 그리고 기존 클라이언트 측 메모리 도구와 어떻게 다른지
  • 스토어가 세션 샌드박스의 /mnt/memory/에 어떻게 마운트되고 에이전트가 어떻게 사용하는지
  • 사람들이 걸려 넘어지는 베타 헤더 규칙 (agent-memory-2026-07-22 vs managed-agents-2026-04-01)
  • 전체 라이프사이클: 생성 → 시드 → 첨부 → 읽기/쓰기 → 버전 감사 → 편집(리댁션)
  • 구체적인 한도: 세션당 스토어 8개, 스토어당 메모리 2,000개, 메모리당 100 kB

관리형 에이전트로 개발해 본 적이 있다면, 각 세션이 기본적으로 새로운 컨텍스트로 시작한다는 것을 알 것입니다. 세션이 끝나면 에이전트가 학습한 내용은 함께 사라집니다. 메모리 스토어는 이에 대한 퍼스트파티 해결책입니다: 세션 간에 지속되며 에이전트의 샌드박스에 일반 디렉터리로 마운트되어 파일 도구로 읽고 쓸 수 있는, 서버 측 버전 관리형 텍스트 문서 컬렉션입니다.

메모리 스토어 vs 클라이언트 측 메모리 도구​

Claude 플랫폼에는 이제 두 가지 서로 다른 "메모리" 프리미티브가 있습니다. 혼동하지 마세요.

메모리 스토어 (이 페이지)클라이언트 측 메모리 도구 (별도 페이지)
메모리가 저장되는 곳Anthropic 호스팅, 워크스페이스 범위사용자 자체 스토리지 (Redis, Postgres, 파일 등)
루프 실행자관리형 에이전트사용자 (Messages API + 도구 루프)
베타 헤더agent-memory-2026-07-22context-management-2025-06-27 (메모리 도구)
에이전트가 읽는 방식/mnt/memory/에 파일로 마운트됨도구 호출 (view, str_replace, create 등)
감사 추적불변 버전, 편집(리댁션) 엔드포인트사용자가 직접 구축

같은 개념(영구 상태), 다른 프리미티브입니다. 아래 내용은 모두 메모리 스토어에 관한 것입니다 — 관리형 에이전트 전용, 서버 측 메모리.

개념 모델​

스토어는 워크스페이스 범위로 지정된 작은 Markdown/텍스트 파일(메모리)의 폴더입니다. 세션에 첨부하면 샌드박스 내부의 마운트로 나타나고, Claude는 표준 에이전트 도구셋 — 파일 시스템의 나머지 부분에 사용하는 것과 동일한 도구 — 으로 이를 읽고 씁니다.

두 가지 중요한 귀결:

  • 각 마운트에 대한 메모(이름, 마운트 경로, 액세스 모드, 설명 및 세션별 instructions)가 시스템 프롬프트에 자동으로 삽입됩니다. 에이전트는 여러분이 알려주지 않아도 마운트가 존재한다는 것을 압니다.
  • 마운트 경로 바깥에 대한 쓰기 — /mnt/memory/ 아래 다른 어떤 곳이든 — 는 컨테이너 로컬 스크래치에 저장되며 세션이 종료되면 사라집니다. 마운트 경로에 대한 쓰기만 지속됩니다.

베타 헤더 규칙 (함정)​

여기서 사람들이 20분을 잃습니다.

Watch out
  • 메모리 스토어 엔드포인트는 anthropic-beta: agent-memory-2026-07-22만 사용합니다 — 그 외에는 없습니다.
  • 세션 엔드포인트(메모리 스토어를 세션에 첨부하는 것 포함)는 여전히 managed-agents-2026-04-01을 사용합니다.
  • 메모리 스토어 요청에 둘 다 보내면 HTTP 400을 반환합니다. 코드가 베타 헤더를 명시적으로 설정한다면, 추가하지 말고 교체하세요.

공식 SDK를 사용하면 올바른 헤더가 자동으로 설정됩니다. 원시 HTTP를 사용하는 경우 호출 지점을 분리하세요:

호출헤더
POST /v1/memory_stores (생성)agent-memory-2026-07-22
POST /v1/memory_stores/{id}/memories (메모리 생성/목록/업데이트/삭제)agent-memory-2026-07-22
POST /v1/memory_stores/{id}/memory_versions/…/redactagent-memory-2026-07-22
POST /v1/sessions — resources[]에 스토어 첨부managed-agents-2026-04-01

라이프사이클​

Guided walkthrough1 of 5
  1. 이름과 설명으로 POST /v1/memory_stores. 설명은 에이전트에게 전달되므로, 브리핑처럼 읽혀야 합니다: '사용자별 환경 설정 및 프로젝트 컨텍스트'.

스토어 생성과 첫 번째 메모리​

스토어 이름과 설명은 에이전트가 보는 것입니다 — 폴더의 README를 작성하듯이 작성하세요.

스토어 생성 (curl, 원시 HTTP)

curl -s https://api.anthropic.com/v1/memory_stores \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: agent-memory-2026-07-22" \
-H "content-type: application/json" \
-d '{"name": "User Preferences", "description": "Per-user preferences and project context."}'
# -> {"id": "memstore_01Hx...", ...}

메모리 시드

curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memories" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: agent-memory-2026-07-22" \
-H "content-type: application/json" \
-d '{"path": "/formatting_standards.md", "content": "All reports use GAAP formatting. Dates are ISO-8601."}'

세션에 스토어 첨부​

헤더가 다시 managed-agents-2026-04-01로 바뀐다는 점에 유의하세요 — 첨부를 포함한 세션 엔드포인트는 관리형 에이전트 헤더를 사용합니다.

세션 생성 시 첨부 (read_write)

curl -s https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "resources": [{
    "type": "memory_store",
    "memory_store_id": "$STORE_ID",
    "access": "read_write",
    "instructions": "User preferences and project context. Check before starting any task."
  }]
}'

instructions 필드는 4,096자로 제한되며 스토어의 name 및 description과 함께 에이전트에게 표시됩니다.

액세스 모드와 인젝션 위험​

access는 기본적으로 read_write입니다. 에이전트가 세션에서 학습해야 할 때 올바른 선택입니다. 아무도(또는 아무것도) 수정하지 않기를 원하는 스토어에는 잘못된 선택입니다.

Watch out
  • read_write 스토어는 세션의 프롬프트 인젝션 위험 하류에 있습니다. 에이전트가 신뢰할 수 없는 입력(사용자 프롬프트, 가져온 페이지, 서드파티 도구 출력)을 처리하면, 성공한 인젝션이 악의적인 콘텐츠를 스토어에 쓸 수 있습니다. 이후 세션은 이를 신뢰할 수 있는 메모리로 읽습니다.
  • 경험 법칙: 공유 참조 자료(표준, 용어집, 도메인 문서)는 read_only로 첨부하세요. 성장해야 하는 사용자별 또는 세션별 상태만 read_write로 첨부하세요.
  • 필요하면 둘 다 첨부하세요: 읽기 전용 참조 스토어 하나 + 읽기/쓰기 스크래치 스토어 하나. 세션당 최대 8개.

구체적인 한도​

모두 공식 문서에서 가져온 것이며, 모두 외울 가치가 있습니다:

한도값
세션당 메모리 스토어8
스토어당 메모리2,000
메모리당 바이트100 kB (~25k 토큰)
instructions 길이 (첨부당)4,096자
버전 보존30일 (최근 버전은 항상 유지)

스토어가 메모리 2,000개에 도달하면 이후 쓰기는 — 직접 API 호출 및 에이전트 자신의 파일 쓰기 — 실패하기 시작합니다. 문서의 권장 해결책은 "하나의 거대한 스토어"가 아닙니다: 여러 개의 작고 집중된 스토어(사용자당 하나, 공유 참조용 하나, 프로젝트당 하나)를 사용하고, memories.delete로 오래된 항목을 정리하거나, 드리밍 세션을 실행하여 통합하세요.

감사 추적, 버전, 롤백​

메모리에 대한 모든 쓰기는 불변 메모리 버전(memver_...)을 생성합니다. 버전은 메모리가 아닌 스토어에 속하므로, 메모리 자체가 삭제된 후에도 살아남습니다 — 감사 추적은 완전한 상태로 유지됩니다.

유용한 패턴:

  • 특정 시점 검사: GET /v1/memory_stores/{id}/memory_versions?memory_id=… 로 최신순으로 누가 무엇을 변경했는지 확인하세요.
  • 롤백: 전용 복원 엔드포인트는 없습니다. 원하는 버전을 가져와서 그 content를 memories.update로 다시 쓰세요 (부모 메모리가 사라진 경우 memories.create).
  • 안전한 동시 편집: memories.update에 content_sha256 사전 조건을 전달하세요. 헤드 해시가 더 이상 일치하지 않으면 업데이트가 거부되고, 다시 시도하기 전에 다시 읽습니다 — 고전적인 낙관적 동시성 제어입니다.

컴플라이언스: 버전 편집(리댁션)​

PII, 비밀, 또는 사용자 삭제 요청으로 콘텐츠를 히스토리에서 사라지게 해야 할 때 redact를 사용하세요. 콘텐츠는 지우지만 감사 추적(누가, 언제, 무엇을 했는지)은 보존합니다.

Pro tip
  • 활성 메모리의 현재 헤드는 편집(리댁션)할 수 없습니다. 먼저 새 버전을 쓰거나(또는 메모리를 삭제하고), 그 다음 이전 버전을 편집하세요.
  • 버전이 부모 메모리보다 오래 지속되기 때문에, 메모리를 삭제해도 히스토리가 자동으로 삭제되지는 않습니다 — 여전히 버전마다 편집(리댁션)해야 합니다.
  • 버전 보존은 최소 30일입니다. 컴플라이언스를 위해 더 긴 보존이 필요한 경우, 만료되기 전에 API를 통해 버전을 내보내세요.

흔한 실수​

Pro tip
  • 메모리 스토어 호출에 두 개의 베타 헤더를 모두 보내는 것 — HTTP 400을 받습니다. 추가하지 말고 교체하세요.
  • 실행 중인 세션에서 스토어를 추가하거나 제거하려는 시도 — 지원되지 않습니다. 첨부는 세션 생성 시에만 이루어집니다, 끝.
  • 공유 참조 스토어를 read_write로 첨부하기 — 인젝션 한 번이면 여러분의 표준이 향후 모든 세션에서 손상됩니다.
  • 여러 개의 집중된 스토어 대신 하나의 거대한 스토어 — 2,000 한도에 부딪혀 이후 쓰기가 잠깁니다.
  • /mnt/memory/scratch/에 쓰면서 지속되기를 바라는 것 — 마운트 경로 바깥의 모든 것은 컨테이너 로컬이며 세션 종료 시 증발합니다.

스스로 확인해 보기​

스스로 확인해 보기

0/5
  1. 메모리 스토어 생성 요청에 anthropic-beta: agent-memory-2026-07-22와 anthropic-beta: managed-agents-2026-04-01을 둘 다 보냈습니다. 어떻게 될까요?
  2. 메모리 스토어는 세션 샌드박스 내부의 어디에 나타나나요?
  3. 에이전트가 외부 사용자로부터 온 이메일을 처리합니다. 공유 '표준 및 용어집' 스토어에 가장 안전한 액세스 모드는 무엇인가요?
  4. 히스토리에서 유출된 비밀을 삭제해야 합니다. 어떤 순서가 작동합니까?
  5. 메모리당 크기 한도와 스토어당 메모리 개수는 얼마입니까?
Key takeaways
  • 메모리 스토어는 관리형 에이전트를 위한 서버 측 영구 메모리 프리미티브입니다 — 클라이언트 측 메모리 도구와 다릅니다.
  • 헤더 규칙: 메모리 스토어 엔드포인트에는 agent-memory-2026-07-22, 세션 엔드포인트에는 managed-agents-2026-04-01. 절대 둘 다 사용하지 마세요.
  • 스토어는 세션 생성 시 첨부되고 /mnt/memory/[store-slug]/에 마운트됩니다; 세션 도중 추가/제거는 지원되지 않습니다.
  • 공유 참조에는 기본적으로 read_only를 사용하세요; 사용자별 또는 세션별 성장만 read_write여야 합니다.
  • 모든 쓰기는 불변 버전을 생성합니다; 롤백은 '가져와서 다시 쓰기'; 편집(리댁션)은 컴플라이언스를 위해 히스토리를 지웁니다.

다음​