Thoughtbox

Thoughtbox

監査可能なマルチエージェント協調推論。 Thoughtbox は、構造化されたマルチエージェント推論のための MCP サーバーで、ワークスペースや調査のワークフローに対応するウェブアプリを付属しています。すべてのステップは、永続的な推論台帳に構造化された思考として記録され、可視化、エクスポート、分析できます。

実行モード： ローカル開発では、ファイルシステムまたはインメモリストレージを使用できます。デプロイモードでは Supabase を利用したストレージを使用し、現在の本番 MCP サーバーは Cloud Run で実行されています。

推論セッションの思考が 14 件表示され、思考 5 から分岐した分岐探索（紫色のノード 13～14）が示されている Observatory UI。

コードモード

Thoughtbox は、コードモードパターンを使用する 2 つの MCP ツールのみを公開します。

• thoughtbox_search — JavaScript を記述して、操作／プロンプト／リソースのカタログを検索します。LLM はカタログに対して、プログラムによるフィルタリング機能をすべて利用できます。
• thoughtbox_execute — tb SDK を使った JavaScript を記述して、操作を連鎖させます。統一された名前空間を通じて、思考、セッション、ナレッジ、ノートブック、ハブ、可観測性、プロトコルツールにアクセスできます。

ワークフロー： まず検索して利用可能な操作を確認し、次にコードを実行して操作を呼び出します。デバッグには console.log() を使用します。出力は応答ログに記録されます。

これにより、操作ごとにツールを登録する方式を、コンテキストウィンドウを肥大化させずに拡張できる 2 ツール構成に置き換えます。

マルチエージェント協調

ハブは調整レイヤーです。エージェントは役割に応じたプロフィールを登録し、共有ワークスペースに参加して、構造化された問題解決ワークフローに沿って作業します。これらはすべて thoughtbox_execute を通じて行われます。

ワークフロー： 登録 → ワークスペースを作成 → 問題を作成 → 担当を引き受ける → 作業する → 解決策を提案する → ピアレビュー → マージ → 合意

ワークスペースのプリミティブ：

• 問題 — 依存関係、サブ問題、ステータス追跡（未対応 → 進行中 → 解決済み → クローズ）を備えた作業単位
• 提案 — ソースブランチの参照とレビューワークフローを備えた解決策の提案
• 合意 — 追跡可能性を確保するため、思考への参照に結び付けられた意思決定マーカー
• チャンネル — 議論のために問題に紐付けられたメッセージストリーム

エージェントプロフィール： MANAGER、ARCHITECT、DEBUGGER、SECURITY、RESEARCHER、REVIEWER — それぞれが、分野に特化したメンタルモデルと行動のプライミングを提供します。

アイデンティティ、ワークスペース管理、問題、提案、合意、チャンネル、ステータス報告にわたる 28 の操作があります。

監査可能な推論

すべての思考はグラフ内のノードであり、番号、タイムスタンプ、先行ノードへのリンクが付与され、セッションをまたいで永続化されます。これにより、結論に至った過程を監査可能な形で記録できます。

エージェントは順方向に思考し、逆方向に計画を立て、並行探索へ分岐し、以前の結論を修正できます。それぞれのパターンは、第一級の操作として用意されています。

パターン	説明	使用例
順方向	1→2→3→N と順に進む	探索、発見、自由形式の分析
逆方向	目標（N）から始め、開始点（1）へさかのぼる	計画、システム設計、既知の目標からの作業
分岐	並行探索（A、B、C...）に分岐する	選択肢の比較、A/B シナリオ
修正	新しい情報を使って以前の思考を更新する	エラー修正、理解の精緻化

各思考には、使用するプロセスパターンとは独立して、思考の「種類」を分類する意味的な thoughtType（reasoning、decision_frame、action_report、belief_snapshot、assumption_update、context_snapshot、progress）が付与されています。

包括的な例については、**パターンのクックブック**を参照してください。

リアルタイムオブザーバビリティ

Observatory は、推論の進行をリアルタイムで確認できる、http://localhost:1729 で利用可能な組み込みのウェブ UI です。

• ライブグラフ — WebSocket 経由で思考がノードとしてリアルタイムに表示されます
• ブランチナビゲーション — ブランチはクリック可能なスタブに折りたたまれ、詳細を確認したり、元に戻ったりできます
• 詳細パネル — 任意のノードをクリックすると、思考の内容全体を表示できます
• 複数セッション — アクティブな推論セッションを切り替えられます
• 詳細分析 — セッションを分析して、推論パターン、認知負荷、意思決定ポイントを確認できます

オブザーバビリティスタック全体には、OpenTelemetry トレーシング、Prometheus メトリクス、Grafana ダッシュボードが含まれます。

ナレッジと推論のツール

ナレッジグラフ — セッションをまたいで保持されるメモリです。インサイト、概念、ワークフロー、意思決定を、型付きエンティティと型付きの関係（BUILDS_ON、CONTRADICTS、SUPERSEDES など）、および可視性制御（public、agent-private、team-private）とともに記録します。

ノートブック — ドキュメントと、隔離された環境で実行可能な JavaScript／TypeScript を組み合わせた、インタラクティブな文芸的プログラミング環境です。

クライアントとの互換性

Thoughtbox は現在、Claude Code 向けに最適化されています。ほかの MCP クライアントのサポートにも積極的に取り組んでいます。MCP エコシステム全体で機能のサポート状況（サーバー機能（プロンプト、リソース、ツール）、クライアント機能（ルート、サンプリング、エリシテーション）、listChanged 通知のような動作）に違いがあるため、多くのクライアント向けに個別の調整を実装しています。

Claude Code 以外のクライアントを使用していて問題が発生した場合は、使用しているクライアントと問題の内容を記載して、issue を作成してください。

インストール

Thoughtbox は Docker ベースの MCP サーバーとして動作します。Docker と Docker Compose が必要です。

クイックスタート

git clone https://github.com/Kastalien-Research/thoughtbox.git
cd thoughtbox
docker compose up --build

これにより、Thoughtbox とオブザーバビリティスタック全体が起動します。MCP サーバーはポート 1731 でリッスンし、Observatory UI は http://localhost:1729 で利用できます。

MCP クライアントの設定

Thoughtbox は HTTP トランスポートを使用するため、URL 経由で接続するように MCP クライアントを設定してください。

Claude Code

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

{
  "mcpServers": {
    "thoughtbox": {
      "url": "http://localhost:1731/mcp"
    }
  }
}

オブザーバビリティサイドカー経由で接続する場合（OpenTelemetry トレーシングが追加されます）：

{
  "mcpServers": {
    "thoughtbox": {
      "url": "http://localhost:4000/mcp"
    }
  }
}

Cline / VS Code

MCP 設定または .vscode/mcp.json に追加します。

{
  "servers": {
    "thoughtbox": {
      "url": "http://localhost:1731/mcp"
    }
  }
}

使用例

前向き思考 — 問題分析

Thought 1: "Users report slow checkout. Let's analyze..."
Thought 2: "Data shows 45s average, target is 10s..."
Thought 3: "Root causes: 3 API calls, no caching..."
Thought 4: "Options: Redis cache, query optimization, parallel calls..."
Thought 5: "Recommendation: Implement Redis cache for product data"

後ろ向き思考 — システム設計

Thought 8: [GOAL] "System handles 10k req/s with <100ms latency"
Thought 7: "Before that: monitoring and alerting operational"
Thought 6: "Before that: resilience patterns implemented"
Thought 5: "Before that: caching layer with invalidation"
...
Thought 1: [START] "Current state: 1k req/s, 500ms latency"

分岐 — 選択肢の比較

Thought 4: "Need to choose database architecture..."

Branch A (thought 5): branchId="sql-path"
  "PostgreSQL: ACID compliance, mature tooling, relational integrity"

Branch B (thought 5): branchId="nosql-path"
  "MongoDB: Flexible schema, horizontal scaling, document model"

Thought 6: [SYNTHESIS] "Use PostgreSQL for transactions, MongoDB for analytics"

環境変数

変数	説明	デフォルト
DISABLE_THOUGHT_LOGGING	stderr への思考ログ出力を抑制します	false
THOUGHTBOX_DATA_DIR	永続ストレージのベースディレクトリ	~/.thoughtbox
THOUGHTBOX_PROJECT	セッション分離に使用するプロジェクトスコープ	_default
THOUGHTBOX_TRANSPORT	トランスポートの種類（stdio または http）	http
THOUGHTBOX_STORAGE	ストレージバックエンド（fs、memory、supabase のいずれか）	fs
THOUGHTBOX_OBSERVATORY_ENABLED	Observatory ウェブ UI を有効にします	false
THOUGHTBOX_OBSERVATORY_PORT	Observatory UI のポート	1729
THOUGHTBOX_OBSERVATORY_CORS	Observatory の CORS オリジン（カンマ区切り）	（なし）
THOUGHTBOX_AGENT_ID	事前に割り当てられた Hub エージェント ID	（なし）
THOUGHTBOX_AGENT_NAME	事前に割り当てられた Hub エージェント名	（なし）
SUPABASE_URL	Supabase プロジェクト URL（supabase ストレージに必要）	（なし）
SUPABASE_SERVICE_ROLE_KEY	Supabase サービスロールキー（supabase ストレージに必要）	（なし）
PORT	HTTP サーバーのポート	1731
HOST	HTTP サーバーのバインドアドレス	0.0.0.0
NODE_ENV	Node 環境	（なし）
PROMETHEUS_URL	Prometheus エンドポイント（Docker）	http://prometheus:9090
GRAFANA_URL	Grafana エンドポイント（Docker）	http://grafana:3000

開発

ローカル開発の場合（Node.js 22 以降が必要です）：

pnpm install
pnpm build
pnpm dev      # Development with hot reload

テスト

npx vitest run              # Unit tests
pnpm test                   # Full suite (build + vitest)
pnpm test:agentic           # Agentic tests — full suite (build + run)
pnpm test:agentic:tool      # Agentic tests — tool-level only
pnpm test:agentic:quick     # Agentic tests — quick (no build)
pnpm test:behavioral        # Behavioral contract tests

Docker Compose

docker compose up --build を実行すると、スタック全体が起動します。

サービス	ポート	説明
thoughtbox	1731 (MCP), 1729 (Observatory)	コア MCP サーバー + Observatory UI
mcp-sidecar	4000	OpenTelemetry を使用した可観測性プロキシ
otel-collector	4318 (HTTP), 8889 (メトリクス)	OpenTelemetry Collector
prometheus	9090	メトリクスの保存 + アラート
grafana	3001	ダッシュボードと可視化

永続データは、名前付きボリューム thoughtbox-data、prometheus-data、grafana-data に保存されます。

アーキテクチャ

src/
├── index.ts                # Entry point (Streamable HTTP transport)
├── server-factory.ts       # MCP server factory with tool registration
├── thought-handler.ts      # Core thought recording logic
├── types.ts                # Shared type definitions
├── database.types.ts       # Supabase generated types
├── code-mode/              # Code Mode tool surface
│   ├── search-tool.ts      # thoughtbox_search — catalog query via JS
│   ├── execute-tool.ts     # thoughtbox_execute — operation chaining via tb SDK
│   ├── search-index.ts     # Frozen catalog of operations/prompts/resources
│   └── sdk-types.ts        # TypeScript definitions for the tb SDK
├── thought/                # Thought operations and tool definitions
├── sessions/               # Session management
├── persistence/            # Storage layer
│   ├── storage.ts          # InMemoryStorage with LinkedThoughtStore
│   ├── filesystem-storage.ts  # FileSystemStorage with atomic writes
│   └── supabase-storage.ts # SupabaseStorage for deployed/cloud usage
├── observatory/            # Real-time visualization
│   ├── ui/                 # Self-contained HTML/CSS/JS
│   └── ws-server.ts        # WebSocket server for live updates
├── hub/                    # Multi-agent collaboration
│   ├── identity.ts         # Agent registration
│   ├── workspace.ts        # Workspace management
│   ├── problems.ts         # Problem tracking with dependencies
│   ├── proposals.ts        # Solution proposals with reviews
│   ├── consensus.ts        # Decision recording
│   ├── channels.ts         # Problem-scoped messaging
│   ├── hub-handler.ts      # Hub operation dispatcher
│   └── operations.ts       # 28-operation catalog
├── channel/                # Hub event channels and SSE streaming
├── protocol/               # Ulysses and Theseus protocol tools
├── knowledge/              # Knowledge graph memory
├── auth/                   # API key authentication
├── audit/                  # Audit manifest generation
├── evaluation/             # LangSmith evaluation and online monitoring
├── notebook/               # Literate programming engine
├── events/                 # Event emission system
├── observability/          # Prometheus/Grafana integration
├── prompts/                # MCP prompt definitions
├── references/             # Anchor parsing and resolution
├── revision/               # Revision indexing
├── operations-tool/        # Operations tool handler
└── resources/              # Documentation and patterns cookbook

ストレージ

Thoughtbox は、次の 3 種類のストレージバックエンドをサポートしています。

• InMemoryStorage：テスト用の揮発性ストレージです。O(1) の思考検索には LinkedThoughtStore を使用します。
• FileSystemStorage：アトミックな書き込みとプロジェクト分離に対応した永続ストレージです（デフォルト）。
• SupabaseStorage：デプロイ済みインスタンス向けの、Supabase Postgres を基盤とするクラウドネイティブストレージです。

データはデフォルトで ~/.thoughtbox/ に保存されます（FileSystemStorage）。

~/.thoughtbox/
├── config.json           # Global configuration
└── projects/
    └── {project}/
        └── sessions/
            └── {date}/
                └── {session-id}/
                    ├── manifest.json
                    └── {thought-number}.json

コントリビューション

コントリビューションを歓迎します！CONTRIBUTING.md では、以下について説明しています。

• 開発環境のセットアップ
• コミット規約（thick_read のコード理解に最適化）
• vitest とエージェント型スクリプトを使ったテスト
• プルリクエストの手順

ライセンス

MIT License — 無料で使用、変更、配布できます。