Agent dreaming — memory consolidation, deduplication, pruning, contradiction resolution, and session summarization via the SwarmRecall API. Enables agents to optimize their memory store during idle periods.
Agent dreaming — memory consolidation, deduplication, pruning, contradiction resolution, and session summarization via the SwarmRecall API. Enables agents to optimize their memory store during idle periods.
metadata
{"openclaw":{"emoji":"💤","requires":{"env":"[Truncated]"},"primaryEnv":"SWARMRECALL_API_KEY","privacyPolicy":"Dream operations read and modify existing agent data on SwarmRecall servers (swarmrecall-api.onrender.com). No new external data is collected. Archived memories are soft-deleted and recoverable.","dataHandling":"All data is transmitted over HTTPS. Tier 1 operations (decay, prune, candidate detection) run server-side. Tier 2 operations (merge, summarize, resolve) are agent-driven using existing API endpoints. Data remains tenant-isolated by owner ID and agent ID."}}
Agent dreaming — memory consolidation, deduplication, pruning, contradiction resolution, and session summarization. Run during idle periods to keep your memory store lean and accurate.
Auto-Registration
Before making any API calls, check for a SWARMRECALL_API_KEY environment variable:
If SWARMRECALL_API_KEY is set, use it for all requests as a Bearer token.
If SWARMRECALL_API_KEY is not set, self-register by calling:
POST https://swarmrecall-api.onrender.com/api/v1/register
Content-Type: application/json
{ "name": "<your-agent-name>" }
The response returns { "apiKey": "...", "claimToken": "..." }. Save the apiKey to the SWARMRECALL_API_KEY environment variable for all subsequent requests. Do NOT write the key to disk or any file without user consent.
Tell the user: "SwarmRecall is set up! To manage your agent's data, visit swarmrecall.ai/claim with code: <claimToken>"
Authentication
All API requests require:
Authorization: Bearer <SWARMRECALL_API_KEY>
API Base URL
https://swarmrecall-api.onrender.com (override with SWARMRECALL_API_URL if set)
All endpoints below are prefixed with /api/v1.
Privacy & Data Handling
All data is sent to swarmrecall-api.onrender.com over HTTPS
Dream operations only read and modify your agent's existing data — no new external data is collected
Archived memories are soft-deleted (recoverable) — never hard-deleted
Data is isolated per agent and owner — no cross-tenant access
The SWARMRECALL_API_KEY should be stored as an environment variable only, not written to disk
How Dreaming Works
Dreaming uses a two-tier architecture:
Tier 1 (server-side): SwarmRecall runs deterministic operations that don't need intelligence — finding duplicate clusters, decaying importance, pruning low-importance memories, cleaning orphaned relations, and surfacing candidates for agent review.
Tier 2 (agent-driven): You (the agent) orchestrate the intelligent operations — reading candidate clusters, reasoning about what to merge/keep/archive, writing summaries, and resolving contradictions. You use the standard memory/knowledge/learnings endpoints to make changes.
Endpoints
Dream Cycle Management
Start a dream cycle
POST /api/v1/dream
{
"operations": ["deduplicate", "decay_prune", "summarize_sessions"], // optional, defaults to config
"thresholds": { // optional, override defaults for this cycle
"similarityThreshold": 0.90,
"decayAgeDays": 30,
"decayFactor": 0.95,
"pruneThreshold": 0.05,
"batchSize": 500
}
}
Returns the dream cycle with status: "running". Only one cycle can run per agent at a time (409 if already running).
List dream cycles
GET /api/v1/dream?limit=20&offset=0&status=completed
Get a dream cycle
GET /api/v1/dream/:id
Update a dream cycle (report results, mark complete/failed)
These return pre-computed analysis for agent-driven (Tier 2) operations.
Duplicate memory clusters
GET /api/v1/dream/candidates/duplicates?limit=50
Response:
{"clusters":[{"anchor":{"id":"mem_1","content":"User prefers dark mode","importance":0.8},"members":[{"id":"mem_7","content":"The user likes dark mode themes","importance":0.5,"similarity":0.94},{"id":"mem_12","content":"User said they prefer dark mode","importance":0.6,"similarity":0.92}]}],"totalClusters":3,"thresholdUsed":0.90}
Unsummarized sessions
GET /api/v1/dream/candidates/unsummarized-sessions?limit=20
GET /api/v1/dream/candidates/contradictions?limit=50
Response:
{"pairs":[{"memory_a":{"id":"mem_3","content":"User's timezone is PST","createdAt":"2026-01-15T..."},"memory_b":{"id":"mem_45","content":"User's timezone is EST","createdAt":"2026-03-20T..."},"similarity":0.91,"contentDivergence":0.67}],"totalPairs":1}
GET /api/v1/dream/candidates/unprocessed?limit=100
Returns memories where metadata.dreamProcessedAt is null or before the last dream cycle.
Behavior
When to dream
Between sessions: After ending a session and before starting the next one. This is the natural idle period.
On idle detection: If your framework detects the agent is idle (no user interaction for a configured period), trigger a dream.
Periodically: If auto-dream is enabled in your config, the server runs Tier 1 ops automatically on your interval. You can layer Tier 2 on top.
On explicit request: When the user says something like "clean up your memory" or "consolidate what you know."
Full dream flow
Follow this sequence for a complete dream cycle:
Start the cycle:
POST /api/v1/dream
{ "operations": ["deduplicate", "summarize_sessions", "decay_prune", "resolve_contradictions"] }
Run Tier 1 server-side ops (decay, prune, orphan cleanup):
POST /api/v1/dream/execute
Fetch and process duplicate clusters:
GET /api/v1/dream/candidates/duplicates
For each cluster:
Read all members, reason about which content to keep
Update the anchor memory with merged content: PATCH /api/v1/memory/:anchorId
Archive each duplicate: PATCH /api/v1/memory/:duplicateId with { "archived": true }
Fetch and process unsummarized sessions:
GET /api/v1/dream/candidates/unsummarized-sessions
For each session:
Read its memories: GET /api/v1/memory?sessionId=<id>&limit=100
Reason about the session's key decisions, facts, and outcomes
Write the summary: POST /api/v1/memory with { "content": "<summary>", "category": "session_summary", "sessionId": "<id>", "importance": 0.7 }
Fetch and resolve contradictions:
GET /api/v1/dream/candidates/contradictions
For each pair:
Read both memories and their context (timestamps, sessions)
Decide which is the current truth
Archive the stale one: PATCH /api/v1/memory/:staleId with { "archived": true }
Optionally update the current one with a note about what changed
Complete the cycle:
PATCH /api/v1/dream/:cycleId
{
"status": "completed",
"results": { ... counts of what you did ... }
}
Tips
Start small: For your first dream, just run decay_prune and deduplicate. Add more operations as you get comfortable.
Check before you merge: Always read the full content of duplicate clusters before merging. High similarity doesn't always mean the memories are truly redundant — they might add different context.
Protect important memories: Add the "pinned" tag to any memory that should never be pruned. Session summaries are automatically protected.
Report results: Always update the dream cycle with results when done. This creates an audit trail and helps the dashboard show what happened.
Don't dream too often: Once every 24 hours is a good default. More frequent dreaming wastes compute with diminishing returns.
Shared Pools
Dream operations respect pool boundaries. Candidate endpoints only return data the agent has access to.
Pool-scoped data (memories, entities, learnings with a poolId) is included in candidate analysis if the agent has readwrite access to the pool.
When merging pool-scoped memories, ensure the merged result retains the poolId.
