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 mcp from the CLI. Best for desktop apps, editors, and any client that spawns MCP servers as subprocesses.
  • Remote HTTP — connect to your own API's /mcp endpoint, such as http://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/cli

Verify the install:

swarmrecall --version

Alternatively, if you use ClawHub, the skill will install the CLI for you:

clawhub install swarmrecall

2. Authenticate

Register a new agent and save the API key to ~/.config/swarmrecall/config.json:

SWARMRECALL_API_URL=http://localhost:3300 swarmrecall register --save

Or, 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 mcp

Or 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_storeStore a memory (fact, preference, decision, context, session summary).
memory_searchSemantic search across memories.
memory_getFetch a memory by ID.
memory_listList memories with optional filtering.
memory_updateUpdate importance, tags, metadata, or archived flag.
memory_deleteArchive a memory.
memory_sessions_startStart a new memory session.
memory_sessions_currentGet the currently active session.
memory_sessions_updateUpdate session state, summary, or mark ended.
memory_sessions_listList sessions.

Knowledge (11)

knowledge_entity_createCreate an entity (person, project, tool, concept).
knowledge_entity_getFetch an entity with its outgoing relations.
knowledge_entity_listList entities with optional filtering.
knowledge_entity_updateUpdate an entity.
knowledge_entity_deleteArchive an entity; later maintenance cleans up orphaned relations.
knowledge_relation_createCreate a directed relation between two entities.
knowledge_relation_listList relations.
knowledge_relation_deleteDelete a relation.
knowledge_traverseTraverse the graph from a starting entity.
knowledge_searchSemantic search across entities.
knowledge_validateValidate the graph against defined constraints.

Learnings (9)

learning_logLog a correction, insight, knowledge gap, best practice, error, or feature request.
learning_searchSemantic search across learnings.
learning_getFetch a learning by ID.
learning_listList learnings with filtering.
learning_updateUpdate status, priority, resolution, area, or tags.
learning_patternsList recurring patterns detected across learnings.
learning_promotionsList patterns ready to be promoted into rules.
learning_resolveMark a learning as resolved.
learning_linkLink related learnings for pattern detection.

Skills (6)

skill_registerRegister a skill the agent has acquired.
skill_listList registered skills.
skill_getFetch a skill by ID.
skill_updateUpdate a skill's version, config, or status.
skill_removeUnregister a skill.
skill_suggestSuggest skills relevant to a task context.

Pools (2)

pool_listList shared pools this agent belongs to.
pool_getGet details for a specific pool and its members.

Dream (15)

dream_startStart a dream cycle for memory consolidation.
dream_getGet details of a specific dream cycle.
dream_listList dream cycles.
dream_updateUpdate a cycle status or attach results.
dream_completeMark a cycle as completed.
dream_failMark a cycle as failed.
dream_get_configGet the current dream configuration.
dream_update_configUpdate dream configuration.
dream_get_duplicatesFetch memory clusters above similarity threshold.
dream_get_unsummarized_sessionsFetch completed sessions missing summaries.
dream_get_duplicate_entitiesFetch entity pairs that may be duplicates.
dream_get_staleFetch memories past the decay age.
dream_get_contradictionsFetch memory pairs with divergent content.
dream_get_unprocessedFetch memories not yet processed for entity extraction.
dream_executeRun 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://poolsShared pools this agent belongs to with access levels.
swarmrecall://skillsSkills this agent has registered.
swarmrecall://sessions/currentThe currently active memory session, if any.
swarmrecall://dream/configThe 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?