Mcp Shared Memory Server

MCP Shared Memory Server (junto-memory)

Junto マルチエージェント連携システムの メモリ コンポーネントです。docker-compose と導入者向けの手順を含む、すぐに動かせるスタックについては、junto-stack から始めてください。

Model Context Protocol（MCP）を基盤とする、複数の AI コーディングエージェント向けの共有メモリおよび連携サーバーです。

📋 すでにサーバーを実行していますか？ リリースノートは CHANGELOG.md をご覧ください。現在のリリース（1.39.0）では、グローバルガイドラインの初期設定方法が変更され、execute-don't-ask のデフォルトが汎用化されています。それぞれにアップグレード時の注意事項があります。

重要

これは手作業でインストールするものではなく、AI エージェントがセットアップすることを想定しています。 Junto はコーディングエージェントの群れを連携させるためのものなので、インストール手順はエージェントが読んで実行するように書かれています。リポジトリをクローンして、Claude Code（または MCP 対応の任意のツール）のセッションに渡し、作業を任せてください。この README と AGENT_INSTALL.md に記載されたコマンドは、作業を見守れるように、またエージェントが正確に実行できるように用意されています。人間向けに調整された手順書ではなく、最初から最後まで通して読むことも想定していません。主導権はあなたにあります。エージェントは実際の判断が必要になるたびに一時停止します（パスワード、ポート、認証など）。セットアップをエージェントに任せたくない場合は、おそらくこのツールは適していません。

同じコードベースで複数の AI エージェントを動かすと、すぐに次の3つの問題が起こります。

1. セッション間であらゆることを忘れてしまいます。 エージェントが作業を中断すると、知識が失われます。次のエージェントは同じコードを再読し、同じバグを再発見し、同じ落とし穴を再学習することになります。
2. 互いの作業を妨げます。 2つのエージェントが同じファイルを変更します。誰が何をしているのか、何をロックしているのか、誰にもわかりません。
3. セッションが長くなるほど賢さが失われます。 研究ではこれを「コンテキストの劣化」と呼びます。コンテキストウィンドウが埋まるにつれて、モデルの性能が低下します。やがてすべてのエージェントが引き継ぎを行う必要がありますが、共有の頭脳がなければ、引き継ぎのたびに学習した内容がすべて失われます。

このサーバーは、これら3つすべての問題を解決します。セッションをまたいで維持される共有の頭脳をエージェントに提供し、エージェント間の作業を調整します。また、学んだことを記録できるため、次のエージェントは前のエージェントが中断したところから始められます。

実運用で実証済みです。 商用 IoT プラットフォームで、6つの専門エージェントを500以上のセッションにわたって連携させるために、本番環境で稼働しています。C#/.NET サーバー、Raspberry Pi 上の Python、.NET MAUI モバイルアプリ、MQTT、Redis など、さまざまな技術を扱っています。このサーバーが解決する問題は、苦労して見つけ出したものです。

---

できること

• 永続的なナレッジベース -- アーキテクチャ文書、学び、注意点、コードスニペットを保存します。セッションをまたいで保持され、ベクトル類似度（ChromaDB）を使って検索できます。
• マルチエージェント連携 -- ファイルロック、エージェント間のメッセージ送信、ハートビート監視、競合の検出により、複数の AI エージェントが互いの作業を妨げずに同じコードベースで作業できます。
• タスクとバックログの管理 -- 作業項目の追跡、エージェントへのタスク割り当て、チェックリストの管理、セッション間でのコンテキストの引き継ぎができます。
• 自動拡充機能付き関数レジストリ -- 関数を一度登録するだけで、ライブラリアンデーモンがソースコードを分析し、シグネチャ、注意点、セマンティック検索用の要約を追加します。
• ローカルモデルへの委任 -- エージェントは、定期的または一度だけ、定型的なテキスト作業（分類、抽出、要約、メールボックスの監視）を、Ollama 経由で自分のハードウェア上で実行するモデルに委任できます。結果はエージェントに返されます。クラウドエージェントの利用を、クラウドエージェントを必要としない作業に使わずに済みます。ローカルモデルへの委任を参照してください。
• 管理用 Web UI -- サーバー上の /admin から、設定、エージェントとそのコンテキスト使用状況、アラート、ローカルタスクと実行履歴、接続、変更ログを確認できます。管理用 Web UIを参照してください。

---

他のサーバーとの比較

PulseMCP には 370 以上の MCP メモリーサーバーが掲載されています。その多くは、単一のエージェントに永続的なメモリーを提供します。このサーバーは、同じプロジェクトで数週間から数か月にわたって協力するエージェントチーム向けに構築されています。

機能	一般的な MCP メモリーサーバー	このサーバー
永続ストレージ	あり	あり — MongoDB + ChromaDB ベクトル検索
マルチエージェントのセッション追跡	なし	あり — エージェントレジストリ、ハートビート、競合の検出
エージェント間のメッセージ送信	なし	あり — スレッド化とステータス追跡に対応したメッセージの送受信
関数レジストリ	なし	あり — 一度登録すれば、ライブラリアンデーモンがコード分析で自動拡充
タスクバックログ	なし	あり — タスクの作成、エージェントへの割り当て、ステータスと優先度の追跡
バージョン管理された仕様と契約	なし	あり — オーナーの強制、セマンティックバージョニング履歴
ファイルロック	なし	あり — 古いロックの検出、自動解放に対応したアトミックロック
セッション終了時の自動解放
行動ガイドライン	なし	あり — 一度ルールを設定すれば、どのマシンのどのエージェントにも適用
古さの管理	なし	あり — 経過期間の警告、置き換え、アーカイブ、タグによる一括クリーンアップ
ライブラリアンモード	なし	あり — エージェントがソースコードを分析し、ナレッジベースを拡充
外部データベースへのアクセス	なし	あり — プロジェクトデータベース（MSSQL、MySQL）への読み取り専用 SQL クエリ
チェックリスト	なし	あり — リリース準備、デプロイ手順などを共有
ローカルモデルへの委任	なし	あり — エージェントが所有するタスクをローカルの Ollama ランナーで実行し、結果をエージェントまたは日次ダイジェストに返却
データソース用のシークレット	なし	あり — 暗号化された保管庫。エージェントが接続を要求し、オペレーターが有効化します。エージェントにシークレットが表示されることはありません
オペレーター用 Web UI	なし	あり — /admin：設定、エージェント、アラート、タスク、接続、変更ログ

23 カテゴリにわたる 63 個のツールを備えています。おもちゃではなく、連携システムです。

---

単一のエージェントにも対応

このサーバーのメリットを得るのに、複数のエージェントは必要ありません。単一の Claude Code または Cursor インスタンスでも、次の機能を利用できます。

• セッションをまたぐ永続的なメモリー — エージェントは昨日学んだことを覚えています
• 関数レジストリ — すでに分析したコードをエージェントが再度読み込む必要はありません
• 学び — 注意点、回避策、わかりにくい動作も、セッションを再起動しても保持されます
• ライブラリアンによる拡充 — コードベースにインデックスが作成され、時間とともに検索可能になります
• バックログ — セッション間で完了した作業と次の作業を追跡できます
• 状態仕様 — 中断したところから正確に再開できます

メッセージ送信、ファイルロック、マルチエージェント認識といった連携機能は、使わずにそのままにしておけます。何も支障はありません。規模を拡大するまでは、エージェントが呼び出さないツールです。

まずはエージェントを 1 つ使いましょう。準備ができたらマルチエージェント機能を使えます。必要になるまでは作業の邪魔になりません。

---

アーキテクチャ

graph LR
    A1[Claude Code] -->|MCP/HTTP| S[MCP Shared Memory Server]
    A2[Cursor] -->|MCP/HTTP| S
    A3[Other MCP Client] -->|MCP/HTTP| S
    S -->|Vector search| C[(ChromaDB)]
    S -->|Documents & state| M[(MongoDB)]
    S -.->|Optional| E[(External DBs)]

サーバーは単一の Docker Compose スタックとして実行されます。AI エージェントは MCP（ポート 8080 のストリーミング可能な HTTP トランスポート）経由で接続します。すべてのナレッジ、メッセージ、連携状態は MongoDB と ChromaDB のボリュームに保存され、再起動後も保持されます。

---

インストール — AI エージェントに任せる

このサーバーは AI コーディングエージェント向けに設計されているため、インストール手順も同様です。リポジトリをクローンし、エージェントにインストールを依頼してください。

git clone https://github.com/tlemmons/junto-memory.git
cd junto-memory
# Now hand the prompt below to your AI agent in a fresh session.

クローンしたディレクトリで、新しい Claude Code（または Cursor、あるいは MCP 対応エージェント）のセッションを開き、次のプロンプトをコピーしてください。

このリポジトリに MCP Shared Memory Server をインストールしてください。AGENT_INSTALL.md を読み、手順に沿って進めてください。ルートレベルの docker-compose.yml を使用してください。破壊的な操作を行う前、実際の値（パスワード、API キー、ポートの選択）が必要な変更を行う前、および認証を有効にする前に、作業を止めて私に確認してください。インストールが完了したら、ドキュメントに記載されたスモークテストを実行し、「完了条件」の6項目すべての結果を報告してください。

エージェントは、前提条件、環境ファイルの設定、コンテナーの起動、ヘルスチェック、MCP クライアントの設定を順に進め、適切なタイミングで判断が必要な項目（パスワード、ポート、認証の有効／無効）について質問します。

この方法を選ぶ理由は？ インストールには、運用上の注意点がかなり蓄積されています。Chroma のボリュームのマウントパス、Mongo の初期化時の認証情報、フォールバックが緩やかな認証用環境変数、localhost とリモートホストで異なる信頼モデルなどがあり、6行のクイックスタートではかえって誤解を招きます。AGENT_INSTALL.md は詳細で分岐が多く、現在の実際のコードに照らしてテスト済みです。エージェントなら数分で読み、実行できます。インストールを AI エージェントに任せることに不安がある場合、このサーバーはおそらく適していません。このサーバーは、実際のコードベースで作業する複数の AI エージェントを連携させることを目的としているためです。

手動でインストールしますか？ AGENT_INSTALL.md は人間にも読める内容で、注意深く手順に従えばインストールできます。ただし、エージェントが実行することを前提に書かれているため、詳細で分岐が多く、人間向けチュートリアルにあるような丁寧な案内は多くありません。上記のエージェント主導の方法が、サポート対象の手順です。

インストール後、MongoDB は localhost:27019、ChromaDB は localhost:8001、MCP サーバーは localhost:8080 で待ち受けます。

最初のセッション

接続すると、エージェントは最初に次のようにやり取りします。

Agent: memory_start_session(project="my-app", claude_instance="main")
→ Returns: session ID, any prior learnings, active work, handoff notes

Agent: memory_record_learning(
    session_id="...",
    topic="postgres connection pooling",
    content="PgBouncer silently drops connections after 5 min idle.
             Must set keepalive_idle=60 in connection string or
             requests fail with 'server closed the connection unexpectedly'."
)
→ Stored. Next session, memory_start_session returns this automatically.

Agent: memory_register_function(
    session_id="...",
    name="retry_with_backoff",
    file_path="src/utils/resilience.py:42",
    purpose="Retry async calls with exponential backoff and jitter",
    gotchas="Max 5 retries. Raises RetryExhausted, not the original exception."
)
→ Registered. Any future agent asking "how do we handle retries?"
  finds this via memory_find_function.

3回の呼び出しで、エージェントは永続的なメモリを利用できるようになります。以降のセッションは、何もない状態ではなく、コンテキストがある状態から始まります。

---

AI の接続

Claude Code

~/.claude.json（またはプロジェクトの .mcp.json）に追加します。

{
  "mcpServers": {
    "shared-memory": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

トランスポート名に関する注意： 基盤となる MCP プロトコルは「streamable HTTP」ですが、Claude Code 2.x では JSON 設定ファイル内の値は "http" です。設定に "streamable-http" を指定すると、スキーマ検証エラーが発生します。

Cursor

プロジェクトのルートにある .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "shared-memory": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

MCP 対応クライアント全般

クライアントの接続先として、次の MCP エンドポイントを指定します。

URL:       http://localhost:8080/mcp
Transport: Streamable HTTP (stateless)

stdio トランスポートも、こちらを優先するクライアント向けにサポートされています。サーバーの起動時に --transport stdio を指定します。

# From the project root:
python server.py --transport stdio

# Or as a module (from the src/ directory):
python -m shared_memory --transport stdio

stdio モード用の MCP クライアント設定例：

{
  "mcpServers": {
    "shared-memory": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "shared_memory", "--transport", "stdio"],
      "cwd": "/path/to/mcp-shared-memory/src"
    }
  }
}

ローカルでの利用に API キーや認証トークンは必要ありません（リモート環境へのデプロイについてはセキュリティを参照してください）。

---

ツールリファレンス

23カテゴリに整理された63個のツールがあります。（分類とエンドツーエンドのフローを含む、正式かつ最新の一覧については、サーバー内のアーキテクチャ仕様を参照してください：memory_get_spec(name="architecture:shared-memory-v1", project="junto")。）

セッション管理（2）

ツール	説明
memory_start_session	セッションを登録し、コンテキスト（最近の学び、アクティブなエージェント、ファイルロック、未処理のシグナル）を受け取ります。最初に呼び出してください。
memory_end_session	要約、変更したファイル、引き継ぎメモを記録します。すべてのロックを解除します。作業が終わったときに呼び出してください。

ナレッジベース（4）

ツール	説明
memory_query	自然言語でナレッジベースを検索します。関連度スコア付きで関連ドキュメントを返します。
memory_get_by_id	正確な ID を指定して、特定のドキュメントを取得します。
memory_store	新しいドキュメント（アーキテクチャ、API 仕様、コードスニペット、インターフェース契約など）を保存します。
memory_record_learning	学び、注意点、またはテクニックを他のエージェント向けに記録する簡単なショートカットです。

検索と発見（2）

ツール	説明
memory_search_global	すべてのプロジェクトと共有コレクションを一度に検索します。
memory_list_projects	ドキュメント数とともにすべてのプロジェクトを一覧表示します。セッションは不要です。

ファイルロック（3）

ツール	説明
memory_lock_files	排他的編集のためにファイルをアトミックにロックします。ディレクトリのロックにも対応しています。セッション終了時に自動的にロックを解除します。
memory_unlock_files	特定のファイルロック、またはセッションが保持するすべてのロックを解除します。
memory_get_locks	古いロック（30 分以上非アクティブ）の検出機能付きで、現在のファイルロックを表示します。

バックログ管理（4）

ツール	説明
memory_add_backlog_item	タスク、機能リクエスト、または技術的負債項目をバックログに追加します。
memory_list_backlog	プロジェクト、ステータス、優先度、担当者、マイルストーンで絞り込んでバックログ項目を一覧表示します。
memory_update_backlog_item	バックログ項目のステータス、優先度、担当者、または説明を更新します。
memory_complete_backlog_item	任意の解決メモを添えて、バックログ項目を完了または対応不要としてマークします。

エージェント間メッセージング（7）

ツール	説明
memory_send_message	別のエージェントにメッセージを送信します。カテゴリ（タスク、質問、ブロッカーなど）とスレッドに対応しています。
memory_get_messages	エージェント宛ての未処理メッセージを取得します。プロジェクト単位で絞り込まれます。
memory_acknowledge_message	メッセージを受信済みとしてマークします（ステータス更新のショートカット）。
memory_update_message_status	メッセージのライフサイクル（保留中、配信済み、受信済み、完了、失敗）を追跡します。
memory_heartbeat	現在のステータス（アイドル、作業中、エラー）を含むハートビートを送信します。古い状態の検出が可能になります。
memory_get_agent_status	エージェントのハートビートステータスを取得します。5 分経過したエージェントに古い状態のフラグを付けます。
memory_list_agents	プロジェクト全体から、登録済みエージェントの役割と最終アクティビティを確認します。

関数レジストリ（5）

ツール	説明
memory_register_function	名前、ファイル、目的、任意の注意点を指定して関数リファレンスを登録します。ライブラリアンによる詳細情報の追加がトリガーされます。
memory_find_function	目的または名前で関数を検索します。重複を避けるため、実装前に確認してください。
memory_enrich_function	関数リファレンスにシグネチャ、パラメーター、副作用、複雑さの詳細な分析を追加します。ライブラリアン向けです。
memory_get_enrichment_queue	ライブラリアンによる詳細情報の追加を待っている関数を表示します。
memory_become_librarian	プロンプトと、ローカル環境で詳細情報を追加する関数を取得します。

仕様管理（3）

ツール	説明
memory_define_spec	オーナーのみが実行できるよう制限し、バージョン管理された仕様を作成または更新します。セマンティックバージョニングと履歴に対応しています。
memory_get_spec	名前で仕様を取得します。特定の過去バージョンを指定することもできます。
memory_list_specs	バージョン履歴とタイプで任意に絞り込み、すべての仕様を一覧表示します。

プロジェクトレジストリ（CRUD ツール 1 個）

ツール	説明
memory_project	プロジェクトとエージェントを管理します。アクション：create、get、list、delete、add_agent、remove_agent、update_agent。

チェックリスト（CRUD ツール 1 個）

ツール	説明
memory_checklist	リリース準備状況、デプロイ手順などの共有チェックリストです。アクション：create、get、add、check、delete、list。

外部データベースへのクエリ（CRUD ツール 1 個）

ツール	説明
memory_db	登録済みの外部データベースに対する読み取り専用クエリです。アクション：list、schema、query。SQL インジェクション対策が組み込まれています。

サーバー管理のガイドライン（1 個）

ツール	説明
memory_guidelines	すべてのエージェントがセッション開始時に受け取る行動ルールを管理します。アクション：list、set、delete、get。一度更新すれば、すべてのマシン上のすべてのエージェントに反映されます。

管理（CRUD ツール 1 個）

ツール	説明
memory_admin	API キーを管理し、監査ログを確認します。アクション：create_key、revoke_key、list_keys、audit_log、auth_status。認証が有効な場合は、オーナーのロールが必要です。

ドキュメントのライフサイクル（4 個）

ツール	説明
memory_update_work	現在の作業状況と変更したファイルを更新します。作業の重複検出と依存関係の通知が可能になります。
memory_change_status	ドキュメントのステータス（active、deprecated、superseded、archived）を変更します。履歴は保持されます。
memory_archive_by_tag	タグに一致するすべてのドキュメントを一括でアーカイブします（例：バージョン終了時のクリーンアップ）。
memory_restore_by_tag	タグを指定して、以前にアーカイブしたドキュメントを一括で復元します。

調整とアクティビティ（2 個）

ツール	説明
memory_get_active_work	他のエージェントが現在取り組んでいるタスク、変更したファイル、タイムスタンプを確認できます。作業の重複を避けるのに役立ちます。
memory_claim_message	グループ内でメッセージを要求し、必ず 1 つのエージェントが処理するようにします（複数コンシューマー間の調整）。

リマインダーとスケジュール設定（3 個）

ツール	説明
memory_set_reminder	指定した時刻に、自分（または同僚）宛てのメッセージを予約します。期限、フォローアップ、「X の後に通知して」などに使えます。
memory_cancel_reminder	以前に予約したリマインダーをキャンセルします。
memory_list_reminders	保留中の予約済みリマインダーを一覧表示します。

スキル（6 個）

再利用可能な、タスクから呼び出す手順です。draft として作成され、信頼ゲートを通じて active に昇格されます。その後、ランチャーが .claude/skills/ に展開し、クライアントのネイティブマッチャーがタスクの途中で起動できるようにします。

ツール	説明
memory_register_skill	再利用可能なスキル（トリガー、手順、注意点、前提条件）を作成します。常に draft として作成されます。
memory_confirm_skill	下書きのスキルを active に昇格させます（信頼ゲート）。オーナーまたは人間のみが実行できます。
memory_get_skill	ID または名前を指定して、スキルの全内容を取得します。
memory_list_skills	プロジェクト、ロール、ディレクトリ、ステータスで絞り込んだスキル（ヘッダー）を一覧表示します。ピン留め済み、次に有効なスキルの順です。
memory_pin_skill	スキルをピン留め、またはピン留め解除し、表示時に最初にランク付けされるようにします。
memory_export_skills	スコープに一致する有効なスキルを、ランチャーが展開できる、そのまま書き込める SKILL.md ペイロードとしてエクスポートします。

行動指示（1 個）

ツール	説明
memory_ack_directive	サーバーから発行された指示（例：保留や行動に関する指示）を確認し、解除します。

プッシュ制御、アラート、テレメトリ（2 個）

メッセージのレート制限／プッシュ制御サブシステム（チェーン深度の上限、エージェントごとの時間単位の予算、通知なしの抑制）をオペレーターが確認できます。

ツール	説明
memory_list_alerts	プッシュ制御のアラート（予算の警告、予算超過、ハード上限への到達）を一覧表示します。オペレーターダッシュボードやポーリングによるフォールバックに利用できます。
memory_get_emission_stats	エージェントごとのメッセージ送信カウンターと予算使用状況を表示します。

チームのステータスと健全性（3）

ツール	説明
memory_report_context	任意のマシンからエージェントのコンテキストウィンドウの使用状況を報告します（各マシン上の contrib/context-report レポーターが使用します）。memory_get_agent_status を使うと、各エージェントのコンテキストゲージが表示され、アイドル状態から待機状態への移行を促す通知でも使われます（コンテキストゲージとアイドル時の待機通知を参照）。
memory_standup	プロジェクトのチーム状況を自動でまとめます。各エージェントの現在のタスク、ブロッカー、古くなった状態仕様、集約された意思決定キューを確認できます。読み取り専用で、エージェントが作成する必要はありません。
memory_health	サーバーの健全性を確認します。MongoDB と ChromaDB のステータス、アクティブなセッション／ロック／シグナルの件数を表示します。セッションは不要です。

レプリケーション／同期（2、サーバー間）

フェーズ 2 のローカルファーストなレプリケーション用エンドポイント（admin／owner 権限）。LAN 内の junto-memory が、操作ログのエントリを送信して中央のインスタンスと同期します。ピア間でテキストを再埋め込みすることはありません。

ツール	説明
memory_sync_pull	呼び出し元のオリジンごとのカーソルより新しい操作ログのエントリを取得します。
memory_sync_push	ピアから受け取った操作ログのエントリのバッチを適用します（シーケンス番号の単調増加、インテントの重複排除）。

バックログ — 一括操作（1）

ツール	説明
memory_batch_backlog	1 回の呼び出しで複数のバックログ項目を作成または更新します。

ローカルモデルへの委任（4）

作業を自分のハードウェア上のモデルに任せます。仕組みについては、ローカルモデルへの委任を参照してください。

ツール	説明
memory_delegate	ローカルモデル用のタスクを作成します。データソース（スコープ）、指示、JSON 出力スキーマ、ルート、任意のスケジュールとカナリアを指定します。スケジュールを指定しない場合は、今すぐ 1 回実行します。同じ呼び出しで新しい接続をリクエストできます。
memory_schedule	タスクを管理します。list、get、edit（バージョン管理）、pause、resume、delete、run_now、history、runs、approve（オペレーター）を使用できます。
memory_job	1 回の実行を操作します。status、result（各項目の出力と使用されたルート）、cancelを使用できます。所有者のみが利用できます。
memory_runners	ランナーと接続を管理します。list（ホスト、モデル、最終ハートビート）、scopes（使用可能な接続）、request_connectionを使用できます。define_scopeとcreate_runner_keyはオペレーター専用です。

---

ローカルモデルへの委任

エージェントの作業には、最先端のモデルを必要としないものが多くあります。サポート受信トレイの仕分け、ログからのフィールド抽出、大量のダンプの要約、リストの変更監視などです。委任を使うと、エージェントはそうした作業を自分のハードウェア上で動作するモデルに任せられるため（Ollama経由）、クラウドエージェントの利用を必要な作業に集中できます。仕様は memory_get_spec(name="interface:delegated-inference-v0", project="junto") で確認できます。

仕組み

graph LR
    A[Agent] -->|memory_delegate| S[junto-memory]
    S -->|claim run + sealed secret| R[Runner on your GPU box]
    R -->|fetch items| D[(Connection: imap / mcp / file / inline)]
    R -->|one JSON result per item| O[Ollama]
    R -->|results| S
    S -->|routes: notify / digest / drop| A2[Agents]

1. 接続（スコープ）。 型付きデータソースです。inline（タスクで渡すテキスト）、imap（読み取り専用メールボックス）、mcp（別の MCP サーバー上の読み取り専用ツール）、file（ランナーホスト上で許可されたルート）、gmail（読み取り専用 API。独自の Google OAuth クライアントが必要）のいずれかを指定します。それぞれ、利用を許可されたエージェントと、使用を許可されたランナーホストが設定されています。memory_runners(action="scopes") で自分のスコープを確認できます。
2. タスク。 タスクの所有者はエージェントです。instructions、1 項目の結果に対する JSON Schema である output_schema、source_params、routes、任意の schedule（{"every": "15m"} または {"cron": "0 7 * * *"}、最短 5 分）、任意の canaries を設定します。すべてのフィールドは後から編集でき、編集内容はバージョン管理されます。スケジュールを指定しない場合は、今すぐ 1 回実行します。
3. 実行。 サーバーが実行をキューに登録します。GPU マシン上のランナーが実行を取得し、項目を取得して、それぞれをタスクの指示とともにモデルに送信し、スキーマに照らして応答を検証してから結果を返します。1 つのランナーが同時に処理できる実行は 1 件です。
4. ルート。 各結果の処理方法を決定するのはモデルではなくサーバーです。テンプレートを使ってエージェントにnotifyするか、所有者の日次ダイジェストに追加するか、dropします。最初に一致したルールが適用され、一致するルールがなければダイジェストに追加されます。ローカルモデルはアクションを実行できません。モデルが提案した内容は、すべてデータとしてエージェントに届きます。

memory_delegate(
    session_id=sid, name="ticket-sort", scope="myproject:inline",
    instructions="Classify this support message.",
    output_schema={"type": "object", "properties": {
        "classification": {"type": "string", "enum": ["bug", "billing", "how_to", "spam"]},
        "summary": {"type": "string"}}, "required": ["classification", "summary"]},
    source_params={"items": ["text of message 1", "text of message 2"]},
    routes=[{"if": {"field": "classification", "op": "in", "value": ["bug"]},
             "then": "notify", "to": "myproject/backend", "category": "task",
             "template": "{classification}: {summary}"},
            {"if": {"field": "classification", "op": "eq", "value": "spam"}, "then": "drop"}],
    run_now=True)
# → a "Delegated job done" notice; then memory_job(run_id, action="result")

安全モデル

• アイテムの内容は信頼できないデータです。 タスクを再掲した後に、フェンスで囲まれた状態でモデルに渡されます。デフォルトのモデルである gpt-oss:20b はテストであらゆるプロンプトインジェクションのケースに耐えました。qwen3:14b はより高速ですが、もっともらしいメールに埋め込まれた指示に従ったため、信頼できるテキストにのみ使用してください。
• カナリアは、期待される出力が決まっている既知のアイテムです。毎日（または実行のたびに）と、指示、スキーマ、モデル、ソースを編集した後に実行されます。カナリアに失敗すると、オーナーに通知が届きます。
• 読み取り専用のソース。 IMAP は EXAMINE と BODY.PEEK で開きます。MCP ツールは、タスクが要求するものと接続の tools_allowed の両方で許可されているものに限られます。
• 失敗したアイテムは必ず通知されます。 有効な出力がないアイテムにはルートが設定されません。スケジュールされたタスクの場合、ソースカーソルがそのアイテムを通過しているため、オーナーには各アイテム（参照、送信者／件名、エラー）を記載した対応通知が届きます。
• 可視性。 実行結果を確認できるのはタスクのオーナーのみです。"x-sensitive": true と指定されたスキーマフィールドは、接続の content_visible_to に含まれないエージェントへの通知から取り除かれます。

接続とシークレットボールト

エージェントが認証情報を扱うことはありません。エージェントは接続をリクエストします（memory_runners(action="request_connection")、または memory_delegate の connection=）。オペレーターがシークレットを貼り付けて /admin → Connections で接続を有効化します。この操作が承認となります。接続を待っていたタスクは、その後開始されます。

• シークレットは JUNTO_VAULT_KEY を使用して暗号化（Fernet）して保存されます。各クレーム時に、新しいコピーがそのランナーの X25519 キーで暗号化されます。ランナーはその実行中だけメモリ上で復号し、ログへの記録やキャッシュは行いません。
• 接続を取り消すと、暗号文が削除され、キューに入った実行がキャンセルされます。すでにクレーム済みの実行は、10 分のリース期間内に完了します。
• すべてのリクエスト、有効化、ローテーション、取り消しは、接続の監査ログに記録されます（/admin → Connections）。
• JUNTO_VAULT_KEY は .env に保存され、Mongo のバックアップには含まれません。バックアップに含まれるのは暗号文のみです。キーを失うと、シークレットを再入力する必要があります。

ランナーの実行

ランナー（contrib/runner/junto-runner.py）は、cryptography（および MCP ソースの場合は mcp）が必要な単一の Python ファイルです。通信先は junto サーバー、ローカルの Ollama、および接続先独自のソースのみです。

まず、オーナー／管理者のエージェントセッションから、ランナーのキーを作成します（キーは一度だけ表示されます）。 memory_runners(session_id=sid, action="create_runner_key", runner_id="gpu-1", host="gpubox").

# On the GPU box
cp contrib/runner/junto-runner.py ~/.local/bin/ && chmod 755 ~/.local/bin/junto-runner.py
mkdir -p ~/.config/junto-runner && chmod 700 ~/.config/junto-runner
# save that key to ~/.config/junto-runner/runner.key (mode 600)
# config.json (mode 600): {"server": "http://<server>:8080", "runner_id": "gpu-1",
#   "key_file": "~/.config/junto-runner/runner.key", "ollama": "http://localhost:11434"}
cp contrib/runner/junto-runner.service ~/.config/systemd/user/
systemctl --user daemon-reload && systemctl --user enable --now junto-runner
loginctl enable-linger $USER

ランナーは初回起動時に X25519 キーペアを作成し、インストール済みモデルを登録します。ランナー API（/runner/api/*）は LAN 内からのみアクセスできます。

制限事項と注意点

制限	値
エージェントあたりのタスク数	25 件まで稼働可能です（単発タスクは memory_schedule(action="delete") で削除します）
1 回の実行あたりの項目数	200
指示	20,000 文字
インライン項目	20,000 文字（imap の max_chars のデフォルトは 12,000 です）
モデルコンテキスト	ランナーは実行ごとに num_ctx を選択します。実行内で最も長い項目が収まる 8,192 / 16,384 トークン（設定 num_ctx_buckets）のうち小さい方を選びます。ただし、モデルが学習済みのコンテキスト、モデルごとの num_ctx_max、および 30 GB を超えるモデルでは 4,096 が上限です（24 GB のカード 1 枚には収まりません）。num_ctx を変更するとモデルが再読み込みされるため、1 回の実行中は値が固定されます。それでも収まらない項目は、ランナーによって切り詰められ、明示的なマーカーが付きます。実行の証跡には num_ctx と items_truncated が表示されます。返信用の予算を確保すると、16K では項目を約 20,000 文字まで扱えます。
返信の長さ	モデル呼び出しごとの num_predict は min(8,192, context/2) トークンです。推論も含みます（gpt-oss は think: false でも推論を行うため、2,048 では不十分でした）。上限で切られた返信は reply cut at num_predict=… として失敗します。gpt-oss では、上限で切られた返信を think: "low" で 1 回再試行します（実行の証跡では low_effort_retries としてカウントされます）。デフォルトの推論レベルを最初に使うのは、プロンプトインジェクションへの耐性がより高かったためです（デフォルトでは 0/16、low では 1/16）。
キュー	1 つのランナーが一度に処理する実行は 1 件です。スケジュール済みタスクの実行は単発バッチより先に割り当てられ、各グループ内では古いものから処理されます。
スケジュール	5 分以上の間隔です。digest_at が設定されていない場合、日次ダイジェストはタスクのタイムゾーンで 07:00 に実行されます

VRAM に収まらない大きさのモデル（例：2×24 GB 上の 72B モデル）は、一部が CPU 上で実行され、読み込み済みの他のモデルがすべて退避されます。大きなモデルはバッチに含めないでください。

---

管理 Web UI

サーバーはオペレーター用ページを http://<server>:8080/admin で提供します。LAN 内のみで利用できます。トンネル経由で届いたリクエストには 403 が返されます。LAN 上の誰でも閲覧できますが、変更にはすべてオーナー API キーが必要です（ページに貼り付けると、Bearer ヘッダーで送信されます）。

タブ	表示内容／機能
Overview	主な件数を表示します。/dashboard（アクティビティフィード）と /health へのリンクもあります
Settings	調整可能な設定をすべて表示します。コードのデフォルト値とサーバーの値を比較でき、サーバー全体またはプロジェクトごとに編集できます
Agents	登録済みエージェント、最終アクティビティ、コンテキスト使用率ゲージを表示します
Alerts	プッシュ制御のアラート（予算の警告と超過）を表示します。アラートを確認済みにできます
Local tasks	委任されたタスク（一時停止／再開／今すぐ実行／承認）、証跡付きの最近の実行、カナリア、ルートとエラー、ランナーのハートビートを表示します
Connections	要求済みおよび有効な接続を表示します。シークレットを貼り付けて有効化またはローテーションし、取り消すことができます。接続の監査記録も確認できます
Change log	設定変更をすべて表示します。変更者、日時、変更前と変更後の値が含まれます

ホスト名の背後に配置するには、nginx などを使って /admin をプロキシし、その仮想ホストも LAN 内のみにしてください。

---

コンテキストゲージとアイドル時のパーク通知

コンテキストゲージ。 contrib/context-report/junto-context-report.py は、各マシン上で実行されます（systemd ユーザータイマー）。ローカルの claude プロセスを検出し、ステータス行が書き込んだ各エージェントのコンテキスト使用率メトリクスを読み取り、memory_report_context を呼び出します。その後、memory_get_agent_status と /admin → Agents で、すべてのマシンにおける各エージェントのコンテキスト使用率を確認できます。

アイドル時のパーク通知。 エージェントが idle_park_minutes（デフォルトは 50 分。約 60 分のプロンプトキャッシュ TTL より少し短い時間）にわたって実質的なツール呼び出しを行わないと、サーバーは安全な区切りでパークするよう提案する通知を 1 件送信します。通知の対象は、報告済みコンテキストが少なくとも idle_park_min_context（デフォルトは 200K）あるエージェントのみです。idle_park_autoreset に記載されたエージェントでは、さらに次の処理が行われます。通知を受けてパークした後、レポーターがエージェントの tmux ペインに安全に入力できることを確認し、/clear と go を入力します。memory_admin push_control_set_config または /admin → Settings で設定してください。

---

Configuration

設定はすべて環境変数で行います。完全なリファレンスについては .env.example を参照してください。

必須変数

変数	デフォルト	説明
MONGO_PASSWORD	changeme	MongoDB のルートパスワードです。変更してください。
MONGO_USER	mcp_orch	MongoDB のユーザー名です。
MONGO_DB	mcp_orchestrator	MongoDB のデータベース名です。
MONGO_HOST	localhost	MongoDB のホストです（Docker Compose で自動的に設定されます）。
MONGO_PORT	27019	MongoDB の外部ポートです。（.env.example には現在 27018 と記載されていますが、古い値です。docker-compose.yml では 27019 が使用されています。）
CHROMA_HOST	localhost	ChromaDB のホストです（Docker Compose で自動的に設定されます）。
CHROMA_PORT	8001	ChromaDB の外部ポートです。

任意の変数

変数	デフォルト	説明
MCP_AUTH_ENABLED	false	API キー認証を有効にします。有効にすると、memory_start_session では有効なキーが必要になります。キーは api_key ツール引数、または Authorization: Bearer <key> HTTP ヘッダーで渡します（セキュリティを参照）。
JUNTO_VAULT_KEY	--	接続シークレット保管庫（ローカルモデルへの委譲）用の Fernet キーです。接続シークレットを保存する場合にのみ必要です。python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" で生成してください。バックアップや git には含めないでください。
ANTHROPIC_API_KEY	--	スタンドアロンの librarian エンリッチメントサービスにのみ必要です。
LIBRARIAN_PROJECT_ROOTS	--	librarian のコード分析用に、プロジェクト名とファイルシステムパスを対応付ける JSON マップです。
DB_<NAME>_TYPE	--	外部データベースを登録します。対応している値：mssql、mysql。詳しい形式は .env.example を参照してください。
DB_<NAME>_HOST	--	外部データベースのホスト名です。
DB_<NAME>_PORT	1433	外部データベースのポートです。
DB_<NAME>_NAME	--	外部データベース名です。
DB_<NAME>_USER	--	外部データベースのユーザー名です。
DB_<NAME>_PASS	--	外部データベースのパスワードです。
DB_<NAME>_READONLY	true	読み取り専用クエリを強制します。
DB_<NAME>_TIMEOUT	30	クエリのタイムアウト時間（秒）です。
DB_<NAME>_MAX_ROWS	500	クエリごとに返される最大行数です。

---

プロジェクト構成

mcp-shared-memory/
├── server.py                     # Entry point (imports from package)
├── src/
│   └── shared_memory/
│       ├── __init__.py
│       ├── __main__.py           # CLI argument parsing
│       ├── app.py                # FastMCP server instance
│       ├── config.py             # All configuration and constants
│       ├── clients.py            # MongoDB and ChromaDB client setup
│       ├── state.py              # In-memory state (sessions, locks, signals)
│       ├── helpers.py            # Shared utility functions
│       ├── auth.py               # API key auth, RBAC, tenant isolation
│       ├── audit.py              # Audit logging to MongoDB
│       ├── delegation.py         # Local-model tasks, scopes/connections, scheduling, routes
│       ├── vault.py              # Encrypted connection secrets, sealed per runner
│       ├── runner_api.py         # /runner/api/* (register, heartbeat, claim, complete, fail)
│       ├── admin_ui.py           # /admin web UI + its JSON API
│       ├── idle_park.py          # Idle→park nudge and auto-reset
│       └── tools/
│           ├── __init__.py       # Tool registration
│           ├── sessions.py       # Session start/end
│           ├── query.py          # Knowledge base queries
│           ├── storage.py        # Document storage and learnings
│           ├── search.py         # Cross-project search, list projects
│           ├── locking.py        # File lock management
│           ├── backlog.py        # Backlog/task management
│           ├── messaging.py      # Inter-agent messaging and status
│           ├── functions.py      # Function registry and enrichment
│           ├── specs.py          # Versioned spec management
│           ├── projects.py       # Project and agent registry
│           ├── checklists.py     # Shared checklists
│           ├── database.py       # External database queries
│           ├── lifecycle.py      # Document lifecycle and work status
│           ├── delegation.py     # memory_delegate / schedule / job / runners
│           └── admin.py          # API key management and audit logs
├── librarian.py                  # Standalone enrichment daemon (uses Haiku)
├── contrib/runner/               # Local-model runner + systemd user unit
├── contrib/context-report/       # Per-machine context-fill reporter
├── docker-compose.yml            # Full stack: server + MongoDB + ChromaDB
├── Dockerfile
├── requirements.txt
├── .env.example
└── LICENSE

---

開発

前提条件

• Python 3.11+
• Docker および Docker Compose（MongoDB と ChromaDB 用）

ローカルでの実行

バックエンドサービスを起動します：

docker compose up -d mongodb chromadb

Python の依存関係をインストールします：

pip install -r requirements.txt

サーバーを直接実行します：

python server.py --host 0.0.0.0 --port 8080

または、モジュールとして実行します：

cd src && python -m shared_memory --host 0.0.0.0 --port 8080

Docker Compose での実行（フルスタック）

docker compose up -d

これにより、ヘルスチェックと自動再起動を備えた3つのサービス（MCP サーバー、MongoDB、ChromaDB）が起動します。

ログの表示

# All services
docker compose logs -f

# Just the MCP server
docker compose logs -f mcp-server

---

セキュリティ

このサーバーは、ローカルまたは信頼できるネットワークでの使用を想定して設計されています。認証は任意ですが、利用できます。

組み込みの API キー認証

.env で MCP_AUTH_ENABLED=true を設定すると、すべてのセッションで API キーが必須になります。キーは、ロールベースのアクセス制御に対応した memory_admin ツールで管理します：

ロール	アクセス権
owner	フルアクセス — API キー、ガイドライン、すべてのプロジェクトを管理
admin	すべてのプロジェクトにわたるバックログ、仕様、機能、メッセージングを管理
agent	割り当てられたプロジェクトに限定された標準的なエージェントアクセス
readonly	書き込みは行わず、クエリと検索のみ

各 API キーは特定のプロジェクトに限定でき、テナントを分離できます。エージェントには、許可されたプロジェクトのデータのみが表示されます。セキュリティ上重要な操作はすべて、監査ログに記録されます（保存期間は90日間）。

認証が無効（デフォルト）の場合、すべてのツールが開放されます。ローカルでの単一ユーザー構成に適しています。

キーを渡す方法：ツール引数またはAuthorizationヘッダー

キーは次の2つの方法でサーバーに渡せます（design:header-auth-v0）。

1. api_keyツール引数 — memory_start_sessionにapi_key="smk_..."を渡します。明示的に指定した値が常に優先されます。

2. Authorization: Bearerヘッダー — MCPクライアントの設定にheadersブロックを追加します（標準的なMCPの規約です）。api_key引数が指定されていない場合、サーバーはヘッダーからキーを読み取ります。

   {
     "mcpServers": {
       "junto": {
         "type": "http",
         "url": "https://your-host/mcp",
         "headers": { "Authorization": "Bearer smk_..." }
       }
     }
   }
   

優先順位：明示的なapi_key引数 > ヘッダー > キーなし。キーなしのセッション（どちらも指定されていない場合）は、agentティアにフォールバックします。指定されているものの無効なキー（引数またはヘッダー）は、そのまま拒否されます（気づかれないまま下位ティアに切り替わるのではなく、エラーになります）。ヘッダー方式は、固定ヘッダーをそのまま転送するClaude Codeで検証済みです。

ネットワークセキュリティ

リモートアクセスが必要な場合は、ポート8080を直接公開しないでください。代わりに、次の方法を使用してください。

• Tailscale / WireGuard — サーバーをプライベートなメッシュネットワークに配置します。これが最も簡単で安全な方法です。
• 認証付きリバースプロキシ — サーバーの前段に、HTTPベーシック認証、mTLS、またはOAuth2を設定したnginxやCaddyを使用します。
• SSHトンネル — 臨時のリモートアクセスには、ssh -L 8080:localhost:8080 your-serverを使用します。

.env.exampleのMONGO_PASSWORDのデフォルト値はchangemeです。この値のままでもサーバーは起動しますが、使い捨て以外のデプロイでは必ず変更してください。Docker Composeでは、MongoDBとChromaDBのポートもデフォルトで公開されます。お使いのマシンがネットワークからアクセス可能な場合は、ファイアウォールルールでこれらを制限してください。

---

CLAUDE.mdファイル

これらはClaude Code用の指示ファイルです。Claude Codeを使用していない場合は、無視しても問題ありません。

• GLOBAL_CLAUDE.md.example — すべてのマシンで~/.claude/CLAUDE.mdにコピーします。これは、Claudeにセッションを開始し、サーバー管理のガイドラインに従うよう指示する最小限のブートストラップです。
• CLAUDE.md.template — 各プロジェクトディレクトリにコピーし、プロジェクト名、エージェント名、主要なファイルに合わせてカスタマイズします。
• CLAUDE.md — このプロジェクト独自のClaude Code設定です（サーバー自体の開発用）。

動作ルールはこれらのファイルではなく、サーバー側で管理されます。memory_guidelines(action="set", ...)を使用してルールを追加または更新すると、すべてのマシン上のすべてのエージェントが、次回のセッション開始時に自動的にそのルールを取得します。

---

エージェントの規律の問題

共有メモリーサーバーがあるだけでは不十分です。エージェントが一貫して実際に使用する必要があります。

エージェントは次第に本来の使い方から離れていきます。memory_record_learningの呼び出しを忘れたり、トピックごとに分けたメモリーではなく、すべてを1つの巨大な状態仕様に詰め込んだりします。他のエージェントが見られないローカルファイルに書き込むこともあります。コンテキストの劣化によって自分自身の指示を忘れるまで、長時間のセッションを続けることもあります。

このサーバーには、そうした逸脱を防ぐツールが含まれています。

サーバー管理のガイドライン

すべてのエージェントは、セッション開始時に一連の行動ルール（memory_start_session のレスポンス内）を受け取ります。ルールには次の2つの階層があります。

組み込みのグローバルデフォルト（同梱・共通）。 Junto は、コード内に scope="global" のルールを用意しています — src/shared_memory/global_guidelines.py — これらはサーバー起動のたびに DB に再登録されます。そのため、新しいサーバー（自分のサーバーでも、分離されたピアや作業用サーバーでも）には、手動設定なしで適切なデフォルトが適用され、デフォルトの更新はデプロイとともに反映されます。これらは意図的に普遍的なプロセスに関するものです — メモリを優先した照会、長めのセッションを実行して適切な区切りで終了すること、同意より正確さを重視すること、知識をサーバーに保存すること、学びをすぐに記録すること、セッションの規律、メッセージの意味、要約ではなくポインターを使うこと、コードを書く前に契約を確認すること、鮮度の確認、簡潔な出力、断言する前にソースを読むことなどです。チームやデプロイ固有の内容は含まれません。グローバルスコープはコードで管理され、ツールからは読み取り専用です — デフォルトを変更するには、そのファイルを編集してデプロイしてください（シーダーがその内容を再適用します）。実行中に編集することはできません。

独自のルール（プロジェクトスコープ・実行時）。 チームやプロジェクト固有のルールは、memory_guidelines(action="set", scope="<project>", name=..., rule=...) を使って追加できます — これらは実行時に書き込み可能で、そのプロジェクトのエージェントにのみ提供されます。デプロイ固有の内容はここに記述します。

承認の境界。 組み込みの「尋ねずに実行する」ルールは、意図的に汎用的な内容です — 原則（取り消し可能な作業は実行し、取り消し不可能な作業のみ人間が承認する）を示し、具体的な境界の定義は各環境固有の承認契約に委ねています。契約は仕様として（例：memory_define_spec(name="approval-contract", spec_type="interface", ...)）、またはプロジェクトスコープのガイドラインとして定義できます。エージェントは、ある操作の可逆性が問題になるときにこの契約を参照します。特定の環境におけるステージング／本番／マージのポリシーを、同梱のデフォルトに組み込まないでください。

サーバーのガイドラインは、対象とするプロセスについて権威あるものです — プロジェクトの CLAUDE.md に残っている古いコンテキストやセッション上のヒューリスティックより優先されます。

古い情報の管理

すべての memory_query の結果には、情報の古さに関する警告が含まれます。エージェントは古くなった情報を見つけた時点で置き換えるよう指示されています — 通常の作業の中で分散して整理するため、別途作業する必要はありません。完了した機能をまとめてアーカイブするには memory_archive_by_tag を使用してください。

2つのエージェントが実際のタスクで連携する例については、docs/WORKED_EXAMPLE.md を参照してください。

---

ロードマップ

貢献を歓迎します！プロジェクトに役立つ、既知の不足事項は次のとおりです。

• 認証とテナント分離 — 完了！RBAC とプロジェクトスコープに対応した API キーを実装しました。セキュリティを参照してください。
• PostgreSQL のサポート — memory_db ツールは MSSQL と MySQL に対応しています。PostgreSQL はまだ実装されていません。
• librarian のローカルモデル対応 — Ollama を統合し、エンリッチメントデーモンがクラウド API キーを必要としないようにします
• TTL と古いデータの整理 — 保持期間を設定できる、期限切れのセッション、ロック、メッセージのバックグラウンド削除
• データのエクスポート／バックアップツール — 移行および災害復旧用のダンプと復元スクリプト

マルチエージェント連携の最初から最後までの例については、docs/WORKED_EXAMPLE.md を参照してください。

---

ホステッド版

自分でサーバーを運用したくありませんか？ホステッド版を利用できます — MongoDB と ChromaDB を備えた専用インスタンスが提供されるので、エージェントを URL に接続するだけですぐに使えます。

• サーバーのセットアップは不要 — 数分でエージェントを接続できます
• 自動バックアップ
• 同じ57個のツール、同じ機能
• マルチプロジェクト分離

ご興味がありますか？ Issue を開くか、詳細についてお問い合わせください。

---

ライセンス

全文については LICENSE を参照してください。

Copyright (c) 2024-2026 Thomas Lemmons.

---

貢献

貢献を歓迎します。大きな変更を加える場合は、プルリクエストを送信する前に、イシューを作成して議論してください。このプロジェクトでは標準的な Python ツールを使用しており、requirements.txt に記載された依存関係以外に、特別なビルドシステムやテストフレームワークは必要ありません。

マルチエージェント構成を運用していて、うまく機能する連携パターンがあれば、ぜひお聞かせください。

---

このプロジェクトによって時間を節約できた場合は、開発へのスポンサーをご検討ください。