SwarmRecall Dream
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)
PATCH /api/v1/dream/:id
{
"status": "completed",
"results": {
"deduplicate": { "clustersFound": 3, "memoriesMerged": 5, "memoriesArchived": 5 },
"decay_prune": { "memoriesDecayed": 12, "memoriesPruned": 2 },
"summarize_sessions": { "sessionsProcessed": 4, "summariesCreated": 4, "memoriesDecayed": 0 },
"durationMs": 4500
}
}
Dream Config
Get dream config
GET /api/v1/dream/config
Update dream config
PATCH /api/v1/dream/config
{
"enabled": true, // enable/disable auto-dreaming
"intervalHours": 24, // how often to auto-dream (1-168)
"operations": ["deduplicate", "decay_prune", "summarize_sessions"],
"thresholds": {
"similarityThreshold": 0.90,
"decayAgeDays": 30
}
}
Tier 1 Execute (run server-side ops)
POST /api/v1/dream/execute
{
"operations": ["decay_prune"] // optional, defaults to Tier 1 ops in config
}
Runs server-side operations (decay, prune, orphan cleanup) immediately. Returns results.
Candidate Endpoints
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
Response:
{
"sessions": [
{ "id": "sess_1", "memoryCount": 14, "startedAt": "2026-03-15T...", "endedAt": "2026-03-15T..." },
{ "id": "sess_2", "memoryCount": 8, "startedAt": "2026-03-18T...", "endedAt": "2026-03-18T..." }
],
"totalSessions": 2
}
Duplicate entity pairs
GET /api/v1/dream/candidates/duplicate-entities?limit=50
Response:
{
"pairs": [
{
"entity_a": { "id": "ent_1", "type": "Person", "name": "John Smith", "properties": {} },
"entity_b": { "id": "ent_5", "type": "Person", "name": "J. Smith", "properties": {} },
"similarity": 0.93
}
],
"totalPairs": 1,
"thresholdUsed": 0.92
}
Stale memories
GET /api/v1/dream/candidates/stale?limit=100
Response:
{
"memories": [
{ "id": "mem_20", "content": "...", "importance": 0.12, "createdAt": "2025-12-01T...", "ageDays": 121 }
],
"totalStale": 15,
"decayAgeDaysUsed": 30
}
Contradiction pairs
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
}
Unprocessed memories (for knowledge graph enrichment)
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.
