에이전트 메모리 사용하기

각 Managed Agents 세션은 기본적으로 새로운 컨텍스트로 시작합니다. 세션이 종료되면 에이전트가 쌓아 온 모든 상태는 사라집니다. "Memory store"(메모리 스토어)를 사용하면 에이전트가 사용자 선호도, 프로젝트 규칙, 이전의 실수, 도메인 컨텍스트 등의 정보를 세션 간에 이어서 가져갈 수 있습니다.

개요

메모리 스토어는 Claude에 최적화된, 워크스페이스 범위의 텍스트 문서 모음입니다. 스토어를 세션에 연결하면 세션의 샌드박스 내부에 디렉터리로 마운트됩니다. 에이전트는 파일 시스템의 나머지 부분에 사용하는 것과 동일한 파일 도구로 이를 읽고 쓰며, 각 마운트를 설명하는 메모가 시스템 프롬프트에 자동으로 추가되어 에이전트에게 어디를 살펴봐야 하는지 알려 줍니다. 이러한 상호작용에는 에이전트 도구 세트가 필요하므로, 에이전트 생성 시 반드시 활성화하세요. 자체 호스팅 샌드박스에서는 해당 디렉터리가 라이브 마운트가 아닙니다. 대신 SDK의 환경 워커가 에이전트의 도구가 실행되기 전에 연결된 각 스토어를 샌드박스로 다운로드하고, 해당 사본을 스토어와 동기화된 상태로 유지합니다.

스토어 내의 각 메모리는 경로로 지정되며, API 또는 Claude Console을 통해 직접 읽고 편집할 수 있어 튜닝, 가져오기, 내보내기가 가능합니다.

메모리에 대한 모든 변경은 변경 불가능한 메모리 버전을 생성하므로, 에이전트가 작성하는 모든 내용에 대해 감사 추적과 특정 시점 복구가 가능합니다.

메모리 스토어 생성

스토어에 name과 description을 지정하세요. description은 에이전트에게 전달되어 스토어에 무엇이 들어 있는지 알려 줍니다.

store_id=$(ant beta:memory-stores create \
  --name "User Preferences" \
  --description "Per-user preferences and project context." \
  --transform id --raw-output)

메모리 스토어 id(memstore_...)는 스토어를 세션에 연결할 때 전달하는 값입니다.

콘텐츠로 초기화하기(선택 사항)

에이전트가 실행되기 전에 스토어에 참조 자료를 미리 로드하세요.

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/formatting_standards.md" \
  --content "All reports use GAAP formatting. Dates are ISO-8601..." \
  > /dev/null

세션에 메모리 스토어 연결

메모리 스토어는 세션이 생성될 때 세션의 resources[] 배열에 연결됩니다. 파일 리소스와 달리 메모리 스토어는 세션 생성 시점에만 연결할 수 있으며, 실행 중인 세션에서 추가하거나 제거하는 것은 지원되지 않습니다. 클라우드 및 자체 호스팅 환경의 세션 모두 동일한 방식으로 메모리 스토어를 연결합니다. 자체 호스팅 환경은 memory_store 리소스만 허용합니다.

선택적으로 instructions를 포함하여 에이전트가 이 스토어를 어떻게 사용해야 하는지에 대한 세션별 지침을 제공할 수 있습니다. 이는 스토어의 name 및 description과 함께 에이전트에게 표시되며, 4,096자로 제한됩니다.

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

ant beta:sessions create <<YAML
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.
YAML

세션당 최대 8개의 메모리 스토어가 지원됩니다. 메모리의 서로 다른 부분에 소유자나 액세스 규칙이 다를 경우 여러 스토어를 연결하세요. 일반적인 이유는 다음과 같습니다.

• 공유 참조 자료: 여러 세션에 연결되는 하나의 읽기 전용 스토어(표준, 규칙, 도메인 지식)를 각 세션 고유의 읽기-쓰기 스토어와 분리하여 유지합니다.
• 제품 구조에 매핑: 단일 에이전트 구성을 공유하면서 최종 사용자별, 팀별 또는 프로젝트별로 하나의 스토어를 둡니다.
• 서로 다른 수명 주기: 단일 세션보다 오래 유지되는 스토어, 또는 자체 일정에 따라 아카이브하려는 스토어입니다.

에이전트가 메모리에 액세스하는 방법

연결된 각 스토어는 세션의 샌드박스 내부에 /mnt/memory/ 아래의 디렉터리로 마운트됩니다. 디렉터리 이름은 스토어의 표시 이름을 파일 시스템에 안전한 슬러그로 정리한 것(소문자화, 영숫자가 아닌 연속 문자는 하나의 하이픈으로 변환)이므로, "Demo Memory"라는 이름의 스토어는 /mnt/memory/demo-memory/에 마운트됩니다. 정확한 경로는 세션의 메모리 스토어 리소스에 있는 mount_path 필드로 반환되므로, 직접 구성하지 말고 거기서 읽으세요. 에이전트는 표준 에이전트 도구 세트로 스토어를 읽고 씁니다. 마운트 경로 아래의 쓰기는 스토어에 다시 영구 저장되며 이를 공유하는 세션 간에 동기화된 상태로 유지됩니다. /mnt/memory/ 아래의 다른 경로에 대한 쓰기는 실패하는데, 샌드박스가 해당 상위 디렉터리를 읽기 전용으로 마운트하기 때문입니다. 각 마운트에 대한 짧은 설명(표시 이름, 마운트 경로, 액세스 모드, 스토어 description 및 모든 instructions)이 시스템 프롬프트에 자동으로 추가됩니다.

access는 파일 시스템 수준에서 적용됩니다. read_only 마운트는 쓰기를 거부하며, read_write 마운트에 대한 쓰기는 해당 세션에 귀속되는 메모리 버전을 생성합니다.

에이전트의 읽기 및 쓰기는 마운트에 접근한 도구에 대한 일반적인 agent.tool_use 및 agent.tool_result 이벤트로 이벤트 스트림에 나타납니다.

메모리 보기 및 편집

메모리 스토어는 API를 통해 직접 관리할 수 있습니다. 검토 워크플로 구축, 잘못된 메모리 수정 또는 세션 실행 전 스토어 초기화에 이를 사용하세요.

메모리 목록 조회

스토어의 메모리 목록을 조회합니다. 결과는 안정적인 서버 정의 순서로 반환됩니다.

• path_prefix는 목록을 하나의 디렉터리로 범위를 한정합니다. /로 끝나야 하며 전체 경로 세그먼트와 일치하므로, path_prefix=/notes/는 /notes/todo.md를 반환하지만 /notes-archive/todo.md는 반환하지 않습니다.
• depth는 path_prefix 아래로 목록이 얼마나 깊이 내려가는지를 제어합니다. 생략하거나(0 전달) 전체 하위 트리를 나열하거나, 1을 전달하여 직계 하위 항목만 나열합니다. 다른 값은 400 오류를 반환합니다.

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/"

전체 매개변수 및 응답 스키마는 메모리 목록 조회 레퍼런스를 참조하세요.

메모리 읽기

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

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

전체 매개변수 및 응답 스키마는 메모리 조회 레퍼런스를 참조하세요.

메모리 생성

memories.create는 지정된 path에 메모리를 생성합니다. 생성은 덮어쓰지 않습니다. 기존 메모리를 변경하려면 memories.update를 사용하세요.

mem=$(ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces." \
  --format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")

전체 매개변수 및 응답 스키마는 메모리 생성 레퍼런스를 참조하세요.

메모리 업데이트

memories.update는 ID로 기존 메모리를 수정합니다. content, path(이름 변경) 또는 둘 다 변경할 수 있습니다. 예시에서는 메모리를 아카이브 경로로 이름을 변경합니다.

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md" \
  > /dev/null

전체 매개변수 및 응답 스키마는 메모리 업데이트 레퍼런스를 참조하세요.

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

동시 쓰기를 덮어쓰는 것을 방지하려면 content_sha256 전제 조건을 전달하세요. 업데이트는 저장된 콘텐츠 해시가 읽었을 때의 해시와 여전히 일치하는 경우에만 적용됩니다. 불일치 시 메모리를 다시 읽고 최신 상태에 대해 재시도하세요.

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --content "CORRECTED: Always use 2-space indentation." \
  --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
  > /dev/null

메모리 삭제

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  > /dev/null

전체 매개변수 및 응답 스키마는 메모리 삭제 레퍼런스를 참조하세요.

메모리 변경 감사

메모리에 대한 모든 변경은 변경 불가능한 메모리 버전(memver_...)을 생성합니다. 버전 엔드포인트를 사용하여 누가 무엇을 언제 변경했는지 감사하고, 이전 스냅샷을 검사하거나 복원하고, redact로 기록에서 민감한 콘텐츠를 제거하세요.

버전은 (개별 메모리가 아닌) 스토어에 속하며 메모리 자체가 삭제되어도 삭제되지 않으므로, 아래에 설명된 보존 정책에 따라 감사 추적은 삭제된 메모리도 포함합니다. 버전은 작성된 후 30일 동안 보존됩니다. 다만 라이브 메모리의 최근 버전은 기간에 관계없이 항상 유지되므로, 자주 변경되지 않는 메모리는 30일을 넘어서도 기록을 보존할 수 있습니다. 라이브 memories.retrieve 호출은 항상 최신 버전을 반환하며, 버전 엔드포인트는 보존된 기록을 제공합니다.

전용 복원 엔드포인트는 없습니다. 롤백하려면 원하는 버전을 조회하고 해당 content를 memories.update로 다시 쓰세요(상위 메모리가 삭제된 경우에는 원하는 버전이 아직 보존되어 있다면 memories.create를 사용하세요).

과거 메모리 버전은 30일 후에 삭제될 수 있습니다. 메모리 기록을 더 오래 보존하려면 API를 통해 버전을 내보내세요.

버전 목록 조회

스토어의 버전 기록을 최신순으로 나열합니다. 예시에서는 단일 메모리의 기록으로 필터링합니다.

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
# `list --format json`은 항목당 하나의 JSON 객체를 출력합니다.
jq -r '"\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -rs '.[1].id' <<< "$versions")

전체 매개변수 및 응답 스키마는 메모리 버전 목록 조회 레퍼런스를 참조하세요.

버전 조회

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

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

전체 매개변수 및 응답 스키마는 메모리 버전 조회 레퍼런스를 참조하세요.

버전 수정(redact)

Redact는 감사 추적(누가 무엇을 언제 했는지)을 보존하면서 과거 버전에서 콘텐츠를 제거합니다. 유출된 시크릿, PII 제거 또는 사용자 삭제 요청과 같은 컴플라이언스 워크플로에 사용하세요.

라이브 메모리의 현재 헤드인 버전은 redact할 수 없습니다. 먼저 새 버전을 작성하거나(또는 메모리를 삭제한 후) 이전 버전을 redact하세요.

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

전체 매개변수 및 응답 스키마는 메모리 버전 redact 레퍼런스를 참조하세요.

메모리 스토어 관리

create 외에도 메모리 스토어는 retrieve, update, list, archive, delete를 지원합니다.

스토어 목록 조회

워크스페이스의 스토어 목록을 조회합니다. 아카이브된 스토어는 기본적으로 제외되며, 포함하려면 include_archived: true를 전달하세요.

ant beta:memory-stores list --include-archived

전체 매개변수 및 응답 스키마는 메모리 스토어 목록 조회 레퍼런스를 참조하세요.

스토어 아카이브

아카이브하면 스토어가 읽기 전용이 되고 새 세션에 연결할 수 없게 됩니다. 아카이브는 단방향이며, 아카이브 해제는 없습니다.

ant beta:memory-stores archive --memory-store-id "$store_id"

전체 매개변수 및 응답 스키마는 메모리 스토어 아카이브 레퍼런스를 참조하세요.

스토어를 모든 메모리 및 버전과 함께 영구적으로 제거하려면 memory_stores.delete를 사용하세요.

메모리 관리 모범 사례

스토어가 10,000개 메모리 한도에 도달하면 새 메모리에 대한 쓰기가 실패합니다. 직접적인 memories.create 호출과 매핑되지 않은 경로에 대한 에이전트의 파일 쓰기 모두 해당됩니다. 기존 메모리는 계속 읽고 편집할 수 있습니다. 다음 사례는 한도보다 훨씬 아래에 머무르고, 한도에 도달하더라도 원활하게 복구하는 데 도움이 됩니다.

• 집중된 스토어를 사용하세요. 하나의 큰 범용 스토어 대신, 사용자별 스토어, 공유 도메인 지식용 스토어, 프로젝트별 컨텍스트용 스토어처럼 목적에 맞게 만든 더 작은 스토어를 사용하세요. 각 스토어에는 자체적인 10,000개 메모리 한도가 있으므로, 스토어의 범위를 한정하면 어느 하나가 가득 찰 가능성이 줄어듭니다.

• 스토어가 가득 차기 전에 압축하거나 정리하세요. memories.delete로 오래되었거나 중복된 메모리를 삭제하세요. 드리밍 세션을 실행할 수도 있는데, 이는 원본을 수정하는 대신 단편화된 콘텐츠를 별도의 새 출력 스토어로 통합합니다. 세션을 해당 출력 스토어로 전환한 다음 원본을 아카이브하거나 삭제하세요.

• 적절한 경우 새 스토어를 연결하세요. 스토어가 유용한 범위를 넘어 커졌다면, 새 콘텐츠를 위해 새 스토어를 연결하고 원본은 read_only 액세스로 연결하세요. 에이전트는 두 스토어 모두에서 읽을 수 있지만 새 스토어에만 씁니다.

• 적절한 경우 쓰기 액세스를 제한하세요. 공유 참조 자료만 읽는 세션에는 read_write가 필요하지 않습니다. 실제로 새 메모리를 추가하는 세션으로 쓰기 액세스 범위를 한정하면 증가가 어디에서 발생하는지 추적하기가 더 쉬워집니다.