Thoughtbox

Multi-agent collaborative reasoning that's auditable.Thoughtbox is an MCP server for structured, multi-agent reasoning, with a companion web app for workspace and inspection flows. Every step is recorded as a structured thought in a persistent reasoning ledger that can be visualized, exported, and analyzed.

Runtime modes:Local development can use filesystem or in-memory storage. Deployed mode uses Supabase-backed storage, and the current production MCP server runs on Cloud Run.

Observatory UI showing a reasoning session with 14 thoughts and a branch exploration (purple nodes 13-14) forking from thought 5.

Thoughtbox exposes exactlytwo MCP toolsusing the Code Mode pattern:

- thoughtbox_search— Write JavaScript to query the operation/prompt/resource catalog. The LLM has full programmatic filtering power over the catalog.
- thoughtbox_execute— Write JavaScript using thetbSDK to chain operations. Access thoughts, sessions, knowledge, notebooks, hub, observability, and protocol tools through a unified namespace.

Workflow:search to discover available operations, then execute code against them. Useconsole.log()for debugging — output is captured in response logs.

This replaces per-operation tool registration with a two-tool surface that scales without context window bloat.

The Hub is the coordination layer. Agents register with role-specific profiles, join shared workspaces, and work through a structured problem-solving workflow — all viathoughtbox_execute.

The workflow:register → create workspace → create problem → claim → work → propose solution → peer review → merge → consensus

- Problem— A unit of work with dependencies, sub-problems, and status tracking (open → in-progress → resolved → closed)
- Proposal— A proposed solution with a source branch reference and review workflow
- Consensus— A decision marker tied to a thought reference for traceability
- Channel— A message stream scoped to a problem for discussion

Agent Profiles:MANAGER,ARCHITECT,DEBUGGER,SECURITY,RESEARCHER,REVIEWER— each provides domain-specific mental models and behavioral priming.

28 operationsacross identity, workspace management, problems, proposals, consensus, channels, and status reporting.

Every thought is a node in a graph — numbered, timestamped, linked to its predecessors, and persisted across sessions. This creates an auditable trail of how conclusions were reached.

Agents can think forward, plan backward, branch into parallel explorations, and revise earlier conclusions. Each pattern is a first-class operation:

Each thought carries a semanticthoughtType(reasoning,decision_frame,action_report,belief_snapshot,assumption_update,context_snapshot,progress) that classifieswhat kindof thought it is, orthogonal to the process pattern used.

See thePatterns Cookbookfor comprehensive examples.

If you're using a client other than Claude Code and encounter issues, pleaseopen an issuedescribing your client and the problem.

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

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

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

{ "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"

For local development (requires 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 up --buildstarts the full stack:

Persistent data is stored in named volumes: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 supports three storage backends:

- InMemoryStorage: Volatile storage for testing, usesLinkedThoughtStorefor O(1) thought lookups
- FileSystemStorage: Persistent storage with atomic writes and project isolation (default)
- SupabaseStorage: Cloud-native storage backed by Supabase Postgres for deployed instances

Data is stored at~/.thoughtbox/by default (FileSystemStorage):

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

We welcome contributions! SeeCONTRIBUTING.mdfor:

Institutional research and manager diligence reports on hedge funds, venture capital and private equity managers. Summary of filings, personnel changes, media screening and social signals delivered to you in minutes.