에이전트 메모리 사용하기

각 Managed Agents 세션은 기본적으로 새로운 컨텍스트로 시작됩니다. 세션이 종료되면 에이전트가 구축한 모든 상태는 사라집니다. 메모리 스토어를 사용하면 에이전트가 사용자 선호도, 프로젝트 규칙, 이전 실수, 도메인 컨텍스트와 같은 정보를 세션 간에 유지할 수 있습니다.



개요

**"Memory store"(메모리 스토어)**는 Claude에 최적화된 워크스페이스 범위의 텍스트 문서 모음입니다. 스토어를 세션에 연결하면 세션의 샌드박스 내부에 디렉터리로 마운트됩니다. 에이전트는 파일 시스템의 나머지 부분에 사용하는 것과 동일한 파일 도구로 이를 읽고 쓰며, 각 마운트를 설명하는 메모가 시스템 프롬프트에 자동으로 추가되어 에이전트에게 어디를 참조해야 하는지 알려줍니다. 이러한 상호작용에는 에이전트 도구 세트가 필요하므로 에이전트 생성 시 반드시 활성화하세요.

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

메모리에 대한 모든 변경은 불변의 **"memory version"(메모리 버전)**을 생성하여 에이전트가 작성하는 모든 내용에 대한 감사 추적과 특정 시점 복구를 제공합니다.



메모리 스토어 생성하기

스토어에 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[] 배열에 연결됩니다. 파일 및 리포지토리 리소스와 달리 메모리 스토어는 세션 생성 시에만 연결할 수 있으며, 실행 중인 세션에서 추가하거나 제거하는 것은 지원되지 않습니다.

선택적으로 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로 필터링하여 경로를 디렉터리처럼 탐색할 수 있습니다:

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

전체 매개변수 및 응답 스키마는 메모리 나열 참조를 참조하세요.



메모리 읽기

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

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)
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")

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



버전 조회하기

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

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

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



버전 삭제(redact)하기

삭제(redact)는 감사 추적(누가 무엇을 언제 했는지)을 보존하면서 과거 버전에서 콘텐츠를 제거합니다. 유출된 비밀, PII 또는 사용자 삭제 요청 제거와 같은 규정 준수 워크플로에 사용하세요.

활성 메모리의 현재 헤드인 버전은 삭제할 수 없습니다. 먼저 새 버전을 작성하거나 메모리를 삭제한 다음 이전 버전을 삭제하세요.

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

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



메모리 스토어 관리하기

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를 사용하세요.



메모리 관리 모범 사례

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

• 집중된 스토어를 사용하세요. 하나의 큰 범용 스토어 대신 사용자별 하나, 공유 도메인 지식용 하나, 프로젝트별 컨텍스트용 하나와 같이 더 작은 목적별 스토어를 사용하세요. 각 스토어는 자체 2,000개 메모리 제한을 가지므로 스토어의 범위를 제한하면 단일 스토어가 가득 찰 가능성이 줄어듭니다.

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

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

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