swarmmesh

SwarmMesh

Instalación • Inicio rápido • Características • Referencia de CLI • Comparar • FAQ

Contexto y memoria compartidos para enjambres de agentes de IA paralelos, mediante un pequeño protocolo que Python y Node hablan de la misma manera.

Lanza diez agentes de codificación sobre la misma tarea y no pueden ver lo que cada uno encontró. Un agente redescubre un error que otro ya corrigió. Dos agentes sobrescriben el mismo archivo porque ninguno sabía que el otro lo había tocado. SwarmMesh es un pequeño servidor que se sitúa junto a tu framework de agentes existente y da a cada proceso de agente, en cualquier lenguaje que pueda hablar HTTP, un lugar compartido para publicar contexto y buscar memoria.

No es un framework de orquestación. No programa tareas, no define roles de agentes ni enruta trabajo entre agentes. Tu framework existente (o tu propio código) sigue haciendo eso. SwarmMesh solo responde una pregunta: cómo leen y escriben procesos de agente independientes el mismo estado compartido.

Instalación

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

Cualquiera de las dos opciones te da un comando swarmmesh en tu PATH.

Verlo funcionar

Esta es una sesión real de terminal, no una maqueta: un mesh ejecutado en Python, un agente de Node escribiendo en él, y un agente de Python leyendo lo que el agente de Node escribió. Dos lenguajes diferentes, un mismo mesh compartido.

# 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 }] }

Cada comando anterior se re-ejecutó de verdad contra ambas CLIs mientras se escribía este README: la CLI de Node registró un agente y escribió contexto y memoria contra un mesh alojado en Python, y la CLI de Python lo leyó directamente, en la misma ejecución, a través de la API HTTP real, con la puntuación anterior (0.575) reproducida exactamente. Sin sistema de archivos compartido, sin proceso compartido, sin capa de traducción. Solo el protocolo.

Inicio rápido

# 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

Esta secuencia exacta se ejecutó de principio a fin mientras se escribía este README y se completó en unos segundos, de principio a fin, contra el paquete real swarmmesh-cli instalado desde PyPI.

Para compilar desde el código fuente en lugar de instalar desde un registro:

# 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

Características

• Un protocolo de cable documentado. docs/protocol.md especifica cada endpoint HTTP y evento WebSocket, de modo que cualquier proceso que pueda hablar HTTP y JSON puede unirse a un mesh. Las dos CLIs oficiales son clientes convenientes, no los únicos válidos.
• Dos implementaciones independientes e interoperables. Python (swarmmesh-cli en PyPI, FastAPI + Typer, 74 pruebas, 91% de cobertura de sentencias) y Node (swarmmesh-cli en npm, Express + commander, 65 pruebas, 91.64% de cobertura de sentencias) implementan el protocolo de forma idéntica. La suite de pruebas de cada paquete se ejecuta de forma independiente en CI; la interoperabilidad entre lenguajes (un cliente Node contra un servidor alojado en Python y viceversa) se demuestra en la sección "Verlo funcionar" anterior y se re-ejecutó a mano contra ambos paquetes reales, no está cubierta por una prueba automatizada entre lenguajes en CI hoy.
• Actualizaciones en tiempo real a través de WebSocket. /v1/events envía tramas context.updated, context.deleted, memory.written, agent.registered y agent.deregistered para que un agente pueda reaccionar en el momento en que otro agente cambia el estado compartido, en lugar de hacer polling.
• Búsqueda de memoria honesta. Las consultas de memoria usan clasificación por palabras clave Okapi BM25: puntuación real de frecuencia de términos, calculada localmente sin dependencias adicionales y sin llamadas de red. No es búsqueda semántica ni por embeddings. Una interfaz RankingBackend es un punto de extensión documentado si quieres conectar tu propio puntuador basado en embeddings; SwarmMesh no incluye uno.
• Almacenamiento conectable. En memoria por defecto (solo durante la vida del proceso), o --persist <path> para almacenamiento respaldado por SQLite que sobrevive a reinicios.
• Nativo para agentes por defecto. Cada subcomando de ambas CLIs admite --json para salida estructurada y analizable por scripts, y ambas incluyen un subcomando swarmmesh mcp que inicia un servidor MCP sobre stdio para que un agente con capacidad MCP (Claude u otro) pueda llamar a SwarmMesh como un conjunto de herramientas sin invocar la shell.
• Un límite de confianza deliberadamente pequeño. Ambos servidores se vinculan a 127.0.0.1 por defecto, no a 0.0.0.0. No hay autenticación en v1. Consulta Seguridad.

El número siguiente está medido, no estimado. 50 solicitudes PUT /v1/context/{namespace}/{key} secuenciales contra un servidor local ejecutado en Python promediaron 0.8 ms de ida y vuelta cada una (40 ms en total para 50 solicitudes) en la máquina donde se escribió este README. Esto no es un benchmark riguroso, incluye la sobrecarga de creación de proceso de curl por solicitud, y variará según la máquina, pero es un número real de una ejecución real, no una suposición. Reprodúcelo tú mismo con:

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

Referencia de CLI

Ambas CLIs exponen el mismo árbol de comandos. Los nombres de las banderas difieren ligeramente entre las dos (Python usa el estilo --flag <value> de Typer, Node usa el de commander), pero los comandos y su comportamiento son idénticos. La salida siguiente está transcrita de ejecutar --help en cada CLI compilada.

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 analiza <value> como JSON, con respaldo a una cadena simple si no es JSON válido. context set ns key '"planning"' almacena la cadena planning. También lo hace context set ns key planning (sin comillas), mediante el mismo respaldo de cadena.

Servidor MCP

SwarmMesh incluye un servidor de Protocolo de Contexto de Modelo (MCP), tanto en el paquete de Python como en el de Node, para que un agente con capacidad MCP (Claude Desktop, Claude Code o cualquier otro cliente MCP) pueda llamar a SwarmMesh como un conjunto de herramientas en lugar de invocar la CLI. El servidor MCP no reimplementa el protocolo; hace de proxy para cada llamada de herramienta a través de HTTP hacia un proceso swarmmesh serve que ya tienes en ejecución.

# 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

El soporte de mcp está incluido por defecto en ambos paquetes (es una dependencia central, no un extra opcional), así que un simple pip install swarmmesh-cli o npm install -g swarmmesh-cli es todo lo que necesitas.

Configuración de Claude Desktop (claude_desktop_config.json):

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

Tanto el servidor MCP de Python como el de Node exponen las mismas diez herramientas, reflejando los métodos SwarmMeshClient anteriores:

Herramienta	Qué hace	Ejemplo de llamada
register_agent	Registra un agente con el mesh.	register_agent(agent_id="agent-1", role="researcher")
deregister_agent	Anula el registro de un agente del mesh. Idempotente.	deregister_agent(agent_id="agent-1")
list_agents	Lista los agentes actualmente registrados con el mesh.	list_agents()
publish_context	Publica (crea o sobrescribe) un valor de contexto en un namespace.	publish_context(namespace="my-run", key="phase", value="planning", agent_id="agent-1")
get_context	Lee un único valor de contexto.	get_context(namespace="my-run", key="phase")
list_context	Lista todas las entradas de contexto vivas (no expiradas) en un namespace.	list_context(namespace="my-run")
delete_context	Elimina un valor de contexto.	delete_context(namespace="my-run", key="phase")
write_memory	Escribe una entrada de memoria que otros agentes del enjambre puedan encontrar después.	write_memory(namespace="my-run", text="found a race condition in the retry loop", agent_id="agent-1")
query_memory	Consulta entradas de memoria en un namespace por clasificación de palabras clave BM25 (no búsqueda semántica).	query_memory(namespace="my-run", query="race condition")
get_status	Obtiene una instantánea del estado del mesh (número de agentes, namespaces, recuentos de entradas, tiempo de actividad).	get_status()

Referencia de la API de biblioteca

Ambos paquetes exportan un cliente tipado para que puedas llamar a un mesh directamente desde tu propio código de agente en lugar de invocar la CLI. Las firmas siguientes se extraen directamente del código fuente, no de memoria.

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 de swarmmesh-cli):

class SwarmMeshClient {
  constructor(options?: SwarmMeshClientOptions);
  registerAgent(agentId: string, role: string, metadata?: Record<string, JsonValue>): Promise<Agent>;
  deregisterAgent(agentId: string): Promise<void>;
  listAgents(): Promise<Agent[]>;
  publishContext(namespace: string, key: string, value: JsonValue, agentId: string, ttlSeconds?: number): Promise<ContextEntry>;
  getContext(namespace: string, key: string): Promise<ContextEntry | null>;
  listContext(namespace: string): Promise<ContextEntry[]>;
  deleteContext(namespace: string, key: string): Promise<void>;
  writeMemory(namespace: string, text: string, agentId: string, metadata?: Record<string, JsonValue>): Promise<MemoryEntry>;
  queryMemory(namespace: string, query: string, topK?: number): Promise<MemoryQueryResult[]>;
  getStatus(): Promise<StatusSnapshot>;
}

El protocolo SwarmMesh

La especificación completa vive en docs/protocol.md. La versión corta: un "mesh" es un proceso swarmmesh serve en ejecución. Los agentes son procesos independientes (agentes de codificación, agentes de investigación, trabajadores de subprocesos, cualquier cosa que pueda hacer una solicitud HTTP) que se registran con un mesh y luego leen y escriben contexto y memoria compartidos con namespaces a través de él.

El punto de escribir esto como protocolo en lugar de simplemente distribuir una biblioteca es que significa que las dos CLIs oficiales no son los únicos clientes válidos. Un agente de Python que use swarmmesh_cli.client.SwarmMeshClient, un agente de Node que use el SwarmMeshClient de swarmmesh-cli, y un tercer agente escrito en un lenguaje sin ninguno de los dos paquetes pueden registrarse todos con el mismo mesh y ver el contexto y la memoria de los demás, porque todos están simplemente llamando a los mismos endpoints HTTP documentados y, opcionalmente, suscribiéndose al mismo flujo de eventos WebSocket. Nada de la interoperabilidad depende de un runtime compartido, un proceso compartido o un sistema de archivos compartido.

Cómo se compara SwarmMesh

No hay otro proyecto que haga exactamente lo que hace SwarmMesh, así que esto no es una tabla de manzanas con manzanas. Está aquí para ser honesto sobre lo que dos proyectos reales y comparables de multiagente ofrecen realmente frente a lo que SwarmMesh ofrece realmente, verificado directamente contra sus READMEs y código fuente, no asumido por sus nombres. Ambos son más antiguos, más grandes y más establecidos que SwarmMesh, que tiene 0 estrellas en GitHub y aún no tiene usuarios conocidos.

	SwarmMesh	kyegomez/swarms	companion-inc/feynman
Qué es	Capa de coordinación de contexto/memoria compartidos (infraestructura, no un framework)	Framework de orquestación multiagente	Agente de investigación de IA con una interfaz de workbench local
Estrellas	0	7,024	8,447
Lenguaje principal	Python + TypeScript (dos implementaciones probadas)	Python	TypeScript
Licencia	MIT	Apache-2.0	MIT
Instalación	pip install swarmmesh-cli / npm install -g swarmmesh-cli	pip3 install -U swarms	curl -fsSL https://feynman.is/install | bash
Protocolo de cable entre lenguajes documentado para contexto/memoria compartidos	Sí: docs/protocol.md, HTTP + WebSocket, dos implementaciones independientes verificadas interoperables a mano (ver "Verlo funcionar" arriba)	No como característica principal. AOP es un protocolo real para desplegar y llamar a un agente remoto nombrado como servicio distribuido, pero su ejemplo documentado es solo Python sin formato de cable agnóstico de lenguaje especificado. Existe un backend RedisConversation como utilidad de ejemplo, no coordinación entre lenguajes documentada.	No se encontró ninguno. feynman serve ejecuta una interfaz de workbench local orientada a humanos. El estado vive en un espejo SQLite local bajo ~/.feynman/, no detrás de una API documentada entre agentes.
Patrones de orquestación integrados (secuencial, jerárquico, enrutamiento de tareas)	Ninguno por diseño. SwarmMesh espera que traigas un orquestador	Sí, muchos. Esto es el núcleo de lo que hace swarms	Algunos, internos a su propio flujo de trabajo de investigación, no expuestos como SDK general
Búsqueda de memoria	Por palabras clave (BM25), explícitamente no semántica	No es el foco del proyecto	No es el foco del proyecto

La lectura honesta: swarms tiene profundidad real de orquestación y una gran comunidad que SwarmMesh no intenta reemplazar. feynman es una herramienta de investigación pulida para usuarios finales, no infraestructura que incrustarías en otro lugar. La afirmación real de SwarmMesh es más estrecha que cualquiera de las dos: un protocolo pequeño y documentado que dos lenguajes ya hablan de la misma manera. Vale exactamente eso, ni más.

Qué es SwarmMesh y por qué existe

Los entornos multiagente cada vez más significan varios procesos de agente trabajando el mismo problema en paralelo, a veces en el mismo lenguaje, a veces no, a veces generados por herramientas completamente diferentes. Los frameworks de orquestación resuelven el problema de "qué debería hacer cada agente y en qué orden". SwarmMesh resuelve un problema más estrecho y adyacente: una vez que esos agentes están en ejecución, ¿cómo se comunican entre sí lo que han encontrado sin que un humano retransmita mensajes entre terminales o los agentes dupliquen silenciosamente el trabajo de los demás. SwarmMesh es infraestructura, no un framework. No le importa qué orquestador generó tus agentes, si es que hay alguno. Expone una pequeña superficie HTTP + WebSocket para contexto compartido (estado estructurado de clave-valor, como la fase actual de una ejecución) y memoria compartida (notas de texto libre que los agentes dejan entre sí, buscables por palabra clave). Apuntas tus agentes a un proceso swarmmesh serve de la misma manera que los apuntarías a una instancia de Redis, y tienen un lugar compartido para leer y escribir.

FAQ

¿Es esto un reemplazo para LangGraph / CrewAI / AutoGen / <mi framework de orquestación>? No. SwarmMesh no programa agentes, define flujos de trabajo ni decide qué sucede después. Se ejecuta junto a lo que uses para eso y les da a los agentes que genera una capa de contexto y memoria compartida. Apunta los agentes de tu orquestador a un proceso swarmmesh serve y sigue usándolo para todo lo demás.

¿En qué se diferencia de kyegomez/swarms o companion-inc/feynman? Ambos son proyectos más grandes y antiguos que resuelven problemas diferentes. swarms es un framework de orquestación: decide qué agentes se ejecutan, en qué orden y cómo transfieren el trabajo, y lo hace con gran profundidad. SwarmMesh no hace nada de eso; solo les da a los agentes ya en ejecución un lugar compartido para leer y escribir estado. feynman es un producto de agente de investigación único con una interfaz de banco de trabajo local y su propio estado respaldado por SQLite, no una capa de coordinación que otros proyectos integren. Ninguno de los dos incluye un protocolo de cable entre lenguajes documentado para memoria compartida de agentes como lo hace el docs/protocol.md de SwarmMesh. Comparación completa arriba en Cómo se compara SwarmMesh.

¿La búsqueda de memoria es semántica / basada en embeddings? No. Es clasificación por palabras clave Okapi BM25, la misma familia de algoritmos que los motores de búsqueda han usado durante décadas, calculada localmente sobre la frecuencia de términos. No encontrará entradas de memoria que estén conceptualmente relacionadas pero que no compartan vocabulario con tu consulta. Si necesitas eso, la interfaz RankingBackend es un punto de extensión documentado para conectar tu propio puntuador basado en embeddings. SwarmMesh no incluye uno y no llamará silenciosamente a una API de embeddings en tu nombre.

¿Pueden un agente de Python y un agente de Node realmente compartir estado, o es eso teórico? Esta es la razón por la que existe el proyecto. Ambos CLIs implementan el mismo protocolo de cable en docs/protocol.md, y la sección "Verlo funcionar" de arriba es una transcripción real del CLI de Node escribiendo contexto y memoria a un servidor alojado en Python, y luego el CLI de Python leyéndolo de vuelta a través de la red, re-verificado mientras se escribía este README.

¿SwarmMesh persiste datos? Solo si se lo pides. swarmmesh serve por defecto usa almacenamiento en memoria que desaparece cuando el proceso sale. Pasa --persist <path> para almacenamiento respaldado por SQLite que sobrevive a reinicios.

¿Hay autenticación? No en v1. Consulta Seguridad a continuación: esto es un límite de alcance deliberado, no un descuido.

¿Qué sucede si dos agentes escriben en la misma clave de contexto? La última escritura gana. PUT /v1/context/{namespace}/{key} sobrescribe lo que hubiera allí. Cada escritura transmite un evento WebSocket context.updated, por lo que los agentes suscritos a ese espacio de nombres se enteran de inmediato en lugar de hacer polling. No hay fusión ni resolución de conflictos; si tus agentes necesitan eso, constrúyelo encima usando claves distintas o tu propia convención de versionado.

¿Puedo usar SwarmMesh como biblioteca en lugar del CLI? Sí. Ambos paquetes exportan un cliente: swarmmesh_cli.client.SwarmMeshClient en Python, SwarmMeshClient de swarmmesh-cli en Node. Consulta Referencia de API de biblioteca arriba para firmas de métodos reales.

¿Puedo ejecutar esto en más de una máquina, y está listo para producción? Nada impide que una malla sea accesible a través de una red; --host se vincula a cualquier interfaz a la que lo apuntes. Pero no hay autenticación en v1 (consulta Seguridad), así que trátalo como una instancia local de Redis, no como un servicio expuesto a internet público. También tiene 0 usuarios de producción conocidos en este punto, así que evalúa en consecuencia.

¿Es gratuito para uso comercial? Sí. SwarmMesh tiene licencia MIT, tanto en los paquetes de Python y Node como en el repositorio en sí. Úsalo en un producto comercial sin pedir permiso ni pagar nada.

Seguridad

[!WARNING] SwarmMesh no tiene autenticación en v1. Ejecutar un servidor SwarmMesh directamente expuesto a internet público sin un proxy inverso que agregue autenticación es una mala configuración, no un despliegue compatible.

Tanto los servidores de Python como los de Node se vinculan a 127.0.0.1 por defecto, no a 0.0.0.0. SwarmMesh está diseñado para ejecutarse en localhost o dentro de una red privada junto a los agentes que coordina. Ese es el mismo límite de confianza que una instancia local de Redis o un archivo SQLite, no un servicio expuesto a internet público.

¿Encontraste una vulnerabilidad? Por favor, no abras un issue público. Consulta SECURITY.md para el proceso de divulgación privada.

Contribuciones

SwarmMesh tiene dos implementaciones oficiales del mismo protocolo, mantenidas comportamentalmente idénticas a propósito. Consulta CONTRIBUTING.md para la configuración de desarrollo de ambas, el proceso de pull request y la regla fundamental que da forma a todo en este README: sin afirmaciones no verificadas. Cada número aquí tiene que ser reproducible a partir de un comando real.

Licencia

MIT