SwarmRecall#

Persistent memory, a knowledge graph, learnings, a skill registry, shared collaboration pools, and background "dream" consolidation — for any AI agent — via the SwarmRecall API at https://swarmrecall-api.onrender.com.

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):

bash

npm install -g @swarmrecall/cli
swarmrecall register --save      # mints an API key and stores it in ~/.config/swarmrecall/config.json
swarmrecall mcp                  # runs the MCP server over stdio — point your client at this command

Remote HTTP (no install):

text

URL:     https://swarmrecall-api.onrender.com/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#

bash

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:

bash

npm install @swarmrecall/sdk

ts

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 and a hosted agent needs one, self-register with no account:

text

POST https://swarmrecall-api.onrender.com/api/v1/register
Content-Type: application/json

{ "name": "<agent-name>" }

Response returns { "apiKey": "...", "claimToken": "..." }. Tell the user: "SwarmRecall is set up! To manage your agent's data, visit https://swarmrecall.ai/claim with code: <claimToken>."

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 swarmrecall-api.onrender.com over HTTPS.
• 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#

ToolPurposememory_storeStore a memory with category, importance, and tags.memory_searchSemantic search over memories.memory_get / memory_listFetch a specific memory or filtered list.memory_update / memory_deleteUpdate metadata or archive a memory.memory_sessions_startStart a new memory session.memory_sessions_currentGet the active session.memory_sessions_updateAppend state, summary, or mark ended.memory_sessions_listList 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#

ToolPurposeknowledge_entity_create/get/list/update/deleteEntity CRUD.knowledge_relation_create/list/deleteRelation CRUD.knowledge_traverseWalk the graph from an entity, filtered by relation and depth.knowledge_searchSemantic search over entities.knowledge_validateCheck 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#

ToolPurposelearning_logLog a learning with category, summary, priority, area.learning_search/get/list/updateRetrieve and update.learning_patternsList recurring patterns.learning_promotionsList promotion candidates.learning_resolveMark resolved with a resolution + optional commit SHA.learning_linkLink 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#

ToolPurposeskill_registerRegister a new skill.skill_list/get/update/removeManage registered skills.skill_suggestGet 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#

ToolPurposepool_listList pools this agent belongs to.pool_getPool 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#

ToolPurposedream_startStart a dream cycle.dream_get/list/updateCycle management.dream_complete/failCycle completion.dream_get_config / dream_update_configConfiguration.dream_get_duplicates/unsummarized_sessions/duplicate_entities/stale/contradictions/unprocessedCandidate primitives.dream_executeRun Tier 1 server-side operations (decay, prune, orphan cleanup).

Behavior#

1. Start a cycle: dream_start.
2. Run Tier 1 ops: dream_execute (decay, prune, orphan cleanup).
3. Fetch candidates: dream_get_duplicates, dream_get_unsummarized_sessions, dream_get_contradictions.
4. For each candidate: reason about it, then use the memory / knowledge / learnings tools to act.
5. 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 to
• swarmrecall://skills — skills this agent has registered
• swarmrecall://sessions/current — current memory session
• swarmrecall://dream/config — dream configuration

Pointers#

• https://www.swarmrecall.ai/docs/mcp — MCP setup for Claude Desktop, Claude Code, Cursor, MCP Inspector
• https://www.swarmrecall.ai/docs/api-reference — raw HTTP endpoints
• https://www.npmjs.com/package/@swarmrecall/cli — CLI source
• https://github.com/swarmclawai/swarmrecall — source repository
• examples/quickstart.md, examples/memory-workflow.md, examples/knowledge-graph.md, examples/learnings-workflow.md — workflow recipes
• references/commands.md, references/mcp-tools.md — complete command and tool references
• TROUBLESHOOTING.md — common auth and connectivity issues