Dreams

에이전트는 작업하면서 메모리 스토어에 기록하지만, 이러한 기록은 국소적이고 점진적입니다. 여러 세션이 진행되면서 메모리 스토어에는 중복, 모순, 오래된 항목이 쌓이게 됩니다.

Dreams는 Claude가 이를 정리할 수 있게 합니다. Dream은 기존 메모리 스토어를 과거 세션 트랜스크립트와 함께 읽은 다음, 새롭게 재구성된 메모리 스토어를 생성합니다. 중복은 병합되고, 오래되거나 모순된 항목은 최신 값으로 대체되며, 새로운 인사이트가 도출됩니다.

입력 스토어는 절대 수정되지 않으므로, 출력을 검토한 후 결과가 마음에 들지 않으면 폐기할 수 있습니다.



작동 방식

Dream은 다음을 입력으로 받는 비동기 작업입니다.

• 기존 메모리 스토어: Claude가 검증, 중복 제거, 재구성하는 스토어
• 1~100개의 세션: Claude가 패턴과 인사이트를 추출하여 출력에 반영할 과거 트랜스크립트

Dream은 입력과 별개인 또 다른 출력 메모리 스토어를 생성합니다. 출력 스토어 ID는 워크플로가 입력 스토어를 복제한 후, dream이 running 상태가 된 직후 dream의 outputs[]에 나타납니다. running 상태의 dream은 잠시 동안 빈 outputs[]를 보고할 수 있습니다.



Dream 생성

dream = client.beta.dreams.create(
    inputs=[
        {"type": "memory_store", "memory_store_id": store_id},
        {"type": "sessions", "session_ids": [session_a, session_b]},
    ],
    model="claude-opus-4-8",
    instructions="Focus on coding-style preferences; ignore one-off debugging notes.",
)
print(dream.id)  # drm_01...

Dreaming 입력에는 기존 메모리 스토어와 세션 배열이 포함됩니다. 선택한 모델이 dreaming 파이프라인을 실행합니다. 연구 프리뷰 기간 동안 claude-opus-5, claude-fable-5, claude-opus-4-8, claude-opus-4-7, claude-sonnet-5, claude-sonnet-4-6이 지원됩니다. 선택적으로 instructions를 전달하여 dreaming 프로세스를 조정할 수 있습니다. Instructions로 조정하기를 참조하세요.

응답은 status: "pending" 상태의 전체 dream 리소스입니다.

{
  "type": "dream",
  "id": "drm_01AbCDefGhIjKlMnOpQrStUv",
  "status": "pending",
  "inputs": [
    { "type": "memory_store", "memory_store_id": "memstore_01Hx..." },
    { "type": "sessions", "session_ids": ["sesn_01...", "sesn_02..."] }
  ],
  "outputs": [],
  "model": { "id": "claude-opus-4-8" },
  "instructions": "Focus on coding-style preferences; ignore one-off debugging notes.",
  "session_id": null,
  "created_at": "2026-04-29T17:04:10Z",
  "ended_at": null,
  "archived_at": null,
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  },
  "error": null
}



Instructions로 조정하기

선택적 instructions 필드는 dreaming 파이프라인이 무엇을 종합할지 조정합니다. 이는 파이프라인 전반에 걸쳐 적용됩니다. 즉, 무엇을 자세히 읽을지, 무엇을 병합하거나 삭제할지, 출력 스토어를 어떻게 구조화할지에 영향을 줍니다.

instructions는 집중 영역("코딩 스타일 선호도에 집중"), 변경 없이 보존할 콘텐츠, 스토어 전반에 적용할 출력 규칙과 같은 상위 수준의 종합 지침에 사용하세요. 파이프라인은 입력에 대한 종합 과정이지 스토어 텍스트에 적용되는 편집기가 아니므로, 특정 줄을 대상으로 하는 명령형 지시("문장 X를 Y로 변경", "섹션 Z의 개수 수정")는 일반적으로 아무런 변경을 만들지 않습니다. 개별 메모리를 대상으로 편집하려면 출력 스토어에 직접 Memory Stores API를 사용하세요.



진행 상황 추적

Dreams는 비동기적으로 실행되며 일반적으로 입력 트랜스크립트 수에 따라 몇 분에서 몇 시간이 소요됩니다. ID로 dream을 폴링하여 상태를 확인하세요.

while dream.status in ("pending", "running"):
    time.sleep(10)
    dream = client.beta.dreams.retrieve(dream.id)
    print(f"status={dream.status} input_tokens={dream.usage.input_tokens}")



수명 주기



파이프라인 실행 관찰

Dream이 running 상태가 되면 session_id 필드는 파이프라인을 실행하는 기본 세션을 가리킵니다. 해당 세션의 이벤트를 스트리밍하여 dream이 실시간으로 무엇을 읽고 쓰는지 관찰할 수 있습니다. Dream이 종료 상태에 도달하면 세션은 삭제되지 않고 아카이브되므로, 이후에도 트랜스크립트를 계속 사용할 수 있습니다.



출력 사용

status가 completed에 도달하면 outputs[]의 memory_store 항목은 완전히 채워진 스토어를 참조합니다. 이는 워크스페이스의 일반 메모리 스토어입니다. Memory Stores API 또는 Console에서 검토한 다음, 다음 중 하나를 수행하세요.

• 활용: 입력 메모리 스토어 대신(또는 함께) 향후 세션에 memory_store 리소스로 연결하거나,
• 폐기: 메모리 스토어를 삭제하거나 메모리 스토어를 아카이브합니다.

# dream이 종료된 후 출력에는 재구성된 메모리 저장소가 담깁니다
output_store_id = next(
    output.memory_store_id for output in dream.outputs if output.type == "memory_store"
)

session = client.beta.sessions.create(
    agent=agent_id,
    environment_id=environment_id,
    resources=[
        {"type": "memory_store", "memory_store_id": output_store_id},
    ],
)

Dream 자체는 입력을 절대 삭제하거나 수정하지 않습니다. failed 또는 canceled 상태에서는 출력 스토어가 부분적인 내용과 함께 유지되므로 중단 전에 생성된 내용을 검사할 수 있습니다. 필요하지 않은 경우 Memory Stores API를 통해 정리하세요.



Dream 취소

취소는 pending 또는 running 상태의 dream을 즉시 canceled 상태로 전환합니다. 이미 canceled 상태인 dream을 취소하는 것은 멱등성 no-op입니다. completed 또는 failed 상태의 dream을 취소하면 400이 반환됩니다.

client.beta.dreams.cancel(dream.id)



Dream 아카이브

아카이브는 종료 상태(completed, failed, canceled)에 도달한 dream에 archived_at을 설정합니다. status는 변경되지 않습니다. 아카이브된 dreams는 기본 목록 응답에서 제외되지만 ID로 계속 읽을 수 있습니다. 이미 아카이브된 dream을 아카이브하는 것은 멱등성 no-op입니다. pending 또는 running 상태의 dream을 아카이브하면 400이 반환됩니다. 먼저 취소하세요. 아카이브 해제는 없습니다.

client.beta.dreams.archive(dream.id)

Dream을 아카이브해도 출력 메모리 스토어는 영향을 받지 않습니다. Memory Stores API를 통해 별도로 관리하세요.



Dreams 목록 조회

워크스페이스의 아카이브되지 않은 모든 dreams를 최신순으로 반환합니다. limit(기본값 20, 최대 100)과 page 커서를 사용하여 페이지네이션하세요. 아카이브된 dreams를 포함하려면 include_archived=true를 전달하세요.

for listed_dream in client.beta.dreams.list(limit=20):
    print(listed_dream.id, listed_dream.status)



오류

다음은 발생 가능한 dreaming 오류의 일부 목록입니다.



과금

Dreams는 선택한 모델의 표준 API 토큰 요율로 과금됩니다. 리소스의 usage가 정확한 총계를 보고합니다. 비용은 입력 세션의 수와 길이에 대략 선형적으로 비례합니다. 소규모 세션 배치로 시작한 다음 큐레이션 품질에 만족하면 규모를 확장하세요.



제한

이 기능이 연구 프리뷰 상태인 동안 dream 생성에는 기본 속도 제한이 적용됩니다. 더 높은 제한이 필요한 경우 지원팀에 문의하세요.