| name | swarmrecall |
| description | 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. |
| version | 1.2.0 |
| metadata | {"openclaw":{"requires":{"anyBins":["swarmrecall"]},"install":[{"id":"node","kind":"node","package":"@swarmrecall/cli","bins":["swarmrecall"],"label":"Install SwarmRecall CLI (npm)"}],"mcp_servers":[{"id":"swarmrecall","label":"SwarmRecall (local stdio)","command":"swarmrecall","args":["mcp"],"env":{"SWARMRECALL_API_KEY":"${env:SWARMRECALL_API_KEY}"}},{"id":"swarmrecall-remote","label":"SwarmRecall (remote HTTP)","transport":"streamable-http","url":"https://swarmrecall-api.onrender.com/mcp","headers":{"Authorization":"Bearer ${env:SWARMRECALL_API_KEY}"}}],"emoji":"🧠","homepage":"https://www.swarmrecall.ai/docs/mcp","privacyPolicy":"All data is stored on SwarmRecall servers (swarmrecall-api.onrender.com). Data is scoped per agent and owner. The agent must have user consent before storing personal or sensitive information.","dataHandling":"All data is transmitted over HTTPS. Data is stored in PostgreSQL with pgvector embeddings. Data is tenant-isolated by owner ID and agent ID across all modules.","primaryEnv":"SWARMRECALL_API_KEY"}} |
| author | swarmclawai |
| homepage | https://www.swarmrecall.ai |
| tags | ["memory","knowledge-graph","learnings","skills","pools","dreaming","consolidation","mcp","ai-agents","persistence"] |
SwarmRecall
Self-host only. The hosted SwarmRecall service has been discontinued.
SwarmRecall is now open-source; run your own instance and point clients at it
via SWARMRECALL_API_URL (defaults to http://localhost:3300). The
onrender.com URLs below are illustrative — substitute your own host.
See https://github.com/swarmclawai/swarmrecall/blob/main/docs/self-hosting.md.
Persistent memory, a knowledge graph, learnings, a skill registry, shared collaboration pools, and background "dream" consolidation — for any AI agent — via a self-hosted SwarmRecall API (default http://localhost:3300).
For onboarding, examples, command references, or troubleshooting, read the bundled README.md, examples/, references/, and TROUBLESHOOTING.md before improvising workflow advice.
Setup
Three ways to connect, in increasing order of flexibility:
1. MCP (recommended for Claude Desktop, Claude Code, Cursor)
Local stdio (default):
npm install -g @swarmrecall/cli
swarmrecall register --save
swarmrecall mcp
Remote HTTP (no install):
URL: ${SWARMRECALL_API_URL}/mcp # e.g. http://localhost:3300/mcp
Auth: Authorization: Bearer ${SWARMRECALL_API_KEY}
Transport: streamable-http
Both transports expose the same 52 tools and 4 resources. See https://www.swarmrecall.ai/docs/mcp for client-specific configuration snippets.
2. CLI
npm install -g @swarmrecall/cli
swarmrecall register --save
swarmrecall memory store "<content>" --category fact --importance 0.8
swarmrecall memory search "<query>"
swarmrecall knowledge create --type person --name "Alice" --props '{"role":"engineer"}'
swarmrecall learnings log --category error --summary "<summary>"
swarmrecall dream start
See references/commands.md for the full command surface.
3. Raw HTTP / SDK
If the user is wiring a custom agent, install the SDK:
npm install @swarmrecall/sdk
import { SwarmRecallClient } from '@swarmrecall/sdk';
const client = new SwarmRecallClient({ apiKey: process.env.SWARMRECALL_API_KEY! });
await client.memory.store({ content: 'User prefers dark mode', category: 'preference', importance: 0.8 });
If SWARMRECALL_API_KEY is not set, register against your instance:
POST ${SWARMRECALL_API_URL}/api/v1/register # e.g. http://localhost:3300/api/v1/register
Content-Type: application/json
{ "name": "<agent-name>" }
Response returns { "apiKey": "...", "claimToken": "..." }. Use the claimToken to link the agent in your self-hosted dashboard's claim page.
Authentication
All API requests require a Bearer token in the Authorization header: Authorization: Bearer <SWARMRECALL_API_KEY>.
Privacy & Data Handling
- All data is sent to your self-hosted SwarmRecall instance (
SWARMRECALL_API_URL).
- Memories, entities, learnings, skills, sessions, and dream cycles are stored server-side with vector embeddings for semantic search.
- Data is isolated per agent and owner — no cross-tenant access.
- Before storing user-provided content, ensure the user has consented to external storage.
- Store
SWARMRECALL_API_KEY as an environment variable or in ~/.config/swarmrecall/config.json (created by swarmrecall register --save). Do not check it into source control.
Module 1: Memory
Conversational memory with semantic search and session tracking.
When to use
- Storing user preferences, facts, decisions, and context.
- Recalling relevant information from past interactions.
- Managing conversation sessions end-to-end.
MCP tools
| Tool | Purpose |
|---|
memory_store | Store a memory with category, importance, and tags. |
memory_search | Semantic search over memories. |
memory_get / memory_list | Fetch a specific memory or filtered list. |
memory_update / memory_delete | Update metadata or archive a memory. |
memory_sessions_start | Start a new memory session. |
memory_sessions_current | Get the active session. |
memory_sessions_update | Append state, summary, or mark ended. |
memory_sessions_list | List sessions. |
Behavior
- On session start: call
memory_sessions_current to load context. If none, call memory_sessions_start.
- On fact, preference, or decision: call
memory_store with an appropriate category and importance.
- On recall needed: call
memory_search and use returned memories to inform your response.
- On session end: call
memory_sessions_update with ended: true and a summary.
Module 2: Knowledge
Knowledge graph with entities, relations, traversal, and semantic search.
When to use
- Storing structured information about people, projects, tools, and concepts.
- Linking related entities together.
- Exploring connections between concepts.
MCP tools
| Tool | Purpose |
|---|
knowledge_entity_create/get/list/update/delete | Entity CRUD. |
knowledge_relation_create/list/delete | Relation CRUD. |
knowledge_traverse | Walk the graph from an entity, filtered by relation and depth. |
knowledge_search | Semantic search over entities. |
knowledge_validate | Check graph constraints. |
Behavior
- When the user provides structured information: call
knowledge_entity_create.
- When linking concepts: call
knowledge_relation_create.
- When the user asks "what do I know about X?":
knowledge_search then knowledge_traverse to explore connections.
- Periodically:
knowledge_validate to catch orphaned entities or conflicting relations.
Module 3: Learnings
Error tracking, correction logging, and pattern detection that surfaces recurring issues.
When to use
- Logging errors, corrections, discoveries, optimizations, or preferences.
- Detecting recurring patterns across sessions.
- Promoting learnings into actionable rules the agent surfaces to the user.
MCP tools
| Tool | Purpose |
|---|
learning_log | Log a learning with category, summary, priority, area. |
learning_search/get/list/update | Retrieve and update. |
learning_patterns | List recurring patterns. |
learning_promotions | List promotion candidates. |
learning_resolve | Mark resolved with a resolution + optional commit SHA. |
learning_link | Link two learnings for pattern detection. |
Behavior
- On error or correction:
learning_log with the full error output / what was wrong vs. correct.
- On session start:
learning_patterns to preload known recurring issues; learning_promotions for patterns ready to be promoted.
- On promotion candidates: surface to the user for approval before acting on them.
Module 4: Skills
Skill registry for tracking installed agent capabilities and getting contextual suggestions.
When to use
- Registering capabilities the agent acquires.
- Listing what the agent can do.
- Getting skill recommendations for a given task.
MCP tools
| Tool | Purpose |
|---|
skill_register | Register a new skill. |
skill_list/get/update/remove | Manage registered skills. |
skill_suggest | Get skill suggestions for a task context. |
Behavior
- On skill install:
skill_register with name, version, and source.
- On "what can I do?":
skill_list.
- On task context:
skill_suggest for relevant skill recommendations.
Module 5: Shared Pools
Named shared data containers for cross-agent collaboration.
When to use
- Sharing memories, knowledge, learnings, or skills between agents.
- Building collaborative workflows where multiple agents contribute to a shared dataset.
MCP tools
| Tool | Purpose |
|---|
pool_list | List pools this agent belongs to. |
pool_get | Pool details + members. |
Behavior
- Pool data returned in responses includes
poolId and poolName to distinguish shared data from the agent's private data.
- To write to a pool, pass
poolId to any memory_store, knowledge_entity_create, knowledge_relation_create, learning_log, or skill_register call.
- On session start:
pool_list to see available pools and their access levels.
Module 6: Dreaming
Background memory consolidation — deduplication, pruning, contradiction resolution, and session summarization.
When to use
- Between sessions or during idle periods for memory maintenance.
- When the user asks to "clean up", "consolidate", or "optimize" memories.
- Periodically via auto-dream scheduling.
MCP tools
| Tool | Purpose |
|---|
dream_start | Start a dream cycle. |
dream_get/list/update | Cycle management. |
dream_complete/fail | Cycle completion. |
dream_get_config / dream_update_config | Configuration. |
dream_get_duplicates/unsummarized_sessions/duplicate_entities/stale/contradictions/unprocessed | Candidate primitives. |
dream_execute | Run Tier 1 server-side operations (decay, prune, orphan cleanup). |
Behavior
- Start a cycle:
dream_start.
- Run Tier 1 ops:
dream_execute (decay, prune, orphan cleanup).
- Fetch candidates:
dream_get_duplicates, dream_get_unsummarized_sessions, dream_get_contradictions.
- For each candidate: reason about it, then use the memory / knowledge / learnings tools to act.
- Complete the cycle:
dream_complete with the results.
Resources
Read-only MCP resources for clients that surface resources as inline context:
swarmrecall://pools — pools this agent belongs toswarmrecall://skills — skills this agent has registeredswarmrecall://sessions/current — current memory sessionswarmrecall://dream/config — dream configuration
Pointers
