SwarmMesh

Install • Quickstart • Features • CLI reference • Compare • FAQ

Shared context and memory for swarms of parallel AI agents, over a small protocol both Python and Node speak the same way.

Spin up ten coding agents on the same task and they cannot see what each other found. One agent rediscovers a bug another already fixed. Two agents overwrite the same file because neither knew the other touched it. SwarmMesh is a small server that sits alongside your existing agent framework and gives every agent process, in any language that can speak HTTP, a shared place to publish context and search memory.

It is not an orchestration framework. It does not schedule tasks, define agent roles, or route work between agents. Your existing framework (or your own code) keeps doing that. SwarmMesh only answers one question: how do independent agent processes read and write the same shared state.

Install

pip install swarmmesh-cli
# or
npm install -g swarmmesh-cli

Either gives you a swarmmesh command on your PATH.

See it work

This is a real terminal session, not a mockup: a Python-run mesh, a Node agent writing to it, and a Python agent reading back what the Node agent wrote. Two different languages, one shared mesh.

# Terminal 1: start a mesh (Python implementation, but either works)
$ swarmmesh serve --port 8420
INFO: Uvicorn running on http://127.0.0.1:8420

# Terminal 2: a Node agent joins and writes
$ swarmmesh agent register node-agent-1 researcher --port 8420 --json
{ "agent_id": "node-agent-1", "role": "researcher", ... }

$ swarmmesh context set interop-demo status '"investigating flaky test"' \
    --agent-id node-agent-1 --port 8420 --json
{ "namespace": "interop-demo", "key": "status", "value": "investigating flaky test", ... }

$ swarmmesh memory write interop-demo \
    "found a race condition in the retry loop" --agent-id node-agent-1 --port 8420 --json
{ "namespace": "interop-demo", "text": "found a race condition in the retry loop", ... }

# Terminal 3: a Python agent joins the same mesh and reads it back
$ swarmmesh context get interop-demo status --port 8420 --json
{ "value": "investigating flaky test", "updated_by": "node-agent-1", ... }

$ swarmmesh memory query interop-demo "race condition" --port 8420 --json
{ "results": [{ "entry": { "text": "found a race condition in the retry loop" }, "score": 0.575 }] }

Every command above was re-run for real against both CLIs while writing this README: the Node CLI registered an agent and wrote context and memory against a Python-hosted mesh, and the Python CLI read it straight back, in the same run, over the real HTTP API, with the score above (0.575) reproduced exactly. No shared filesystem, no shared process, no translation layer. Just the protocol.

Quickstart

# Start a mesh (in-memory by default; add --persist ./mesh.db for SQLite storage)
swarmmesh serve --host 127.0.0.1 --port 8420

# From another terminal: register an agent
swarmmesh agent register agent-1 researcher

# Publish and read shared context
swarmmesh context set my-run phase '"planning"' --agent-id agent-1
swarmmesh context get my-run phase

# Write and search shared memory
swarmmesh memory write my-run "found a race condition in the retry loop" --agent-id agent-1
swarmmesh memory query my-run "race condition"

# Check what's on the mesh
swarmmesh status --json

This exact sequence was run end to end while writing this README and completed in a few seconds, start to finish, against the real swarmmesh-cli package installed from PyPI.

To build from source instead of installing from a registry:

# Python
git clone https://github.com/RudrenduPaul/swarmmesh.git
cd swarmmesh
pip install -e python/

# Node
cd swarmmesh/node
npm install
npm run build
npm link

Features

• A documented wire protocol. docs/protocol.md specifies every HTTP endpoint and WebSocket event, so any process that can speak HTTP and JSON can join a mesh. The two official CLIs are convenient clients, not the only valid ones.
• Two independent, interoperating implementations. Python (swarmmesh-cli on PyPI, FastAPI + Typer, 74 tests, 91% statement coverage) and Node (swarmmesh-cli on npm, Express + commander, 65 tests, 91.64% statement coverage) implement the protocol identically. Each package's own test suite runs independently in CI; cross-language interop (a Node client against a Python-hosted server and back) is demonstrated in the "See it work" section above and was re-run by hand against both real packages, not covered by an automated cross-language test in CI today.
• Real-time updates over WebSocket. /v1/events pushes context.updated, context.deleted, memory.written, agent.registered, and agent.deregistered frames so an agent can react the moment another agent changes shared state, instead of polling.
• Honest memory search. Memory queries use Okapi BM25 keyword ranking: real term-frequency scoring, computed locally with no extra dependencies and no network calls. It is not semantic or embedding search. A RankingBackend interface is a documented extension point if you want to plug in your own embedding-based scorer; SwarmMesh doesn't ship one.
• Pluggable storage. In-memory by default (process lifetime only), or --persist <path> for SQLite-backed storage that survives restarts.
• Agent-native by default. Every subcommand on both CLIs supports --json for structured, script-parseable output, and both ship a swarmmesh mcp subcommand that starts an MCP server over stdio so an MCP-capable agent (Claude or otherwise) can call SwarmMesh as a set of tools without shelling out.
• A deliberately small trust boundary. Both servers bind to 127.0.0.1 by default, not 0.0.0.0. There's no authentication in v1. See Security.

The number below is measured, not estimated. 50 sequential PUT /v1/context/{namespace}/{key} requests against a local Python-run server averaged 0.8ms round trip each (40ms total for 50 requests) on the machine this README was written on. This isn't a rigorous benchmark, includes curl's own process-spawn overhead per request, and will vary by machine, but it's a real number from a real run, not a guess. Reproduce it yourself with:

for i in $(seq 1 50); do curl -s -o /dev/null -w "%{time_total}\n" \
  -X PUT "http://127.0.0.1:8420/v1/context/bench/key$i" \
  -H "Content-Type: application/json" -d "{\"value\":\"v$i\",\"agent_id\":\"bench\"}"; done

CLI reference

Both CLIs expose the same command tree. Flag names differ slightly between the two (Python uses Typer's --flag <value> style, Node uses commander's), but the commands and their behavior are identical. Output below is transcribed from running --help on each built CLI.

swarmmesh serve [--host HOST] [--port PORT] [--persist PATH]
    Start a SwarmMesh coordination server.

swarmmesh status [--host HOST] [--port PORT] [--json]
    Show a mesh status snapshot (agent count, namespaces, entry counts, uptime).

swarmmesh mcp [--host HOST] [--port PORT]
    Start an MCP server over stdio, proxying tool calls to a running mesh.

swarmmesh agent register <agent_id> <role> [--metadata JSON] [--host HOST] [--port PORT] [--json]
swarmmesh agent list [--host HOST] [--port PORT] [--json]
swarmmesh agent deregister <agent_id> [--host HOST] [--port PORT] [--json]

swarmmesh context set <namespace> <key> <value> [--agent-id ID] [--ttl SECONDS] [--host HOST] [--port PORT] [--json]
swarmmesh context get <namespace> <key> [--host HOST] [--port PORT] [--json]
swarmmesh context list <namespace> [--host HOST] [--port PORT] [--json]
swarmmesh context delete <namespace> <key> [--host HOST] [--port PORT] [--json]

swarmmesh memory write <namespace> <text> [--agent-id ID] [--metadata JSON] [--id ID] [--host HOST] [--port PORT] [--json]
swarmmesh memory query <namespace> <query> [--top-k N] [--host HOST] [--port PORT] [--json]

context set parses <value> as JSON, falling back to a plain string if it isn't valid JSON. context set ns key '"planning"' stores the string planning. So does context set ns key planning (no quotes), through the same string fallback.

MCP Server

SwarmMesh ships a Model Context Protocol (MCP) server, on both the Python and Node packages, so an MCP-capable agent (Claude Desktop, Claude Code, or any other MCP client) can call SwarmMesh as a set of tools instead of shelling out to the CLI. The MCP server doesn't reimplement the protocol; it proxies each tool call over HTTP to a swarmmesh serve process you already have running.

# 1. Start a mesh
swarmmesh serve --host 127.0.0.1 --port 8420

Read the full README on GitHub →