Loading...
    • 빌드
    • 관리
    • 모델 및 가격
    • 클라이언트 SDK
    • API 참조
    Search...
    ⌘K
    시작하기
    Claude 소개빠른 시작
    Claude로 구축하기
    기능 개요Messages API 사용중지 이유 처리
    모델 기능
    확장 사고적응형 사고노력빠른 모드 (베타: 리서치 프리뷰)구조화된 출력인용스트리밍 메시지일괄 처리검색 결과스트리밍 거부다국어 지원임베딩
    도구
    개요도구 사용 방법웹 검색 도구웹 가져오기 도구코드 실행 도구메모리 도구Bash 도구컴퓨터 사용 도구텍스트 편집기 도구
    도구 인프라
    도구 검색프로그래밍 방식 도구 호출세밀한 도구 스트리밍
    컨텍스트 관리
    컨텍스트 윈도우압축컨텍스트 편집프롬프트 캐싱토큰 계산
    파일 작업
    Files APIPDF 지원이미지 및 비전
    스킬
    개요빠른 시작모범 사례엔터프라이즈용 스킬API의 스킬
    MCP
    원격 MCP 서버MCP 커넥터
    프롬프트 엔지니어링
    개요프롬프트 모범 사례Console 프롬프트 도구
    테스트 및 평가
    성공 기준 정의 및 평가 구축Console의 평가 도구 사용지연 시간 줄이기
    가드레일 강화
    환각 줄이기출력 일관성 높이기탈옥 방지프롬프트 유출 줄이기
    리소스
    용어집
    릴리스 노트
    Claude Platform
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    에이전트에 작업 위임

    메모리 사용

    메모리 저장소를 사용하여 세션을 통해 지속되는 에이전트 메모리를 제공합니다.

    Agent Memory는 Research Preview 기능입니다. 액세스 요청하여 시도해보세요.

    Agent API 세션은 기본적으로 임시적입니다. 세션이 끝나면 에이전트가 학습한 모든 것이 사라집니다. 메모리 저장소를 사용하면 에이전트가 세션을 통해 학습을 전달할 수 있습니다: 사용자 선호도, 프로젝트 규칙, 이전 실수, 도메인 컨텍스트.

    모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. 연구 미리보기 기능에는 추가 베타 헤더가 필요합니다. SDK는 이러한 베타 헤더를 자동으로 설정합니다.

    개요

    메모리 저장소는 Claude에 최적화된 작업 공간 범위의 텍스트 문서 모음입니다. 하나 이상의 메모리 저장소가 세션에 연결되면, 에이전트는 작업을 시작하기 전에 자동으로 저장소를 확인하고 완료 후 지속적인 학습을 작성합니다 - 추가 프롬프팅이나 구성이 필요하지 않습니다.

    저장소의 각 메모리는 API 또는 Console을 통해 직접 액세스하고 편집할 수 있으므로 메모리를 조정, 가져오기, 내보내기할 수 있습니다.

    메모리에 대한 모든 변경은 불변 memory_version을 생성하여 메모리 변경 사항의 감사 및 롤백을 지원합니다.

    메모리 저장소 생성

    저장소에 name과 description을 지정합니다. 설명은 에이전트에 전달되어 저장소에 포함된 내용을 알려줍니다.

    Was this page helpful?

    store=$(curl -fsS https://api.anthropic.com/v1/memory_stores \
      -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" \
      --data @- <<EOF
    {
      "name": "User Preferences",
      "description": "Per-user preferences and project context."
    }
    EOF
    )
    store_id=$(jq -r '.id' <<< "$store")
    echo "$store_id"  # memstore_01Hx...

    메모리 저장소 id (memstore_...)는 저장소를 세션에 연결할 때 전달하는 것입니다.

    콘텐츠로 시드하기 (선택 사항)

    에이전트가 실행되기 전에 저장소를 참고 자료로 미리 로드합니다:

    curl -fsS "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: managed-agents-2026-04-01" \
      -H "content-type: application/json" \
      --data @- > /dev/null <<EOF
    {
      "path": "/formatting_standards.md",
      "content": "All reports use GAAP formatting. Dates are ISO-8601..."
    }
    EOF

    저장소 내의 개별 메모리는 100KB(약 25K 토큰)로 제한됩니다. 메모리를 몇 개의 큰 파일이 아닌 많은 작은 집중된 파일로 구조화합니다.

    세션에 메모리 연결

    메모리 저장소는 세션의 resources[] 배열에 연결됩니다.

    선택적으로 prompt를 포함하여 이 메모리 저장소를 사용하는 방법에 대해 Claude에 세션별 지침을 제공할 수 있습니다. 메모리 저장소의 name과 description에 추가로 제공되며 4,096자로 제한됩니다.

    access도 구성할 수 있습니다. 기본값은 read_write이지만 read_only도 지원됩니다(아래 예제에서 명시적으로 표시됨).

    session=$(curl -fsS 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" \
      --data @- <<EOF
    {
      "agent": "$agent_id",
      "environment_id": "$environment_id",
      "resources": [
        {
          "type": "memory_store",
          "memory_store_id": "$store_id",
          "access": "read_write",
          "prompt": "User preferences and project context. Check before starting any task."
        }
      ]
    }
    EOF
    )

    세션당 최대 8개의 메모리 저장소가 지원됩니다. 메모리의 다른 부분이 다른 소유자 또는 액세스 규칙을 가질 때 여러 저장소를 연결합니다. 일반적인 이유:

    • 공유 참고 자료 - 많은 세션에 연결된 하나의 읽기 전용 저장소(표준, 규칙, 도메인 지식)로, 각 세션의 자체 읽기-쓰기 학습과 분리됨.
    • 제품 구조에 매핑 - 단일 에이전트 구성을 공유하면서 최종 사용자당, 팀당 또는 프로젝트당 하나의 저장소.
    • 다른 수명 주기 - 단일 세션보다 오래 지속되는 저장소 또는 자체 일정에 따라 보관하려는 저장소.

    메모리 도구

    메모리 저장소가 세션에 연결되면, 에이전트는 자동으로 메모리 도구에 액세스할 수 있습니다. 메모리 저장소와의 에이전트 상호작용은 이벤트 스트림에서 agent.tool_use 이벤트로 등록됩니다.

    도구설명
    memory_list저장소의 문서를 나열하며, 선택적으로 경로 접두사로 필터링합니다.
    memory_search문서 콘텐츠 전체에서 전체 텍스트 검색을 수행합니다.
    memory_read문서의 콘텐츠를 읽습니다.
    memory_write경로에 문서를 생성하거나 덮어씁니다.
    memory_edit기존 문서를 수정합니다.
    memory_delete문서를 제거합니다.

    메모리 검사 및 수정

    메모리 저장소는 API를 통해 직접 관리할 수 있습니다. 이를 사용하여 검토 워크플로우를 구축하거나, 잘못된 메모리를 수정하거나, 세션이 실행되기 전에 저장소를 시드합니다.

    메모리 나열

    나열은 메모리 콘텐츠를 반환하지 않고 객체 메타데이터만 반환합니다. 디렉토리 범위 목록에 path_prefix를 사용합니다(후행 슬래시 포함: /notes/는 /notes/a.md와 일치하지만 /notes_backup/old.md와는 일치하지 않음).

    page=$(curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memories?path_prefix=/" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: managed-agents-2026-04-01")
    jq -r '.data[] | "\(.path)  (\(.size_bytes) bytes, sha=\(.content_sha256[0:8]))"' <<< "$page"

    메모리 읽기

    개별 메모리를 가져오면 전체 문서 콘텐츠가 반환됩니다.

    mem=$(curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$memory_id" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: managed-agents-2026-04-01")
    jq -r '.content' <<< "$mem"

    문서 작성

    memories.write를 사용하여 경로별로 문서를 업서트합니다. 경로에 아무것도 없으면 생성되고, 문서가 이미 있으면 콘텐츠가 바뀝니다. mem_... ID별로 기존 문서를 변경하려면(예: 경로 이름을 바꾸거나 콘텐츠 편집을 안전하게 적용하려면), 대신 memories.update를 사용합니다(아래 업데이트 참조).

    mem=$(curl -fsS "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: managed-agents-2026-04-01" \
      -H "content-type: application/json" \
      --data @- <<EOF
    {
      "path": "/preferences/formatting.md",
      "content": "Always use tabs, not spaces."
    }
    EOF
    )

    경로가 비어있을 때만 생성

    precondition={"type": "not_exists"}를 memories.write에 전달하여 생성 전용 가드를 만듭니다. 경로에 문서가 이미 있으면 쓰기는 대신 바꾸지 않고 409 memory_precondition_failed를 반환합니다. 저장소를 시드할 때 기존 콘텐츠를 덮어쓰지 않으려는 경우 이를 사용합니다.

    curl -fsS "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: managed-agents-2026-04-01" \
      -H "content-type: application/json" \
      --data @- > /dev/null <<EOF
    {
      "path": "/preferences/formatting.md",
      "content": "Always use 2-space indentation.",
      "precondition": {"type": "not_exists"}
    }
    EOF

    기존 문서를 안전하게 편집하려면(읽기, 수정, 동시 변경을 덮어쓰지 않고 다시 쓰기), 대신 content_sha256 사전 조건과 함께 memories.update를 사용합니다. 아래 업데이트를 참조하세요.

    업데이트

    memories.update()는 mem_... ID로 기존 문서를 수정합니다. 한 번의 호출로 content, path(이름 바꾸기) 또는 둘 다를 변경할 수 있습니다.

    점유된 경로로 이름을 바꾸면 409 conflict를 반환합니다. 호출자는 먼저 차단자를 삭제하거나 이름을 바꾸거나, precondition={"type": "not_exists"}를 전달하여 대상에 이미 있는 것이 있으면 이름 바꾸기를 작동 없음으로 만들어야 합니다.

    아래 예제는 문서를 아카이브 경로로 이름을 바꿉니다:

    curl -fsS -X PATCH "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
      -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 '{"path": "/archive/2026_q1_formatting.md"}' > /dev/null

    안전한 콘텐츠 편집 (낙관적 동시성)

    동시 쓰기를 덮어쓰지 않고 문서의 콘텐츠를 편집하려면 content_sha256 사전 조건을 전달합니다. 업데이트는 저장된 해시가 읽은 것과 여전히 일치하는 경우에만 적용되며, 불일치 시 409 memory_precondition_failed를 반환합니다. 이 시점에서 문서를 다시 읽고 새로운 상태에 대해 다시 시도합니다.

    curl -fsS -X PATCH "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
      -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" \
      --data @- > /dev/null <<EOF
    {
      "content": "CORRECTED: Always use 2-space indentation.",
      "precondition": {"type": "content_sha256", "content_sha256": "$mem_sha"}
    }
    EOF

    문서 삭제

    curl -fsS -X DELETE "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: managed-agents-2026-04-01" > /dev/null

    선택적으로 조건부 삭제를 위해 expected_content_sha256을 전달합니다.

    메모리 버전

    메모리에 대한 모든 변경은 불변 메모리 버전 (memver_...)을 생성합니다. 버전은 부모 메모리의 수명 동안 누적되며 그 아래의 감사 및 롤백 표면을 형성합니다. 라이브 memories.retrieve 호출은 항상 현재 헤드를 반환하고, 버전 엔드포인트는 전체 기록을 제공합니다.

    모든 변경에서 새 버전이 작성됩니다:

    • 경로에 대한 첫 번째 memories.write는 operation: "created"를 사용하여 버전을 생성합니다.
    • content, path 또는 둘 다를 변경하는 memories.update는 operation: "modified"를 사용하여 버전을 생성합니다.
    • memories.delete는 operation: "deleted"를 사용하여 버전을 생성합니다.

    버전 엔드포인트를 사용하여 어떤 사용자 또는 에이전트가 무엇을 언제 변경했는지 감사하고, 이전 스냅샷을 검사하거나 복원하고, 삭제를 통해 기록에서 민감한 콘텐츠를 제거합니다.

    버전 나열

    저장소의 페이지 매김된 버전 메타데이터를 최신순으로 나열합니다. memory_id, operation (created, modified, 또는 deleted), session_id, api_key_id, 또는 created_at_gte/created_at_lte 시간 범위로 필터링할 수 있습니다. 목록 응답에는 content 본문이 포함되지 않습니다. 전체 내용이 필요한 경우 retrieve를 사용하여 개별 버전을 가져옵니다.

    curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions?memory_id=$mem_id" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: managed-agents-2026-04-01" \
      | jq -r '.data[] | "\(.id): \(.operation)"'

    버전 검색

    개별 버전을 가져오면 목록 응답과 동일한 필드와 전체 content 본문이 반환됩니다.

    curl -fsS "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions/$version_id" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: managed-agents-2026-04-01"

    버전 수정

    수정은 감사 추적(누가 무엇을 언제 했는지)을 유지하면서 과거 버전의 내용을 제거합니다. 유출된 비밀, 개인 식별 정보, 또는 사용자 삭제 요청 제거와 같은 규정 준수 워크플로우에 사용합니다. 수정은 content, content_sha256, content_size_bytes, 및 path를 완전히 제거합니다. 행위자 및 타임스탬프를 포함한 다른 모든 필드는 유지됩니다.

    curl -fsS -X POST "https://api.anthropic.com/v1/memory_stores/$store_id/memory_versions/$version_id/redact" \
      -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 '{}'