Waggle Mcp

人間とAIエージェントのためのプロジェクトメモリー。
会話をまたいで、決定事項、コンテキスト、そしてその理由を保持します。

Waggle をインストール · ブラウザワークスペースを試す · ドキュメント

---

会話だけでなく、コンテキストも保持

Waggle は、AI エージェント向けのオープンソースのローカルファーストなメモリレイヤーです。プロジェクトの知識をグラフとして保存します。何を決めたのか、なぜ重要なのか、何に依存しているのか、何が変わったのかを記録します。次の会話では、最初からやり直すのではなく、そのコンテキストを引き継いで始められます。

Waggle を MCP クライアントで使ったり、Graph Studio でメモリーを確認・編集したり、ポータブルなメモリーグラフをブラウザワークスペースに持ち込んだりできます。

• セッションをまたいで続ける。 プロジェクトの決定事項、要件、好み、未解決の質問を、コンテキストを何度も貼り付けることなく呼び出せます。
• 推論の経緯を理解する。 関係性、根拠となる証拠、矛盾、決定に至るまでの履歴を確認できます。
• 修正を管理する。 WebMCP ワークスペースでは、エージェントが変更を提案し、人間が正確な内容を承認してから正式な情報として反映します。
• メモリーを持ち運ぶ。 対応するワークフロー間で .abhi ファイルをエクスポートおよびインポートでき、グラフを特定のクライアントに縛らずに利用できます。
• ローカルで始める。 デフォルトの SQLite ストアはお使いのマシン上に保存されます。ローカルでの利用に Waggle アカウントや外部データベースは必要ありません。

クイックスタート

Python パッケージには Python 3.11 以降と pipx が必要です。macOS では、brew install pipx で pipx をインストールできます。クライアントごとのオプションについては、インストールガイドをご覧ください。

pipx install waggle-mcp
pipx ensurepath

最初の pipx ensurepath の実行後、ターミナルを再起動してから、次を実行してください。

waggle-mcp setup --yes
waggle-mcp doctor

Waggle を読み込むには、MCP クライアントを再起動してください。セットアップでは対応クライアントを検出して設定を書き込みます。メモリーの自動処理には、クライアントにインストールされたフック、スキル、またはプロジェクトの指示が使用されます。

継続性を確認するには、エージェントにプロジェクトの決定事項を記憶するよう依頼してから、同じプロジェクトで新しいセッションを開き、何が決まったか尋ねてください。セッション間で同じプロジェクト識別子を使い続けてください。

クライアントを選択

クライアント	セットアップガイド
Codex	Waggle プラグインをインストールするか、MCP サーバーを設定する
Claude Code	MCP サーバーとメモリー自動化フック
Claude Desktop	デスクトップ拡張機能と手動設定
VS Code	Waggle 拡張機能とワークスペースのセットアップ
Cursor	ローカル MCP サーバーに接続
Antigravity	クライアントの設定
その他の MCP クライアント	標準的な MCP 設定
Site ツールを使う ChatGPT	ブラウザワークスペースを使う

mcpServers 設定を受け付けるクライアントの場合：

{
  "mcpServers": {
    "waggle": {
      "command": "waggle-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

コマンドが見つからない場合は、pipx ensurepath を実行してターミナルを開き直してください。インストール、起動、クライアント接続の問題については、トラブルシューティングガイドをご覧ください。

メモリの仕組み

Waggle は、長期保存されるプロジェクトの知識と、モデルのコンテキストウィンドウを分離します。 エージェントは必要に応じて関連するメモリを取得し、後の会話に役立つ重要な成果を記録します。

1. 記録： 決定事項、制約、好み、根拠となるコンテキストを記録します。
2. 関連付け： 関連するメモリをリンクし、矛盾や更新を保持します。
3. 想起： 根拠と出所を含む、範囲を絞ったコンテキストを取得します。
4. 継続： 別のセッションまたは対応クライアントで、そのコンテキストを利用します。

コアとなる MCP ワークフローでは、prime_context でプロジェクトのコンテキストを読み込み、 query_graph で関連する履歴を取得し、observe_conversation で長期保存する成果を 記録します。build_context は、特定のタスク向けに簡潔なコンテキストパックを 組み立てます。ツールが利用可能というだけでは、エージェントがメモリを自動的に 使うようにはなりません。これらのツールを呼び出すには、フック、スキル、または指示が必要です。

API と取得設定の詳細については、ツールリファレンスと 設定リファレンスをご覧ください。

Graph Studio

Graph Studio では、プロジェクトのメモリを確認、編集できます。ノードや 関係を参照したり、グラフの内容を追加、削除したり、ソースの根拠を調べたり、 メモリが時間の経過とともにどのように変化したかを確認したりできます。

ブラウザワークスペースでは、プロジェクトのコンテキスト、メモリ、 提案、アクティビティを目的別のビューで確認できます。Graph Studio は、 サーバーに保存されたメモリをグラフレベルで表示します。ブラウザに取り込んだ プライベートデータは、ワークスペースのタブに引き続き表示されます。

Graph Studio を開く

WebMCP — ブラウザ内のメモリ

Waggle ワークスペースでは、人間と 互換性のあるブラウザエージェントが、同じプロジェクトメモリを使って作業できます。その WebMCP アダプターは、 document.modelContext.registerTool を通じて、ページレベルの Site ツールを登録します。 これは、Waggle の MCP サーバーをインストールしたり、リモート MCP コネクターを設定したりする方法とは別のものです。

ワークスペースに接続して使用する

1. Site ツールに対応したモデルとアカウント設定を使い、ChatGPT の組み込みブラウザでワークスペースを開きます。
2. アドレスバーで Site tools → Available site tools を確認し、Waggle の 5 つのツールが利用可能であることを確かめます。メモリを操作している間は、このワークスペースのタブを開いたままにします。
3. サンプルプロジェクトを確認するか、Load private .abhi を選択して独自のグラフを使用します。
4. プロジェクトの概要を依頼するか、特定の決定事項を想起するよう依頼します。ホストされたワークスペースでは、独自のグラフをインポートした後も project_id: waggle-webmcp を使用します。
5. メモリを修正するには、エージェントに置き換え案を提案するよう依頼します。Proposals で内容を確認し、必要に応じて編集してから、正確な値を承認します。
6. 実際の提案 ID のみを使って、承認済みの提案を適用するようエージェントに依頼します。結果を確認するため、もう一度決定事項を想起し、その履歴を調べます。

例：

Call Waggle's get_project_brief with project_id "waggle-webmcp".
Use the returned memories to catch me up on this project.

Site ツールが利用できない場合は、ブラウザの権限と設定を確認してください。 ブラウザが適用の呼び出しをブロックする場合は、承認済みの提案にある Apply approved change を使い、 自分で操作を確定できます。これは同じ承認確認と鮮度確認を行うものであり、ブラウザの保護機能を回避するものではありません。

ブラウザツール

ツール	機能
get_project_brief	プロジェクトの目標、現在の決定事項、制約、状態、未解決の質問を返します。
recall_memory	利用可能な場合は置き換えの出所情報とともに、クエリに対する最新の正式なメモリを検索します。
propose_memory_change	正式なメモリを変更せず、人間による確認用の修正案を作成します。
apply_approved_memory_change	提案 ID のみを使って、承認済みの正確な値を適用します。
load_abhi_for_session	ポータブルなグラフをこのブラウザタブに読み込み、概要を返します。

確認できる修正

flowchart LR
    A[Agent proposes a correction] --> B[Human reviews and approves]
    B --> C[Waggle checks approval and target version]
    C --> D[Approved value becomes authoritative]
    D --> E[Previous memory stays in history]

承認済みの内容は、適用するエージェントによって変更されることはありません。提案の作成後に対象のメモリが変更された場合、提案は新しい情報を上書きするのではなく、古いものとしてマークされます。適用時には以前のメモリが保持され、updates エッジで置き換え先にリンクされます。

これらの承認ルールは、WebMCP の修正ワークフローを対象としています。グラフの直接編集やローカル MCP 操作のすべてに承認が必要だと主張するものではありません。

独自のメモリを使用する

.abhi ファイルは、Waggle のポータブルなメモリグラフです。ブラウザーインポーターは既存のメモリを読み込みます。ソースリポジトリを取り込んで、プロジェクトの概要を生成するものではありません。

1. ワークスペースで Load private .abhi を選択します。
2. 暗号化されていないスキーマ 2.x のファイルを選択します。圧縮時の上限は 700 KiB、展開時の上限は 4 MiB です。
3. Private session graph インジケーターが表示されたことを確認します。以降、概要、想起、提案、承認にはインポートしたコピーが使用されます。

インポートすると、このタブのアクティブなワークスペースが置き換わります。サンプルグラフとのマージ、元のファイルの変更、別の訪問者への影響はありません。

互換性のあるチャットにファイルを添付して、次のように依頼することもできます。

Use Waggle's load_abhi_for_session tool to load this .abhi file into
project "waggle-webmcp" for this session. Then call get_project_brief.

エージェントは添付ファイルを読み取り、そのバイト列を base64 で提供できる必要があります。このツールは、ローカルファイルパスやダウンロード URL を受け付けません。チャットから添付ファイルにアクセスできない場合は、ページのファイル選択機能を使用してください。

アーカイブの構造とサポートされる操作については、ポータブルメモリ形式を参照してください。

データとデプロイの選択肢

Waggle の使用場所	メモリの保存場所
ローカル MCP サーバー	お使いのマシン上の SQLite。デフォルトの保存先は ~/.waggle/waggle.db です。
プライベートブラウザーインポート	このタブの sessionStorage。インポーターがグラフを Waggle のバックエンドにアップロードすることはありません。
ホスト型サンプルワークスペース	分離された一時的なサーバー側のサンプルプロジェクト。アカウントベースのクラウドバックアップではありません。
セルフホスト型リモート MCP サーバー	設定済みの Neo4j バックエンドとインフラストラクチャ。

ブラウザーでの保持期間。 プライベートインポートはページを再読み込みしても保持され、ブラウザーのセッション復元で保持される場合もあります。プライベートコピーを明示的に消去してサンプルプロジェクトに戻すには、ワークスペースの Reset Demo コントロールを使用してください。チャットの会話を閉じただけでは、削除が保証されません。インポーターによってブラウザーのストレージが暗号化されることはありません。

AI サービス。 チャットにファイルを添付すると、そのチャットプロバイダーと共有されます。ツール呼び出しで返されるメモリも、リクエスト元の AI サービスと共有されます。ローカルに保存していても、モデルへの入力がデバイス上に留まるとは限りません。

ホスト型プレビュー。 公開ワークスペースは、ブラウザーでの使用感を試すためのものであり、永続的な本番ストレージではありません。無料ホスティングは、アイドル状態になると一時停止することがあり、再開に時間がかかる場合や、再起動または再デプロイ時にサンプルの状態が失われる場合があります。開いても、ローカルの Waggle データベースには接続されません。付属の SQLite プレビュー構成では、破棄可能な状態を /tmp に保存し、データベースあたりのセッション数を 128 に制限します。上限に達すると、既存のセッションを削除せずに新しいセッションを拒否します。

セルフホスティング。 ブラウザープレビューのガバナンスバックエンドは、現在 SQLite を必要とします。Neo4j を使用したリモート MCP のホスティングは別の構成であり、ブラウザーワークフローにそのまま置き換えられるものではありません。リモートデプロイでは、HTTPS、認証、永続ストレージ、バックアップを設定してください。サーバーを公開する前に、本番環境へのデプロイガイド、セキュリティモデル、セキュリティ強化チェックリストをお読みください。

開発

Waggle は、メモリエンジンと MCP サーバーに Python を、Graph Studio とブラウザーワークスペースに React/Vite を使用しています。

git clone https://github.com/Abhigyan-Shekhar/Waggle-mcp.git
cd Waggle-mcp
python -m venv .venv
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

WAGGLE_MODEL=deterministic pytest -q
ruff check src/ tests/
ruff format --check src/ tests/

PowerShell では、pytest -q を実行する前に $env:WAGGLE_MODEL="deterministic" を設定してください。決定論的な埋め込みを使うと、テストをオフラインで実行できます。意味検索の評価には、通常の埋め込みモデルを使用してください。

フロントエンドを変更する場合：

npm ci --prefix apps/mcp/graph-ui
npm run test:unit --prefix apps/mcp/graph-ui
npm run build --prefix apps/mcp/graph-ui

ドキュメントとコントリビューション

• インストールガイド
• ツールリファレンス
• 設定
• ポータブルメモリ形式
• デプロイとセキュリティ
• コントリビューション
• リポジトリの構成
• 問題を報告

ライセンス

Waggleは、Apache License 2.0に基づくオープンソースです。