HutchDB

HutchDB

Um banco de dados para agentes de IA. Sem schema, SQL ou estrutura necessária.
Um workspace estruturado que Claude Code, Codex, Cursor, Hermes, Claw, Grokbot e outros clientes MCP podem ler e atualizar juntos. Open source.

O que é HutchDB?

O HutchDB Core é um servidor MCP headless, para um único usuário, que dá a cada agente que você executa os mesmos dados estruturados e duráveis. Conecte Claude Code, Codex, Cursor, VS Code ou outro cliente MCP e eles poderão armazenar, consultar e atualizar coleções compartilhadas de registros entre sessões.

As coleções usam Postgres JSONB com schema opcional, busca em texto completo, validação opcional e definições de views. Não há dashboard, tela de login ou cerimônia de OAuth — apenas um endpoint MCP e um banco de dados Postgres que você controla.

Este repositório é o motor OSS. Se você quiser que pessoas e agentes trabalhem no mesmo workspace visual, o HutchDB Cloud adiciona views web, páginas publicadas, login social e compartilhamento por organização. Veja Core vs Cloud abaixo.

Para que você pode usá-lo?

O destino padrão para dados de trabalho de agentes é um arquivo markdown: um TODO.md, um diretório de notas, um arquivo de memória cheio de prosa. Isso funciona para um agente fazendo anotações para si mesmo. Quebra no momento em que você quer filtrar ("bugs abertos acima da severidade 2"), agregar ("valor do pipeline por etapa") ou ter dois agentes atualizando a mesma lista sem sobrescrever um ao outro.

O HutchDB guarda as mesmas informações como registros reais: endereçáveis individualmente, consultáveis e seguros para que vários agentes leiam e atualizem ao mesmo tempo. Isso o torna adequado para qualquer lugar onde um agente produza ou use dados estruturados que precisem sobreviver a um único chat. Alguns padrões que as pessoas usam nele:

Pesquisa que se acumula. Entrevistas com clientes, análises de concorrentes, listagens raspadas, revisões de literatura. Cada sessão adiciona registros a uma coleção; qualquer sessão posterior pode consultar o conjunto inteiro.

"Salve estas cinco páginas de preços de concorrentes em competitor-pricing, depois me diga quem mudou desde o mês passado."

Rastreadores que você manteria em uma planilha. Relatórios de bugs, calendários de conteúdo, candidaturas a empregos, inventário, listas de leitura. A diferença de uma planilha: seus agentes podem consultar e atualizar os registros no meio da tarefa.

"Registre este bug em bug-reports com severidade alta e depois liste tudo que ainda está aberto."

Pipelines com transferências entre agentes. Um agente coleta registros, outro os processa, um terceiro relata os resultados. Um campo de status em cada registro marca onde ele está no pipeline, então nada é copiado entre ferramentas.

"Puxe todos os registros de leads com status new, enriqueça cada um e defina o status como ready-for-outreach."

Estado de trabalho para projetos de longo prazo. Decisões, perguntas em aberto e itens de backlog permanecem consultáveis depois que a janela de contexto fecha. Uma nova sessão começa perguntando o que veio antes, em vez de receber um novo briefing.

"O que decidimos sobre a página de preços na semana passada, e o que ainda está sem solução?"

Playbooks repetíveis. Armazene as instruções, entradas e status atual de tarefas recorrentes (relatórios semanais, checklists de release, produção de conteúdo) para que qualquer agente possa pegar uma e executá-la.

"Execute o playbook de métricas semanais e armazene os resultados em weekly-reports."

Nada disso exige design de schema antecipado: as coleções são criadas automaticamente na primeira escrita e os registros são JSON arbitrário. Comece com "salve isso no HutchDB" e depois consulte os mesmos registros de qualquer agente conectado.

Início Rápido

Nota: A documentação completa está em hutchdb.com.

1. Clone e inicie (Docker):

   git clone https://github.com/ExpeditedProjects/hutchdb
   cd hutchdb
   docker compose up
   

   O Core migra o banco de dados e inicia na porta 3000. O usuário singleton e a organização pessoal são inseridos de forma preguiçosa na primeira requisição — não há etapa de seed.

2. Proteja (opcional, mas recomendado fora do localhost) — exija um bearer token em cada chamada MCP definindo uma chave de API antes de iniciar:

   export HUTCH_API_KEY="$(openssl rand -hex 32)"
   

   Se não definido, todas as requisições são confiáveis — ok para localhost, não ok para um host público.

3. Conecte seu agente. Para Claude Code, adicione ao seu config MCP:

   {
     "mcpServers": {
       "hutch": {
         "type": "http",
         "url": "http://localhost:3000/api/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_HUTCH_API_KEY"
         }
       }
     }
   }
   

   Cursor, Codex e VS Code aceitam o mesmo formato de servidor MCP HTTP — mesmo url, mesmo header bearer.

4. Use. As coleções são criadas automaticamente na primeira escrita — não há etapa de configuração. Basta conversar com seu agente:

   "Salve estas tarefas de lançamento no HutchDB." "O que armazenamos sobre a pesquisa de preços na semana passada?" "Consulte a coleção de relatórios de bugs por qualquer menção a timeouts."

5. Verifique o endpoint (opcional):

   curl -X POST http://localhost:3000/api/mcp \
     -H "Authorization: Bearer $HUTCH_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
   

   Você deve ver a lista de ferramentas hutch_* (coleções, registros, schema, views).

git clone https://github.com/ExpeditedProjects/hutchdb
cd hutchdb
npm install
cp .env.local.example .env.local
# Required: HUTCH_DATABASE_URL
# Optional: HUTCH_API_KEY
npm run db:migrate
npm run dev

Exemplo

Uma sessão típica com Claude Code conectado a uma instância local do Core:

You:    Save each of these customer interviews as a record — tag the ones
        that mention pricing.

Agent:  Stored 9 records in `customer-interviews`, 4 tagged "pricing".

You:    (a week later) Which interviewees complained about onboarding?

Agent:  Querying `customer-interviews`... 3 records match: Dana R.,
        Marcus T., and the anonymous Feb 12 call.

Os registros são JSON arbitrário em Postgres JSONB — consultáveis via filtros de contenção, operadores estilo Mongo ($gt, $in, $exists, $contains, …) e busca em texto completo, com schemas opcionais quando você quer estrutura imposta. As coleções exportam e importam como CSV ou JSON quando os dados precisam ser movidos.

HutchDB Core vs HutchDB Cloud

O Core é intencionalmente pequeno. Se você quiser a camada de produto, execute o HutchDB Cloud — ou faça um fork do Core e construa o seu.

claude.ai exige OAuth. O Core não inclui servidor de autorização OAuth, então adicionar uma instância do Core ao claude.ai (web) não funcionará de imediato. Claude Code, Cursor, Codex e VS Code aceitam um bearer token estático e funcionam normalmente.

Arquitetura

• Next.js App Router — uma página estática de landing, uma rota MCP (/api/mcp), uma rota REST de seed (/api/v1/collections). Todo o resto foi removido.
• Drizzle + Postgres — registros armazenados como JSONB, consultados via operadores de contenção e busca em texto completo.
• Servidor MCP — ferramentas de coleção (incluindo estatísticas por coleção), ferramentas de registro (armazenar/consultar/buscar/atualizar/excluir/status/transformar, além de exportação e importação CSV/JSON), ferramentas de schema (descrever/inferir/atualizar) e ferramentas de view. As consultas suportam operadores de filtro ($gt/$gte/$lt/$lte/$ne/$in/$nin/$exists/$contains), projeção de campos e agregações de contagem/mín/máx/distinto/soma/média.
• Costura de autenticação (src/lib/auth/seam.ts) — o único lugar onde a autenticação vive: verificação de chave bearer quando HUTCH_API_KEY está definido, contexto singleton caso contrário.
• Bootstrap singleton (src/lib/auth/singleton.ts) — um usuário, uma organização pessoal, criados de forma preguiçosa na primeira requisição.

Contribuindo

• Encontrou um bug? Abra uma issue com passos de reprodução.
• Quer melhorar o Core? PRs são bem-vindos — contribuidores assinam um CLA para que o mantenedor possa licenciar duplamente no HutchDB Cloud. Veja CONTRIBUTING.md e CLA.md.
• Feedback ou ideias? Issues são a porta de entrada; conte-nos o que você está construindo.

npm test          # vitest
npm run smoke     # end-to-end smoke test against a running instance:
                  #   SMOKE_BASE_URL=http://localhost:3000 npm run smoke
                  #   (keyed mode: add SMOKE_API_KEY=...)

Licença

AGPL v3.