Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
각 Managed Agents 세션은 기본적으로 새로운 컨텍스트로 시작합니다. 세션이 종료되면 에이전트가 쌓아 온 모든 상태는 사라집니다. "Memory store"(메모리 스토어)를 사용하면 에이전트가 사용자 선호도, 프로젝트 규칙, 이전의 실수, 도메인 컨텍스트 등의 정보를 세션 간에 이어갈 수 있습니다.
메모리 스토어는 Claude에 최적화된, 워크스페이스 범위의 텍스트 문서 모음입니다. 스토어를 세션에 연결하면 세션의 샌드박스 내부에 디렉터리로 마운트됩니다. 에이전트는 파일 시스템의 나머지 부분에 사용하는 것과 동일한 파일 도구로 이를 읽고 쓰며, 각 마운트를 설명하는 메모가 시스템 프롬프트에 자동으로 추가되어 에이전트에게 어디를 살펴봐야 하는지 알려줍니다. 이러한 상호작용에는 에이전트 도구 세트가 필요하므로, 에이전트 생성 시 반드시 활성화하세요.
스토어 내의 각 메모리는 경로로 지정되며 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[] 배열에 연결됩니다. 파일 리소스와 달리 메모리 스토어는 세션 생성 시점에만 연결할 수 있으며, 실행 중인 세션에서 추가하거나 제거하는 것은 지원되지 않습니다.
선택적으로 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/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?