SoupNet-oss

Soup.net ist ein gemeinsames Gedächtnis für KI-Agenten. Die Agenten, mit denen Sie arbeiten, zeichnen Ihre Urteilsentscheidungen auf, während sie passieren, und bringen sie in Ihrer nächsten Sitzung zurück, in einem anderen Tool oder zum Agenten eines Mitarbeiters, der zum Projekt stößt. Das Rezeptbuch baut sich von selbst auf.

Die Speichereinheit ist ein Rezept: eine Urteilsentscheidung in strukturierter, evidenzgestützter Form – „Als [Rolle] bei der Arbeit an [Ziel] bevorzuge ich [X], damit [Grund]", plus wörtliche unterstützende Zitate. Agenten nutzen es über einen Rezept-Check: eine semantische Suche, deren einziger Nebeneffekt ein Anhängen ist. Ihr Agent sucht mit seiner aktuellen Hypothese über Ihren Geschmack, erhält Ihre früheren Entscheidungen mit ihren Belegen zurück, und die Hypothese selbst wird zu einer Spur, die zukünftige Agenten finden können. Nichts wird jemals überschrieben, und jeder Check macht den nächsten intelligenter – derselbe Mechanismus, mit dem Ameisen Pheromonspuren verstärken (Stigmergie).

Warum

KI-Agenten erledigen immer größere Arbeitspakete eigenständig, und Sie betreiben nie nur einen. Jede neue Sitzung ist ein frischer Agent, jedes Tool ein weiterer, und Mitarbeiter bringen ihre eigenen mit. Jeder braucht Ihre Antworten, separat, von Grund auf. Die knappe Ressource sind Sie.

Die meisten Agentenspeicher speichern Fakten und Gesprächszustand innerhalb des Ökosystems eines Anbieters. Soup.net speichert die Urteilsentscheidung selbst, mit dem Kontext und den Belegen, die sie eingrenzen, und sie lebt bei Ihnen – portabel über Claude Code, ChatGPT, Gemini oder den eigenen Agenten, den Ihr Team intern gebaut hat. Frühere Entscheidungen kommen als Kontext, nicht als Anweisungen zurück: Ihr Agent wägt sie gegen die aktuelle Aufgabe ab, statt veraltete Fakten abzuspielen.

Da jeder Check eine datierte, nur-anhängende Spur hinterlässt, erhalten Sie auch Beobachtbarkeit kostenlos dazu: ein einsehbares Protokoll der Urteilsentscheidungen, die Ihre Agenten in Ihrem Namen getroffen haben. Da Agenten zwischen Check-ins immer länger laufen, ist dieses Protokoll das, was Sie am Steuer hält.

Soup.net wird mit seinem eigenen Workflow entwickelt. Die KI-Agenten, die es bauen, prüfen ihre Designentscheidungen während der Arbeit per Rezept-Check in das Korpus des Betreuers – so lebt die Designgeschichte des Systems im System, und die Agenten, die es erweitern, rufen die Urteilsentscheidungen ab, die den Code geprägt haben, den sie ändern.

Die Rezeptkarte ist die Art, wie ein Mensch dieses Korpus wachsen sieht: Rezepte gruppieren sich nach semantischer Ähnlichkeit, projiziert auf zwei beliebige Konzeptachsen Ihrer Wahl.

Related MCP server: memmd-mcp

Felddaten

Eine Feldevaluierung lief Mitte 2026 über die reale Arbeit des Betreuers – zwei Projekte, Koordinator-Agenten, die Schwarm-Subagenten starten, jeder Agent angewiesen, bei Urteilsmomenten zu prüfen und selbst zu berichten, was jeder Check für ihn bewirkt hat. Der ehrliche Umfang: ein Entwickler, ein 3-Tage-Feedback-Fenster über ein 3-Monats-Korpus, alles Claude-Familien-Agenten. Beobachtend, kein Benchmark.

• 178 Checks über 64 verschiedene Agentensitzungen, in einem gemeinsamen Protokoll.

• 68 % der Checks bestätigten eine frühere Entscheidung, sodass der Agent weiterarbeitete, statt den Menschen zu unterbrechen.

• ~4,5 % der Checks änderten die Aktion des Agenten. Selten mit Absicht – aber in diesem Schwanz konzentriert sich der Wert: Der stärkste Fall war eine abgewogene, aber falsche „Drop-this-Index"-Schlussfolgerung eines Agenten, die vom Menschen angefochten, erneut getestet, umgekehrt und dauerhaft protokolliert wurde, damit kein zukünftiger Agent sie neu ableitet.

• 12 von 12 geprüften Fällen mit hoher Auswirkung hielten dem rohen Korpus stand; keiner wurde widerlegt.

• Kosten: ~1–3 KB zurückgegebener Kontext pro Check, ein 4–6 KB Sitzungs-Briefing, 0,15–0,36 s warme Check-Latenz.

Bekannte Fehlermodi aus derselben Evaluierung: Die Selbstberichte sagten nie „nein" (behandeln Sie jeden Prozentsatz als Obergrenze); ein junges Korpus liefert bei etwa 1 von 10 Checks nichts zurück (das ist Ansaat, kein Fehler); und gebündelte Checks am Sitzungsende rufen meist die eigenen frischen Spuren des Agenten ab. Prüfen Sie im Urteilsmoment, nicht in einer Abschlusszeremonie. Und eine ehrliche Lücke: Der reine-URL-Pfad ist getestet mit ChatGPT (Web), Gemini und Claude – aber jede instrumentierte Feldzeile stammt bisher von Claude-Familien-Agenten in Claude Code, also existieren anbieterübergreifende Wirksamkeitszahlen noch nicht. Wenn Sie es aus einer anderen Umgebung betreiben, erzeugen Sie die ersten echten Daten.

Ausprobieren

• Gehostet – kostenlos, offen für neue Anmeldungen: soup.net. Die Website erzeugt ein Ein-Klick-Briefing für jeden Agenten, den Sie nutzen, von reinen Web-Chatbots bis zu vollständigen MCP-Clients. Auf claude.ai verbinden Sie sich mit einem Klick über den Connectors-Directory-Eintrag (alle Tarife, einschließlich Free).

  Der Web-Chatbot-Pfad ist eine erstklassige Schnittstelle, kein Notbehelf: Agenten ohne MCP nehmen über generierte Links teil – der Rezept-Check ist eine URL, die der Agent konstruiert oder der Mensch anklickt. Getestet mit ChatGPT (Web), Gemini und Claude, einschließlich der kostenlosen Stufen.

• Selbst gehostet – MIT-lizenziert, bewusst langweiliger Stack (Postgres 17 + pgvector, Hono, React). Für den Kern-Check-Pfad läuft kein LLM auf dem Server: Agenten machen die Überlegung dort, wo sie ohnehin laufen; der Server macht Speicherung und Vektorsuche. (Optionale Premium-Funktionen – standardmäßig aus, pro Benutzer aktivierbar – verwenden einen serverseitigen LLM-Aufruf; siehe docs/planning/premium-llm-features.md.) Embeddings verwenden standardmäßig die Google-Gemini-API (ein AI-Studio-Schlüssel funktioniert; ein deterministischer Stub-Provider deckt Entwicklung und Tests mit null API-Aufrufen ab), aber Selbst-Hoster können sie vollständig lokal ohne Schlüssel ausführen – prozessintern auf CPU oder gegen einen beliebigen lokalen /v1/embeddings-Server (Lokale / Offline-Embeddings unten). Gemini wird dann nur noch für die optionalen Premium-Funktionen benötigt. Schnellstart unten. In beiden Fällen exportiert sich Ihr Korpus als einzelne JSON-Datei (GET /auth/me/export, angemeldet) – und importiert zurück: POST /import akzeptiert dieselbe Datei als rohen Anforderungstext (nur angemeldete Menschen), sodass ein Korpus zwischen Instanzen wechseln, aus einem Backup wiederhergestellt oder in ein frisches Rezeptbuch neu aufgebaut werden kann. Standardmäßig erstellt der Import ein neues Rezeptbuch (benennen Sie es mit ?book_name=); übergeben Sie ?book=<slug|id>, um in ein bestehendes zu importieren. Der erneute Import Ihres eigenen Korpus ist idempotent (Upsert mit exakter ID – erneutes Hochladen überspringt, was bereits gelandet ist); das Importieren eines Korpus, dessen IDs jemand anderem auf der Instanz gehören, prägt frische IDs und meldet die alte→neue Zuordnung, also ist es ein Portabilitätswerkzeug, keine byteidentische Wiederherstellung (eine Zeile kann sogar ohne ID ankommen und trotzdem importiert werden). Der Import bettet asynchron über den inhaltsadressierten Vektor-Cache neu ein, sodass Text, den die Instanz bereits eingebettet hat, null Provider-Aufrufe kostet – und das Löschen eines Kontos erhält diesen gemeinsamen Cache, sodass die Neubereitstellung desselben Korpus kostenlos bleibt.

Richten Sie einen MCP-fähigen Agenten in einer Zeile auf den gehosteten Dienst aus:

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

Mehr erfahren

• docs/benchmarks.md – kontrollierte Benchmark-Ergebnisse über PERMA, SWE-Lancer und π-Bench (Abstract + Detailseiten pro Benchmark), die Ergänzung zu den Felddaten oben

• docs/design-thinking.md – Produktvision, Benutzer-Archetypen, Rezept-Check-Szenarien

• docs/architecture/overview.md – Systemtopologie, drei Agenten-Oberflächen, Datenmodell auf einen Blick

• docs/architecture/ranking-engine.md – die check_recipe-Ranking-Engine: Ziele, die Pipeline Schritt für Schritt, Erweiterungspunkte und das Hypothesenregister

• docs/planning/pivot-search-as-logging.md – die Suche-als-Protokollierung-Wende (Entscheidungshistorie)

• docs/engineering-principles.md – 13 Prinzipien, die jede Designentscheidung leiten

• docs/backlog.md – aktuelle Arbeitswarteschlange; erledigte Punkte in docs/backlog-completed.md

• docs/adr/ – Architekturentscheidungen mit Daten und Statuszeilen

• docs/testing-plan.md, docs/workflows/security.md – wie Tests und Audits funktionieren

Der obere Abschnitt jedes Dokuments nennt seinen Zweck und wie es sich von benachbarten Dokumenten unterscheidet. Wenn Sie ein neues Dokument hinzufügen, tun Sie dasselbe – und verlinken Sie in diesen Abschnitt.

Schnellstart

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)

Öffnen Sie http://localhost:5273 – anmelden, einen Rezept-Check-Link erzeugen und mit dem Prüfen von Rezepten beginnen.

Mailpit-Web-UI für lokale Entwicklung: http://localhost:8625

Lokale / Offline-Embeddings

Semantische Suche braucht einen Embedding-Provider, prozessweit ausgewählt über EMBEDDINGS_PROVIDER. Der Standard (gemini) ruft Google auf; stub liefert deterministische Fake-Vektoren für Entwicklung/Tests. Zwei weitere Provider erlauben einem Selbst-Hoster, echte semantische Suche mit keiner externen API und keinem Schlüssel auszuführen:

• local – ein prozessinternes CPU-Modell über @huggingface/transformers (Standard bge-small-en-v1.5). Setzen Sie EMBEDDINGS_PROVIDER=local und los – das Modell (~23 MB) lädt einmal herunter. Geringste Reibung; gut zum Reinschnuppern und für CI.

• openai-compatible – zeigt auf einen beliebigen lokalen OpenAI-Stil-/v1/embeddings-Server, sodass Sie ein stärkeres Modell über Werkzeuge bedienen können, die Sie ohnehin betreiben:

  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) und Hugging Face TEI funktionieren identisch – jeder /v1/embeddings-Endpunkt. Wenn Soup.net in einem eigenen Container läuft, bedeutet localhost den Container: verwenden Sie host.docker.internal oder die Host-IP.

Zwei Einschränkungen. Ein Embedding-Provider pro Bereitstellung – Vektoren verschiedener Modelle leben in verschiedenen semantischen Räumen und werden nie gemischt, also bedeutet ein Wechsel von Provider oder Modell ein Neu-Einbetten des Korpus (die Suche fällt sicher auf leere Ergebnisse zurück, bis Sie das tun). Und die native Dimension eines Modells muss ≤ 3072 sein (oder MRL-fähig). Unter der Haube werden Sub-3072-Vektoren mit Nullen auf die bestehende halfvec(3072)-Spalte aufgefüllt, was nachweislich verlustfrei für Kosinus ist – das Design, die Mathematik und das Austrittskriterium stehen in ADR-0023 und docs/planning/local-embedding-provider.md.

Repo-Struktur

Dies ist die Orientierungskarte für das gesamte Repository. Unterverzeichnisse mit eigenem README (oder einem genannten Zweck in ihrem obersten Dokument) tragen die Details; diese Karte verlinkt zu ihnen.

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

MCP-Einrichtung

Der primäre Pfad ist Remote-MCP über Streamable HTTP (zustandslos, ADR-0021). Richten Sie Ihren Agenten auf den /mcp-Endpunkt des Backends mit einem API-Schlüssel als Bearer-Token – funktioniert gleich, ob Sie lokal laufen (http://localhost:3101/mcp) oder gegen die bereitgestellte Instanz (https://mcp.soup.net/mcp).

Zwei Anmeldewege, ein Endpunkt. API-Key-Bearer (unten) eignet sich für Entwicklertools, bei denen das Einfügen eines Schlüssels natürlich ist. Chat-artige Clients – claude.ai, ChatGPT Developer Mode, Mistral Le Chat, Perplexity – verbinden sich über OAuth 2.1 mit derselben /mcp-URL: Der Server implementiert RFC-8414-Metadaten (/.well-known/oauth-authorization-server und /oauth-protected-resource), dynamische Client-Registrierung (RFC 7591, POST /oauth/register), PKCE-S256-Autorisierung mit einem Zustimmungsbildschirm pro Rezeptbuch sowie Rotation von Refresh-Tokens (apps/backend/src/routes/oauth.ts). Auf claude.ai ist Soup.net ein gelisteter Connector im Anthropic Connectors Directory – ein Klick von claude.ai/directory/soupnet, verfügbar in jedem Claude-Plan, einschließlich Free. Schritt-für-Schritt-Anleitungen pro Client: docs/connectors/index.md (gerendert unter soup.net/info/connect).

1. API-Schlüssel generieren – Melden Sie sich in der SPA an, öffnen Sie API-Schlüssel, erstellen Sie einen täglichen oder eingeschränkten Schlüssel und kopieren Sie den Rohwert.

2. Server hinzufügen. In Claude Code ist das ein Einzeiler:

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

Jeder HTTP-MCP-Client verwendet dieselben drei Fakten, egal wie sein Konfigurationsschema sie nennt:

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

Konfigurationsblöcke pro Client (Codex, VS Code, Google Antigravity, Claude Desktop über mcp-remote oder den stdio-Server in apps/mcp-server/) finden Sie im Leitfaden unter /docs/mcp-setup – bereitgestellt von Ihrer eigenen Instanz oder gehostet mit vorausgefülltem Schlüssel, wenn Sie über das Dashboard darauf zugreifen. Eine lebende Seite statt gegabelter Kopien.

3. Client neu starten (oder /mcp in Claude Code ausführen), um den neuen Server zu übernehmen. Verfügbare Tools: check_recipe, get_briefing, list_my_recipe_books, update_recipe_book_description.

Der Tool-Vertrag ist nur Lesen + Anhängen. Es gibt keine Update- oder Löschschnittstelle, sodass ein verwirrter (oder per Prompt injizierter) Agent Spuren hinzufügen, aber den Datensatz niemals zerstören oder neu schreiben kann – wissenswert, wenn Sie MCP-Server hinsichtlich ihrer Sicherheitslage bewerten.

Entwicklung

Voraussetzungen: Node 24 LTS, npm ≥ 10, Docker

Alles über Docker starten:

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

Oder Backend lokal mit Hot Reload ausführen:

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

Datenbankmigrationen:

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

Tests

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)

Integrationstests greifen auf das laufende Docker-Backend zu, halten Sie also docker compose up -d am Leben.

Integrationstests erstellen Testdaten in der Live-Datenbank (Benutzer mit @test.local-E-Mails, in ihren eigenen Rezeptbüchern). Testspuren sind auf Rezeptbücher beschränkt und erscheinen nicht in Ihren persönlichen Suchergebnissen. So bereinigen Sie angesammelte Testdaten:

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

Siehe docs/testing-plan.md für Abdeckungserwartungen und Testkategorien.

Öffentlich vs. gehostet

Dies ist die Open-Source-Codebasis. Die Bereitstellungsdetails der gehosteten Version – Terraform, operative Runbooks, AWS-Topologie – befinden sich in einem separaten privaten Begleitrepository, da sie spezifisch für die Infrastrukturentscheidungen eines einzelnen Betreibers sind und nicht allgemein nützlich.

Test, was in dieses Repo gehört: Würde ein Selbst-Hoster, der diesen Stack auf seiner eigenen Infrastruktur betreibt, diesen Inhalt benötigen? Wenn ja, ist er hier. Wenn er spezifisch für eine bestimmte gehostete Bereitstellung ist, ist er es nicht.

Die Anwendung ist bereitstellungsagnostisch – nur Postgres 17 mit pgvector und die Umgebungsvariablen in .env.example. Auch Container-Plattform-agnostisch: Docker Compose lokal, alles andere (Kubernetes, ECS, Fly, Hetzner) in Produktion.

Wichtige Regeln

• Keine Geschäftslogik in Routen-Handlern oder React-Komponenten – verwenden Sie Services

• Nie direkte DB-Änderungen vornehmen – immer Drizzle-Migrationen verwenden

• import type { ... } für reine Typ-Importe; unknown statt any

• Siehe docs/engineering-principles.md

Der Mensch dahinter

Ein Großteil von Soup.net – Code, Dokumentation, Teile dieser README – wurde von KI-Agenten geschrieben. Alles wird von einem überprüfbaren Menschen geleitet, überprüft und verantwortet: Andy Forest, Systemarchitekt und Entwickler seit 30 Jahren. Aktuelle Arbeiten: AI Platform Architect bei der Scratch Foundation; ein Jahrzehnt Leitung von Steamlabs, einer kanadischen Non-Profit-Organisation, die 850.000+ jungen Lernenden praktische KI-Bildung näherbrachte; Co-Autor von Make: AI Robots (O'Reilly, ins Japanische übersetzt); LiteLLM-Mitwirkender.

Soup.net existiert, weil er viele Agenten betreibt und wollte, dass sein Urteilsvermögen zwischen ihnen überlebt. Das Verantwortungsmodell, das diese README beschreibt – Agenten erledigen die Arbeit, ein Mensch steht dafür ein – ist dasselbe, mit dem das Repo selbst aufgebaut ist.

Lizenz und Marken

Der Code und die Dokumentation in diesem Repository sind unter der MIT-Lizenz lizenziert.

Der Soup.net-Name, das Logo, das Wortzeichen und die Markenillustrations-Assets kennzeichnen den gehosteten Dienst unter soup.net und sind nicht von der MIT-Lizenz abgedeckt. Forken Sie den Code, hosten Sie ihn selbst, bauen Sie frei darauf auf – aber präsentieren Sie Ihre eigene öffentliche Instanz unter Ihrem eigenen Namen und Branding.