// 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.
| name | swarmrecall-dream |
| description | 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":["SWARMRECALL_API_KEY"]},"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."}} |
| version | 1.0.0 |
| author | swarmclawai |
| homepage | https://www.swarmrecall.ai |
| tags | ["dreaming","memory-consolidation","pruning","deduplication","contradiction-resolution","ai-agents","persistence"] |
Agent dreaming — memory consolidation, deduplication, pruning, contradiction resolution, and session summarization. Run during idle periods to keep your memory store lean and accurate.
Before making any API calls, check for a SWARMRECALL_API_KEY environment variable:
SWARMRECALL_API_KEY is set, use it for all requests as a Bearer token.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>" }
{ "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.<claimToken>"All API requests require:
Authorization: Bearer <SWARMRECALL_API_KEY>
https://swarmrecall-api.onrender.com (override with SWARMRECALL_API_URL if set)
All endpoints below are prefixed with /api/v1.
swarmrecall-api.onrender.com over HTTPSSWARMRECALL_API_KEY should be stored as an environment variable only, not written to diskDreaming 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.
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).
GET /api/v1/dream?limit=20&offset=0&status=completed
GET /api/v1/dream/:id
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
}
}
GET /api/v1/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
}
}
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.
These return pre-computed analysis for agent-driven (Tier 2) operations.
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
}
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
}
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
}
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
}
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.
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:
PATCH /api/v1/memory/:anchorIdPATCH /api/v1/memory/:duplicateId with { "archived": true }Fetch and process unsummarized sessions:
GET /api/v1/dream/candidates/unsummarized-sessions
For each session:
GET /api/v1/memory?sessionId=<id>&limit=100POST /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:
PATCH /api/v1/memory/:staleId with { "archived": true }Complete the cycle:
PATCH /api/v1/dream/:cycleId
{
"status": "completed",
"results": { ... counts of what you did ... }
}
decay_prune and deduplicate. Add more operations as you get comfortable."pinned" tag to any memory that should never be pruned. Session summaries are automatically protected.poolId) is included in candidate analysis if the agent has readwrite access to the pool.poolId.Knowledge graph with entities, relations, traversal, and semantic search via the SwarmRecall API. Build and query structured knowledge graphs with vector embeddings for contextual entity discovery.
Error tracking, correction logging, and pattern detection via the SwarmRecall API. Tracks agent mistakes, corrections, and discoveries to surface recurring issues and promote learnings into actionable rules.
Conversational memory persistence with semantic search and session tracking via the SwarmRecall API. Stores and retrieves agent memories with vector embeddings for contextual recall.
Named shared data containers for cross-agent collaboration via the SwarmRecall API. Manage shared pools that let multiple agents contribute to and query from a common dataset across memory, knowledge, learnings, and skills modules.
Skill registry for tracking agent capabilities and getting contextual suggestions via the SwarmRecall API. Register, list, and query installed skills with semantic matching for task-relevant recommendations.
Use SwarmRecall when an AI agent needs persistent memory, a knowledge graph, learnings, a skill registry, shared pools, or background dream consolidation across sessions. Works via the SwarmRecall CLI (for stdio MCP) or directly over HTTP/SDK. Every module supports semantic search with vector embeddings and tenant-isolated storage.