Visual Memory MCP

@putervision/vision-memory-mcp

@putervision/vision-memory-mcp は、インフラ不要のローカルファーストな Model Context Protocol（MCP）サーバー兼 CLI ツールです。知覚ハッシュ、ローカル CLIP 埋め込み、遷移グラフを用いたビジュアル状態のキャッシュにより、AI コーディングアシスタント（Cursor、Claude Code、Gemini、Copilot など）での視覚 LLM 呼び出しの繰り返しをなくします。

🌐 公式ドキュメントとウェブサイト：visionmemorymcp.com

---

⚡ クイックスタートとインストール

前提条件：Node.js >= 18.18.0

1. インストール

# Global installation via npm
npm install -g @putervision/vision-memory-mcp

2. ワークスペースの初期化

プロジェクトのルートで init を実行し、データベースディレクトリ、.gitignore、.env、IDE ルールを生成します。

vision-memory-mcp init --yes

3. 基本的な MCP クライアントの設定

MCP クライアントの設定に追加します（例：.cursor/mcp.json または .vscode/mcp.json）。

{
  "mcpServers": {
    "vision-memory-mcp": {
      "command": "vision-memory-mcp",
      "args": ["run"]
    }
  }
}

代替オプションと CLI の使用例

# Run stdio MCP server directly via binary (after global install)
vision-memory-mcp run

# Start server skipping heavy CLIP model downloads (air-gapped / offline mode)
vision-memory-mcp run --skip-model-load

# Re-initialize across all registered workspace projects
vision-memory-mcp init-global

# Health check dependencies, sharp bindings, and git safety
vision-memory-mcp doctor

# Run health diagnostics & aggregate metrics across all registered projects
vision-memory-mcp doctor-global

# Inspect stored visual states and metadata in terminal ASCII table
vision-memory-mcp inspect

# Register baseline design mockup contract (Visual SDD)
vision-memory-mcp spec set --name "Dashboard" --file ./dashboard-spec.png

# Save visual memory checkpoint snapshot
vision-memory-mcp snapshot save --name "v1.0-milestone"

# Ingest WebM / MP4 video recording into visual state memory timeline
vision-memory-mcp video ingest ./playwright-test.webm --category playwright_test

# Open interactive force-directed visual graph viewer in browser
vision-memory-mcp view

---

🌟 主な特長

• 👁️ 知覚的なビジュアルキャッシュとコンパクトスライス：5 ミリ秒未満の L1/L2 dHash によるトークン不要の高速レイアウト認識と、Pentad System 1 StatePack の組み立てに使える 1 KB 未満の compact_slice エクスポートを実現します。
• 🎬 WebM および MP4 動画の取り込み：E2E テストの録画や画面キャプチャを、検索可能なキーフレームのビジュアル状態と状態遷移グラフに変換します。
• ⚡ 15 種類の主要 MCP ツール：認識、動画メモリ、エビデンスパック、軌跡比較、セマンティック検索、要素グラウンディング、ビジュアル SDD、スナップショット、統合コンテキストおよびメトリクスを網羅する、高い一貫性を備えた統合ツールセットです。
• 🔗 デュアル MCP の相乗効果と不変のエビデンスパック：@putervision/state-memory-mcp のタスク DAG とビジュアル状態メモリを緊密に連携させ、コンプライアンスと監査証跡のために暗号学的にハッシュ可能なエビデンスパックを生成します。
• 📉 トークンのオーバーヘッドを削減：dHash、ローカル CLIP ベクトル検索、アクセシビリティツリーを使って UI 状態をローカルにキャッシュし、ビジョントークンの節約を最大化します。
• 🚀 5 ミリ秒未満の高速処理レイテンシ：視覚 LLM API の繰り返し呼び出しをなくし、視覚的なハルシネーションのループを防ぎます。
• 🎯 要素グラウンディングとアクション対象の予測：画面上の要素を CSS セレクターと座標に対応付け、決定論的な UI 操作を実現します。
• 🎨 ビジュアル仕様駆動開発（Visual SDD）：デザインモックアップやスクリーンショットを知覚的なベースライン契約として登録し、ビジュアルリグレッションを検証します。
• 🛡️ 100% ローカルファーストのプライバシー：ローカルの LanceDB ベクトルストアとローカル CLIP モデルを使用し、クラウドテレメトリを一切行わず、PII の秘匿化を保証します。

---

🛠️ MCP ツールスイート

@putervision/vision-memory-mcp は、視覚認識と自動化に関する4つの主要ドメインにわたる、本番環境対応の統合 MCP ツール15個を提供します。

• 認識とセマンティック検索：analyze_screenshot（L1/L2 知覚 dHash と AX ツリー解析、単一／バッチ）、recall_memory（テキストおよび画像のセマンティックベクトル検索）、get_session_context（キャッシュヒット率、最近の状態、1 KB 未満の compact_slice エクスポートを集約）。
• 要素のグラウンディングとナビゲーション：predict_next_action（決定論的な CSS セレクターとバウンディング座標）、record_outcome（UI 操作の遷移と視覚的なブロッカー）、get_navigation_paths（BFS 最短経路プランナー）、wait_for_visual_state（対象 UI 状態をポーリング）。
• 動画の軌跡とエビデンスパック：manage_video（WebM/MP4 キーフレームの取り込み、タイムライン検索）、compare_states（視覚レイアウトの差分と動画軌跡の比較）、create_evidence_pack（動画キーフレームを状態メモリ DAG に結び付ける暗号学的監査証明）、export_trajectories（マルチモーダル微調整用データセット）。
• スナップショットと視覚的 SDD：manage_visual_spec（モックアップのベースライン契約とリグレッションチェック）、manage_snapshot（チェックポイント、エクスポート、復元）、undo_visual_mutation（状態の取り込みを元に戻す）、forget_state（プライバシー保護と PII の消去）。

👉 パラメーター仕様、戻り値のスキーマ、ペイロードの例については、正式な API リファレンス および 機能とアーキテクチャガイド をご覧ください。

---

🚀 アーキテクチャの概要

                     Incoming Screen
                            │
                            ▼
              ┌──────────────────────────────┐
              │ L1: In-Memory Cache Lookup   │ ──(Hit)──▶ Return Cached Description & Grounded Elements
              └──────────────┬───────────────┘
                             │ (Miss)
                             ▼
              ┌──────────────────────────────┐
              │ L2: Perceptual Hash Scan     │ ──(Hit)──▶ Return Cached Description & Grounded Elements
              └──────────────┬───────────────┘
                             │ (Miss)
                             ▼
              ┌──────────────────────────────┐
              │ L3: Local CLIP Vector Search │ ──(Hit)──▶ Return Semantically Close
              └──────────────┬───────────────┘
                             │ (Miss)
                             ▼
              ┌──────────────────────────────┐
              │ L4: Vision LLM Fallback      │ ──(Ingest)──▶ Save Redacted State to DB
              └──────────────┬───────────────┘

---

📚 ドキュメント一覧

docs/ ディレクトリにある各種ガイドと詳しい解説をご覧ください。

ガイド	説明
🏗️ アーキテクチャとコードベースの分析	要点を押さえたアーキテクチャの概要、4層パイプライン、モジュール一覧、設計上の判断。
🚀 機能とアーキテクチャ	主な機能、4層の検索パイプライン、要素のグラウンディング、Dual MCP Synergy。
📘 正式な API リファレンス	統合 MCP ツール15個すべての仕様、パラメーター、スキーマ。
🔌 複数 IDE との連携ガイド	Cursor、Claude Desktop、Antigravity、Windsurf、Zed、Roo Code、Agent Rules の設定手順。
💻 CLI コマンドリファレンス	CLI の管理、視覚仕様、スナップショットに関する16個のコマンドすべてを網羅したガイド。
⚙️ 設定ガイド	.env 環境変数、しきい値、L4 ビジョンのフォールバック設定を網羅。
🔒 ストレージの暗号化とセキュリティ	暗号化の詳細、ローカルストレージのプライバシー、PII マスキングの保証。
🤝 コントリビューションガイド	開発環境のセットアップ、コードベースの構成、提出ガイドライン。
🛡️ セキュリティポリシー	セキュリティ脆弱性の報告とプライバシーに関する開示。
📜 変更履歴	リリース機能、修正、パッチ更新の時系列記録。

---

⚠️ このサーバーを使用しないケース

vision-memory-mcp は、視覚的なフロントエンド状態のキャッシュ、UI テスト、マルチモーダルワークフロー向けに設計されていますが、次の用途には適さない場合があります。

• ヘッドレス／純粋なバックエンド開発：UI 描画を伴わない非視覚的な CLI ツール、データベーススクリプト、純粋なバックエンドマイクロサービス。（代わりに state-memory-mcp を単独で使用してください）。
• 高フレームレートのライブ動画ストリーミング：キーフレームやテストアクションの明確な区切りを設けずに、60 fps のライブ動画を継続的に取り込む用途。
• メモリが極端に少ない組み込み環境（RAM 512 MB 未満）：ローカルで CLIP ニューラル埋め込みをフル稼働させるには約300 MB の RAM が必要です（メモリに制約がある場合は、軽量な dHash のみによる認識を行うため --skip-model-load を使用してください）。

---

🧪 テスト

# Run full unit and integration test suite across all 72 test files (312 tests)
npm run test

---

⚖️ ライセンスと免責事項

PuterVision が開発・保守しています。MIT License の下で公開されています。

• ローカルストレージの保証：「現状有姿」で提供され、保証はありません。スクリーンショット、知覚ハッシュ、ベクトル埋め込み、遷移グラフは、アプリケーションレベルで暗号化されずに .vision-memory-mcp/ にローカル保存されます。テレメトリーや分析データが送信されることは一切ありません。
• 商標と非提携：製品名（Cursor、Claude Code、Gemini、Windsurf、VS Code、Sharp、LanceDB、ONNX、HuggingFace）は、それぞれの所有者に帰属し、互換性を識別する目的でのみ使用しています。