A Dream is an asynchronous memory consolidation task. After creating a task, use the list or get endpoint to check its execution status and results.
A Dream is an asynchronous memory consolidation task. After creating a task, use the list or get endpoint to check its execution status and results.
The create, list, get, cancel, and archive endpoints use the following Dream object:
The Memory Store specified by
At creation, the current Default Memory for the specified Identity and Template is resolved and recorded. On completion, the output Memory Store automatically becomes the new Default Memory for the same Identity and Template.
If another operation replaces the Default Memory while the task is running, the new mount is not overwritten. Instead, the Dream is marked as
When the Dream completes,
Dream object
The create, list, get, cancel, and archive endpoints use the following Dream object:
| Field | Type | Description |
|---|---|---|
id | string | Dream ID with the drm_ prefix. |
type | string | Always dream. |
status | string | Execution status. See Dream status. |
inputs | object[] | Inputs submitted when the task was created. An identity_template input is returned in its original form without expanding the internally resolved Memory Store ID. |
outputs | object[] | Consolidation results. An empty array is returned before completion and when the task fails or is canceled. |
model | object | Model configuration used for this task. |
model.id | string | Model tier: auto, lite, or ultimate. |
instructions | string | Consolidation instructions submitted at creation; an empty string if omitted. |
usage | object | Token usage. See Dream usage. All fields are 0 until the task incurs usage. |
error | object/null | Error details when the task fails. See Dream error. null in other states. |
created_at | string | Creation time in UTC RFC 3339 format. |
ended_at | string/null | Time when the task reached a terminal state, in UTC RFC 3339 format; null until it ends. |
archived_at | string/null | Archive time in UTC RFC 3339 format; null if not archived. |
Dream status
| Value | Description |
|---|---|
pending | Created and waiting to run. |
running | Consolidating memories. |
completed | Consolidation completed. outputs contains the resulting Memory Store. |
failed | Execution or result application failed. See error for details. |
canceled | The task was canceled. |
completed, failed, and canceled are terminal states.
Dream input
inputs must contain exactly one primary input and can include additional Session inputs:
type | Field | Description |
|---|---|---|
memory_store | memory_store_id | Consolidate a Memory Store accessible to the caller directly. |
identity_template | identity_id、template_id | Consolidate the Default Memory currently mounted to the specified Identity and Template. |
sessions | session_ids | Optional array of Session IDs to focus on during review; all sessions inputs combined can contain at most 100 IDs. |
memory_store and identity_template are mutually exclusive and cannot be submitted in the same request. Each input can contain only the fields defined for its type.
Processing memory_store
The Memory Store specified by memory_store_id is used directly as input. When the task completes, the output is a new Memory Store. The original input Store is not overwritten, and no Identity and Template mounts are changed automatically.
Processing identity_template
At creation, the current Default Memory for the specified Identity and Template is resolved and recorded. On completion, the output Memory Store automatically becomes the new Default Memory for the same Identity and Template.
If another operation replaces the Default Memory while the task is running, the new mount is not overwritten. Instead, the Dream is marked as failed with error code memory_changed_during_dream.
Dream output
When the Dream completes, outputs contains one element:
| Field | Type | Description |
|---|---|---|
type | string | Always memory_store. |
memory_store_id | string | ID of the Memory Store produced by consolidation. |
files_touched | string[] | Paths of memory files created, modified, or deleted during consolidation. Omitted when details are unavailable. |
Dream usage
| Field | Type | Description |
|---|---|---|
input_tokens | integer | Number of input tokens. |
output_tokens | integer | Number of output tokens. |
cache_creation_input_tokens | integer | Number of input tokens used to create the cache. |
cache_read_input_tokens | integer | Number of input tokens read from the cache. |
Dream error
| Field | Type | Description |
|---|---|---|
type | string | Error type, such as no_output or internal_error. |
code | string | Optional stable error code. This field is omitted when no code is provided. |
message | string | Error description for troubleshooting. Do not use it for programmatic decisions. |