Commons

Commons に接続された AI はすべて、起動できます。起動できないエージェント（自分から定期的に接続するだけのもの）は、ドロワーに「Commons はこの AI を起動できません」と表示され、起動サービスをインストールしてキーを保持するために送る一文が示されます。

手動で設定する場合は、AI が実行されているマシンで次のコマンドを実行します。

pip install -U commons-memory && commons setup --client claude-code --agent my-agent --url http://HUB:8770

エージェントのキーを一度だけ入力すると（入力は非表示で、0600 の権限で保存されます）、各手順を既定ですべて実行します。

• MCP 経由で AI を Commons に接続します。
• 常に読み込まれるマスター指示をインストールします（CLAUDE.md と commons スキル、AGENTS.md、GEMINI.md、または Cursor ルール）。
• 自動キャプチャフックをインストールします。
• 即時起動機能をインストールします。
• AI の既存のメモリを引き継ぎます。
• 接続を検証します。

手順を省略するには --no-<step> を追加します。ダッシュボードの Connect ページでは、手順ごとのチェックボックスを使ってこのコマンドを作成できます。 クライアント：claude-code、codex、gemini、cursor、opencode、copilot、cline、kilo、amp、factory、qwen、crush、goose、windsurf、zed、roo、warp。

ホスト型チャットアプリ（claude.ai、ChatGPT、Grok、Muse）はコマンドを実行できません。カスタム指示に PROMPT.md を貼り付けてください。マスター指示と同じ内容から生成されるため、古くなることはありません。また、Commons は各エージェントに、初回のチェックイン時と内容が変更されたときに同じプレイブックを渡します。

スクリーンショット

デモハブ（python scripts/demo_seed.py demo.db）から取得したスクリーンショットです：架空のエージェント、ジョブ、メモリが表示されています。

概要：まず対応が必要なこと（ワンタップでの回答、承認）を確認し、次に利用料金、実行中のジョブ、チーム、アクティビティを確認できます	ジョブ：ライブフィルターですべてのジョブを確認できます。ジョブを開くとドロワーが表示され、ステージの流れ、ステップ、ルーティング、担当者のアクションを確認できます
エージェント：エージェント群、それぞれの作業内容、モデル、クォータ、ツールのバージョンを確認できます。クリックするとエージェントのドロワーが開きます	スマートフォンでの表示：すべてのページが幅 390 px で動作し、下部バーとサブタブが表示されます
ボード（ライトテーマ）：依頼内容、目標、納品物を確認でき、「完了」と「取り消し」をワンクリックで実行できます	利用状況：エージェントごとの日別の利用料金とトークン数を、7～30 日分確認できます
メモリ：まず検索し、フィルターチップ、ドロワー、一括操作を利用できます	AI の接続：参加リンクは 1 つだけです。ターミナルの 1 行、ボット向けの 1 文、またはコネクターアドレスを使い、各 AI は参加すると表示されます
ナレッジ：プロジェクトごとに自動作成され、出典が示されたナレッジベースです	グラフ：メモリ、コード、セッション、エージェントを 1 つのグラフにまとめます
ミッションコントロール：公平な割り当てスケジューリングと、容量に対するエージェントの負荷を確認できます	プロジェクト：1 つの製品に関するすべてを 1 か所にまとめます。進行中の作業、タイムライン、差分、メモリ、各作業の担当者を確認できます
インフラストラクチャ：すべての稼働場所を確認できます。容量と各ゲストへの割り当てに続いて、ズーム可能なマップ、グラフ、各項目のドロワーが表示されます

5 つのコマンドでマルチエージェント

commons serve --transport http --host <tailnet-ip> --port 8770 --dashboard     # 1. the hub (keys required)
commons connect grok --expertise code:0.9,review:0.7                           # 2. each agent gets a key + profile
commons connect muse --expertise writing:0.9,review:0.8
commons submit "Ship the onboarding docs:
- write the quickstart
- write the troubleshooting page" --project docs                             # 3. bullets → parallel parts + reviews
commons worker --agent grok --preset claude --url http://<tailnet-ip>:8770/mcp --api-key "$(cat ~/.commons/agents/grok.key)" &   # 4. headless seats
commons status                                                                  # 5. or the dashboard's Mission control

対話型 AI は pickup → claim_subtask → complete_subtask の順に操作して、同じサブタスクを引き受けます。オフラインのエージェントは各自のチャネル経由で呼び起こされ、行き詰まった作業はエスカレーションされます。

セキュリティモデル

• ID。 HTTP ではすべてのリクエストでエージェントキーまたは OAuth 2.1 トークンが必要です（それ以外は 401）。保存されるのはキーのハッシュのみです。各プリンシパルにはレート制限が適用されます（429、COMMONS_RATE_PER_MIN）。
• アクセス制御。 プロジェクトごとの ACL（commons acl grant PROJECT AGENT --role read|write|admin）。プロジェクトの唯一の作成者は、そのプロジェクトを非公開にできます。信頼スコアは検索と KB の重み付けに使われます。
• メモリに生のシークレットを保持しません。 すべての書き込みは、gitleaks 形式の検出とエントロピーに基づくマスキング処理を通ります。シークレットは参照として保存され（env://、vault://、vault-dyn://、op://、infisical://）、エージェントに紐付いた短期間のリースを通じて使用されます。commons secret-exec は値を子プロセスに渡し、そのプロセスの出力では値をマスキングします。
• ツール。 MCP ハブは、エージェントとツールごとに許可／拒否／承認ポリシーを適用します。破壊的な呼び出しには、正確な引数に紐付いた人間による承認が必要です。上流からの出力は信頼できないものとして区切られます。監視対象の GitHub リポジトリに第三者が書き込めるもの（issue や PR のテキスト、ブランチ名、コミットメッセージ）も同様です。これらがジョブタイトルに使われることはなく、github_outside を有効にしない限り、リポジトリ外の人による issue や PR からジョブが作成されることもありません。
• 所有者の確認。 トークン不要の LAN ダッシュボードでは、同じネットワーク上のエージェントとあなたを区別できません。そのため、エージェント自身のリクエストを承認したり、キーにアクセスしたりする可能性のある操作（承認、プロバイダー、設定、Vault、MCP ポリシー、信頼、ルーティング、新しいエージェントキー）には、所有者パスワードを一度設定すると、その入力が必要です。初回訪問時にパスワードを設定します。Commons の起動後 30 分間、ダッシュボードにはコード不要の「このハブを自分のものにする」が表示され、どのブラウザーからでも最初に開いた人が設定できます（パスワードが設定されるまでは再起動のたびに設定可能な状態に戻ります。所有権の取得は毎回通知されます。COMMONS_CLAIM_MINUTES=0 の場合はセットアップコードのみが使われます）。その後、各ブラウザーでは 14 日間サインイン状態が維持されます。ダッシュボード全体をパスワードで保護するには、Setup で dashboard_lock を有効にしてください。モデルプロバイダー、ロールモデル、キルスイッチ後の再開には、MCP 経由での管理者権限も必要です。
• レビューゲート。 スキルと承認が必要なサブタスクは、別のエージェント（またはあなた）による承認が必要です。キルスイッチ、1 日あたりのコスト上限、ジョブごとの予算があります。
• ネットワーク。 ループバックまたはプライベートネットワークにバインドしてください（以下を参照）。ダッシュボードでトークンが不要なのはプライベートアドレスのみです。パブリックアドレスへのバインドにはトークンが必要です。アウトバウンド Webhook は HTTPS のみで、SSRF チェックが適用されます（COMMONS_WEBHOOK_ALLOWLIST）。シークレット、ACL、承認、エスカレーションは監査ログに記録されます。
• 保存時の暗号化：SQLCipher（COMMONS_DB_KEY）またはディスク暗号化。既知の課題は FLAWS_AND_GAPS.md で正直に追跡しています。

ネットワーク

• 1 台のマシン： stdio MCP。ネットワーク上では何も待ち受けません。
• 複数台のマシン（推奨）：テイルネット／VPN。 commons serve --transport http --host <tailscale-ip> --port 8770 --dashboard。ダッシュボードは --host に従います。localhost、LAN（RFC 1918）、テイルネット（100.64.0.0/10）のアドレスでは、トークンは不要です。パブリックアドレスにバインドするには、COMMONS_DASHBOARD_TOKEN が必要です。どこからのアクセスにもトークンを要求するには、COMMONS_DASHBOARD_REQUIRE_TOKEN=1 を設定してください。
• 0.0.0.0 にはバインドしないでください。 ただし、ホストにパブリックインターフェースがない場合は除きます。--host <private-ip> と TLS（--tls-self-signed または --tls-cert/--tls-key）を使用し、キーを必須のままにしてください。
• どこからでもアクセスする場合： commons expose up tailscale|cloudflare|ngrok|ssh|…。キーが必須でない限り、パブリックへの公開は拒否されます。サービスとして実行するには、commons expose service systemd|launchd|windows を使います。詳細は docs/networking.md を参照してください。
• Docker： docker compose up -d、または以下のワンライナーを使います（docs/docker.md で確定予定）：

  docker run -d --name commons -p 8770:8770 -p 8766:8766 -v commons-data:/data ghcr.io/neoo-blue/commons-memory:latest   # placeholder, see docs/docker.md
  

設定

すべてデフォルト設定で動作します。通常、変更する設定は次のとおりです。

89 個すべての変数はdocs/configuration.mdに記載されています。これはコードから scripts/gen_env_reference.py によって生成され、設定がドキュメントに記載されていない場合はテストが失敗します。

トラブルシューティング

FAQ

• サーバーは必要ですか？ いいえ。1 台のマシンであれば、stdio と 1 つの SQLite ファイルを使います。別のマシン上の AI が接続する必要がある場合にのみ、serve --transport http を実行してください。
• どの AI が使えますか？ MCP（stdio またはストリーミング可能な HTTP）に対応しているものなら何でも使えます。それ以外は、HTTP の /bus/* および /agent/* エンドポイント、または CLI ワーカーを利用できます。
• モデルにシークレットが漏れますか？ 書き込みは秘匿化され、シークレットは参照のみで扱われます。値が子プロセスに渡されるのは secret-exec 経由のみです。
• 費用はかかりますか？ プランナー、要約ツール、プロバイダーを設定しない限り、Commons 自体が LLM を呼び出すことはありません。エージェントが報告した使用状況はダッシュボードに表示されます。
• SQLite から Postgres に移行できますか？ はい。commons migrate-postgres postgresql://… を実行してください。
• 停止できますか？ はい。commons pause を実行してください（緊急停止スイッチ）。commons dump を実行すると、すべてを JSONL としてエクスポートします。

ベンチマーク（v0.9.0、v0.28でQA、v0.30でツールサイズを測定）

他のジョブで負荷がかかっていた8コアのApple M1ラップトップで、CPUのみを使って測定しました。全テーブル、留意事項、質問ごとの結果はbenchmarks/README.mdにあります。すべての数値はcommons benchで再現できます。

同じLoCoMoデータで実行した競合製品との直接比較（詳細はbenchmarks/README.mdを参照）：

他の場所で公開されている数値は、異なる回答者、判定者、サブセットを使用しています（mem0の論文：gpt-4o-miniで66.9%。mem0のマネージドプラットフォームとZepは、独自の設定で92～95%を主張）。したがって、単純に比較できるのは上の表のみです。

比較

ロードマップ

• PyPIへの初回リリース（公開ワークフローは整備済みです。リリース後は uvx commons-memory ／ pipx install commons-memory が使えます）。
• OIDCによるホスト型ダッシュボードの認証。

履歴：CHANGELOG.md。

開発

git clone https://github.com/Neoo-Blue/commons-memory && cd commons-memory
uv venv && uv pip install -e ".[dev,all]" && uv run pytest -q
python scripts/gen_env_reference.py      # after adding a COMMONS_* setting

MITライセンスです。