{
  "markdown": "<!-- mcp-name: io.github.RudrenduPaul/swarmmesh -->\n\n# SwarmMesh\n\n[![CI (Python)](https://github.com/RudrenduPaul/swarmmesh/actions/workflows/ci-python.yml/badge.svg)](https://github.com/RudrenduPaul/swarmmesh/actions/workflows/ci-python.yml)\n[![CI (Node)](https://github.com/RudrenduPaul/swarmmesh/actions/workflows/ci-node.yml/badge.svg)](https://github.com/RudrenduPaul/swarmmesh/actions/workflows/ci-node.yml)\n[![PyPI](https://img.shields.io/pypi/v/swarmmesh-cli.svg)](https://pypi.org/project/swarmmesh-cli/)\n[![npm](https://img.shields.io/npm/v/swarmmesh-cli.svg)](https://www.npmjs.com/package/swarmmesh-cli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n[Install](#install) • [Quickstart](#quickstart) • [Features](#features) • [CLI reference](#cli-reference) • [Compare](#how-swarmmesh-compares) • [FAQ](#faq)\n\n**Shared context and memory for swarms of parallel AI agents, over a small\nprotocol both Python and Node speak the same way.**\n\n![swarmmesh demo: starting a mesh, registering an agent, writing context and memory, then querying memory back](docs/demo.gif)\n\nSpin up ten coding agents on the same task and they cannot see what each\nother found. One agent rediscovers a bug another already fixed. Two agents\noverwrite the same file because neither knew the other touched it. SwarmMesh\nis a small server that sits alongside your existing agent framework and gives\nevery agent process, in any language that can speak HTTP, a shared place to\npublish context and search memory.\n\nIt is not an orchestration framework. It does not schedule tasks, define\nagent roles, or route work between agents. Your existing framework (or your\nown code) keeps doing that. SwarmMesh only answers one question: how do\nindependent agent processes read and write the same shared state.\n\n## Install\n\n```bash\npip install swarmmesh-cli\n# or\nnpm install -g swarmmesh-cli\n```\n\nEither gives you a `swarmmesh` command on your `PATH`.\n\n## See it work\n\nThis is a real terminal session, not a mockup: a Python-run mesh, a Node\nagent writing to it, and a Python agent reading back what the Node agent\nwrote. Two different languages, one shared mesh.\n\n```bash\n# Terminal 1: start a mesh (Python implementation, but either works)\n$ swarmmesh serve --port 8420\nINFO: Uvicorn running on http://127.0.0.1:8420\n\n# Terminal 2: a Node agent joins and writes\n$ swarmmesh agent register node-agent-1 researcher --port 8420 --json\n{ \"agent_id\": \"node-agent-1\", \"role\": \"researcher\", ... }\n\n$ swarmmesh context set interop-demo status '\"investigating flaky test\"' \\\n    --agent-id node-agent-1 --port 8420 --json\n{ \"namespace\": \"interop-demo\", \"key\": \"status\", \"value\": \"investigating flaky test\", ... }\n\n$ swarmmesh memory write interop-demo \\\n    \"found a race condition in the retry loop\" --agent-id node-agent-1 --port 8420 --json\n{ \"namespace\": \"interop-demo\", \"text\": \"found a race condition in the retry loop\", ... }\n\n# Terminal 3: a Python agent joins the same mesh and reads it back\n$ swarmmesh context get interop-demo status --port 8420 --json\n{ \"value\": \"investigating flaky test\", \"updated_by\": \"node-agent-1\", ... }\n\n$ swarmmesh memory query interop-demo \"race condition\" --port 8420 --json\n{ \"results\": [{ \"entry\": { \"text\": \"found a race condition in the retry loop\" }, \"score\": 0.575 }] }\n```\n\nEvery command above was re-run for real against both CLIs while writing this\nREADME: the Node CLI registered an agent and wrote context and memory\nagainst a Python-hosted mesh, and the Python CLI read it straight back, in\nthe same run, over the real HTTP API, with the score above (0.575)\nreproduced exactly. No shared filesystem, no shared process, no translation\nlayer. Just the protocol.\n\n## Quickstart\n\n```bash\n# Start a mesh (in-memory by default; add --persist ./mesh.db for SQLite storage)\nswarmmesh serve --host 127.0.0.1 --port 8420\n\n# From another terminal: register an agent\nswarmmesh agent register agent-1 researcher\n\n# Publish and read shared context\nswarmmesh context set my-run phase '\"planning\"' --agent-id agent-1\nswarmmesh context get my-run phase\n\n# Write and search shared memory\nswarmmesh memory write my-run \"found a race condition in the retry loop\" --agent-id agent-1\nswarmmesh memory query my-run \"race condition\"\n\n# Check what's on the mesh\nswarmmesh status --json\n```\n\nThis exact sequence was run end to end while writing this README and\ncompleted in a few seconds, start to finish, against the real\n`swarmmesh-cli` package installed from PyPI.\n\nTo build from source instead of installing from a registry:\n\n```bash\n# Python\ngit clone https://github.com/RudrenduPaul/swarmmesh.git\ncd swarmmesh\npip install -e python/\n\n# Node\ncd swarmmesh/node\nnpm install\nnpm run build\nnpm link\n```\n\n## Features\n\n- **A documented wire protocol.** [`docs/protocol.md`](docs/protocol.md)\n  specifies every HTTP endpoint and WebSocket event, so any process that can\n  speak HTTP and JSON can join a mesh. The two official CLIs are convenient\n  clients, not the only valid ones.\n- **Two independent, interoperating implementations.** Python\n  (`swarmmesh-cli` on PyPI, FastAPI + Typer, 74 tests, 91% statement\n  coverage) and Node (`swarmmesh-cli` on npm, Express + commander, 65 tests,\n  91.64% statement coverage) implement the protocol identically. Each\n  package's own test suite runs independently in CI; cross-language interop\n  (a Node client against a Python-hosted server and back) is demonstrated in\n  the \"See it work\" section above and was re-run by hand against both real\n  packages, not covered by an automated cross-language test in CI today.\n- **Real-time updates over WebSocket.** `/v1/events` pushes\n  `context.updated`, `context.deleted`, `memory.written`,\n  `agent.registered`, and `agent.deregistered` frames so an agent can react\n  the moment another agent changes shared state, instead of polling.\n- **Honest memory search.** Memory queries use Okapi BM25 keyword ranking:\n  real term-frequency scoring, computed locally with no extra dependencies\n  and no network calls. It is not semantic or embedding search. A\n  `RankingBackend` interface is a documented extension point if you want to\n  plug in your own embedding-based scorer; SwarmMesh doesn't ship one.\n- **Pluggable storage.** In-memory by default (process lifetime only), or\n  `--persist <path>` for SQLite-backed storage that survives restarts.\n- **Agent-native by default.** Every subcommand on both CLIs supports\n  `--json` for structured, script-parseable output, and both ship a\n  `swarmmesh mcp` subcommand that starts an MCP server over stdio so an\n  MCP-capable agent (Claude or otherwise) can call SwarmMesh as a set of\n  tools without shelling out.\n- **A deliberately small trust boundary.** Both servers bind to\n  `127.0.0.1` by default, not `0.0.0.0`. There's no authentication in v1.\n  See [Security](#security).\n\nThe number below is measured, not estimated. 50 sequential `PUT /v1/context/{namespace}/{key}`\nrequests against a local Python-run server averaged 0.8ms round trip each\n(40ms total for 50 requests) on the machine this README was written on.\nThis isn't a rigorous benchmark, includes `curl`'s own process-spawn\noverhead per request, and will vary by machine, but it's a real number from\na real run, not a guess. Reproduce it yourself with:\n```bash\nfor i in $(seq 1 50); do curl -s -o /dev/null -w \"%{time_total}\\n\" \\\n  -X PUT \"http://127.0.0.1:8420/v1/context/bench/key$i\" \\\n  -H \"Content-Type: application/json\" -d \"{\\\"value\\\":\\\"v$i\\\",\\\"agent_id\\\":\\\"bench\\\"}\"; done\n```\n\n## CLI reference\n\nBoth CLIs expose the same command tree. Flag names differ slightly between\nthe two (Python uses Typer's `--flag <value>` style, Node uses commander's),\nbut the commands and their behavior are identical. Output below is\ntranscribed from running `--help` on each built CLI.\n\n![swarmmesh --help and swarmmesh agent --help output](docs/demo-help.gif)\n\n```\nswarmmesh serve [--host HOST] [--port PORT] [--persist PATH]\n    Start a SwarmMesh coordination server.\n\nswarmmesh status [--host HOST] [--port PORT] [--json]\n    Show a mesh status snapshot (agent count, namespaces, entry counts, uptime).\n\nswarmmesh mcp [--host HOST] [--port PORT]\n    Start an MCP server over stdio, proxying tool calls to a running mesh.\n\nswarmmesh agent register <agent_id> <role> [--metadata JSON] [--host HOST] [--port PORT] [--json]\nswarmmesh agent list [--host HOST] [--port PORT] [--json]\nswarmmesh agent deregister <agent_id> [--host HOST] [--port PORT] [--json]\n\nswarmmesh context set <namespace> <key> <value> [--agent-id ID] [--ttl SECONDS] [--host HOST] [--port PORT] [--json]\nswarmmesh context get <namespace> <key> [--host HOST] [--port PORT] [--json]\nswarmmesh context list <namespace> [--host HOST] [--port PORT] [--json]\nswarmmesh context delete <namespace> <key> [--host HOST] [--port PORT] [--json]\n\nswarmmesh memory write <namespace> <text> [--agent-id ID] [--metadata JSON] [--id ID] [--host HOST] [--port PORT] [--json]\nswarmmesh memory query <namespace> <query> [--top-k N] [--host HOST] [--port PORT] [--json]\n```\n\n![Registering an agent, then swarmmesh status --json and setting/listing context on a running mesh](docs/demo-status.gif)\n\n`context set` parses `<value>` as JSON, falling back to a plain string if it\nisn't valid JSON. `context set ns key '\"planning\"'` stores the string\n`planning`. So does `context set ns key planning` (no quotes), through the\nsame string fallback.\n\n## MCP Server\n\nSwarmMesh ships a Model Context Protocol (MCP) server, on both the Python\nand Node packages, so an MCP-capable agent (Claude Desktop, Claude Code, or\nany other MCP client) can call SwarmMesh as a set of tools instead of\nshelling out to the CLI. The MCP server doesn't reimplement the protocol; it\nproxies each tool call over HTTP to a `swarmmesh serve` process you already\nhave running.\n\n```bash\n# 1. Start a mesh\nswarmmesh serve --host 127.0.0.1 --port 8420\n\n# 2. In another terminal (or from an MCP client), start the MCP server\n#    (stdio transport) pointed at that mesh:\nswarmmesh mcp --host 127.0.0.1 --port 8420\n```\n\n`mcp` support is included by default in both packages (it's a core\ndependency, not an optional extra), so a plain `pip install swarmmesh-cli`\nor `npm install -g swarmmesh-cli` is all you need.\n\nClaude Desktop config (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"swarmmesh\": {\n      \"command\": \"swarmmesh\",\n      \"args\": [\"mcp\", \"--host\", \"127.0.0.1\", \"--port\", \"8420\"]\n    }\n  }\n}\n```\n\nBoth the Python and Node MCP servers expose the same ten tools, mirroring\nthe `SwarmMeshClient` methods above:\n\n| Tool | What it does | Example call |\n|---|---|---|\n| `register_agent` | Register an agent with the mesh. | `register_agent(agent_id=\"agent-1\", role=\"researcher\")` |\n| `deregister_agent` | Deregister an agent from the mesh. Idempotent. | `deregister_agent(agent_id=\"agent-1\")` |\n| `list_agents` | List agents currently registered with the mesh. | `list_agents()` |\n| `publish_context` | Publish (create or overwrite) a context value in a namespace. | `publish_context(namespace=\"my-run\", key=\"phase\", value=\"planning\", agent_id=\"agent-1\")` |\n| `get_context` | Read a single context value. | `get_context(namespace=\"my-run\", key=\"phase\")` |\n| `list_context` | List all live (non-expired) context entries in a namespace. | `list_context(namespace=\"my-run\")` |\n| `delete_context` | Delete a context value. | `delete_context(namespace=\"my-run\", key=\"phase\")` |\n| `write_memory` | Write a memory entry other agents in the swarm can find later. | `write_memory(namespace=\"my-run\", text=\"found a race condition in the retry loop\", agent_id=\"agent-1\")` |\n| `query_memory` | Query memory entries in a namespace by BM25 keyword ranking (not semantic search). | `query_memory(namespace=\"my-run\", query=\"race condition\")` |\n| `get_status` | Get a mesh status snapshot (agent count, namespaces, entry counts, uptime). | `get_status()` |\n\n## Library API reference\n\nBoth packages export a typed client so you can call a mesh directly from\nyour own agent code instead of shelling out to the CLI. Signatures below are\ngrepped straight from source, not from memory.\n\n**Python** (`swarmmesh_cli.client.SwarmMeshClient`):\n\n```python\nclass SwarmMeshClient:\n    def __init__(self, base_url: str = DEFAULT_BASE_URL, timeout: float = 10.0) -> None: ...\n    async def register_agent(self, agent_id: str, role: str, metadata: dict | None = None) -> dict: ...\n    async def deregister_agent(self, agent_id: str) -> None: ...\n    async def list_agents(self) -> dict: ...\n    async def publish_context(self, namespace: str, key: str, value, agent_id: str, ttl_seconds: int | None = None) -> dict: ...\n    async def get_context(self, namespace: str, key: str) -> dict: ...\n    async def list_context(self, namespace: str) -> dict: ...\n    async def delete_context(self, namespace: str, key: str) -> None: ...\n    async def write_memory(self, namespace: str, text: str, agent_id: str, metadata: dict | None = None) -> dict: ...\n    async def query_memory(self, namespace: str, query: str, top_k: int = 10) -> dict: ...\n    async def get_status(self) -> dict: ...\n```\n\n**Node / TypeScript** (`SwarmMeshClient` from `swarmmesh-cli`):\n\n```typescript\nclass SwarmMeshClient {\n  constructor(options?: SwarmMeshClientOptions);\n  registerAgent(agentId: string, role: string, metadata?: Record<string, JsonValue>): Promise<Agent>;\n  deregisterAgent(agentId: string): Promise<void>;\n  listAgents(): Promise<Agent[]>;\n  publishContext(namespace: string, key: string, value: JsonValue, agentId: string, ttlSeconds?: number): Promise<ContextEntry>;\n  getContext(namespace: string, key: string): Promise<ContextEntry | null>;\n  listContext(namespace: string): Promise<ContextEntry[]>;\n  deleteContext(namespace: string, key: string): Promise<void>;\n  writeMemory(namespace: string, text: string, agentId: string, metadata?: Record<string, JsonValue>): Promise<MemoryEntry>;\n  queryMemory(namespace: string, query: string, topK?: number): Promise<MemoryQueryResult[]>;\n  getStatus(): Promise<StatusSnapshot>;\n}\n```\n\n## The SwarmMesh protocol\n\nThe full specification lives in [`docs/protocol.md`](docs/protocol.md). The\nshort version: a \"mesh\" is one running `swarmmesh serve` process. Agents are\nindependent processes (coding agents, research agents, subprocess workers,\nanything that can make an HTTP request) that register with a mesh, then\nread and write namespaced shared context and memory through it.\n\nThe point of writing this down as a protocol instead of just shipping a\nlibrary is that it means the two official CLIs aren't the only valid\nclients. A Python agent using `swarmmesh_cli.client.SwarmMeshClient`, a Node\nagent using the `SwarmMeshClient` from `swarmmesh-cli`, and a third agent\nwritten in a language with neither package can all register with the same\nmesh and see each other's context and memory, because they're all just\ncalling the same documented HTTP endpoints and, optionally, subscribing to\nthe same WebSocket event stream. Nothing about interop depends on a shared\nruntime, a shared process, or a shared filesystem.\n\n## How SwarmMesh compares\n\nThere's no other project doing exactly what SwarmMesh does, so this isn't an\napples-to-apples table. It's here to be honest about what two real,\ncomparable multi-agent projects actually offer versus what SwarmMesh\nactually offers, checked directly against their READMEs and source, not\nassumed from their names. Both are older, larger, and more established than\nSwarmMesh, which has 0 GitHub stars and no known users yet.\n\n| | **SwarmMesh** | **[kyegomez/swarms](https://github.com/kyegomez/swarms)** | **[companion-inc/feynman](https://github.com/companion-inc/feynman)** |\n|---|---|---|---|\n| What it is | Shared context/memory coordination layer (infrastructure, not a framework) | Multi-agent orchestration framework | AI research agent with a local workbench UI |\n| Stars | 0 | 7,024 | 8,447 |\n| Primary language | Python + TypeScript (two tested implementations) | Python | TypeScript |\n| License | MIT | Apache-2.0 | MIT |\n| Install | `pip install swarmmesh-cli` / `npm install -g swarmmesh-cli` | `pip3 install -U swarms` | `curl -fsSL https://feynman.is/install \\| bash` |\n| Documented cross-language wire protocol for shared context/memory | Yes: [`docs/protocol.md`](docs/protocol.md), HTTP + WebSocket, two independent implementations verified interoperable by hand (see \"See it work\" above) | Not as a headline feature. AOP is a real protocol for deploying and calling a named remote agent as a distributed service, but its documented example is Python-only with no language-agnostic wire format specified. A `RedisConversation` backend exists as an example utility, not documented cross-language coordination. | None found. `feynman serve` runs a local, human-facing workbench UI. State lives in a local SQLite mirror under `~/.feynman/`, not behind a documented agent-to-agent API. |\n| Built-in orchestration patterns (sequential, hierarchical, task routing) | None by design. SwarmMesh expects you to bring an orchestrator | Yes, many. This is the core of what swarms does | Some, internal to its own research workflow, not exposed as a general SDK |\n| Memory search | Keyword (BM25), explicitly not semantic | Not the focus of the project | Not the focus of the project |\n\nThe honest read: swarms has real orchestration depth and a large community\nthat SwarmMesh doesn't try to replace. feynman is a polished end-user\nresearch tool, not infrastructure you'd embed elsewhere. SwarmMesh's actual\nclaim is narrower than either: a small, documented protocol two languages\nalready speak the same way. It's worth exactly that much, no more.\n\n## What SwarmMesh is, and why it exists\n\nMulti-agent setups increasingly mean several agent processes working the\nsame problem in parallel, sometimes in the same language, sometimes not,\nsometimes spawned by different tools entirely. Orchestration frameworks\nsolve the \"what should each agent do and in what order\" problem. SwarmMesh\nsolves a narrower, adjacent problem: once those agents are running, how do\nthey tell each other what they've found without a human relaying messages\nbetween terminals or agents silently duplicating each other's work.\n\nSwarmMesh is infrastructure, not a framework. It doesn't care what\norchestrator spawned your agents, if any. It exposes a small HTTP + WebSocket\nsurface for shared context (structured key-value state, like a run's current\nphase) and shared memory (free-text notes agents leave for each other,\nsearchable by keyword). You point your agents at a `swarmmesh serve` process\nthe same way you'd point them at a Redis instance, and they have a shared\nplace to read and write.\n\n## FAQ\n\n**Is this a replacement for LangGraph / CrewAI / AutoGen / \\<my orchestration\nframework\\>?**\nNo. SwarmMesh doesn't schedule agents, define workflows, or decide what\nhappens next. It runs alongside whatever you use for that and gives the\nagents it spawns a shared context and memory layer. Point your orchestrator's\nagents at a `swarmmesh serve` process and keep using it for everything else.\n\n**How is this different from kyegomez/swarms or companion-inc/feynman?**\nBoth are larger, older projects solving different problems. swarms is an\norchestration framework: it decides what agents run, in what order, and how\nthey hand off work, and it does that at real depth. SwarmMesh doesn't do any\nof that; it only gives already-running agents a shared place to read and\nwrite state. feynman is a single research-agent product with a local\nworkbench UI and its own SQLite-backed state, not a coordination layer other\nprojects embed. Neither ships a documented cross-language wire protocol for\nshared agent memory the way SwarmMesh's `docs/protocol.md` does. Full\nside-by-side above in [How SwarmMesh compares](#how-swarmmesh-compares).\n\n**Is the memory search semantic / embedding-based?**\nNo. It's Okapi BM25 keyword ranking, the same family of algorithm search\nengines have used for decades, computed locally over term frequency. It\nwon't find memory entries that are conceptually related but share no\nvocabulary with your query. If you need that, the `RankingBackend` interface\nis a documented extension point for wiring in your own embedding-based\nscorer. SwarmMesh doesn't ship one and won't silently call an embedding API\non your behalf.\n\n**Can a Python agent and a Node agent really share state, or is that\ntheoretical?**\nThis is the reason the project exists. Both CLIs implement the same wire\nprotocol in [`docs/protocol.md`](docs/protocol.md), and the \"See it work\"\nsection above is a real transcript of the Node CLI writing context and\nmemory to a Python-hosted server, then the Python CLI reading it back over\nthe network, re-verified while writing this README.\n\n**Does SwarmMesh persist data?**\nOnly if you ask it to. `swarmmesh serve` defaults to in-memory storage that's\ngone when the process exits. Pass `--persist <path>` for SQLite-backed\nstorage that survives restarts.\n\n**Is there authentication?**\nNot in v1. See [Security](#security) below: this is a deliberate scope\nboundary, not an oversight.\n\n**What happens if two agents write to the same context key?**\nLast write wins. `PUT /v1/context/{namespace}/{key}` overwrites whatever\nwas there. Every write broadcasts a `context.updated` WebSocket event, so\nagents subscribed to that namespace find out immediately rather than\npolling. There's no merge or conflict resolution; if your agents need that,\nbuild it on top using distinct keys or your own versioning convention.\n\n**Can I use SwarmMesh as a library instead of the CLI?**\nYes. Both packages export a client: `swarmmesh_cli.client.SwarmMeshClient`\nin Python, `SwarmMeshClient` from `swarmmesh-cli` in Node. See\n[Library API reference](#library-api-reference) above for real method\nsignatures.\n\n**Can I run this on more than one machine, and is it production-ready?**\nNothing stops a mesh from being reachable across a network; `--host` binds\nto any interface you point it at. But there's no authentication in v1 (see\n[Security](#security)), so treat it like a local Redis instance, not a\npublic-internet-facing service. It also has 0 known production users at\nthis point, so evaluate accordingly.\n\n**Is it free to use commercially?**\nYes. SwarmMesh is MIT licensed, on both the Python and Node packages and the\nrepository itself. Use it in a commercial product without asking permission\nor paying anything.\n\n## Security\n\n> [!WARNING]\n> SwarmMesh has no authentication in v1. Running a SwarmMesh server directly\n> exposed to the public internet without a reverse proxy adding\n> authentication is a misconfiguration, not a supported deployment.\n\nBoth the Python and Node servers bind to `127.0.0.1` by default, not\n`0.0.0.0`. SwarmMesh is designed to run on localhost or inside a private\nnetwork alongside the agents it coordinates. That's the same trust boundary\nas a local Redis instance or a SQLite file, not a public-internet-facing\nservice.\n\nFound a vulnerability? Please don't open a public issue. See\n[`SECURITY.md`](SECURITY.md) for the private disclosure process.\n\n## Contributing\n\nSwarmMesh has two official implementations of the same protocol, kept\nbehaviorally identical on purpose. See [`CONTRIBUTING.md`](CONTRIBUTING.md)\nfor development setup for both, the pull request process, and the ground\nrule that shapes everything in this README: no unverified claims. Every\nnumber here has to be reproducible from a real command.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 23454,
  "sha": "7cd632659b476149658cf9bde2f36d5a54f5ce09eea01e9b5b1be902eb0f15ea",
  "repo_slug": "rudrendupaul/swarmmesh",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rudrendupaul_swarmmesh_67106a8d/readme"
}