Thoughtbox

ferramenta de raciocínio MCP de próxima geração. sucessora do Clear Thought da Waldzell AI.

Documentação

Thoughtbox

Raciocínio colaborativo multiagente que é auditável. Thoughtbox é um servidor MCP para raciocínio estruturado multiagente, com um aplicativo web complementar para fluxos de workspace e inspeção. Cada etapa é registrada como um pensamento estruturado em um registro de raciocínio persistente que pode ser visualizado, exportado e analisado.

Modos de execução: O desenvolvimento local pode usar armazenamento em sistema de arquivos ou em memória. O modo implantado usa armazenamento com suporte do Supabase, e o servidor MCP de produção atual roda no Cloud Run.

Thoughtbox Observatory UI do Observatory mostrando uma sessão de raciocínio com 14 pensamentos e uma exploração de ramo (nós roxos 13-14) ramificando a partir do pensamento 5.

Modo de Código

Thoughtbox expõe exatamente duas ferramentas MCP usando o padrão Code Mode:

thoughtbox_search — Escreva JavaScript para consultar o catálogo de operações/prompts/recursos. O LLM tem poder total de filtragem programática sobre o catálogo.
thoughtbox_execute — Escreva JavaScript usando o SDK tb para encadear operações. Acesse pensamentos, sessões, conhecimento, notebooks, hub, observabilidade e ferramentas de protocolo por meio de um namespace unificado.

Fluxo de trabalho: pesquise para descobrir operações disponíveis e depois execute código contra elas. Use console.log() para depuração — a saída é capturada nos logs de resposta.

Isso substitui o registro de ferramentas por operação por uma superfície de duas ferramentas que escala sem inflar a janela de contexto.

Colaboração Multiagente

O Hub é a camada de coordenação. Os agentes se registram com perfis específicos de função, entram em workspaces compartilhados e trabalham em um fluxo de trabalho estruturado de resolução de problemas — tudo via thoughtbox_execute.

O fluxo de trabalho: registrar → criar workspace → criar problema → reivindicar → trabalhar → propor solução → revisão por pares → mesclar → consenso

Primitivas de workspace:

Problema — Uma unidade de trabalho com dependências, subproblemas e rastreamento de status (aberto → em andamento → resolvido → fechado)
Proposta — Uma solução proposta com referência de branch de origem e fluxo de revisão
Consenso — Um marcador de decisão vinculado a uma referência de pensamento para rastreabilidade
Canal — Um fluxo de mensagens com escopo de problema para discussão

Perfis de agente: MANAGER, ARCHITECT, DEBUGGER, SECURITY, RESEARCHER, REVIEWER — cada um fornece modelos mentais específicos de domínio e preparação comportamental.

28 operações em identidade, gerenciamento de workspace, problemas, propostas, consenso, canais e relatórios de status.

Raciocínio Auditável

Cada pensamento é um nó em um grafo — numerado, com carimbo de tempo, vinculado aos seus predecessores e persistido entre sessões. Isso cria uma trilha auditável de como as conclusões foram alcançadas.

Os agentes podem pensar para frente, planejar para trás, ramificar em explorações paralelas e revisar conclusões anteriores. Cada padrão é uma operação de primeira classe:

Padrão	Descrição	Caso de uso
Para frente	Progressão sequencial 1→2→3→N	Exploração, descoberta, análise aberta
Para trás	Comece na meta (N), trabalhe de volta ao início (1)	Planejamento, design de sistemas, trabalhar a partir de metas conhecidas
Ramificação	Bifurque em explorações paralelas (A, B, C...)	Comparar alternativas, cenários A/B
Revisão	Atualize pensamentos anteriores com novas informações	Correção de erros, compreensão refinada

Cada pensamento carrega um thoughtType semântico (reasoning, decision_frame, action_report, belief_snapshot, assumption_update, context_snapshot, progress) que classifica que tipo de pensamento é, ortogonal ao padrão de processo usado.

Consulte o Patterns Cookbook para exemplos abrangentes.

Observabilidade em Tempo Real

O Observatory é uma interface web integrada em http://localhost:1729 para assistir ao raciocínio se desenrolar ao vivo.

Grafo ao vivo — pensamentos aparecem como nós em tempo real via WebSocket
Navegação de ramos — ramos colapsam em stubs clicáveis; aprofunde e volte
Painel de detalhes — clique em qualquer nó para ver o conteúdo completo do pensamento
Multi-sessão — alterne entre sessões de raciocínio ativas
Análise profunda — analise sessões para padrões de raciocínio, carga cognitiva e pontos de decisão

A pilha completa de observabilidade inclui rastreamento OpenTelemetry, métricas Prometheus e dashboards Grafana.

Ferramentas de Conhecimento e Raciocínio

Grafo de conhecimento — Memória persistente entre sessões. Capture insights, conceitos, fluxos de trabalho e decisões como entidades tipadas com relações tipadas (BUILDS_ON, CONTRADICTS, SUPERSEDES, etc.) e controles de visibilidade (public, agent-private, team-private).

Notebooks — Programação literária interativa combinando documentação com JavaScript/TypeScript executável em ambientes isolados.

Compatibilidade com Clientes

Thoughtbox está atualmente otimizado para Claude Code. Estamos trabalhando ativamente para suportar clientes MCP adicionais. Devido à variação no suporte de recursos no ecossistema MCP — recursos do servidor (prompts, recursos, ferramentas), recursos do cliente (roots, amostragem, elicitação) e comportamentos como notificações listChanged — implementamos adaptações personalizadas para muitos clientes.

Se você estiver usando um cliente diferente do Claude Code e encontrar problemas, por favor abra uma issue descrevendo seu cliente e o problema.

Instalação

Thoughtbox roda como um servidor MCP baseado em Docker. Requer Docker e Docker Compose.

Início Rápido

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

Isso inicia o Thoughtbox e a pilha completa de observabilidade. O servidor MCP escuta na porta 1731 e a UI do Observatory está disponível em http://localhost:1729.

Configuração do Cliente MCP

Como o Thoughtbox usa transporte HTTP, configure seu cliente MCP para conectar via URL.

Claude Code

Adicione ao seu ~/.claude/settings.json ou ao .claude/settings.json do projeto:

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

Para conectar através do sidecar de observabilidade (adiciona rastreamento OpenTelemetry):

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

Cline / VS Code

Adicione às suas configurações MCP ou ao .vscode/mcp.json:

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

Exemplos de Uso

Pensamento para Frente — Análise de Problema

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"

Pensamento para Trás — Design de Sistema

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"

Ramificação — Comparando Alternativas

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"

Variáveis de Ambiente

Variável	Descrição	Padrão
`DISABLE_THOUGHT_LOGGING`	Suprimir registro de pensamentos no stderr	`false`
`THOUGHTBOX_DATA_DIR`	Diretório base para armazenamento persistente	`~/.thoughtbox`
`THOUGHTBOX_PROJECT`	Escopo do projeto para isolamento de sessão	`_default`
`THOUGHTBOX_TRANSPORT`	Tipo de transporte (`stdio` ou `http`)	`http`
`THOUGHTBOX_STORAGE`	Backend de armazenamento (`fs`, `memory` ou `supabase`)	`fs`
`THOUGHTBOX_OBSERVATORY_ENABLED`	Habilitar UI web do Observatory	`false`
`THOUGHTBOX_OBSERVATORY_PORT`	Porta da UI do Observatory	`1729`
`THOUGHTBOX_OBSERVATORY_CORS`	Origens CORS para Observatory (separadas por vírgula)	(nenhum)
`THOUGHTBOX_AGENT_ID`	ID de agente Hub pré-atribuído	(nenhum)
`THOUGHTBOX_AGENT_NAME`	Nome de agente Hub pré-atribuído	(nenhum)
`SUPABASE_URL`	URL do projeto Supabase (necessária para armazenamento `supabase`)	(nenhum)
`SUPABASE_SERVICE_ROLE_KEY`	Chave de função de serviço do Supabase (necessária para armazenamento `supabase`)	(nenhum)
`PORT`	Porta do servidor HTTP	`1731`
`HOST`	Endereço de bind do servidor HTTP	`0.0.0.0`
`NODE_ENV`	Ambiente Node	(nenhum)
`PROMETHEUS_URL`	Endpoint Prometheus (Docker)	`http://prometheus:9090`
`GRAFANA_URL`	Endpoint Grafana (Docker)	`http://grafana:3000`

Desenvolvimento

Para desenvolvimento local (requer Node.js 22+):

pnpm install
pnpm build
pnpm dev      # Development with hot reload

Testes

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 inicia a pilha completa:

Serviço	Porta	Descrição
thoughtbox	1731 (MCP), 1729 (Observatory)	Servidor MCP principal + UI do Observatory
mcp-sidecar	4000	Proxy de observabilidade com OpenTelemetry
otel-collector	4318 (HTTP), 8889 (métricas)	Coletor OpenTelemetry
prometheus	9090	Armazenamento de métricas + alertas
grafana	3001	Dashboards e visualização

Os dados persistentes são armazenados em volumes nomeados: thoughtbox-data, prometheus-data, grafana-data.

Arquitetura

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

Armazenamento

Thoughtbox suporta três backends de armazenamento:

InMemoryStorage: Armazenamento volátil para testes, usa LinkedThoughtStore para buscas de pensamento O(1)
FileSystemStorage: Armazenamento persistente com gravações atômicas e isolamento de projeto (padrão)
SupabaseStorage: Armazenamento nativo em nuvem com suporte do Supabase Postgres para instâncias implantadas

Os dados são armazenados em ~/.thoughtbox/ por padrão (FileSystemStorage):

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

Contribuindo

Aceitamos contribuições! Consulte CONTRIBUTING.md para:

Configuração de desenvolvimento
Convenções de commit (otimizadas para compreensão de código thick_read)
Testes com vitest e scripts agênticos
Processo de pull request

Licença

Licença MIT — livre para usar, modificar e distribuir.