HutchDB

HutchDB

Una base de datos para agentes de IA. Sin esquema, SQL ni estructura requerida.
Un espacio de trabajo estructurado que Claude Code, Codex, Cursor, Hermes, Claw, Grokbot y otros clientes MCP pueden leer y actualizar en conjunto. Código abierto.

¿Qué es HutchDB?

HutchDB Core es un servidor MCP headless y de un solo usuario que brinda a cada agente que ejecutes los mismos datos estructurados y duraderos. Conecta Claude Code, Codex, Cursor, VS Code u otro cliente MCP y podrán almacenar, consultar y actualizar colecciones compartidas de registros entre sesiones.

Las colecciones usan Postgres JSONB con esquema opcional, búsqueda de texto completo, validación opcional y definiciones de vistas. No hay panel de control, ni pantalla de inicio de sesión, ni trámites de OAuth — solo un endpoint MCP y una base de datos Postgres que tú controlas.

Este repositorio es el motor de código abierto. Si quieres que personas y agentes trabajen desde el mismo espacio visual, HutchDB Cloud añade vistas web, páginas publicadas, inicio de sesión social y uso compartido por organizaciones. Consulta Core vs Cloud más abajo.

¿Para qué puedes usarlo?

El destino predeterminado para los datos de trabajo de un agente es un archivo markdown: un TODO.md, un directorio de notas, un archivo de memoria lleno de prosa. Eso funciona para un agente que se toma notas a sí mismo. Se rompe en el momento en que quieres filtrar ("bugs abiertos con severidad superior a 2"), agregar ("valor del pipeline por etapa") o hacer que dos agentes actualicen la misma lista sin sobrescribirse entre sí.

HutchDB guarda la misma información como registros reales: direccionables individualmente, consultables y seguros para que varios agentes los lean y actualicen a la vez. Eso lo hace adecuado para cualquier lugar donde un agente produzca o use datos estructurados que deban sobrevivir a un solo chat. Algunos patrones que la gente ejecuta en él:

Investigación que se acumula. Entrevistas con clientes, análisis de competidores, listados extraídos, revisiones de literatura. Cada sesión añade registros a una colección; cualquier sesión posterior puede consultar el conjunto completo.

"Guarda estas cinco páginas de precios de la competencia en competitor-pricing, luego dime quién cambió desde el mes pasado."

Seguimientos que de otro modo llevarías en una hoja de cálculo. Informes de bugs, calendarios de contenido, solicitudes de empleo, inventario, listas de lectura. La diferencia con una hoja de cálculo: tus agentes pueden consultar y actualizar los registros a mitad de tarea.

"Registra este bug en bug-reports con severidad alta, luego lista todo lo que sigue abierto."

Pipelines con traspasos entre agentes. Un agente recopila registros, otro los procesa, un tercero informa sobre los resultados. Un campo de estado en cada registro marca dónde está en el pipeline, para que nada se copie entre herramientas.

"Toma cada registro de leads con estado new, enriquécelo y establece su estado en ready-for-outreach."

Estado de trabajo para proyectos de larga duración. Decisiones, preguntas abiertas y elementos del backlog permanecen consultables después de que se cierra la ventana de contexto. Una nueva sesión comienza preguntando qué ocurrió antes en lugar de recibir un nuevo informe.

"¿Qué decidimos sobre la página de precios la semana pasada y qué sigue sin resolver?"

Manuales de procedimientos repetibles. Almacena las instrucciones, entradas y estado actual de trabajos recurrentes (informes semanales, listas de verificación de lanzamiento, producción de contenido) para que cualquier agente pueda retomarlos y ejecutarlos.

"Ejecuta el manual de métricas semanales y guarda los resultados en weekly-reports."

Nada de esto requiere diseño de esquema de antemano: las colecciones se crean automáticamente en la primera escritura y los registros son JSON arbitrario. Empieza con "guarda esto en HutchDB" y luego consulta los mismos registros desde cualquier agente conectado.

Inicio rápido

Nota: La documentación completa está en hutchdb.com.

1. Clona e inicia (Docker):

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

   Core migra la base de datos y arranca en el puerto 3000. El usuario único y la organización personal se insertan de forma diferida en la primera solicitud — no hay paso de inicialización.

2. Protégelo (opcional pero recomendado fuera de localhost) — exige un token de portador en cada llamada MCP configurando una clave API antes de arrancar:

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

   Si no se configura, todas las solicitudes se consideran de confianza — está bien para localhost, no está bien para un host público.

3. Conecta tu agente. Para Claude Code, añade a tu configuración de MCP:

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

   Cursor, Codex y VS Code aceptan la misma forma de servidor MCP HTTP — mismo url, mismo encabezado de portador.

4. Úsalo. Las colecciones se crean automáticamente en la primera escritura — no hay paso de configuración. Solo habla con tu agente:

   "Guarda estas tareas de lanzamiento en HutchDB." "¿Qué guardamos sobre la investigación de precios la semana pasada?" "Consulta la colección de informes de bugs para cualquier cosa que mencione timeouts."

5. Verifica el 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":{}}'
   

   Deberías ver la lista de herramientas hutch_* (colecciones, registros, esquema, vistas).

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

Ejemplo

Una sesión típica con Claude Code conectado a una instancia local de 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.

Los registros son JSON arbitrario en Postgres JSONB — consultables mediante filtros de contención, operadores estilo Mongo ($gt, $in, $exists, $contains, …) y búsqueda de texto completo, con esquemas opcionales cuando quieres que se aplique estructura. Las colecciones se exportan e importan como CSV o JSON cuando los datos necesitan moverse.

HutchDB Core vs HutchDB Cloud

Core es intencionalmente pequeño. Si quieres la capa de producto, ejecuta HutchDB Cloud — o haz un fork de Core y construye el tuyo propio.

claude.ai requiere OAuth. Core no incluye un servidor de autorización OAuth, por lo que añadir una instancia de Core a claude.ai (web) no funcionará de inmediato. Claude Code, Cursor, Codex y VS Code aceptan un token de portador estático y funcionan bien.

Arquitectura

• Next.js App Router — una página estática de aterrizaje, una ruta MCP (/api/mcp), una ruta REST de inicialización (/api/v1/collections). Todo lo demás está eliminado.
• Drizzle + Postgres — registros almacenados como JSONB, consultados mediante operadores de contención y búsqueda de texto completo.
• Servidor MCP — herramientas de colección (incluidas estadísticas por colección), herramientas de registro (almacenar/consultar/buscar/actualizar/eliminar/estado/transformar más exportación e importación CSV/JSON), herramientas de esquema (describir/inferir/actualizar) y herramientas de vista. Las consultas admiten operadores de filtro ($gt/$gte/$lt/$lte/$ne/$in/$nin/$exists/$contains), proyección de campos y agregaciones de conteo/mín/máx/distinto/suma/promedio.
• Costura de autenticación (src/lib/auth/seam.ts) — el único lugar donde vive la autenticación: verificación de clave de portador cuando HUTCH_API_KEY está configurado, contexto singleton en caso contrario.
• Arranque singleton (src/lib/auth/singleton.ts) — un usuario, una organización personal, creados de forma diferida en la primera solicitud.

Contribuciones

• ¿Encontraste un bug? Abre un issue con pasos para reproducirlo.
• ¿Quieres mejorar Core? Las solicitudes de extracción (PR) son bienvenidas — los contribuyentes firman un CLA para que el mantenedor pueda licenciar de forma dual en HutchDB Cloud. Consulta CONTRIBUTING.md y CLA.md.
• ¿Comentarios o ideas? Los issues son la puerta de entrada; cuéntanos qué estás construyendo.

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=...)

Licencia

AGPL v3.