swarmmesh

SwarmMesh

Instalação • Início rápido • Recursos • Referência da CLI • Comparação • FAQ

Contexto e memória compartilhados para enxames de agentes de IA paralelos, por meio de um pequeno protocolo que Python e Node falam da mesma forma.

Inicie dez agentes de codificação na mesma tarefa e eles não conseguem ver o que cada um encontrou. Um agente redescobre um bug que outro já corrigiu. Dois agentes sobrescrevem o mesmo arquivo porque nenhum sabia que o outro o tocou. SwarmMesh é um pequeno servidor que fica ao lado do seu framework de agentes existente e dá a cada processo de agente, em qualquer linguagem que possa falar HTTP, um lugar compartilhado para publicar contexto e buscar memória.

Não é um framework de orquestração. Ele não agenda tarefas, define papéis de agentes ou roteia trabalho entre agentes. Seu framework existente (ou seu próprio código) continua fazendo isso. SwarmMesh responde apenas a uma pergunta: como processos de agentes independentes leem e escrevem o mesmo estado compartilhado.

Instalação

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

Qualquer uma das opções fornece um comando swarmmesh no seu PATH.

Veja funcionando

Esta é uma sessão real de terminal, não uma simulação: um mesh executado em Python, um agente Node escrevendo nele e um agente Python lendo de volta o que o agente Node escreveu. Duas linguagens diferentes, um único mesh compartilhado.

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

Todos os comandos acima foram reexecutados de verdade contra ambas as CLIs enquanto este README era escrito: a CLI Node registrou um agente e escreveu contexto e memória em um mesh hospedado em Python, e a CLI Python leu tudo de volta, na mesma execução, pela API HTTP real, com a pontuação acima (0.575) reproduzida exatamente. Sem sistema de arquivos compartilhado, sem processo compartilhado, sem camada de tradução. Apenas o protocolo.

Início 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 sequência exata foi executada de ponta a ponta enquanto este README era escrito e concluída em poucos segundos, do início ao fim, contra o pacote real swarmmesh-cli instalado do PyPI.

Para compilar a partir do código-fonte em vez de instalar de um repositório:

# 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

Recursos

• Um protocolo de rede documentado. docs/protocol.md especifica cada endpoint HTTP e evento WebSocket, para que qualquer processo que fale HTTP e JSON possa entrar em um mesh. As duas CLIs oficiais são clientes convenientes, não os únicos válidos.
• Duas implementações independentes e interoperáveis. Python (swarmmesh-cli no PyPI, FastAPI + Typer, 74 testes, 91% de cobertura de declarações) e Node (swarmmesh-cli no npm, Express + commander, 65 testes, 91,64% de cobertura de declarações) implementam o protocolo de forma idêntica. A suíte de testes de cada pacote roda de forma independente na CI; a interoperabilidade entre linguagens (um cliente Node contra um servidor hospedado em Python e vice-versa) é demonstrada na seção "Veja funcionando" acima e foi reexecutada manualmente contra ambos os pacotes reais, não coberta por um teste automatizado entre linguagens na CI hoje.
• Atualizações em tempo real via WebSocket. /v1/events envia frames de context.updated, context.deleted, memory.written, agent.registered e agent.deregistered para que um agente possa reagir no momento em que outro agente muda o estado compartilhado, em vez de fazer polling.
• Busca de memória honesta. Consultas de memória usam classificação por palavras-chave Okapi BM25: pontuação real de frequência de termos, calculada localmente sem dependências extras e sem chamadas de rede. Não é busca semântica ou por embeddings. Uma interface RankingBackend é um ponto de extensão documentado se você quiser plugar seu próprio classificador baseado em embeddings; o SwarmMesh não inclui um.
• Armazenamento plugável. Em memória por padrão (apenas durante a vida do processo), ou --persist <path> para armazenamento com suporte a SQLite que sobrevive a reinicializações.
• Nativo para agentes por padrão. Todo subcomando em ambas as CLIs suporta --json para saída estruturada e analisável por scripts, e ambas incluem um subcomando swarmmesh mcp que inicia um servidor MCP via stdio, para que um agente com capacidade MCP (Claude ou outro) possa chamar o SwarmMesh como um conjunto de ferramentas sem invocar o shell.
• Um limite de confiança deliberadamente pequeno. Ambos os servidores vinculam a 127.0.0.1 por padrão, não a 0.0.0.0. Não há autenticação na v1. Veja Segurança.

O número abaixo é medido, não estimado. 50 requisições sequenciais de PUT /v1/context/{namespace}/{key} contra um servidor local executado em Python tiveram média de 0,8ms de ida e volta cada (40ms no total para 50 requisições) na máquina em que este README foi escrito. Isso não é um benchmark rigoroso, inclui a sobrecarga de spawn de processo do próprio curl por requisição e varia conforme a máquina, mas é um número real de uma execução real, não um palpite. Reproduza você mesmo com:

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

Referência da CLI

Ambas as CLIs expõem a mesma árvore de comandos. Os nomes das flags diferem ligeiramente entre as duas (Python usa o estilo --flag <value> do Typer, Node usa o do commander), mas os comandos e seu comportamento são idênticos. A saída abaixo é transcrita da execução de --help em 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 analisa <value> como JSON, com fallback para string simples se não for JSON válido. context set ns key '"planning"' armazena a string planning. O mesmo faz context set ns key planning (sem aspas), pelo mesmo fallback de string.

Servidor MCP

O SwarmMesh inclui um servidor Model Context Protocol (MCP), tanto no pacote Python quanto no Node, para que um agente com capacidade MCP (Claude Desktop, Claude Code ou qualquer outro cliente MCP) possa chamar o SwarmMesh como um conjunto de ferramentas em vez de invocar a CLI via shell. O servidor MCP não reimplementa o protocolo; ele faz proxy de cada chamada de ferramenta via HTTP para um processo swarmmesh serve que você já está executando.

# 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

O suporte a mcp está incluído por padrão em ambos os pacotes (é uma dependência central, não um extra opcional), então basta um pip install swarmmesh-cli ou npm install -g swarmmesh-cli simples.

Configuração do Claude Desktop (claude_desktop_config.json):

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

Tanto o servidor MCP Python quanto o Node expõem as mesmas dez ferramentas, espelhando os métodos SwarmMeshClient acima:

Ferramenta	O que faz	Exemplo de chamada
register_agent	Registra um agente no mesh.	register_agent(agent_id="agent-1", role="researcher")
deregister_agent	Remove o registro de um agente do mesh. Idempotente.	deregister_agent(agent_id="agent-1")
list_agents	Lista agentes atualmente registrados no mesh.	list_agents()
publish_context	Publica (cria ou sobrescreve) um valor de contexto em um namespace.	publish_context(namespace="my-run", key="phase", value="planning", agent_id="agent-1")
get_context	Lê um único valor de contexto.	get_context(namespace="my-run", key="phase")
list_context	Lista todas as entradas de contexto ativas (não expiradas) em um namespace.	list_context(namespace="my-run")
delete_context	Exclui um valor de contexto.	delete_context(namespace="my-run", key="phase")
write_memory	Escreve uma entrada de memória que outros agentes do enxame podem encontrar depois.	write_memory(namespace="my-run", text="found a race condition in the retry loop", agent_id="agent-1")
query_memory	Consulta entradas de memória em um namespace por classificação de palavras-chave BM25 (não busca semântica).	query_memory(namespace="my-run", query="race condition")
get_status	Obtém um instantâneo do status do mesh (contagem de agentes, namespaces, contagens de entradas, tempo de atividade).	get_status()

Referência da API de biblioteca

Ambos os pacotes exportam um cliente tipado para que você possa chamar um mesh diretamente do seu próprio código de agente, em vez de invocar a CLI via shell. As assinaturas abaixo são extraídas diretamente do código-fonte, não da memória.

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>;
}

O protocolo SwarmMesh

A especificação completa está em docs/protocol.md. A versão curta: um "mesh" é um processo swarmmesh serve em execução. Agentes são processos independentes (agentes de codificação, agentes de pesquisa, subprocessos de trabalho, qualquer coisa que possa fazer uma requisição HTTP) que se registram em um mesh e depois leem e escrevem contexto e memória compartilhados com namespaces.

O ponto de escrever isso como um protocolo, em vez de apenas fornecer uma biblioteca, é que isso significa que as duas CLIs oficiais não são os únicos clientes válidos. Um agente Python usando swarmmesh_cli.client.SwarmMeshClient, um agente Node usando o SwarmMeshClient de swarmmesh-cli e um terceiro agente escrito em uma linguagem sem nenhum dos pacotes podem todos se registrar no mesmo mesh e ver o contexto e a memória uns dos outros, porque todos estão apenas chamando os mesmos endpoints HTTP documentados e, opcionalmente, assinando o mesmo fluxo de eventos WebSocket. Nada sobre interoperabilidade depende de um runtime compartilhado, um processo compartilhado ou um sistema de arquivos compartilhado.

Como o SwarmMesh se compara

Não há outro projeto fazendo exatamente o que o SwarmMesh faz, então esta não é uma tabela comparável diretamente. Está aqui para ser honesto sobre o que dois projetos reais e comparáveis de multiagentes realmente oferecem versus o que o SwarmMesh realmente oferece, verificado diretamente contra seus READMEs e código-fonte, não presumido pelos nomes. Ambos são mais antigos, maiores e mais estabelecidos que o SwarmMesh, que tem 0 estrelas no GitHub e nenhum usuário conhecido até agora.

	SwarmMesh	kyegomez/swarms	companion-inc/feynman
O que é	Camada de coordenação de contexto/memória compartilhados (infraestrutura, não um framework)	Framework de orquestração multiagentes	Agente de pesquisa de IA com uma UI local de workbench
Estrelas	0	7.024	8.447
Linguagem principal	Python + TypeScript (duas implementações testadas)	Python	TypeScript
Licença	MIT	Apache-2.0	MIT
Instalação	pip install swarmmesh-cli / npm install -g swarmmesh-cli	pip3 install -U swarms	curl -fsSL https://feynman.is/install | bash
Protocolo de rede entre linguagens documentado para contexto/memória compartilhados	Sim: docs/protocol.md, HTTP + WebSocket, duas implementações independentes verificadas interoperáveis manualmente (veja "Veja funcionando" acima)	Não como recurso principal. AOP é um protocolo real para implantar e chamar um agente remoto nomeado como um serviço distribuído, mas seu exemplo documentado é apenas Python, sem formato de rede agnóstico de linguagem especificado. Um backend RedisConversation existe como utilitário de exemplo, não como coordenação entre linguagens documentada.	Nenhum encontrado. feynman serve executa uma UI local de workbench voltada a humanos. O estado fica em um espelho SQLite local sob ~/.feynman/, não atrás de uma API documentada entre agentes.
Padrões de orquestração integrados (sequencial, hierárquico, roteamento de tarefas)	Nenhum por design. O SwarmMesh espera que você traga um orquestrador	Sim, muitos. Este é o núcleo do que o swarms faz	Alguns, internos ao seu próprio fluxo de pesquisa, não expostos como um SDK geral
Busca de memória	Palavras-chave (BM25), explicitamente não semântica	Não é o foco do projeto	Não é o foco do projeto

A leitura honesta: o swarms tem profundidade real de orquestração e uma grande comunidade que o SwarmMesh não tenta substituir. O feynman é uma ferramenta de pesquisa refinada para usuários finais, não infraestrutura que você embutiria em outro lugar. A afirmação real do SwarmMesh é mais estreita que a de ambos: um protocolo pequeno e documentado que duas linguagens já falam da mesma forma. Vale exatamente isso, nada mais.

O que o SwarmMesh é e por que existe

Configurações multiagentes cada vez mais significam vários processos de agente trabalhando o mesmo problema em paralelo, às vezes na mesma linguagem, às vezes não, às vezes gerados por ferramentas completamente diferentes. Frameworks de orquestração resolvem o problema de "o que cada agente deve fazer e em que ordem". O SwarmMesh resolve um problema mais estreito e adjacente: uma vez que esses agentes estão em execução, como eles contam uns aos outros o que encontraram sem um humano retransmitindo mensagens entre terminais ou agentes duplicando silenciosamente o trabalho uns dos outros. SwarmMesh é infraestrutura, não um framework. Ele não se importa com qual orquestrador criou seus agentes, se é que algum foi usado. Ele expõe uma superfície pequena de HTTP + WebSocket para contexto compartilhado (estado estruturado de chave-valor, como a fase atual de uma execução) e memória compartilhada (notas em texto livre que os agentes deixam uns para os outros, pesquisáveis por palavra-chave). Você aponta seus agentes para um processo swarmmesh serve da mesma forma que apontaria para uma instância Redis, e eles têm um lugar compartilhado para ler e escrever.

FAQ

Isso substitui LangGraph / CrewAI / AutoGen / <meu framework de orquestração>? Não. O SwarmMesh não agenda agentes, define fluxos de trabalho ou decide o que acontece em seguida. Ele roda junto com o que você usa para isso e dá aos agentes que ele cria uma camada compartilhada de contexto e memória. Aponte os agentes do seu orquestrador para um processo swarmmesh serve e continue usando-o para todo o resto.

Qual é a diferença em relação ao kyegomez/swarms ou ao companion-inc/feynman? Ambos são projetos maiores e mais antigos que resolvem problemas diferentes. O swarms é um framework de orquestração: ele decide quais agentes rodam, em que ordem e como eles fazem a transferência de trabalho, e faz isso com profundidade real. O SwarmMesh não faz nada disso; ele apenas dá aos agentes já em execução um lugar compartilhado para ler e escrever estado. O feynman é um produto de agente de pesquisa único com uma interface de workbench local e seu próprio estado baseado em SQLite, não uma camada de coordenação que outros projetos incorporam. Nenhum dos dois entrega um protocolo de rede documentado entre linguagens para memória compartilhada de agentes como o docs/protocol.md do SwarmMesh faz. Comparação completa lado a lado acima em Como o SwarmMesh se compara.

A busca na memória é semântica / baseada em embeddings? Não. É ranqueamento por palavra-chave Okapi BM25, a mesma família de algoritmos que mecanismos de busca usam há décadas, calculado localmente sobre a frequência dos termos. Ela não encontrará entradas de memória que sejam conceitualmente relacionadas, mas que não compartilhem vocabulário com sua consulta. Se você precisar disso, a interface RankingBackend é um ponto de extensão documentado para conectar seu próprio classificador baseado em embeddings. O SwarmMesh não inclui um e não chamará silenciosamente uma API de embeddings em seu nome.

Um agente Python e um agente Node realmente conseguem compartilhar estado, ou isso é teórico? Essa é a razão pela qual o projeto existe. Ambos os CLIs implementam o mesmo protocolo de rede em docs/protocol.md, e a seção "Veja funcionando" acima é uma transcrição real do CLI Node escrevendo contexto e memória em um servidor hospedado em Python, e então o CLI Python lendo de volta pela rede, reverificado enquanto este README era escrito.

O SwarmMesh persiste dados? Somente se você pedir. O swarmmesh serve usa armazenamento em memória por padrão, que desaparece quando o processo termina. Passe --persist <path> para armazenamento baseado em SQLite que sobrevive a reinicializações.

Existe autenticação? Não na v1. Veja Segurança abaixo: isso é um limite de escopo deliberado, não uma omissão.

O que acontece se dois agentes escreverem na mesma chave de contexto? A última escrita vence. O PUT /v1/context/{namespace}/{key} sobrescreve o que estava lá. Cada escrita transmite um evento WebSocket context.updated, então os agentes assinados nesse namespace descobrem imediatamente, em vez de fazer polling. Não há mesclagem ou resolução de conflitos; se seus agentes precisarem disso, construa por cima usando chaves distintas ou sua própria convenção de versionamento.

Posso usar o SwarmMesh como biblioteca em vez do CLI? Sim. Ambos os pacotes exportam um cliente: swarmmesh_cli.client.SwarmMeshClient em Python, SwarmMeshClient de swarmmesh-cli em Node. Veja a Referência da API de biblioteca acima para assinaturas reais de métodos.

Posso rodar isso em mais de uma máquina, e está pronto para produção? Nada impede que um mesh seja acessível pela rede; o --host faz bind em qualquer interface que você apontar. Mas não há autenticação na v1 (veja Segurança), então trate-o como uma instância Redis local, não como um serviço voltado para a internet pública. Ele também tem 0 usuários conhecidos em produção neste momento, então avalie de acordo.

É gratuito para uso comercial? Sim. O SwarmMesh é licenciado sob MIT, tanto nos pacotes Python e Node quanto no próprio repositório. Use-o em um produto comercial sem pedir permissão ou pagar nada.

Segurança

[!WARNING] O SwarmMesh não tem autenticação na v1. Rodar um servidor SwarmMesh diretamente exposto à internet pública sem um proxy reverso adicionando autenticação é uma configuração incorreta, não uma implantação suportada.

Tanto os servidores Python quanto os Node fazem bind em 127.0.0.1 por padrão, não em 0.0.0.0. O SwarmMesh é projetado para rodar em localhost ou dentro de uma rede privada junto com os agentes que coordena. Esse é o mesmo limite de confiança de uma instância Redis local ou de um arquivo SQLite, não um serviço voltado para a internet pública.

Encontrou uma vulnerabilidade? Por favor, não abra uma issue pública. Veja SECURITY.md para o processo de divulgação privada.

Contribuindo

O SwarmMesh tem duas implementações oficiais do mesmo protocolo, mantidas comportamentalmente idênticas de propósito. Veja CONTRIBUTING.md para a configuração de desenvolvimento de ambas, o processo de pull request e a regra fundamental que molda tudo neste README: nenhuma afirmação não verificada. Cada número aqui tem que ser reproduzível a partir de um comando real.

Licença

MIT