swarmmesh

SwarmMesh

インストール • クイックスタート • 機能 • CLI リファレンス • 比較 • FAQ

並列で動作する AI エージェントの群れのための、共有コンテキストとメモリです。Python と Node が同じ方法で通信できる、小さなプロトコルを介して利用できます。

同じタスクにコーディングエージェントを10個起動しても、それぞれが見つけたことを互いに確認できません。あるエージェントは、別のエージェントがすでに修正したバグを再発見します。別のエージェントがファイルを編集したことを知らないため、2つのエージェントが同じファイルを上書きします。SwarmMesh は既存のエージェントフレームワークと並行して動作する小さなサーバーで、HTTP に対応するあらゆる言語のエージェントプロセスに、コンテキストを共有し、メモリを検索する場所を提供します。

これはオーケストレーションフレームワークではありません。タスクのスケジュール設定や、エージェントの役割の定義、エージェント間の作業の振り分けは行いません。そうしたことは既存のフレームワーク（または独自のコード）が引き続き担います。SwarmMesh が答えるのは、独立したエージェントプロセスが同じ共有状態を読み書きするにはどうすればよいか、という1つの問いだけです。

インストール

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

どちらの方法でも、PATH 上で swarmmesh コマンドを使えるようになります。

動作を見る

これはモックアップではなく、実際のターミナルセッションです。Python で実行するメッシュに Node のエージェントが書き込み、Python のエージェントが Node のエージェントの書き込み内容を読み取ります。異なる2つの言語が、1つの共有メッシュを使います。

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

上記のすべてのコマンドは、この README の作成中に両方の CLI で実際に再実行しました。Node CLI がエージェントを登録し、Python がホストするメッシュにコンテキストとメモリを書き込みました。その後、同じ実行中に Python CLI が実際の HTTP API 経由で内容を直接読み取り、上記のスコア（0.575）も正確に再現しました。共有ファイルシステムも、共有プロセスも、変換レイヤーもありません。あるのはプロトコルだけです。

クイックスタート

# 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

この一連の手順は、README の作成中に実際の swarmmesh-cli パッケージを PyPI からインストールして最初から最後まで実行し、数秒で完了しました。

レジストリからインストールするのではなく、ソースからビルドするには：

# 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

特長

• 文書化されたワイヤープロトコル。 docs/protocol.md には、すべての HTTP エンドポイントと WebSocket イベントが 記載されているため、HTTP と JSON を扱えるプロセスならどれでも メッシュに参加できます。公式 CLI 2 種は便利なクライアントですが、 使用できるクライアントはそれだけではありません。
• 相互運用可能な、独立した 2 つの実装。 Python （PyPI の swarmmesh-cli、FastAPI + Typer、テスト 74 件、ステートメント カバレッジ 91％）と Node（npm の swarmmesh-cli、Express + commander、テスト 65 件、 ステートメントカバレッジ 91.64％）は、同じプロトコルを実装しています。各 パッケージ独自のテストスイートは CI で個別に実行されます。言語をまたぐ 相互運用性（Node クライアントから Python でホストされたサーバーへの接続と、その逆）は、 上記の「動作を確認する」セクションで実演しており、両方の実際の パッケージを使って手動で再実行しましたが、現時点では CI の自動テストでは 対象になっていません。
• WebSocket によるリアルタイム更新。 /v1/events は context.updated、context.deleted、memory.written、 agent.registered、agent.deregistered の各フレームをプッシュするため、 エージェントはポーリングせずに、別のエージェントが共有状態を変更した 瞬間に反応できます。
• 誠実なメモリー検索。 メモリーのクエリでは Okapi BM25 によるキーワードランキングを使用します。 実際の語頻度スコアをローカルで計算し、追加の依存関係やネットワーク呼び出しは 必要ありません。セマンティック検索でも、埋め込み検索でもありません。 RankingBackend インターフェースは、独自の埋め込みベースのスコアラーを 接続する場合に利用できる、文書化された拡張ポイントです。SwarmMesh には スコアラーは含まれていません。
• ストレージをプラグイン可能。 デフォルトではメモリー内（プロセスの実行中のみ）で、 --persist <path> を指定すると再起動後も保持される SQLite ベースのストレージを 使用できます。
• エージェント向けを標準設定に。 両 CLI のすべてのサブコマンドは 構造化され、スクリプトで解析可能な出力を得るための --json に対応しており、 どちらにも、stdio 経由で MCP サーバーを起動する swarmmesh mcp サブコマンドが用意されています。これにより、 MCP 対応エージェント（Claude など）はシェルコマンドを実行せずに、 SwarmMesh を一連のツールとして呼び出せます。
• 意図的に小さくした信頼境界。 両サーバーはデフォルトで 0.0.0.0 ではなく 127.0.0.1 にバインドします。v1 には認証機能はありません。 セキュリティを参照してください。

以下の数値は推定ではなく、実測値です。この README を作成したマシンで、 ローカルの Python 実行サーバーに対して PUT /v1/context/{namespace}/{key} リクエストを 50 回連続で送信したところ、1 回あたりのラウンドトリップ時間は平均 0.8ms （50 リクエストで合計 40ms）でした。これは厳密なベンチマークではなく、 リクエストごとの curl 自体のプロセス起動オーバーヘッドも含まれており、 マシンによって変動しますが、推測ではなく、実際に実行して得た数値です。 次の方法で再現できます：

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 リファレンス

両 CLI は同じコマンドツリーを公開しています。フラグ名は 2 つの CLI 間で 多少異なります（Python は Typer の --flag <value> 形式、Node は commander の形式を 使用します）が、コマンドとその動作は同じです。以下の出力は、ビルド済みの各 CLI で --help を実行した結果を転記したものです。

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 は <value> を JSON として解析し、有効な JSON でない場合は プレーンな文字列として扱います。context set ns key '"planning"' は文字列 planning を保存します。引用符を付けない context set ns key planning も、同じく 文字列として扱われ、文字列 planning が保存されます。

MCP サーバー

SwarmMesh は Python パッケージと Node パッケージの両方で Model Context Protocol（MCP）サーバーを提供しているため、MCP 対応エージェント（Claude Desktop、Claude Code、その他の MCP クライアント）は、CLI を呼び出す代わりに、ツールの集合として SwarmMesh を呼び出せます。MCP サーバーはプロトコルを再実装するのではなく、各ツール呼び出しを、すでに実行中の swarmmesh serve プロセスに HTTP 経由でプロキシします。

# 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 のサポートは両方のパッケージにデフォルトで含まれているため（オプションの追加機能ではなく、コア依存関係です）、通常の pip install swarmmesh-cli または npm install -g swarmmesh-cli だけで準備できます。

Claude Desktop の設定（claude_desktop_config.json）：

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

Python と Node の MCP サーバーは、上記の SwarmMeshClient メソッドに対応する、同じ 10 個のツールを公開します。

ツール	機能	呼び出し例
register_agent	エージェントをメッシュに登録します。	register_agent(agent_id="agent-1", role="researcher")
deregister_agent	エージェントをメッシュから登録解除します。冪等です。	deregister_agent(agent_id="agent-1")
list_agents	現在メッシュに登録されているエージェントを一覧表示します。	list_agents()
publish_context	名前空間内のコンテキスト値を公開（作成または上書き）します。	publish_context(namespace="my-run", key="phase", value="planning", agent_id="agent-1")
get_context	単一のコンテキスト値を読み取ります。	get_context(namespace="my-run", key="phase")
list_context	名前空間内の有効な（期限切れでない）コンテキストエントリをすべて一覧表示します。	list_context(namespace="my-run")
delete_context	コンテキスト値を削除します。	delete_context(namespace="my-run", key="phase")
write_memory	スウォーム内の他のエージェントが後で見つけられるメモリエントリを書き込みます。	write_memory(namespace="my-run", text="found a race condition in the retry loop", agent_id="agent-1")
query_memory	BM25 キーワードランキング（セマンティック検索ではありません）で、名前空間内のメモリエントリを検索します。	query_memory(namespace="my-run", query="race condition")
get_status	メッシュのステータススナップショット（エージェント数、名前空間、エントリ数、稼働時間）を取得します。	get_status()

ライブラリ API リファレンス

両方のパッケージは型付きクライアントを公開しているため、CLI を呼び出す代わりに、独自のエージェントコードからメッシュを直接呼び出せます。以下のシグネチャは記憶を頼りにしたものではなく、ソースコードから直接抽出しています。

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（swarmmesh-cli の SwarmMeshClient）：

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

SwarmMesh プロトコル

完全な仕様は docs/protocol.md にあります。要約すると、「メッシュ」とは、実行中の 1 つの swarmmesh serve プロセスです。エージェントは独立したプロセス（コーディングエージェント、リサーチエージェント、サブプロセスワーカー、HTTP リクエストを送信できるものなら何でも）であり、メッシュに登録してから、名前空間で共有されるコンテキストやメモリを読み書きします。

これを単なるライブラリとして提供するのではなく、プロトコルとして文書化する理由は、これにより公式 CLI 2 つだけが有効なクライアントではなくなるからです。swarmmesh_cli.client.SwarmMeshClient を使う Python エージェント、swarmmesh-cli の SwarmMeshClient を使う Node エージェント、どちらのパッケージもない言語で書かれた別のエージェントは、いずれも同じメッシュに登録し、互いのコンテキストやメモリを参照できます。これは、全エージェントが同じ文書化された HTTP エンドポイントを呼び出し、必要に応じて同じ WebSocket イベントストリームを購読するだけだからです。相互運用性は、共通のランタイム、共通のプロセス、共通のファイルシステムのいずれにも依存しません。

SwarmMesh の比較

SwarmMesh が実現していることをそのまま行う他のプロジェクトはないため、これは単純に比較できる表ではありません。ここでは、実際に比較可能な 2 つのマルチエージェントプロジェクトが何を提供しているか、そして SwarmMesh が実際に何を提供しているかを、名前から推測するのではなく、それぞれの README とソースを直接確認したうえで率直に示します。どちらも SwarmMesh より歴史が長く、規模も大きく、より確立されています。SwarmMesh の GitHub スター数は 0 で、現時点で既知のユーザーもいません。

	SwarmMesh	kyegomez/swarms	companion-inc/feynman
概要	共有コンテキスト／メモリの調整レイヤー（インフラストラクチャであり、フレームワークではありません）	マルチエージェントのオーケストレーションフレームワーク	ローカルのワークベンチ UI を備えた AI 研究エージェント
スター数	0	7,024	8,447
主な言語	Python + TypeScript（テスト済みの 2 つの実装）	Python	TypeScript
ライセンス	MIT	Apache-2.0	MIT
インストール	pip install swarmmesh-cli / npm install -g swarmmesh-cli	pip3 install -U swarms	curl -fsSL https://feynman.is/install | bash
共有コンテキスト／メモリ用の、文書化された言語横断のワイヤープロトコル	あり：docs/protocol.md、HTTP + WebSocket。独立した 2 つの実装が、手動で相互運用可能であることを確認済みです（上記の「動作を確認する」を参照）	主要機能としては掲げられていません。AOP は、名前付きのリモートエージェントを分散サービスとしてデプロイして呼び出すための実際のプロトコルですが、文書化されている例は Python のみで、言語に依存しないワイヤー形式は定義されていません。RedisConversation バックエンドはサンプルユーティリティとして存在しますが、言語横断の調整機能としては文書化されていません。	見つかりませんでした。feynman serve は、ローカルで人間が使うワークベンチ UI を起動します。状態は ~/.feynman/ 配下のローカル SQLite ミラーに保存され、文書化されたエージェント間 API の背後にはありません。
組み込みのオーケストレーションパターン（逐次、階層型、タスクルーティング）	設計上ありません。SwarmMesh は、別途オーケストレーターを用意することを想定しています	あります。多数のパターンが用意されています。これが swarms の中核機能です	いくつかありますが、独自の研究ワークフロー内に限られており、汎用 SDK としては公開されていません
メモリ検索	キーワード検索（BM25）。セマンティック検索ではないことが明示されています	プロジェクトの主眼ではありません	プロジェクトの主眼ではありません

率直に言うと、swarms には実際に高度なオーケストレーション機能があり、SwarmMesh が置き換えようとしていない大規模なコミュニティもあります。feynman は洗練されたエンドユーザー向け研究ツールであり、別の場所に組み込むインフラストラクチャではありません。SwarmMesh が実際に主張しているのは、どちらよりも限定的なものです。2 つの言語がすでに同じ方法で扱える、小さく文書化されたプロトコルです。その価値はまさにそこまでであり、それ以上ではありません。

SwarmMesh とは何か、なぜ存在するのか

マルチエージェント構成では、複数のエージェントプロセスが同じ問題に並行して取り組むことが増えています。使う言語は同じ場合も違う場合もあり、まったく異なるツールによって起動されることもあります。オーケストレーションフレームワークは、「各エージェントが何を、どの順番で行うべきか」という問題を解決します。SwarmMesh が解決するのは、それに隣接する、より限定的な問題です。エージェントが起動した後、人間がターミナル間でメッセージを中継したり、エージェントが互いの作業を気づかずに重複させたりせずに、見つけたことをどう伝え合うかという問題です。

SwarmMesh はインフラストラクチャであり、フレームワークではありません。エージェントを起動したのがどのオーケストレーターか、あるいはそもそもオーケストレーターを使っているかどうかも問いません。共有コンテキスト（実行の現在のフェーズのような、構造化されたキーと値の状態）と共有メモリ（エージェント同士が残す自由記述のメモ。キーワードで検索可能）用の小さな HTTP + WebSocket インターフェースを提供します。Redis インスタンスを指し示すのと同じように、エージェントを swarmmesh serve プロセスに接続すれば、読み書き用の共有領域を利用できます。

FAQ

これは LangGraph／CrewAI／AutoGen／<my orchestration framework> の代替ですか？ いいえ。SwarmMesh はエージェントのスケジュール設定やワークフローの定義、次に何が起きるかの決定は行いません。そうした用途に使っているものと並行して動作し、起動したエージェントに共有コンテキストとメモリのレイヤーを提供します。オーケストレーターのエージェントを swarmmesh serve プロセスに接続し、それ以外の用途には引き続きオーケストレーターを使用してください。

kyegomez/swarms や companion-inc/feynman とは何が違いますか？ どちらも、異なる課題を解決する、より大規模で歴史の長いプロジェクトです。swarms はオーケストレーションフレームワークです。どのエージェントをどの順序で実行し、どのように作業を引き継ぐかを決定し、その機能を非常に深く実装しています。SwarmMesh はそのようなことは行わず、すでに実行中のエージェントに、状態を読み書きするための共有場所を提供するだけです。feynman はローカルのワークベンチ UI と独自の SQLite ベースの状態管理を備えた単体のリサーチエージェント製品であり、他のプロジェクトに組み込む調整レイヤーではありません。どちらにも、SwarmMesh の docs/protocol.md のように、エージェントのメモリを共有するための、文書化された言語横断のワイヤープロトコルは付属していません。詳しい比較は上のSwarmMesh の比較をご覧ください。

メモリ検索はセマンティック検索／埋め込みベースですか？ いいえ。Okapi BM25 によるキーワードランキングです。これは検索エンジンが何十年も使用してきたアルゴリズムと同じ系統で、用語の出現頻度をもとにローカルで計算します。クエリと語彙がまったく共通しない、概念的に関連するメモリエントリは見つけられません。その機能が必要な場合は、RankingBackend インターフェースが、独自の埋め込みベースのスコアラーを接続するための、文書化された拡張ポイントです。SwarmMesh にそのような機能は付属しておらず、ユーザーに代わって埋め込み API を密かに呼び出すこともありません。

Python エージェントと Node エージェントは、本当に状態を共有できますか？それとも理論上の話ですか？ それこそが、このプロジェクトの存在理由です。両方の CLI は docs/protocol.md に記載された同じワイヤープロトコルを実装しています。また、上の「動作を確認する」セクションには、Node CLI が Python ホストのサーバーにコンテキストとメモリを書き込み、その後 Python CLI がネットワーク経由で読み戻す実際の記録を掲載しています。この README の執筆時にも再検証しました。

SwarmMesh はデータを永続化しますか？ 指定した場合にのみ永続化します。swarmmesh serve はデフォルトでインメモリストレージを使用するため、プロセスの終了時にデータは失われます。再起動後もデータを保持する SQLite ベースのストレージを使うには、--persist <path> を渡してください。

認証機能はありますか？ v1 にはありません。以下のセキュリティをご覧ください。これは見落としではなく、意図的なスコープの境界です。

2 つのエージェントが同じコンテキストキーに書き込むとどうなりますか？ 後からの書き込みが優先されます。PUT /v1/context/{namespace}/{key} は既存の値を上書きします。書き込みのたびに context.updated WebSocket イベントがブロードキャストされるため、その名前空間を購読しているエージェントはポーリングせずにすぐに把握できます。マージや競合解決の機能はありません。エージェントにそれが必要な場合は、個別のキーや独自のバージョン管理規約を使って、上位レイヤーで実装してください。

CLI ではなく、ライブラリとして SwarmMesh を使えますか？ はい。どちらのパッケージもクライアントをエクスポートしています。Python では swarmmesh_cli.client.SwarmMeshClient、Node では swarmmesh-cli の SwarmMeshClient を使用できます。実際のメソッドシグネチャについては、上のライブラリ API リファレンスをご覧ください。

複数のマシンで実行できますか？また、本番環境で使用できますか？ メッシュがネットワーク経由で到達可能になることを妨げるものはありません。--host を使うと、指定した任意のインターフェースにバインドできます。ただし、v1 には認証機能がないため（セキュリティを参照）、パブリックインターネットに公開するサービスではなく、ローカルの Redis インスタンスと同様に扱ってください。また、現時点で本番環境の利用者は確認されていないため、その点を踏まえて評価してください。

商用利用は無料ですか？ はい。SwarmMesh は Python パッケージと Node パッケージ、リポジトリ自体のいずれも MIT ライセンスです。許可を求めたり料金を支払ったりせずに、商用製品で使用できます。

セキュリティ

警告

SwarmMesh v1 には認証機能がありません。認証を追加するリバースプロキシを経由せず、SwarmMesh サーバーを直接パブリックインターネットに公開して実行するのは、サポート対象外の設定ミスです。

Python サーバーと Node サーバーは、デフォルトで 0.0.0.0 ではなく 127.0.0.1 にバインドします。SwarmMesh は、ローカルホスト、または連携するエージェントと同じプライベートネットワーク内で実行するように設計されています。これは、ローカルの Redis インスタンスや SQLite ファイルと同じ信頼境界であり、パブリックインターネットに公開するサービスではありません。

脆弱性を発見した場合は、公開 issue を作成しないでください。非公開での報告手順については、SECURITY.md を参照してください。

コントリビューション

SwarmMesh には、同じプロトコルを実装した公式実装が 2 つあり、意図的に動作を同一に保っています。両方の開発環境のセットアップ、プルリクエストの手順、そしてこの README 全体を貫く基本原則である「未検証の主張をしない」については、CONTRIBUTING.md を参照してください。ここに記載するすべての数値は、実際のコマンドで再現できなければなりません。

ライセンス

MIT