SemanticSwap — ein speicher-optimierter Inferenz-Proxy für LLMs

Ein OpenAI-kompatibler Proxy, der einem Sprachmodell ein durchsuchbares Langzeitgedächtnis gibt — er komprimiert das Kontextfenster laufend, lagert es in einen semantischen Speicher aus und lädt nur das Relevante zurück. Weniger Token-Kosten, ein Gedächtnis, das über die Kontextgrenze hinaus bestehen bleibt.

Die Herausforderung

Nach einer ursprünglichen Idee von Jan Häusle; Umsetzung durch Ivo Häusle. Jede Konversation mit einem großen Sprachmodell läuft gegen dieselbe Wand: Das Kontextfenster ist begrenzt, und jedes Token darin wird bei jeder Antwort neu bezahlt. Wächst ein Chat oder eine Agenten-Session, hat man nur zwei schlechte Optionen — frühere Nachrichten wegwerfen, dann „vergisst" das Modell, oder die ganze Historie immer wieder mitschicken, dann steigen die Kosten mit jeder Antwort. Was Kund:innen eigentlich wollen, ist schnell gesagt und schwer gebaut: ein Modell, das sich an die wichtigen Fakten von weit früher erinnert, ohne dafür das komplette Transkript jedes Mal im Kontext mitzuschleppen.

Die ehrliche Lösung ist kein Prompt-Trick. Sie sitzt unsichtbar zwischen einem beliebigen OpenAI-kompatiblen Client und dem Modell, entscheidet, was im aktiven Fenster bleibt und was ausgelagert wird, speichert es so, dass es nach Bedeutung durchsuchbar ist (nicht nur nach Stichwort), und holt genau das richtige Stück zurück, wenn es gebraucht wird — ohne dass der Client eine einzige Zeile ändert.

Das Vorgehen

• Ein echter Drop-in-Proxy. SemanticSwap spricht die OpenAI-API, jeder vorhandene Client (Open WebUI, LangChain, eigene App) wechselt durch das Ändern einer Base-URL — kein SDK, keine Code-Änderung. Weitergeleitet wird an beliebige Modelle über eine Provider-Abstraktion (LiteLLM), lokal oder gehostet.
• Session-Tracking ohne Mitwirkung des Clients. Sessions werden über eine Prefix-Hash-Kette der Nachrichtenhistorie erkannt, sodass der Proxy einer Konversation folgen — und sogar Forks erkennen — kann, ganz ohne Client-Support.
• Swap-out: komprimieren und strukturieren statt abschneiden. Nähert sich der aktive Kontext seinem Limit, werden ältere Turns zusammengefasst und in einen strukturierten semantischen Speicher destilliert — Graph-Tripel plus Vektor-Embeddings in einer einzigen SQLite-Datenbank — statt still verworfen.
• **Swap-in: das Original zurückholen, keine Paraphrase.** Wird ein archivierter Fakt wieder relevant, findet ihn ein Vektor-Lookup und das Original-Snippet wird erneut injiziert — Antworten bleiben dem tatsächlich Gesagten treu. Das Modell kann archivierte Transkripte auch selbst über ein verstecktes Tool retrieve_archived_memory nachladen — für den Client unsichtbar.
• Eine Mess-Harness statt Bauchgefühl. Ein wiederholbares Eval fährt eine lange synthetische Konversation mit verankerten Fakten und berichtet Recall, Kompressions-Ratio und Proxy-Overhead gegen klare Zielwerte — offline (deterministisch, ohne Modell) oder gegen echte lokale Modelle.
• Zum Beobachten gebaut. Ein Event-Bus streamt die Live-Aktivität über Server-Sent-Events in eine Web-UI: ein /ui-Dashboard für Sessions, Segmente und extrahierte Graph-Tripel und ein /ui/flow-Flowchart, in dem jeder Architektur-Knoten aufleuchtet, während seine Komponente arbeitet (inklusive Hintergrund-Sub-Agenten).
• Dokumentiert, während entschieden wurde. Vierzehn Architecture Decision Records, ein PAD-Design-Dokument und ein Eval-Report halten fest, warum jede Entscheidung fiel — die Spur, mit der jemand anderes das System übernehmen kann.

Das Ergebnis

• Ein funktionierender Proxy mit umgesetzten Meilensteinen M1–M5 (Gateway, Session-Tracking, Swap-out, Swap-in v1, Eval-Harness), selbst-gehostet und im produktiven Betrieb auf dem eigenen Rechner des Betreibers als Dauerläufer-systemd-Service, der lokale Modelle (gemma / qwen) über Ollama ansteuert.
• Gemessen, nicht behauptet: im Offline-Mechanik-Eval 100 % Recall der verankerten Fakten, Proxy-Overhead im einstelligen Millisekunden-Bereich (~1 ms, weit unter dem 100-ms-Ziel) und rund 9× weniger Kontext an das Upstream-Modell bei der geprüften letzten Frage. Die Kompressions-Ratio lag bei ~4,4:1 gegenüber einem 5:1-Ziel — eine echte Zahl, ehrlich berichtet, nicht aufgerundet.
• 73 Tests grün, komplett offline gegen ein deterministisches Fake-Modell gefahren, sodass die Mechanik ohne ein einziges Token verifiziert wird.
• Ein live beobachtbares System: Echtzeit-Flowchart und Ereignisprotokoll machen eine sonst unsichtbare Pipeline leicht vorführ- und debugbar.
• Bereitgestellt „as-is"; der Zugang ist derzeit für den Betreiber selbst-gehostet (über ein privates Netz erreichbar), eine passwort-geschützte öffentliche Route ist vorbereitet, aber noch nicht scharfgeschaltet.

Was das zeigt

• Verantwortung für ein nicht-triviales Infrastruktur-Problem von A bis Z: protokoll-kompatibles Gateway, Kompressions-Pipeline, ein semantischer Speicher aus Graph- und Vektor-Suche, Retrieval, eine Eval-Harness, eine Web-UI und selbst-gehostetes Deployment.
• Sicherheit bei echter LLM-Systemarbeit — Kontext-Management, Provider-Abstraktion, Retrieval-Qualität, Hintergrund-Sub-Agenten — statt eines dünnen Wrappers um eine API.
• Messen zuerst: klare Zielwerte, eine automatisierte Harness und eine ehrliche Berichterstattung darüber, was bestanden wurde und was nicht.
• Infrastruktur lesbar machen — Entscheidungs-Records, ein Design-Dokument und ein Live-Flowchart, das internes Verhalten sichtbar macht.
• Moderne, KI-gestützte Umsetzung, vom Menschen gesteuert und kuratiert — die aus Jan Häusles ursprünglichem Konzept ein laufendes System gemacht hat.

Technik auf einen Blick

Python 3.11+ · FastAPI / Uvicorn · OpenAI-kompatibles Gateway · LiteLLM · SQLite (Graph-Tripel + Vektoren) · Vektor-Embeddings · Server-Sent Events · Ollama (lokal gemma / qwen) · systemd · pytest (73 Tests)

---