Swarmmesh

What swarmmesh does

The swarmmesh MCP server provides shared state for independent AI-agent processes. It is designed for a group of agents working on the same task, where each process needs to see findings, current status, or other coordination data produced by its peers.

The system stores context as namespaced key-value entries and stores memory as text entries that can include metadata and identifiers. Agents can register with an ID and role, list or remove registered agents, and inspect a status snapshot containing agent counts, namespaces, entry counts, and uptime. The project is not an orchestration layer: it does not schedule work, assign roles, or route tasks between agents.

How it works

A mesh is started as a local HTTP service. Agents communicate with it through the documented protocol using HTTP and JSON, so clients do not need to share a filesystem or process. Python and Node implementations use the same protocol and can interoperate; the README demonstrates a Node client writing data to a Python-hosted mesh and a Python client reading it back.

The server can publish real-time changes through the /v1/events WebSocket endpoint. Event types include context updates and deletions, memory writes, and agent registration or deregistration. This allows clients to react to changes instead of repeatedly polling.

Memory queries use local Okapi BM25 keyword ranking. The search is not semantic or embedding-based, and the project does not provide an embedding scorer. A documented RankingBackend interface can be used to add another ranking implementation.

Setup and configuration

Install the swarmmesh-cli package from PyPI or npm; either package provides a swarmmesh command. Start a mesh with swarmmesh serve, optionally selecting the host, port, and SQLite persistence path. Without --persist, storage is held in memory and is lost when the process ends. With --persist <path>, SQLite storage survives restarts.

The default bind address is 127.0.0.1, and the README states that version 1 has no authentication. Every CLI command supports --json for structured output. The swarmmesh mcp subcommand starts an MCP server over stdio and proxies tool calls to an already running mesh.

Tools and capabilities

The swarmmesh MCP server and its CLI support these operations:

• Start a mesh and inspect its status.
• Register, list, and deregister agents.
• Set, read, list, and delete namespaced context values.
• Write memory entries and query them with BM25 ranking.
• Set context expiration with a TTL.
• Receive state-change notifications over WebSocket.
• Use either Python or Node clients against the same protocol.

The protocol is intended for any process that can speak HTTP and JSON; the official CLIs are clients rather than the only possible clients.

Limitations and notes

The swarmmesh MCP server does not provide task scheduling, role management, or agent-to-agent work routing. Its default in-memory storage is process-lifetime only. Memory search uses keyword ranking rather than semantic similarity, and no embedding backend is included. Version 1 has no authentication, so the default loopback binding is important when deploying it locally. The MCP subcommand connects to a running mesh rather than replacing the mesh service itself.