State Memory MCP

@putervision/state-memory-mcp

@putervision/state-memory-mcp は、インフラの構築が不要な決定論的 Model Context Protocol（MCP）サーバーです。Cursor、Claude Code、Gemini、Copilot などの AI コーディングアシスタントに、ワークフローの状態（タスク、判断、成果物、計画、ブロッカー、およびそれらの意味的な関係）を追跡するための、構造化された永続的な SQLite グラフを提供します。

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

---

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

前提条件：Node.js >= 18.18.0

# 1. Install globally
npm install -g @putervision/state-memory-mcp

# 2. Navigate to your project directory
cd your-project

# 3. Initialize state-memory-mcp
# Creates .state-memory-mcp/, updates .gitignore, registers project,
# and scaffolds IDE instructions and MCP configs for Cursor, Claude, VS Code, Windsurf, etc.
state-memory-mcp init

# Done! Restart your IDE or Agent Manager to activate.

その他のオプション

# Run directly via binary (after global install)
state-memory-mcp run

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

---

🌟 主な特長

• 🧠 決定論的な状態メモリとコンパクトな TaskSlice：メモリ操作で LLM を介さず、高速で決定論的な SQLite グラフ走査と、System 1 の高速パス評価に向けた 1 KB 未満の TaskSlice 抽出を実現します。
• ⚡ 本番環境向けの統合 MCP ツール 13 種：完全な CRUD、関連付け、DAG の循環チェック、FTS5 検索、TF-IDF RAG、タイムトラベルによる履歴のロールバック、仕様駆動開発、自動修復バリデーションに対応します。
• 📉 効率的なコンテキスト管理と判断しきい値設定：コンテキストをローカルの SQLite データベースに移し、グラフの肥大化を防ぐため、重要度が 0.70 未満の日常的な判断を追記専用イベントログに記録し、重要度の高いターンを保持します。
• 🚀 レイテンシを 67%～74% 削減：複数ステップにわたるファイルスキャンのループをなくし、エージェントがブロックされていないタスクとブロッカーを数ミリ秒で取得できます。
• 🤝 マルチエージェント・ブラックボード：サブエージェントが判断、タスク、ブロッカーの更新を安全に公開できる共有コンテキストストアです。
• 🎨 インタラクティブな 3D ビジュアライザー：ブラウザー上で動作する、ダークモード対応の 3D WebGL 力指向グラフビジュアライザーです（state-memory-mcp view）。
• 🔗 2 つの MCP の連携：@putervision/vision-memory-mcp と組み合わせることで、視覚状態のキャッシュ、知覚ハッシュ、暗号学的なマルチモーダル証拠パックを利用できます。
• 🛡️ 100% ローカルでプライベート：ローカル優先のアーキテクチャにより、すべての状態はワークスペース内の .state-memory-mcp/ に保存されます。

---

🛠️ MCP ツールスイート

@putervision/state-memory-mcp は、5 つの主要なワークフロードメインに整理された、実運用レベルの統合 MCP ツール 13 個を提供します。

• グラフと関係性：manage_nodes（ノードの CRUD、FTS5/TF-IDF ベクトル検索、アトミックな一括変更、観察メモ、しきい値ベースの高速な意思決定ログ）、manage_edges（型付き DAG リンク、マルチモーダルな視覚状態のリンク）。
• タスク実行と作業キュー：manage_tasks（トポロジカルな依存関係キュー、ブロッカーの検出、成果物を伴うタスク完了、自動整理）、manage_sessions（エージェントの帰属情報、ターンの追跡、コンテキストの初期化）。
• 仕様駆動開発（SDD）：manage_specs（PRD/RFC の解析、要件からタスクへの分解、受け入れ基準のリアルタイム検証、コンプライアンススコアリング）。
• 分析、監査、診断：get_analytics（ベロシティ、バーンダウン、トークン ROI、認知負荷、クリティカルパス）、get_events（SHA-256 による改ざん検知可能なイベント台帳）、run_diagnostics（DAG 検証、ヘルスチェック、AST 参照整合性）。
• データ、スナップショット、マルチエージェント：manage_snapshots（チェックポイント、時間を遡った取り消し）、manage_database（バックアップ、チェックサム監査、VCS ブランチのマージ）、manage_data（一括インポート／エクスポート、高速な意思決定イベントを交互に含む ML 軌跡）、query_graph（サブグラフ、依存関係の追跡、生 SQL、1 KB 未満の compact_slice）、use_blackboard（マルチエージェント非同期トピックボード）。

👉 詳細なパラメーター仕様、戻り値のスキーマ、ペイロード例については、ツールリファレンスガイド と 正式な API リファレンス をご覧ください。

---

🚀 アーキテクチャと状態グラフのライフサイクル

                      AI Agent Prompt / Task
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Agent Session Attribution       │ ──▶ manage_sessions(action: "start")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Context & Task Prioritization   │ ──▶ get_analytics(action: "summary")
               │                                 │ ──▶ manage_tasks(action: "next")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Deterministic Graph Mutation   │ ──▶ manage_nodes(action: "create"|"update")
               │  (Tasks, Decisions, Blockers)   │ ──▶ manage_edges(action: "add"|"link_visual")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Spec & Integrity Verification  │ ──▶ manage_specs(action: "compliance"|"verify")
               │                                 │ ──▶ run_diagnostics(action: "validate")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Persistent SQLite Storage      │ ──▶ .state-memory-mcp/graph.db (WAL mode)
               │  Append-Only Event Ledger       │ ──▶ SHA-256 Cryptographic Audit Chain
               └─────────────────────────────────┘

📚 ドキュメント一覧

docs/ ディレクトリで、専用ガイドや詳細な解説をご覧いただけます。

ガイド	説明
🏗️ アーキテクチャとコードベースの要約	重要なアーキテクチャの概要、モジュール一覧、データフロー、設計上の決定事項。
🚀 v0.10 → v1.0 移行ガイド	手順を追った移行ガイド、旧ツールの対応表、STATE_MEMORY_COMPAT モード。
💡 価値提案と理論	認知の外部化、FSM の形式化、ファーストホップの決定性、ベンチマーク指標。
📋 State Memory の概念	ノードの種類（task、decision、blocker など）、ステータス値、型付きエッジ、シード設定のガイドライン。
⚙️ 設定と IDE のセットアップ	自動初期化の詳細、環境変数の一覧、エディター設定（Cursor、VS Code、Claude、Antigravity、Windsurf）。
🛠️ CLI コマンドリファレンス	CLI フラグ（init、run、view、inspect、metrics、audit、doctor、backup、restore、merge）と Git スキャナー。
⏱️ セッション、スナップショット、SDD	セッションのライフサイクル、イベント監査証跡、スナップショット、軌跡、サブディレクトリのサポート、仕様駆動開発。
🧰 ツール、リソース、プロンプト	13 個すべての統合 MCP ツール、読み取り専用の state-memory:/// リソース、プロンプトテンプレートの完全なリファレンス。
📘 正式な API リファレンス	すべての MCP エンドポイントの正式なパラメーター、戻り値のスキーマ、コードシグネチャ。
🎨 3D ビジュアライザーガイド	インタラクティブな WebGL 3D 力指向グラフビジュアライザーの表示とエクスポート。
🗄️ データベーススキーマ	SQLite のテーブル、列、インデックス、スキーマ移行の履歴。

---

📖 エージェントプレイブック：標準の 5 ステップワークフロー

自律型 AI エージェントが state-memory-mcp を含むリポジトリに入る場合：

1. Orient & Bootstrap ──▶ manage_sessions(action: "start") + get_analytics(action: "summary")
2. Task Selection     ──▶ manage_tasks(action: "next") + manage_tasks(action: "find_blockers")
3. Trace Context      ──▶ query_graph(action: "trace") + manage_specs(action: "compliance")
4. Execute & Record   ──▶ manage_nodes(action: "create", type: "decision") + manage_edges(action: "link_visual")
5. Validate & Close   ──▶ run_diagnostics(action: "validate") + manage_tasks(action: "complete") + manage_sessions(action: "end")

---

🧪 テスト

# Run full unit, integration, and performance benchmark test suite across all 113 test files (418 tests)
npm run test

---

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

PuterVision が開発・メンテナンスしています。MIT License のもとで公開されています。

• ローカルストレージの保証：すべてのグラフデータ、意思決定の記録、イベントログは、ワークスペース内に100％ローカルで保持されます。テレメトリやプロジェクトデータが送信されることはありません。
• 商標と非提携：製品名（Cursor、Claude Code、Gemini、Windsurf、VS Code、GitHub、SQLite）はそれぞれの所有者に帰属し、互換性の識別のみを目的として使用しています。