자체 호스팅 샌드박스의 메모리 스토어
자체 호스팅 샌드박스에서 실행되는 Claude Managed Agents 세션에 메모리 스토어를 연결합니다: 호스트를 준비하고, 동기화를 구성하고, 읽기 전용 스토어와 충돌을 처리합니다.
자체 호스팅 환경의 세션은 클라우드 환경의 세션과 똑같은 방식으로 메모리 스토어를 연결합니다. 세션에 메모리 스토어 연결에 나와 있는 것처럼, 세션을 생성할 때 resources에 나열하세요. 하나의 세션은 최대 8개의 메모리 스토어를 허용합니다.
차이점은 누가 스토어를 구체화하는가입니다. 자체 호스팅 환경에서는 Anthropic의 인프라가 아니라 사용자의 워커가 각 스토어를 샌드박스로 다운로드하고 에이전트의 변경 사항을 다시 동기화합니다.
요구 사항
- 메모리 스토어를 마운트하는 워커:
antCLI 1.33.0 이상을 사용하거나, Python, TypeScript 또는 Go SDK의EnvironmentWorker를 사용하세요. - POSIX 파일 시스템: 워커가 메모리 파일을 열 때
O_NOFOLLOW가 필요하므로 Windows 호스트는 지원되지 않습니다. Anthropic은 대소문자만 다른 메모리 경로가 충돌하지 않도록 대소문자를 구분하는 파일 시스템을 권장합니다. macOS 볼륨은 기본적으로 대소문자를 구분하지 않으므로 해당 환경에서는 이러한 경로가 충돌합니다. - 쓰기 가능한
/mnt/memory디렉터리: 호스트 준비를 참조하세요. macOS에서는 macOS 호스트 준비를 참조하세요. - 작업 항목의 시크릿: 직접 작성한 코드가 워커를 실행하는 경우, 워커에 작업 항목의 시크릿을 전달하세요.
호스트 준비하기
macOS에서는 다음 명령을 건너뛰고 대신 macOS 호스트 준비를 따르세요.
워커를 시작하기 전에 상위 디렉터리를 생성하고, 워커를 실행하는 사용자가 쓸 수 있도록 설정하세요:
sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory스토어의 디렉터리는 직접 생성하지 마세요. 워커는 세션을 가져올 때 각 스토어의 mount_path 디렉터리(예: /mnt/memory/user-preferences)를 생성하고, 해당 세션 처리를 마치면 이를 제거합니다. 해당 경로에 빈 디렉터리를 포함하여 무엇이든 이미 존재하면 워커는 작업 항목을 실패 처리합니다.
세션당 샌드박스 패턴에서는 샌드박스 이미지에 쓰기 가능한 /mnt/memory가 필요합니다. 스토어가 모든 메모리의 영구 사본을 보관하므로, 메모리 디렉터리를 호스트에 바인드 마운트할 필요는 없습니다.
macOS 호스트 준비
macOS에서는 루트 볼륨이 읽기 전용이므로 mkdir로 /mnt를 생성할 수 없습니다. 대신 쓰기 가능한 데이터 볼륨에 /System/Volumes/Data/mnt/memory를 생성하세요. 그런 다음 /etc/synthetic.conf에 한 줄을 추가하여 macOS가 /mnt를 /System/Volumes/Data/mnt에 대한 심볼릭 링크로 생성하도록 하세요. 이 단계에는 관리자 권한이 필요합니다.
이 설정이 없으면 워커가 스토어의 디렉터리를 생성할 수 없으므로 작업 항목이 실패합니다. 그러면 세션은 오류 이벤트 없이 유휴 상태로 유지됩니다. 메모리 스토어 마운트 또는 동기화 실패를 참조하세요.
데이터 볼륨에 디렉터리 생성
memory디렉터리를 생성하고 워커의 사용자를 소유자로 지정하세요.$USER는 본인의 사용자 이름입니다. 워커가 다른 사용자로 실행되는 경우"$USER"를 해당 사용자의 이름으로 바꾸세요.sudo mkdir -p /System/Volumes/Data/mnt/memory && sudo chown "$USER" /System/Volumes/Data/mnt/memory이 위치는 하나의 선택지일 뿐입니다. 다른 위치를 사용하는 경우
synthetic.conf줄의 경로도 그에 맞게 변경하세요. Anthropic은/System/Volumes/Data/mnt만 테스트했습니다.synthetic.conf에 한 줄 추가
cat -et /etc/synthetic.conf를 실행하세요. 이 명령은 각 탭을^I로, 각 줄 끝을$로 표시합니다.mnt^ISystem/Volumes/Data/mnt$라는 줄이 있으면 이 단계는 이미 완료된 것입니다. 다음 단계로 이동하세요.- 다른 줄이
mnt로 시작하면 중단하세요. 이 Mac의 다른 무언가가 이미/mnt를 정의하고 있습니다. - 마지막 줄이
$로 끝나지 않으면echo | sudo tee -a /etc/synthetic.conf를 실행하여 줄을 끝내세요. 그런 다음 해당 줄을 추가하세요. - 아무것도 출력되지 않거나
No such file or directory가 보고되면 해당 줄을 추가하세요. 파일이 없으면 다음 명령이 파일을 생성합니다. - 그 외의 경우에는 해당 줄을 추가하세요.
줄을 추가하려면 이 명령을 실행하세요. 실행할 때마다 줄이 하나씩 추가되므로 이 명령은 한 번만 실행하세요.
printf 'mnt\tSystem/Volumes/Data/mnt\n' | sudo tee -a /etc/synthetic.conf이 명령은 추가한 줄을 출력합니다. 이 줄은 이름
mnt를memory가 들어 있는 디렉터리에 매핑합니다. 파일의 두 열 사이에는 탭이 필요하며,\t가 이를 작성합니다.링크 생성
-t옵션과 함께apfs.util을 실행하세요. 이 명령은 재시작 없이 추가한 줄에서 링크를 생성합니다.sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t결과 확인
/mnt와/mnt/memory를 나열하세요.ls -ld /mnt /mnt/memory첫 번째 줄은
/mnt -> System/Volumes/Data/mnt로 끝납니다. 두 번째 줄은 워커의 사용자가/mnt/memory의 소유자임을 보여줍니다. 이제 워커를 시작할 수 있습니다.
Anthropic은 macOS 26.7.1에서 ant CLI 워커로 이 설정을 테스트했습니다.
스토어를 공유하는 세션 격리하기
두 세션은 동일한 경로가 필요하므로 하나의 파일 시스템에서 같은 스토어를 동시에 마운트할 수 없습니다. 스토어를 공유하는 세션들을 나란히 실행하려면 각 세션에 자체 파일 시스템을 제공하세요. 세션마다 샌드박스를 사용하면 각 세션이 자동으로 자체 파일 시스템을 갖게 됩니다. 세션당 하나의 샌드박스 실행을 참조하세요. 하나의 호스트에서 이러한 샌드박스를 여러 개 실행할 수 있습니다.
워커가 메모리를 처리하는 방식
워커가 메모리 스토어가 연결된 세션의 작업 항목을 가져오면 다음을 수행합니다:
- 각 스토어를 해당
mount_path에 다운로드합니다. 이는 클라우드 세션이 사용하는 것과 동일한/mnt/memory/아래의 디렉터리이며, 세션의 시스템 프롬프트가 이를 에이전트에게 설명합니다. 예를 들어, “User Preferences”라는 이름의 스토어는/mnt/memory/user-preferences/에 위치합니다. - 파일 도구가 해당 디렉터리를 사용할 수 있게 합니다. 에이전트는 작업 디렉터리에서 사용하는 것과 동일한 파일 도구로 메모리를 다룹니다.
- 도구 호출 후 동기화합니다. 마지막 동기화 이후 동기화 간격(기본값 15초)이 지났다면 워커는 도구 호출 후 동기화합니다. 각 동기화는 스토어에서 변경된 메모리를 디스크에 기록하고 에이전트가 변경한 파일을 업로드합니다.
- 세션이 끝나거나 워커의 “idle limit”(유휴 제한 시간) 동안 유휴 상태로 유지되면 최종 동기화를 실행합니다. 최종 동기화는 최대 60초가 걸릴 수 있습니다. 그때까지 업로드되지 않은 변경 사항은 손실됩니다. 그런 다음 워커는 생성했던 디렉터리를 제거합니다.
유휴 제한 시간은 기본적으로 60초입니다. 워커가 세션 처리를 마치는 시점에서 이 제한 시간이 무엇에 적용되는지와 이를 변경하는 방법을 설명합니다.
에이전트의 write 및 edit 도구는 로컬 사본만 변경하며, 워커는 다음 동기화 시 해당 변경 사항을 업로드합니다. 스토어 디렉터리 외부에 있는 /mnt/memory/ 아래의 경로는 임시 작업 공간이 아닙니다. 워커의 파일 도구는 해당 경로에 쓰기를 거부하며, 셸 명령이 그곳에 쓴 내용은 스토어에 절대 동기화되지 않습니다.
메모리 버전, 버전 콘텐츠 제거(redact), 그리고 Claude Console에서 메모리를 보거나 편집하는 기능은 클라우드 세션에서와 동일하게 작동합니다. 에이전트의 메모리 읽기 및 쓰기는 이벤트 스트림에 일반적인 도구 이벤트로 나타납니다.
각 스토어 디렉터리에는 디렉터리를 해당 스토어에 연결하는 .anthropic-memory-store라는 마커 파일이 있습니다. 이 파일을 그대로 두세요. 마커가 없거나 변경되었고 디렉터리에 여전히 파일이 있으면 워커는 해당 디렉터리를 동기화하지 않습니다. 또한 세션 처리를 마칠 때 해당 디렉터리를 제거하지도 않습니다.
동기화 구성하기
두 가지 EnvironmentWorker 옵션이 메모리 동작을 제어합니다. 웹훅 핸들러를 포함하여 워커를 생성하는 모든 곳에서 이를 설정하세요. ant CLI 워커는 항상 기본값을 사용합니다.
동기화 간격
memory_sync_interval는 세션이 실행되는 동안 두 동기화 사이의 최소 시간을 설정합니다.
| 설정 | 값 |
|---|---|
| 기본값 | 15초 |
| 최솟값 | 5초 |
| 예시(10초) | 10 |
| 메모리 지원 비활성화 | None |
워커는 타이머에 따라 동기화하지 않습니다. bash, read 또는 사용자 정의 도구처럼 샌드박스에서 실행되는 도구가 호출될 때마다 그 후에 간격을 확인합니다. 해당 호출이 메모리를 건드릴 필요는 없습니다. 도구 호출이 없으면 최종 동기화 전까지 아무것도 동기화되지 않습니다. 한 세션의 변경 사항은 두 세션이 모두 동기화된 후에야 실행 중인 다른 세션에 도달하므로, 대기 시간은 고정되어 있지 않습니다.
간격이 짧을수록 다른 세션이 오래된 메모리를 보게 되는 시간 범위가 줄어들지만, 메모리 스토어 요청이 더 많아집니다.
메모리 스토어를 연결하지 않는 세션을 처리하는 워커에서만 메모리 지원을 비활성화하세요. 비활성화된 워커는 스토어를 다운로드하거나 동기화하지 않으므로, 스토어가 연결된 세션은 시스템 프롬프트가 여전히 스토어를 설명하고 있음에도 스토어 없이 실행됩니다.
메모리 지원이 활성화된 상태에서, 스토어가 연결된 세션에 대해 secret 없이 도착한 작업 항목은 메모리 없이 실행되는 대신 실패합니다. 메모리 스토어 마운트 또는 동기화 실패를 참조하세요.
삭제
memory_sync_deletions는 에이전트가 로컬에서 삭제한 파일을 스토어에서도 삭제할지 여부를 설정합니다. 업로드와 다운로드에는 영향을 주지 않습니다.
| 값 | 동작 |
|---|---|
"enabled" (기본값) | 이후 동기화에서 파일이 여전히 없는 것으로 확인되면 스토어에서 메모리를 삭제합니다. |
"log_only" | 동일한 검사를 실행하지만 삭제했을 항목을 로그로만 기록합니다. 활성화 모드를 신뢰하기 전에 워커가 무엇을 삭제할지 관찰하는 데 사용하세요. |
"disabled" | 스토어에서 절대 삭제하지 않습니다. |
예를 들어, 최대 10초에 한 번 동기화하고 워커가 수행했을 삭제를 로그로만 기록하려면 다음 샘플을 사용하세요. 이 샘플은 작업 디렉터리로 /workspace를 사용하며, 이 디렉터리는 워커가 시작되기 전에 존재해야 합니다. 디렉터리를 생성하는 방법과 macOS에서 사용할 항목은 상시 실행 워커 실행을 참조하세요.
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
async def main() -> None:
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
async with AsyncAnthropic(auth_token=environment_key) as client:
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
memory_sync_interval=10, # seconds
memory_sync_deletions="log_only",
)
task = asyncio.create_task(worker.run())
loop = asyncio.get_running_loop()
for signum in (signal.SIGINT, signal.SIGTERM):
loop.add_signal_handler(signum, task.cancel)
with contextlib.suppress(asyncio.CancelledError):
await task
asyncio.run(main())읽기 전용 스토어와 충돌
읽기 전용 스토어
access: "read_only"로 연결된 스토어의 경우, write 및 edit 도구는 해당 디렉터리 내부의 파일 변경을 거부합니다. 워커는 해당 디렉터리에서 아무것도 업로드하지 않습니다.
bash를 통해, 또는 샌드박스에서 제공하는 사용자 정의 도구나 MCP 서버를 통해 이루어진 변경은 로컬에서 차단되지 않습니다. 이러한 변경은 스토어에 절대 도달하지 않습니다. 변경된 파일은 다음 중 하나가 발생할 때까지 변경된 상태로 유지됩니다:
- 스토어에서 해당 메모리의 새 버전이 생기는 경우. 워커의 다음 동기화가 해당 버전으로 파일을 덮어씁니다.
- 워커가 세션 처리를 마치는 경우. 워커가 디렉터리를 제거합니다.
로컬 사본도 변경되지 않게 유지하려면 해당 에이전트의 bash 도구를 비활성화하세요. 또한 샌드박스의 파일 시스템에 쓰는 사용자 정의 도구나 MCP 서버를 제공하지 마세요. 스토어 경로에 읽기 전용 볼륨을 마운트하지 마세요. 마운트하면 해당 경로에 디렉터리가 생기며, 그곳에 무엇이든 이미 존재하면 워커는 작업 항목을 실패 처리합니다.
충돌
충돌이란 이전 동기화 이후 스토어와 샌드박스 양쪽에서 모두 변경된 메모리를 말합니다. 삭제도 변경으로 간주됩니다. access: "read_write"로 연결된 스토어의 경우, 워커는 다음 동기화 시 충돌을 해결합니다:
| 스토어에서 | 샌드박스에서 | 결과 |
|---|---|---|
| 변경됨 | 변경됨 | 스토어의 버전이 파일을 덮어씁니다. |
| 변경됨 | 삭제됨 | 워커가 스토어의 버전을 샌드박스에 다시 기록합니다. |
| 삭제됨 | 변경됨 | 워커가 파일로부터 메모리를 다시 생성합니다. |
처음 두 행에서는 도구 호출이 성공했더라도 에이전트의 변경이나 삭제가 손실됩니다. 에이전트에게는 아무것도 알려지지 않으며, 손실의 유일한 징후는 워커 로그의 경고뿐입니다. 마지막 행에서는 스토어에서의 삭제가 취소됩니다.
문제 해결
워커의 로그 메시지와 해결 방법은 메모리 스토어 마운트 또는 동기화 실패를 참조하세요.
제공 여부
Claude API
- 상태
- 베타
- API
- Managed Agents
- 베타 헤더
- 필요
- 모델
- 모든 모델
데이터 처리
데이터 처리 개요적용 엔드포인트
/v1/agents/v1/sessions/v1/environments
자체 호스팅 Managed Agents를 제외하고 ZDR 적격 대상이 아닙니다. 세션은 상태를 유지하는 리소스이며, 트랜스크립트는 삭제할 때까지 유지됩니다. 자세히 알아보기
HIPAA 적격 대상이 아닙니다. 모든 Managed Agents 하위 기능에 적용됩니다.
이 페이지가 도움이 되었나요?