SoupNet-oss

Soup.net es la memoria compartida para agentes de IA. Los agentes con los que trabajas registran tus decisiones de criterio a medida que ocurren y luego las recuperan en tu próxima sesión, en otra herramienta o en el agente de un colaborador que se une al proyecto. El libro de recetas se construye solo.

La unidad de almacenamiento es una receta: una decisión de criterio en una forma estructurada y respaldada por evidencia — "Como [rol] trabajando en [objetivo], prefiero [X] para que [razón]", más citas de apoyo textuales. Los agentes la usan mediante una consulta de recetas: una búsqueda semántica cuyo único efecto secundario es una anexión. Tu agente busca con su hipótesis actual sobre tu gusto, obtiene tus decisiones previas con su evidencia, y la hipótesis misma se convierte en un rastro que futuros agentes pueden encontrar. Nada se sobrescribe jamás, y cada consulta hace que la siguiente sea más inteligente: el mismo mecanismo que usan las hormigas para reforzar rastros de feromonas (estigmergia).

Por qué

Los agentes de IA terminan piezas de trabajo cada vez más grandes por sí solos, y nunca ejecutas solo uno. Cada nueva sesión es un agente nuevo, cada herramienta es otro, y los colaboradores traen los suyos. Cada uno necesita tus respuestas, por separado, desde cero. El recurso escaso eres tú.

La mayoría de las memorias de agentes almacenan hechos y estado de conversación, dentro del ecosistema de un solo proveedor. Soup.net almacena la decisión de criterio en sí, con el contexto y la evidencia que la acotan, y vive contigo: es portátil entre Claude Code, ChatGPT, Gemini o el agente personalizado que tu equipo escribió internamente. Las decisiones pasadas vuelven como contexto, no como directivas: tu agente las sopesa frente a la tarea actual en lugar de reproducir hechos obsoletos.

Como cada consulta deja un rastro fechado y de solo anexión, también obtienes observabilidad gratis: un registro inspeccionable del criterio que tus agentes ejercieron en tu nombre. A medida que los agentes funcionan durante más tiempo entre consultas, ese registro es lo que te mantiene al volante.

Soup.net se desarrolla con su propio flujo de trabajo. Los agentes de IA que lo construyen consultan recetas de sus decisiones de diseño en el corpus del mantenedor mientras trabajan, de modo que la historia de diseño del sistema vive en el sistema, y los agentes que lo amplían recuperan las decisiones de criterio que dieron forma al código que están cambiando.

El Mapa de Recetas es cómo un humano observa crecer ese corpus: las recetas se agrupan por similitud semántica, proyectadas sobre dos ejes conceptuales que tú elijas.

Related MCP server: memmd-mcp

Datos de campo

Una evaluación de campo se ejecutó sobre el trabajo real del mantenedor a mediados de 2026: dos proyectos, agentes coordinadores que lanzaban flotas de subagentes, cada agente instruido para consultar en momentos de criterio y autoinformar qué hizo cada consulta por él. El alcance honesto: un desarrollador, una ventana de retroalimentación de 3 días sobre un corpus de 3 meses, todos agentes de la familia Claude. Observacional, no un punto de referencia.

• 178 consultas en 64 sesiones de agentes distintas, en un solo registro unible.

• El 68% de las consultas confirmaron una decisión previa, por lo que el agente siguió trabajando en lugar de interrumpir al humano.

• ~4,5% de las consultas cambiaron la acción del agente. Raro por diseño, pero esa cola es donde se concentra el valor: el caso más fuerte fue la conclusión medida pero errónea de un agente de "descartar este índice" que fue cuestionada por el humano, re-probada, revertida y registrada permanentemente para que ningún agente futuro la vuelva a derivar.

• 12 de 12 casos auditados de alto impacto se sostuvieron frente al corpus crudo; ninguno fue contradicho.

• Costos: ~1–3 KB de contexto devuelto por consulta, un informe de sesión de 4–6 KB, latencia de consulta en caliente de 0,15–0,36 s.

Modos de fallo conocidos, de la misma evaluación: el autoinforme nunca dijo "no" (trata cada porcentaje como un límite superior); un corpus joven no devuelve nada en aproximadamente 1 de cada 10 consultas (eso es siembra, no fallo); y las consultas por lotes al final de la sesión recuperan en su mayoría los rastros frescos del propio agente. Consulta en el momento del criterio, no en una ceremonia de cierre. Y una brecha honesta: la ruta de URL simple está probada y funciona con ChatGPT (web), Gemini y Claude, pero cada fila de campo instrumentada hasta ahora proviene de agentes de la familia Claude en Claude Code, por lo que los números de efectividad entre proveedores aún no existen. Si lo ejecutas desde otro arnés, estás generando los primeros datos reales.

Pruébalo

• Alojado — gratis, abierto a nuevos registros: soup.net. El sitio genera un informe de un clic para el agente que uses, desde chatbots solo web hasta clientes MCP completos. En claude.ai, conéctate con un clic desde la lista del Directorio de Conectores (todos los planes, incluido Free).

  La ruta de chatbot web es una interfaz de primera clase, no un plan de respaldo: los agentes sin MCP participan mediante enlaces generados: la consulta de recetas es una URL que el agente construye o que el humano hace clic. Probado y funcionando con ChatGPT (web), Gemini y Claude, incluidos los niveles gratuitos.

• Autoalojado — con licencia MIT, pila deliberadamente aburrida (Postgres 17 + pgvector, Hono, React). No se ejecuta ningún LLM en el servidor para la ruta de consulta principal: los agentes razonan donde ya se ejecutan; el servidor hace almacenamiento y búsqueda vectorial. (Las funciones premium opcionales, desactivadas por defecto y opt-in por usuario, usan una llamada LLM del lado del servidor; ver docs/planning/premium-llm-features.md). Los embeddings usan por defecto la API de Gemini de Google (una clave de AI Studio funciona; un proveedor stub determinista cubre desarrollo y pruebas con cero llamadas API), pero los autoalojados pueden ejecutarlos completamente en local sin clave — en proceso en CPU, o contra cualquier servidor local /v1/embeddings (Embeddings locales / sin conexión más abajo). Entonces Gemini solo se necesita para las funciones premium opcionales. Inicio rápido más abajo. De cualquier manera, tu corpus se exporta como un solo archivo JSON (GET /auth/me/export, con sesión iniciada) — y se importa de vuelta: POST /import acepta ese mismo archivo como cuerpo de solicitud crudo (solo humanos con sesión iniciada), por lo que un corpus puede moverse entre instancias, restaurarse desde una copia de seguridad o reconstruirse en un nuevo libro de recetas. Por defecto, la importación crea un nuevo libro de recetas (nómbralo con ?book_name=); pasa ?book=<slug|id> para importar en uno existente. Reimportar tu propio corpus es idempotente (upsert por id exacto: volver a subir omite lo que ya llegó); importar un corpus cuyos ids pertenecen a otra persona en la instancia acuña ids nuevos e informa el mapeo antiguo→nuevo, por lo que es una herramienta de portabilidad, no una restauración byte-idéntica (una fila puede incluso llegar sin id y aun así importarse). La importación re-embediza de forma asíncrona a través de la caché de vectores direccionada por contenido, por lo que el texto que la instancia ya ha embedizado cuesta cero llamadas al proveedor — y eliminar una cuenta preserva esa caché compartida, por lo que reabastecer el mismo corpus sigue siendo gratis.

Apunta un agente con capacidad MCP al servicio alojado en una línea:

claude mcp add --transport http soupnet https://mcp.soup.net/mcp --header "Authorization: Bearer YOUR_KEY"

Aprende más

• docs/benchmarks.md — resultados de puntos de referencia controlados en PERMA, SWE-Lancer y π-Bench (páginas de detalle abstractas y por punto de referencia), el complemento de los datos de campo anteriores

• docs/design-thinking.md — visión del producto, arquetipos de usuario, escenarios de consulta de recetas

• docs/architecture/overview.md — topología del sistema, tres superficies de agente, modelo de datos de un vistazo

• docs/architecture/ranking-engine.md — el motor de clasificación check_recipe: objetivos, el pipeline etapa por etapa, puntos de extensión y el registro de hipótesis

• docs/planning/pivot-search-as-logging.md — el pivote de búsqueda como registro (historial de decisiones)

• docs/engineering-principles.md — 13 principios que gobiernan cada decisión de diseño

• docs/backlog.md — cola de trabajo actual; elementos completados en docs/backlog-completed.md

• docs/adr/ — decisiones de arquitectura con fechas y líneas de estado

• docs/testing-plan.md, docs/workflows/security.md — cómo funcionan las pruebas y las auditorías

La sección superior de cada documento indica su propósito y en qué se diferencia de los documentos cercanos. Si agregas un documento nuevo, haz lo mismo — y enlázalo en esta sección.

Inicio rápido

cp .env.example .env
# Edit .env: set JWT_SECRET (openssl rand -hex 32), DEV_USERNAME, DEV_PASSWORD.
# GEMINI_API_KEY is optional locally — leave EMBEDDINGS_PROVIDER=stub for tests.

docker compose up --build -d    # postgres + backend (with in-process embedding worker) + mailpit
npm run dev:frontend            # Vite SPA on :5273 (separate terminal)

Abre http://localhost:5273 — inicia sesión, genera un enlace de consulta de recetas y comienza a consultar recetas.

Interfaz web de Mailpit para desarrollo local: http://localhost:8625

Embeddings locales / sin conexión

La búsqueda semántica necesita un proveedor de embeddings, seleccionado a nivel de proceso por EMBEDDINGS_PROVIDER. El predeterminado (gemini) llama a Google; stub devuelve vectores falsos deterministas para desarrollo/pruebas. Dos proveedores más permiten que un autoalojado ejecute búsqueda semántica real sin API externa y sin clave:

• local — un modelo CPU en proceso vía @huggingface/transformers (por defecto bge-small-en-v1.5). Configura EMBEDDINGS_PROVIDER=local y listo: el modelo (~23 MB) se descarga una vez. La menor fricción; bueno para probar y para CI.

• openai-compatible — apunta a cualquier servidor local /v1/embeddings estilo OpenAI, para que puedas servir un modelo más potente a través de herramientas que ya ejecutas:

  EMBEDDINGS_PROVIDER=openai-compatible
  EMBEDDINGS_BASE_URL=http://localhost:8080/v1   # llama.cpp: llama-server -m <model>.gguf --embedding --pooling mean
  EMBEDDINGS_MODEL=<the id the server reports>
  # EMBEDDINGS_API_KEY=...                        # optional bearer, if your server requires one

  LM Studio (http://localhost:1234/v1), Ollama (ollama pull nomic-embed-text → http://localhost:11434/v1) y Hugging Face TEI funcionan de manera idéntica: cualquier endpoint /v1/embeddings. Si Soup.net se ejecuta en su propio contenedor, localhost significa el contenedor: usa host.docker.internal o la IP del host.

Dos advertencias. Un proveedor de embeddings por implementación: los vectores de diferentes modelos viven en espacios semánticos distintos y nunca se mezclan, por lo que cambiar de proveedor o modelo significa re-embedizar el corpus (la búsqueda falla de forma segura a resultados vacíos hasta que lo hagas). Y la dimensión nativa de un modelo debe ser ≤ 3072 (o capaz de MRL). Bajo el capó, los vectores de menos de 3072 se rellenan con ceros en la columna existente halfvec(3072), lo que es demostrablemente sin pérdida para coseno: el diseño, las matemáticas y el criterio de salida están en ADR-0023 y docs/planning/local-embedding-provider.md.

Estructura del repositorio

Este es el mapa de orientación de todo el repositorio. Los subdirectorios con su propio README (o un propósito declarado en su documento superior) llevan el detalle; este mapa enlaza a ellos.

apps/backend       Hono HTTP server (port 3101) — auth, REST API, /check recipe page,
                   remote MCP endpoint (/mcp), plus in-process pg-boss embedding consumers
                   (src/embedding-worker/). See ADR-0020, ADR-0021.
apps/frontend      Vite React SPA (port 5273) — dashboard, recipe map, admin pages
apps/mcp-server    Stdio MCP server (bundled as soupnet.mcpb for Claude Desktop)

packages/db        Drizzle schema + migrations — single claimnet schema, single source of truth
packages/domain    Business logic, ranking rules, shared agent-facing copy (no I/O)
packages/contracts Zod schemas + OpenAPI registry (mostly pre-pivot shapes; new routes inline-validate)
packages/client-sdk REST API client wrapper
packages/api-client Auto-generated React Query hooks (regenerated from contracts)
packages/config    Shared tsconfig, ESLint config

docs/              Top level: design-thinking.md, engineering-principles.md, testing-plan.md,
                   backlog.md + backlog-completed.md (the cross-session work queue)
docs/adr/          Architecture decision records — dated, with status lines
docs/architecture/ How the code works: overview, search algorithms, data model (generated)
docs/planning/     Validated proposals ready (or nearly ready) to implement
docs/rough-notes/  Dated working notes, meant to rot — see its README for the contract
                   and the fidelity ladder (rough-notes → planning → adopted docs/ADRs)
docs/workflows/    Repeatable processes (security audit cycle, etc.)
docs/connectors/   Connector-facing docs (claude.ai directory submission material)
docs/legal/        Privacy policy + ToS source material

scripts/           Dev/ops one-offs: test-ci-local.mjs (the canonical gate), cleanup,
                   data-model doc generation, QA harnesses

Configuración de MCP

La ruta principal es MCP remoto sobre HTTP Streamable (sin estado, ADR-0021). Apunta tu agente al endpoint /mcp del backend con una clave API como token Bearer: funciona igual si lo ejecutas localmente (http://localhost:3101/mcp) o contra la instancia desplegada (https://mcp.soup.net/mcp).

Dos rutas de credenciales, un solo endpoint. API-key Bearer (abajo) se adapta a herramientas de desarrollo donde pegar una clave es natural. Los clientes estilo chat — claude.ai, ChatGPT Developer Mode, Mistral Le Chat, Perplexity — se conectan a la misma URL /mcp mediante OAuth 2.1: el servidor implementa metadatos RFC 8414 (/.well-known/oauth-authorization-server y /oauth-protected-resource), Dynamic Client Registration (RFC 7591, POST /oauth/register), autorización PKCE-S256 con una pantalla de consentimiento por libro de recetas, y rotación de tokens de actualización (apps/backend/src/routes/oauth.ts). En claude.ai, Soup.net es un conector listado en el Directorio de Conectores de Anthropic — con un clic desde claude.ai/directory/soupnet, disponible en todos los planes de Claude, incluido el gratuito. Tutoriales por cliente: docs/connectors/index.md (representado en soup.net/info/connect).

1. Genera una clave de API — Inicia sesión en la SPA, abre API keys, crea una clave diaria o con ámbito, y copia el valor sin procesar.

2. Añade el servidor. En Claude Code es una línea:

claude mcp add --transport http soupnet http://localhost:3101/mcp --header "Authorization: Bearer YOUR_KEY"

Cualquier cliente HTTP-MCP usa los mismos tres datos, sin importar cómo los llame su esquema de configuración:

{
  "mcpServers": {
    "soupnet": {
      "type": "http",
      "url": "http://localhost:3101/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Los bloques de configuración por cliente (Codex, VS Code, Google Antigravity, Claude Desktop mediante mcp-remote o el servidor stdio en apps/mcp-server/) están en la guía en /docs/mcp-setup — servida por tu propia instancia, o alojada con tu clave pre-rellenada cuando se accede desde el panel. Una página viva en lugar de copias bifurcadas.

3. Reinicia el cliente (o ejecuta /mcp en Claude Code) para que cargue el nuevo servidor. Herramientas disponibles: check_recipe, get_briefing, list_my_recipe_books, update_recipe_book_description.

El contrato de las herramientas es de solo lectura y adición. No hay superficie de actualización ni eliminación, por lo que un agente confundido (o con inyección de prompt) puede añadir rastros, pero nunca destruir o reescribir el registro — vale la pena saberlo si evalúas servidores MCP por su postura de seguridad.

Desarrollo

Requisitos previos: Node 24 LTS, npm ≥ 10, Docker

Inicia todo con Docker:

docker compose up --build -d    # postgres + backend + worker
npm run dev:frontend             # Vite dev server (separate terminal)

O ejecuta el backend localmente con recarga en caliente:

docker compose up -d postgres    # just the database
npm run build:packages           # build internal packages
source .env && npm run dev:backend   # Hono with tsx watch on :3101
npm run dev:frontend             # Vite on :5273

Migraciones de base de datos:

cd packages/db
npx drizzle-kit generate         # generate migration from schema changes
# migrations auto-apply at backend startup

Pruebas

npx vitest run                    # all tests (.env auto-loaded by vitest config)
npx vitest watch                  # watch mode
npm run test:ci                   # clean reproduction of CI (fresh DB on :5534, no Gemini)

Las pruebas de integración se ejecutan contra el backend de Docker en funcionamiento, así que mantén docker compose up -d activo.

Las pruebas de integración crean datos de prueba en la base de datos en vivo (usuarios con correos @test.local, en sus propios libros de recetas). Los rastros de prueba están limitados al libro de recetas y no aparecen en tus resultados de búsqueda personales. Para limpiar los datos de prueba acumulados:

npx tsx scripts/cleanup-test-data.ts           # clean up
npx tsx scripts/cleanup-test-data.ts --status  # just show counts

Consulta docs/testing-plan.md para conocer las expectativas de cobertura y las categorías de pruebas.

Público vs alojado

Este es el código fuente abierto. Los detalles de despliegue de la versión alojada — Terraform, runbooks operativos, topología de AWS — viven en un repositorio privado complementario porque son específicos de las decisiones de infraestructura de un solo operador y no son generalmente útiles.

Prueba de qué pertenece a este repositorio: ¿un autoalojador que ejecute esta pila en su propia infraestructura necesitaría este contenido? Si es así, está aquí. Si es específico de un despliegue alojado en particular, no lo está.

La aplicación es agnóstica al despliegue — solo Postgres 17 con pgvector y las variables de entorno en .env.example. También es agnóstica a la plataforma de contenedores: Docker Compose localmente, cualquier otra cosa (Kubernetes, ECS, Fly, Hetzner) en producción.

Reglas clave

• Sin lógica de negocio en los manejadores de rutas ni en los componentes de React — usa servicios

• Nunca hagas ediciones directas a la base de datos — usa siempre migraciones de Drizzle

• import type { ... } para importaciones solo de tipos; unknown en lugar de any

• Consulta docs/engineering-principles.md

El humano detrás de esto

Gran parte de Soup.net — código, documentación, partes de este README — está escrito por agentes de IA. Todo ello está dirigido, revisado y respondido por un humano verificable: Andy Forest, arquitecto de sistemas y desarrollador con 30 años de experiencia. Trabajo reciente: Arquitecto de Plataforma de IA en la Scratch Foundation; una década dirigiendo Steamlabs, una organización sin fines de lucro canadiense que llevó educación práctica en IA a más de 850,000 jóvenes estudiantes; coautor de Make: AI Robots (O'Reilly, traducido al japonés); contribuidor de LiteLLM.

Soup.net existe porque ejecuta muchos agentes y quería que su criterio sobreviviera entre ellos. El modelo de responsabilidad que describe este README — los agentes hacen el trabajo, un humano responde por él — es el mismo con el que está construido el propio repositorio.

Licencia y marcas comerciales

El código y la documentación de este repositorio están bajo la Licencia MIT.

El nombre Soup.net, el logotipo, la marca denominativa y los activos de ilustración de la marca identifican el servicio alojado en soup.net y no están cubiertos por la concesión MIT. Haz fork del código, alójalo tú mismo, constrúyelo libremente — pero presenta tu propia instancia pública con tu propio nombre y marca.