자체 호스팅 샌드박스의 메모리 스토어

자체 호스팅 환경의 세션은 클라우드 환경의 세션과 정확히 동일한 방식으로 메모리 스토어를 연결합니다. 세션에 메모리 스토어 연결에 나와 있는 것처럼, 세션을 생성할 때 resources에 메모리 스토어를 나열하세요. 하나의 세션은 최대 8개의 메모리 스토어를 허용합니다.

차이점은 누가 스토어를 구체화하는가입니다. 자체 호스팅 환경에서는 Anthropic의 인프라가 아니라 사용자의 워커가 각 스토어를 샌드박스로 다운로드하고 에이전트의 변경 사항을 다시 동기화합니다.

요구 사항

• 메모리 스토어를 마운트하는 워커: ant CLI 1.33.0 이상을 사용하거나, Python, TypeScript 또는 Go SDK의 EnvironmentWorker를 사용하세요.
• POSIX 파일 시스템: 워커가 메모리 파일을 열 때 O_NOFOLLOW가 필요하므로 Windows 호스트는 지원되지 않습니다. 대소문자만 다른 메모리 경로가 충돌하지 않도록 대소문자를 구분하는 파일 시스템을 권장합니다.
• 쓰기 가능한 /mnt/memory 디렉터리: 호스트 준비하기를 참조하세요.
• 작업 항목의 시크릿: 직접 작성한 코드가 워커를 실행하는 경우, 워커에 작업 항목의 시크릿을 전달하세요.

호스트 준비하기

워커를 시작하기 전에 상위 디렉터리를 생성하고, 워커를 실행하는 사용자가 쓸 수 있도록 설정하세요:

sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory

스토어별 디렉터리는 직접 생성하지 마세요. 워커는 세션이 시작될 때 각 스토어의 mount_path 디렉터리(예: /mnt/memory/user-preferences)를 생성하고 세션이 끝나면 제거합니다. 해당 경로에 이미 무언가가 존재하면 워커는 세션의 작업 시작을 거부합니다.

세션당 샌드박스 패턴에서는 샌드박스 이미지에 쓰기 가능한 /mnt/memory가 필요합니다. 워커가 샌드박스가 종료되기 전에 메모리 디렉터리의 내용을 스토어에 업로드하므로, 메모리 디렉터리를 호스트에 바인드 마운트할 필요는 없습니다.

스토어를 공유하는 세션 격리하기

두 세션은 동일한 경로가 필요하므로 하나의 호스트에서 같은 스토어를 동시에 마운트할 수 없습니다. 세션들이 같은 스토어를 연결하는 경우, 파일 시스템당 하나의 세션을 실행하세요. 각 세션에 자체 샌드박스를 제공하면 이 규칙을 충족합니다.

워커가 메모리를 처리하는 방식

워커가 메모리 스토어가 연결된 세션의 작업 항목을 가져오면 다음을 수행합니다:

1. 각 스토어를 해당 mount_path로 다운로드합니다. 이는 클라우드 세션이 사용하는 것과 동일한 /mnt/memory/ 아래의 디렉터리이며, 세션의 시스템 프롬프트가 이를 에이전트에게 설명합니다. 예를 들어 "User Preferences"라는 이름의 스토어는 /mnt/memory/user-preferences/에 위치합니다.
2. 파일 도구가 해당 디렉터리를 사용할 수 있게 합니다. 에이전트는 작업 디렉터리에서 사용하는 것과 동일한 파일 도구로 메모리를 다룹니다.
3. 도구 호출 후 변경 사항을 조정합니다. 이는 동기화 간격(기본값 15초)당 최대 한 번 수행됩니다. 스토어에서 변경된 메모리는 디스크에 기록되고, 에이전트가 변경한 파일은 스토어에 업로드됩니다.
4. 세션이 끝나면 최종 동기화를 실행합니다. 아직 대기 중인 업로드를 최대 30초 동안 플러시한 다음, 생성했던 디렉터리를 제거합니다.

Anthropic 측의 메모리 스토어가 계속해서 신뢰할 수 있는 원본(source of truth)으로 유지됩니다. 메모리 버전, 수정(redaction), 그리고 Console에서 메모리를 보거나 편집하는 기능은 클라우드 세션과 동일하게 작동합니다. 에이전트의 메모리 읽기 및 쓰기는 이벤트 스트림에 일반 도구 이벤트로 나타납니다.

각 워커는 일정 간격으로 동기화하므로, 한 세션에서 작성된 변경 사항은 두 세션이 모두 동기화된 후에야 실행 중인 다른 세션에 표시됩니다. 기본 간격에서는 일반적으로 1분보다 훨씬 짧습니다. 클라우드 샌드박스의 세션은 서로의 변경 사항을 거의 즉시 확인합니다.

각 스토어 디렉터리에는 디렉터리를 해당 스토어에 연결하는 .anthropic-memory-store라는 마커 파일이 있습니다. 이 파일을 그대로 두세요: 워커는 마커가 없거나 변경된 디렉터리를 동기화하지 않습니다.

동기화 구성하기

두 가지 EnvironmentWorker 옵션이 메모리 동작을 제어합니다. 웹훅 핸들러를 포함하여 워커를 생성하는 모든 곳에서 이를 설정하세요. ant CLI 워커는 항상 기본값을 사용합니다.

동기화 간격

memory_sync_interval는 세션이 실행되는 동안 연결된 스토어가 서버와 조정되는 빈도를 설정합니다.

간격이 짧을수록 다른 세션이 오래된 메모리를 보게 되는 시간 범위가 줄어들지만, 메모리 스토어 요청이 더 많아집니다.

메모리 스토어를 연결하지 않는 세션을 처리하는 워커에서만 메모리 지원을 비활성화하세요. 비활성화된 워커는 스토어를 다운로드하거나 동기화하지 않으므로, 스토어가 연결된 세션은 시스템 프롬프트가 여전히 스토어를 설명하고 있음에도 스토어 없이 실행됩니다.

메모리 지원이 활성화되어 있는 동안, 스토어가 연결된 세션에 대해 secret 없이 도착한 작업 항목은 메모리 없이 실행되는 대신 실패합니다. 메모리 스토어 마운트 실패를 참조하세요.

삭제

memory_sync_deletions는 에이전트가 로컬에서 삭제한 파일을 스토어에서도 삭제할지 여부를 설정합니다. 업로드와 다운로드에는 영향을 주지 않습니다.

예를 들어, 10초마다 동기화하고 워커가 수행했을 삭제를 로그로만 기록하려면 다음과 같이 합니다:

worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)

읽기 전용 스토어와 충돌

access: "read_only"로 연결된 스토어의 경우, write 및 edit 도구는 해당 디렉터리 내부의 파일 변경을 거부합니다. 워커는 해당 디렉터리에서 아무것도 업로드하지 않습니다.

bash를 통해, 또는 샌드박스에서 제공하는 사용자 정의 도구나 MCP 서버를 통해 이루어진 변경은 로컬에서 차단되지 않습니다. 이러한 변경은 스토어에 절대 동기화되지 않으며, 해당 메모리에 대한 다음 원격 변경이 이를 덮어씁니다. 세션 동안 로컬 사본 자체가 변경되지 않아야 하는 경우:

• 해당 에이전트의 bash 도구를 비활성화하고, 샌드박스의 파일 시스템에 쓰는 사용자 정의 도구를 제공하지 마세요.
• 스토어 경로를 읽기 전용으로 마운트하지 마세요. 워커 자체가 디렉터리를 생성하고 다운로드한 메모리를 그 안에 써야 합니다.

충돌은 스토어에 유리하게 해결됩니다. 세션이 마지막으로 동기화한 이후 스토어에서도 변경된 메모리 파일을 에이전트가 변경했다고 가정해 보겠습니다. 다음 동기화 시 워커는 스토어의 버전을 유지하고, 이를 로컬 파일에 덮어쓰며, 경고를 로그로 기록합니다. write 및 edit 도구 자체는 성공하며 에이전트에게 오류가 전달되지 않습니다. 에이전트의 변경이 여전히 유효하다면, 동기화 후 파일을 다시 읽고 변경을 다시 수행할 수 있습니다.

문제 해결

워커의 로그 메시지와 해결 방법은 메모리 스토어 마운트 실패를 참조하세요.