Skip to main content
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

ConceptDescription
DreamAn asynchronous memory consolidation job
Input Memory StoreThe data source — never modified
Output Memory StoreAn automatically cloned copy where consolidation results are written
Dreaming SessionAn internal Session created during Dream execution; hidden from normal Session lists

​
Workflow

POST /v1/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

MethodPathDescription
POST/dreamsCreate a Dream
GET/dreamsList Dreams
GET/dreams/{id}Get a Dream
POST/dreams/{id}/cancelCancel a running Dream
POST/dreams/{id}/archiveArchive 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

ParameterDescription
modelModel selection: auto (default), lite, ultimate
instructionsCustom 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.