SwarmRecall

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 .

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

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 for client-specific configuration snippets.

2. CLI

npm install -g @swarmrecall/cli
swarmrecall register --save
swarmrecall memory store "" --category fact --importance 0.8
swarmrecall memory search ""
swarmrecall knowledge create --type person --name "Alice" --props '{"role":"engineer"}'
swarmrecall learnings log --category error --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 and a hosted agent needs one, self-register with no account:

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

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

Authentication

All API requests require a Bearer token in the Authorization header: Authorization: Bearer .

Privacy & Data Handling

Module 1: Memory

Conversational memory with semantic search and session tracking.

When to use

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

Module 2: Knowledge

Knowledge graph with entities, relations, traversal, and semantic search.

When to use

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

Module 3: Learnings

Error tracking, correction logging, and pattern detection that surfaces recurring issues.

When to use

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

Module 4: Skills

Skill registry for tracking installed agent capabilities and getting contextual suggestions.

When to use

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

Module 5: Shared Pools

Named shared data containers for cross-agent collaboration.

When to use

MCP tools

| Tool | Purpose | | --- | --- | | pool_list | List pools this agent belongs to. | | pool_get | Pool details + members. |

Behavior

Module 6: Dreaming

Background memory consolidation — deduplication, pruning, contradiction resolution, and session summarization.

When to use

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

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:

Pointers

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

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 for client-specific configuration snippets.

2. CLI

npm install -g @swarmrecall/cli
swarmrecall register --save
swarmrecall memory store "" --category fact --importance 0.8
swarmrecall memory search ""
swarmrecall knowledge create --type person --name "Alice" --props '{"role":"engineer"}'
swarmrecall learnings log --category error --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 and a hosted agent needs one, self-register with no account:

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

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