Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
각 Managed Agents 세션은 기본적으로 새로운 컨텍스트로 시작합니다. 세션이 종료되면 에이전트가 구축한 모든 상태가 사라집니다. 메모리 스토어를 사용하면 에이전트가 사용자 선호도, 프로젝트 규칙, 이전 실수, 도메인 컨텍스트와 같은 정보를 세션 간에 유지할 수 있습니다.
메모리 스토어는 Claude에 최적화된 워크스페이스 범위의 텍스트 문서 모음입니다. 스토어를 세션에 연결하면 세션의 샌드박스 내부에 디렉터리로 마운트됩니다. 에이전트는 나머지 파일시스템에 사용하는 것과 동일한 파일 도구로 이를 읽고 쓰며, 각 마운트를 설명하는 노트가 시스템 프롬프트에 자동으로 추가되어 에이전트에게 어디를 봐야 하는지 알려줍니다. 이러한 상호작용에는 에이전트 도구 세트가 필요하므로 에이전트 생성 시 반드시 활성화하세요.
스토어의 각 메모리는 경로로 지정되며 API 또는 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[] 배열에 연결됩니다. 파일 및 저장소 리소스와 달리 메모리 스토어는 세션 생성 시에만 연결할 수 있으며, 실행 중인 세션에서 추가하거나 제거하는 것은 지원되지 않습니다.
선택적으로 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에 메모리를 생성합니다. create는 덮어쓰지 않습니다. 기존 메모리를 변경하려면 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/nullant 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는 감사 추적(누가, 무엇을, 언제)을 보존하면서 과거 버전에서 콘텐츠를 제거합니다. 유출된 시크릿, 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를 사용하세요.
스토어가 2,000개 메모리 제한에 도달하면 새 메모리에 대한 쓰기가 실패합니다. 직접적인 memories.create 호출과 매핑되지 않은 경로에 대한 에이전트의 파일 쓰기 모두 해당됩니다. 기존 메모리는 계속 읽고 편집할 수 있습니다. 다음 사례는 제한에 여유를 두고 제한에 도달하더라도 원활하게 복구하는 데 도움이 됩니다.
목적이 명확한 스토어를 사용하세요. 하나의 큰 범용 스토어 대신 사용자별 하나, 공유 도메인 지식용 하나, 프로젝트별 컨텍스트용 하나와 같이 목적에 맞게 구성된 작은 스토어를 사용하세요. 각 스토어는 자체적으로 2,000개 메모리 제한을 가지므로 스토어의 범위를 좁게 유지하면 어느 하나가 가득 찰 가능성이 줄어듭니다.
스토어가 가득 차기 전에 압축하거나 정리하세요. memories.delete로 오래되었거나 중복된 메모리를 삭제하세요. 또한 드리밍 세션을 실행할 수도 있습니다. 이는 원본을 수정하는 대신 단편화된 콘텐츠를 별도의 새 출력 스토어로 통합합니다. 세션을 해당 출력 스토어로 전환한 다음 원본을 보관하거나 삭제하세요.
필요할 때 새 스토어를 연결하세요. 스토어가 유용한 범위를 넘어 커졌다면 새 콘텐츠를 위한 새 스토어를 연결하고 원본은 read_only 접근 권한으로 연결하세요. 에이전트는 둘 다 읽을 수 있지만 새 스토어에만 쓸 수 있습니다.
적절한 경우 쓰기 접근을 제한하세요. 공유 참조 자료만 읽는 세션에는 read_write가 필요하지 않습니다. 실제로 새 메모리를 추가하는 세션으로 쓰기 접근 범위를 제한하면 증가가 어디에서 발생하는지 추적하기가 더 쉬워집니다.
Was this page helpful?