> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dreams

As Memory Stores accumulate entries over time, they may contain duplicates, outdated information, or gaps. Dreams provide asynchronous memory consolidation — the system spins up a dedicated Agent to review recent sessions and reorganize the Memory Store by merging, pruning, and supplementing entries.

## Core Concepts

| Concept             | Description                                                                          |
| ------------------- | ------------------------------------------------------------------------------------ |
| Dream               | An asynchronous memory consolidation job                                             |
| Input Memory Store  | The data source — **never modified**                                                 |
| Output Memory Store | An automatically cloned copy where consolidation results are written                 |
| Dreaming Session    | An internal Session created during Dream execution; hidden from normal Session lists |

## Workflow

```
POST /api/v1/cloud/dreams
    ↓
Clone input Memory Store → produce independent output copy
    ↓
Create Dreaming Session (built-in Memory Consolidation Agent)
    ↓
Agent executes: read recent sessions → merge/delete/supplement memories
    ↓
Dream completes → outputs contain the consolidated Memory Store ID
```

## API Endpoints

| Method | Path                   | Description               |
| ------ | ---------------------- | ------------------------- |
| POST   | `/dreams`              | Create a Dream            |
| GET    | `/dreams`              | List Dreams               |
| GET    | `/dreams/{id}`         | Get a Dream               |
| POST   | `/dreams/{id}/cancel`  | Cancel a running Dream    |
| POST   | `/dreams/{id}/archive` | Archive a completed Dream |

## Quick Start

### 1. Trigger memory consolidation

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/cloud/dreams' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      { "type": "memory_store", "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4" }
    ]
  }'
```

### 2. Check progress

```bash theme={null}
curl -s 'https://api.qoder.com/api/v1/cloud/dreams/drm_019e86b4a8f070a3b6c5d4e3f2a1b0c9' \
  -H "Authorization: Bearer $QODER_PAT"
```

### 3. View results

Once completed, the `outputs` field contains the consolidated Memory Store ID:

```json theme={null}
{
  "status": "completed",
  "outputs": [
    { "type": "memory_store", "memory_store_id": "memstore_019e86b4b10578059435632bb357c5ed", "files_touched": ["preferences.md", "project/arch.md"] }
  ]
}
```

## Optional Parameters

| Parameter                   | Description                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------- |
| `model`                     | Model selection: `auto` (default), `lite`, `ultimate`                                 |
| `instructions`              | Custom instructions (e.g. "Focus on Python project conventions"), max 4096 characters |
| `inputs[].type: "sessions"` | Specify Session IDs to prioritize (up to 100)                                         |

## Safety Design

* **Copy-on-Write**: The input Memory Store is never modified; all writes target the cloned output
* **Least Privilege**: The Dreaming Agent can only use `memory`, `session_list`, and `session_read` tools — no code execution or network access
* **Single-flight**: Only one active Dream per user (pending or running); duplicate creation returns 409

## FAQ

**Q: Will a Dream modify my original Memory Store?**

A: No. Dreams always operate on a cloned copy. The original Memory Store is completely unaffected.

**Q: How long does a Dream take?**

A: Typically 1-5 minutes, depending on Memory Store size and the number of sessions to review.