CogniVault Backend erklärt, Teil 4 · Study Tools, Fortschritt und die Privacy-Belege

Alle Abkürzungen werden im Anhang am Ende der Seite vollständig erklärt.

In Teil 3 haben wir eine Frage durch das hybride Retrieval und den Agenten-Loop bis hin zur zitierten Antwort verfolgt. In diesem letzten Teil wird dieselbe Maschinerie auf ein ganz anderes Ziel ausgerichtet: Dir etwas beizubringen — und dann schließen wir die Serie ab, indem wir das zentrale Versprechen des Projekts überprüfen: Nichts verlässt deinen Rechner.

Ein Rezept, vier Lerntools

CogniVault generiert Quizzes, mehrteilige Workshops, Karteikartendecks und Mindmaps aus deinen Dokumenten. Vier verschiedene Outputs — aber unter der Haube steckt ein gemeinsames Fünf-Schritte-Rezept:

1. Abrufen (Retrieve). Dieselbe hybride Suche wie aus Teil 3, aber statt deiner Frage lautet der Such-Prompt etwas Breitgefächertes wie “Schlüsselkonzepte, Definitionen, wichtige Fakten, Hauptideen”, eingeschränkt auf die von dir ausgewählten Dokumente. Bis zu 15 repräsentative Chunks kommen zurück.

2. Mit einem Template prompten. Die Anweisungen an Gemma sind nicht tief in Python vergraben — es sind editierbare Markdown-Dateien im Ordner backend/prompts/ (quiz.md, flashcards.md usw.). Legst du eine modifizierte Kopie in backend/prompts/custom/ ab, überschreibt sie die mitgelieferte Version beim allerersten Request danach. Kein Neustart, keine Code-Änderung. Prompt Engineering als reine Konfiguration.

3. Output erzwingen (Constrain). Ein kleines lokales Modell zu bitten, “bitte gib JSON zurück”, klappt in den meisten Fällen — und in den meisten Fällen bedeutet in Produktion schlichtweg einen Bug. CogniVault nutzt Ollamas grammatikgebundene Generierung (format="json"), was ungültiges JSON nicht nur unwahrscheinlich, sondern unmöglich macht, gepaart mit einer niedrigen Temperature für Konstanz. Die ganze Geschichte, wie man zuverlässige Strukturen aus einem 4-Milliarden-Parameter-Modell presst, findest du in Getting Reliable JSON Out of a Local LLM.

4. Defensiv validieren. Jedes generierte Item wird Feld für Feld gecheckt. Fehlerhafte Items werden verworfen, statt den kompletten Batch crashen zu lassen. Kleine Modelle verhauen manchmal eine von zehn Fragen; ein Produkt sollte deswegen nicht gleich zusammenbrechen.

5. Persistieren. Alles landet in SQLite. Quizzes sind später fortsetzbar, Workshop-Fortschritte überleben Neustarts und der Status von Karteikarten wird pro Deck gespeichert.

Hier ist das Rezept für ein Quiz in Aktion:

Die vier Tools unterscheiden sich nur in ihrem Template und ihrer Form: Quizzes produzieren Multiple-Choice- und Wahr/Falsch-Fragen mit Erklärungen; Workshops erstellen zuerst eine Gliederung und schreiben dann jede Lektion on demand, wenn du sie öffnest; Karteikarten liefern Vorder-/Rückseiten-Paare; Mindmaps generieren einen Themenbaum, den das Frontend als interaktives Diagramm rendert. (Dieser Renderer war übrigens sein eigenes kleines Abenteuer: Hand-Rolling an SVG Mindmap.)

Sessions, die sich selbst tracken

Die meisten Lern-Apps zwingen dich, einen Start-Button zu drücken, und die meisten Leute vergessen es. CogniVault geht da einen anderen Weg: Lernsessions werden abgeleitet, nicht manuell gestartet.

Jede Chatnachricht verlängert entweder die aktuelle Session oder — nach einer 15-minütigen Pause — startet stillschweigend eine neue. Geh einen Kaffee holen, komm zurück, mach weiter: gleiche Session. Komm morgen wieder: neue Session. Keine Buttons, kein Vergessen.

Jede Nachricht speichert außerdem ein winziges Event (Zeitstempel, ob du einen Scope-Filter oder Dateianhänge genutzt hast) in progress.db — eine SQLite-Datenbank, also eine komplette relationale Datenbank in einer einzigen Datei. Elf Tabellen halten alles fest: Sessions, Nachrichten-Events, verdiente Badges, Quiz-Versuche und gespeicherte Quizzes, Workshops und Lektionen, Decks und Karten sowie Mindmaps.

Eine kleine Engineering-Note, die sich abzugucken lohnt: Der Tracking-Call im Chat-Endpoint ist so verpackt, dass er den Chat niemals blockieren oder abbrechen kann. Analytics müssen immer Beifahrer sein, niemals der Fahrer.

25 Badges, als Daten definiert

Die Achievements sind nicht als if-Statements im Code verstreut. Sie leben in einer einzigen JSON-Datei — 25 Einträge, jeder mit Code, Name, Icon, der Metrik, die er überwacht, und einem Zielwert. Nach jeder relevanten Aktion prüft ein Evaluator jede Definition gegen die Datenbank und speichert neu verdiente Badges. Einige Badges bilden Leitern und verweisen auf das nächste Level.

Deklarativ schlägt hier imperativ aus einem einfachen Grund: Badge Nummer 26 hinzuzufügen bedeutet einen JSON-Eintrag zu ergänzen, nicht neue Logik zu schreiben. Das Design hinter den Streaks (Serien), der Pausen-Regel und der 90-Tage-Heatmap hat einen eigenen Artikel bekommen: Gamifying Learning.

Spracheingabe, ganz ohne Cloud-Mikrofon

Der Mikrofon-Button wird von faster-whisper befeuert — OpenAIs Whisper Spracherkennungsmodell, neu implementiert auf einer schnelleren Inference-Engine. Es läuft auf deiner CPU mit int8-Quantisierung (8-Bit-Zahlen statt 32-Bit: kleiner, schneller, genau genug). Kein Ton verlässt jemals deinen Rechner.

Das Modell wird erst bei der ersten Transkription geladen (Lazy Loading), damit die App sofort startet. Und wenn faster-whisper gar nicht erst installiert ist, versteckt das Frontend den Mikrofon-Button einfach. Features sollten sanft degradieren, nicht explodieren.

Die Privacy-Belege

Die Serie begann mit einem Versprechen: Nichts verlässt deinen Rechner. Versprechen sind billig — hier ist das Audit. Jedes Byte, das CogniVault speichert, und wo genau es lebt:

Nichts aus dieser Tabelle liegt auf dem Computer von jemand anderem. Inference geht an localhost. Embeddings gehen an localhost. Der einzige ausgehende Request, den das Backend jemals macht, ist der URL-Import — und das nur auf deinen ausdrücklichen Wunsch und geschützt davor, private Adressen abzurufen. Die App zeigt diese Statistiken sogar live im “Privacy Vault Audit”-Panel an.

Und weil Vertrauen mehr braucht als nur eine Tabelle: Das gesamte Backend ist von einer pytest-Suite abgedeckt, die du selbst ausführen kannst. Der Ansatz dazu ist in Testing a Local-AI App: 312 Tests, Zero Infrastructure dokumentiert.

Fazit der Serie

Vier Teile, eine Architektur:

1. Teil 1 — Drei Prozesse, vier Schichten und ein Decoder-Ring für den Jargon
2. Teil 2 — Eine dauerhafte, formatbewusste Pipeline, die jedes Dokument in durchsuchbare Vektoren verwandelt
3. Teil 3 — Zwei Retriever, die gegenseitig ihre blinden Flecken abdecken, durch Rang fusioniert und von einem Agenten gesteuert werden
4. Teil 4 — Dieselbe Maschinerie, die Lernmaterialien generiert, Fortschritt ohne Buttons trackt, und eine Speichermap ohne Cloud-Abhängigkeiten

Wenn es ein Hauptthema gibt, dann das: Langweilige, verifizierbare Entscheidungen im Dienste der Privatsphäre. Exakte Suche statt Approximation. SQLite-Dateien statt gehosteter Datenbanken. Grammatikgebundenes JSON statt hoffnungsvollem Parsen. Soft-Deletes statt cleverer Index-Eingriffe. Jedes Puzzleteil ist etwas, das du öffnen, lesen und überprüfen kannst — und genau das ist der Punkt.

Anhang: Abkürzungen in diesem Post

Nächste Schritte: Klone das Repository und lies mit — die README skizziert die komplette Architektur, und jede Behauptung in dieser Serie kann direkt mit dem Code unter backend/ abgeglichen werden. Und falls du Lust auf die Deep-Dive-Versionen dieser Themen hast: Die Architektur-Serie knüpft genau da an, wo dieser Rundgang endet.