MCP Memory Server
Connect any MCP-compatible desktop app, editor, or agent to SwarmRecall over stdio or remote HTTP. The memory MCP server exposes 53 tools and 4 resources covering every SwarmRecall module.
The hosted API has been discontinued. Run your instance first; both transports connect to your self-hosted API.
Overview
The Model Context Protocol is an open standard that lets agents call tools and read resources over a JSON-RPC stream. SwarmRecall ships its MCP server in two transports so you can pick whichever fits your setup:
- Local stdio — run
swarmrecall mcpfrom the CLI. Best for desktop apps, editors, and any client that spawns MCP servers as subprocesses. - Remote HTTP — connect to your own API's
/mcpendpoint, such ashttp://localhost:3300/mcp, over Streamable HTTP. Run the API yourself; auth via your API key. Best for hosted clients, serverless agents, and teams that do not want to run a local process.
1. Install
The MCP server ships inside the SwarmRecall CLI:
npm install -g @swarmrecall/cliVerify the install:
swarmrecall --versionAlternatively, if you use ClawHub, the skill will install the CLI for you:
clawhub install swarmrecall2. Authenticate
Register a new agent and save the API key to ~/.config/swarmrecall/config.json:
SWARMRECALL_API_URL=http://localhost:3300 swarmrecall register --saveOr, if you already have an API key, set it via environment variable:
export SWARMRECALL_API_KEY=sr_live_...The MCP server reads SWARMRECALL_API_KEY first, then falls back to the saved config file. Override the API URL with SWARMRECALL_API_URL or swarmrecall config set-url when pointing at a staging deployment.
3. Configure your MCP client
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"swarmrecall": {
"command": "swarmrecall",
"args": ["mcp"],
"env": {
"SWARMRECALL_API_KEY": "sr_live_...",
"SWARMRECALL_API_URL": "http://localhost:3300"
}
}
}
}Restart Claude Desktop. SwarmRecall appears in the MCP menu.
Claude Code
From any project directory:
claude mcp add swarmrecall -- swarmrecall mcpOr add it manually to ~/.claude.json under mcpServers with the same shape as the Claude Desktop example.
Cursor
Edit ~/.cursor/mcp.json:
{
"mcpServers": {
"swarmrecall": {
"command": "swarmrecall",
"args": ["mcp"],
"env": { "SWARMRECALL_API_KEY": "sr_live_...",
"SWARMRECALL_API_URL": "http://localhost:3300" }
}
}
}Remote HTTP (no install required)
If your client supports remote MCP servers, point it at SwarmRecall directly — nothing to install locally:
{
"mcpServers": {
"swarmrecall": {
"url": "http://localhost:3300/mcp",
"headers": {
"Authorization": "Bearer sr_live_..."
}
}
}
}The endpoint speaks the MCP Streamable HTTP transport. Authentication is the same SwarmRecall API key you use with the SDK or CLI — pass it as Authorization: Bearer sr_live_....
MCP Inspector (for debugging)
# local stdio
npx @modelcontextprotocol/inspector swarmrecall mcp
# remote HTTP
npx @modelcontextprotocol/inspector \
--transport streamable-http \
--url http://localhost:3300/mcp \
--header "Authorization: Bearer sr_live_..."4. Tools
Memory (10)
| memory_store | Store a memory (fact, preference, decision, context, session summary). |
| memory_search | Semantic search across memories. |
| memory_get | Fetch a memory by ID. |
| memory_list | List memories with optional filtering. |
| memory_update | Update importance, tags, metadata, or archived flag. |
| memory_delete | Archive a memory. |
| memory_sessions_start | Start a new memory session. |
| memory_sessions_current | Get the currently active session. |
| memory_sessions_update | Update session state, summary, or mark ended. |
| memory_sessions_list | List sessions. |
Knowledge (11)
| knowledge_entity_create | Create an entity (person, project, tool, concept). |
| knowledge_entity_get | Fetch an entity with its outgoing relations. |
| knowledge_entity_list | List entities with optional filtering. |
| knowledge_entity_update | Update an entity. |
| knowledge_entity_delete | Archive an entity; later maintenance cleans up orphaned relations. |
| knowledge_relation_create | Create a directed relation between two entities. |
| knowledge_relation_list | List relations. |
| knowledge_relation_delete | Delete a relation. |
| knowledge_traverse | Traverse the graph from a starting entity. |
| knowledge_search | Semantic search across entities. |
| knowledge_validate | Validate the graph against defined constraints. |
Learnings (9)
| learning_log | Log a correction, insight, knowledge gap, best practice, error, or feature request. |
| learning_search | Semantic search across learnings. |
| learning_get | Fetch a learning by ID. |
| learning_list | List learnings with filtering. |
| learning_update | Update status, priority, resolution, area, or tags. |
| learning_patterns | List recurring patterns detected across learnings. |
| learning_promotions | List patterns ready to be promoted into rules. |
| learning_resolve | Mark a learning as resolved. |
| learning_link | Link related learnings for pattern detection. |
Skills (6)
| skill_register | Register a skill the agent has acquired. |
| skill_list | List registered skills. |
| skill_get | Fetch a skill by ID. |
| skill_update | Update a skill's version, config, or status. |
| skill_remove | Unregister a skill. |
| skill_suggest | Suggest skills relevant to a task context. |
Pools (2)
| pool_list | List shared pools this agent belongs to. |
| pool_get | Get details for a specific pool and its members. |
Dream (15)
| dream_start | Start a dream cycle for memory consolidation. |
| dream_get | Get details of a specific dream cycle. |
| dream_list | List dream cycles. |
| dream_update | Update a cycle status or attach results. |
| dream_complete | Mark a cycle as completed. |
| dream_fail | Mark a cycle as failed. |
| dream_get_config | Get the current dream configuration. |
| dream_update_config | Update dream configuration. |
| dream_get_duplicates | Fetch memory clusters above similarity threshold. |
| dream_get_unsummarized_sessions | Fetch completed sessions missing summaries. |
| dream_get_duplicate_entities | Fetch entity pairs that may be duplicates. |
| dream_get_stale | Fetch memories past the decay age. |
| dream_get_contradictions | Fetch memory pairs with divergent content. |
| dream_get_unprocessed | Fetch memories not yet processed for entity extraction. |
| dream_execute | Run Tier 1 server-side operations (decay, prune, cleanup). |
5. Resources
Read-only resources for clients that surface resources as inline context. Each returns JSON.
| swarmrecall://pools | Shared pools this agent belongs to with access levels. |
| swarmrecall://skills | Skills this agent has registered. |
| swarmrecall://sessions/current | The currently active memory session, if any. |
| swarmrecall://dream/config | The dream configuration (schedule, thresholds). |
6. Troubleshooting
"No SwarmRecall API key configured"
The server could not find SWARMRECALL_API_KEY in the environment or ~/.config/swarmrecall/config.json. Run SWARMRECALL_API_URL=http://localhost:3300 swarmrecall register --save or set the env var in your MCP client config.
401 Unauthorized responses
Your key is invalid or revoked. Run swarmrecall config show to verify the active key, then SWARMRECALL_API_URL=http://localhost:3300 swarmrecall register --save to mint a new one.
Tools not appearing in Claude Desktop
Confirm which swarmrecall returns a valid path on your PATH. If npm i -g installed to a location your GUI Claude Desktop does not see, use the absolute path in the command field of your MCP config.
What's next?
- API Reference — every endpoint the MCP tools wrap.
- SDK Guide — use
@swarmrecall/sdkdirectly. - @swarmrecall/mcp on npm — embed the server in your own agent.