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 ` 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 ` 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   [--metadata JSON] [--host HOST] [--port PORT] [--json]
swarmmesh agent list [--host HOST] [--port PORT] [--json]
swarmmesh agent deregister  [--host HOST] [--port PORT] [--json]

swarmmesh context set    [--agent-id ID] [--ttl SECONDS] [--host HOST] [--port PORT] [--json]
swarmmesh context get   [--host HOST] [--port PORT] [--json]
swarmmesh context list  [--host HOST] [--port PORT] [--json]
swarmmesh context delete   [--host HOST] [--port PORT] [--json]

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

`context set` parses `` 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

# 2. In another terminal (or from an MCP client), start the MCP server
#    (stdio transport) pointed at that mesh:
swarmmesh mcp --host 127.0.0.1 --port 8420

`mcp` support is included by default in both packages (it's a core

dependency, not an optional extra), so a plain `pip install swarmmesh-cli`

or `npm install -g swarmmesh-cli` is all you need.

Claude Desktop config (`claude_desktop_config.json`):

{
  "mcpServers": {
    "swarmmesh": {
      "command": "swarmmesh",
      "args": ["mcp", "--host", "127.0.0.1", "--port", "8420"]
    }
  }
}

Both the Python and Node MCP servers expose the same ten tools, mirroring

the `SwarmMeshClient` methods above:

Library API reference

Both packages export a typed client so you can call a mesh directly from

your own agent code instead of shelling out to the CLI. Signatures below are

grepped straight from source, not from memory.

Python (`swarmmesh_cli.client.SwarmMeshClient`):

class SwarmMeshClient:
    def __init__(self, base_url: str = DEFAULT_BASE_URL, timeout: float = 10.0) -> None: ...
    async def register_agent(self, agent_id: str, role: str, metadata: dict | None = None) -> dict: ...
    async def deregister_agent(self, agent_id: str) -> None: ...
    async def list_agents(self) -> dict: ...
    async def publish_context(self, namespace: str, key: str, value, agent_id: str, ttl_seconds: int | None = None) -> dict: ...
    async def get_context(self, namespace: str, key: str) -> dict: ...
    async def list_context(self, namespace: str) -> dict: ...
    async def delete_context(self, namespace: str, key: str) -> None: ...
    async def write_memory(self, namespace: str, text: str, agent_id: str, metadata: dict | None = None) -> dict: ...
    async def query_memory(self, namespace: str, query: str, top_k: int = 10) -> dict: ...
    async def get_status(self) -> dict: ...

Node / TypeScript (`SwarmMeshClient` from `swarmmesh-cli`):

class SwarmMeshClient {
  constructor(options?: SwarmMeshClientOptions);
  registerAgent(agentId: string, role: string, metadata?: Record): Promise;
  deregisterAgent(agentId: string): Promise;
  listAgents(): Promise;
  publishContext(namespace: string, key: string, value: JsonValue, agentId: string, ttlSeconds?: number): Promise;
  getContext(namespace: string, key: string): Promise;
  listContext(namespace: string): Promise;
  deleteContext(namespace: string, key: string): Promise;
  writeMemory(namespace: string, text: string, agentId: string, metadata?: Record): Promise;
  queryMemory(namespace: string, query: string, topK?: number): Promise;
  getStatus(): Promise;
}

The SwarmMesh protocol

The full specification lives in `docs/protocol.md`. The

short version: a "mesh" is one running `swarmmesh serve` process. Agents are

independent processes (coding agents, research agents, subprocess workers,

anything that can make an HTTP request) that register with a mesh, then

read and write namespaced shared context and memory through it.

The point of writing this down as a protocol instead of just shipping a

library is that it means the two official CLIs aren't the only valid

clients. A Python agent using `swarmmesh_cli.client.SwarmMeshClient`, a Node

agent using the `SwarmMeshClient` from `swarmmesh-cli`, and a third agent

written in a language with neither package can all register with the same

mesh and see each other's context and memory, because they're all just

calling the same documented HTTP endpoints and, optionally, subscribing to

the same WebSocket event stream. Nothing about interop depends on a shared

runtime, a shared process, or a shared filesystem.

How SwarmMesh compares

There's no other project doing exactly what SwarmMesh does, so this isn't an

apples-to-apples table. It's here to be honest about what two real,

comparable multi-agent projects actually offer versus what SwarmMesh

actually offers, checked directly against their READMEs and source, not

assumed from their names. Both are older, larger, and more established than

SwarmMesh, which has 0 GitHub stars and no known users yet.

The honest read: swarms has real orchestration depth and a large community

that SwarmMesh doesn't try to replace. feynman is a polished end-user

research tool, not infrastructure you'd embed elsewhere. SwarmMesh's actual

claim is narrower than either: a small, documented protocol two languages

already speak the same way. It's worth exactly that much, no more.

What SwarmMesh is, and why it exists

Multi-agent setups increasingly mean several agent processes working the

same problem in parallel, sometimes in the same language, sometimes not,

sometimes spawned by different tools entirely. Orchestration frameworks

solve the "what should each agent do and in what order" problem. SwarmMesh

solves a narrower, adjacent problem: once those agents are running, how do

they tell each other what they've found without a human relaying messages

between terminals or agents silently duplicating each other's work.

SwarmMesh is infrastructure, not a framework. It doesn't care what

orchestrator spawned your agents, if any. It exposes a small HTTP + WebSocket

surface for shared context (structured key-value state, like a run's current

phase) and shared memory (free-text notes agents leave for each other,

searchable by keyword). You point your agents at a `swarmmesh serve` process

the same way you'd point them at a Redis instance, and they have a shared

place to read and write.

FAQ

Is this a replacement for LangGraph / CrewAI / AutoGen / \?

No. SwarmMesh doesn't schedule agents, define workflows, or decide what

happens next. It runs alongside whatever you use for that and gives the

agents it spawns a shared context and memory layer. Point your orchestrator's

agents at a `swarmmesh serve` process and keep using it for everything else.

How is this different from kyegomez/swarms or companion-inc/feynman?

Both are larger, older projects solving different problems. swarms is an

orchestration framework: it decides what agents run, in what order, and how

they hand off work, and it does that at real depth. SwarmMesh doesn't do any

of that; it only gives already-running agents a shared place to read and

write state. feynman is a single research-agent product with a local

workbench UI and its own SQLite-backed state, not a coordination layer other

projects embed. Neither ships a documented cross-language wire protocol for

shared agent memory the way SwarmMesh's `docs/protocol.md` does. Full

side-by-side above in How SwarmMesh compares.

Is the memory search semantic / embedding-based?

No. It's Okapi BM25 keyword ranking, the same family of algorithm search

engines have used for decades, computed locally over term frequency. It

won't find memory entries that are conceptually related but share no

vocabulary with your query. If you need that, the `RankingBackend` interface

is a documented extension point for wiring in your own embedding-based

scorer. SwarmMesh doesn't ship one and won't silently call an embedding API

on your behalf.

**Can a Python agent and a Node agent really share state, or is that

theoretical?**

This is the reason the project exists. Both CLIs implement the same wire

protocol in `docs/protocol.md`, and the "See it work"

section above is a real transcript of the Node CLI writing context and

memory to a Python-hosted server, then the Python CLI reading it back over

the network, re-verified while writing this README.

Does SwarmMesh persist data?

Only if you ask it to. `swarmmesh serve` defaults to in-memory storage that's

gone when the process exits. Pass `--persist ` for SQLite-backed

storage that survives restarts.

Is there authentication?

Not in v1. See Security below: this is a deliberate scope

boundary, not an oversight.

What happens if two agents write to the same context key?

Last write wins. `PUT /v1/context/{namespace}/{key}` overwrites whatever

was there. Every write broadcasts a `context.updated` WebSocket event, so

agents subscribed to that namespace find out immediately rather than

polling. There's no merge or conflict resolution; if your agents need that,

build it on top using distinct keys or your own versioning convention.

Can I use SwarmMesh as a library instead of the CLI?

Yes. Both packages export a client: `swarmmesh_cli.client.SwarmMeshClient`

in Python, `SwarmMeshClient` from `swarmmesh-cli` in Node. See

Library API reference above for real method

signatures.

Can I run this on more than one machine, and is it production-ready?

Nothing stops a mesh from being reachable across a network; `--host` binds

to any interface you point it at. But there's no authentication in v1 (see

Security), so treat it like a local Redis instance, not a

public-internet-facing service. It also has 0 known production users at

this point, so evaluate accordingly.

Is it free to use commercially?

Yes. SwarmMesh is MIT licensed, on both the Python and Node packages and the

repository itself. Use it in a commercial product without asking permission

or paying anything.

Security

> [!WARNING]

> SwarmMesh has no authentication in v1. Running a SwarmMesh server directly

> exposed to the public internet without a reverse proxy adding

> authentication is a misconfiguration, not a supported deployment.

Both the Python and Node servers bind to `127.0.0.1` by default, not

`0.0.0.0`. SwarmMesh is designed to run on localhost or inside a private

network alongside the agents it coordinates. That's the same trust boundary

as a local Redis instance or a SQLite file, not a public-internet-facing

service.

Found a vulnerability? Please don't open a public issue. See

`SECURITY.md` for the private disclosure process.

Contributing

SwarmMesh has two official implementations of the same protocol, kept

behaviorally identical on purpose. See `CONTRIBUTING.md`

for development setup for both, the pull request process, and the ground

rule that shapes everything in this README: no unverified claims. Every

number here has to be reproducible from a real command.

License

MIT