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

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

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:

{
  "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.