SwarmRecall

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.

Audits

Pending

ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPending

Multi-engine malware detections and file reputation.

Install

openclaw skills install 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 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):

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

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