Beginners |

CogniVault Backend erklärt, Teil 1 · Das Backend kennenlernen: Drei Prozesse, vier Schichten

Fri, 12 Jun 2026 00:00:00 +0000

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

Wenn Leute das erste Mal das CogniVault-Repository öffnen, höre ich meistens eine Variante der Frage: “Wo fange ich überhaupt an?” Da gibt es einen RAG-Agenten, einen FAISS-Index, einen DBOS-Workflow, einen Ollama-Host — und wenn du gerade erst in die Tech-Welt einsteigst, ist jedes dieser Wörter wie eine verschlossene Tür.

Diese Serie öffnet die Türen, eine nach der anderen. Kein RAG-Vorwissen vorausgesetzt, jede Abkürzung wird ausgeschrieben und jede Behauptung lässt sich im nachprüfen. Falls du meine schon gelesen hast, betrachte diese Serie als die Führung, die eigentlich hätte zuerst kommen sollen.

Lass uns das mal aufzeichnen.

Die ganze App besteht aus drei Prozessen

Mit CogniVault kannst du mit deinen eigenen Dokumenten chatten und sie in Quizzes, Workshops, Karteikarten und Mindmaps verwandeln — und dabei verlässt absolut nichts jemals deinen Rechner. (Das Warum hinter dieser Einschränkung ist eine eigene Geschichte: .)

Man könnte erwarten, dass so eine App ein Wildwuchs an Microservices ist. Aber es sind genau drei Prozesse:

Prozess	Was er macht
Das Python-Backend	Eine FastAPI-App auf Port 8000 — sie serviert auch das kompilierte React-Frontend als statische Dateien
Ollama	Der lokale Model-Server auf Port 11434, auf dem die KI-Modelle laufen
PostgreSQL	Ein Docker-Container, der nur für Workflow-Checkpoints genutzt wird — niemals für deine Dokumente

Alles andere — deine Dateien, der Suchindex, dein Chatverlauf, deine Quiz-Ergebnisse — ist einfach eine Datei auf der Festplatte. Das ist keine Faulheit; das ist das Privatsphäre-Argument physisch umgesetzt. Du kannst jedes Byte, das die App speichert, mit einem Texteditor und einem SQLite-Browser öffnen.

Die vier Schichten

Bevor wir Technologien beim Namen nennen, hier das mentale Modell, das du für die ganze Serie im Kopf behalten solltest. Das Backend besteht von oben nach unten aus vier Schichten:

Schicht 1 — die Web-Schicht. Eine FastAPI-Anwendung nimmt jeden HTTP-Request entgegen und routet ihn an einen von sechs Routern: Chat (/rag), Wissensmanagement (/upload, /ingest), Lerntools (/api/study/*), Fortschritt (/api/progress/*), Sprache (/api/transcribe) und Chatverlauf (/api/history). FastAPI (ein modernes Python-Web-Framework) generiert unter /api/docs zudem automatisch eine interaktive API-Dokumentation, was der beste Weg ist, um das Backend zu erkunden, ohne eine Zeile Code lesen zu müssen.

Schicht 2 — die Intelligenz-Schicht. Zwei KI-Modelle mit zwei verschiedenen Jobs. gemma4:e4b generiert: Chat-Antworten, Gedankengänge (Reasoning), Bildanalyse und Tool-Aufrufe. embeddinggemma erstellt Embeddings: Es verwandelt Text in Vektoren (Zahlenlisten, die Bedeutung einfangen), sodass ähnliche Ideen mathematisch gefunden werden können. Beide laufen innerhalb von Ollama — stell dir Ollama wie Docker vor, aber für KI-Modelle.

Schicht 3 — die Retrieval-Schicht. Eine Suchmaschine über deine Dokumente, die semantische Suche (finde Dinge mit gleicher Bedeutung) mit Keyword-Suche (finde exakte Zeichenketten) kombiniert. Teil 3 dieser Serie dreht sich komplett um diese Schicht.

Schicht 4 — die Persistenz-Schicht. Vier Speichersysteme, jedes für einen speziellen Job ausgewählt: ein FAISS-Index plus einer JSON-Datei für durchsuchbares Wissen, SQLite für Lerndaten, PostgreSQL für Workflow-Checkpoints und einfache JSON-Dateien für den Chatverlauf.

Ein Diagramm, alle wichtigen Teile

flowchart TB subgraph CLIENT["Browser"] UI["React Frontend
(kompiliert, serviert von FastAPI)"] end subgraph SERVER["FastAPI Backend — Port 8000"] ROUTERS["6 Router
rag · knowledge · study ·
progress · audio · history"] AGENT["RAG Agent
(Strands SDK, 6 Tools)"] VDB["VectorDB
FAISS + BM25 + RRF"] INGEST["Ingestion
(DBOS dauerhafter Workflow)"] GEN["Study Generatoren
quiz · workshop · cards · mindmap"] PROG["Fortschrittstracker
+ 25 Achievements"] end subgraph OLLAMA["Ollama — Port 11434"] GEMMA["gemma4:e4b
chat · thinking · vision · tools"] EMBED["embeddinggemma
Text zu Vektoren"] end subgraph STORAGE["Lokaler Speicher"] FAISSF["vector_store.faiss + .json"] SQLITE["progress.db (SQLite)"] PG["PostgreSQL
nur Workflow-Status"] DOCS["docs/ Ordner + chat_history.json"] end UI --> ROUTERS ROUTERS --> AGENT --> VDB AGENT --> GEMMA VDB --> EMBED ROUTERS --> INGEST --> EMBED INGEST --> PG INGEST --> FAISSF VDB --- FAISSF ROUTERS --> GEN --> GEMMA GEN --> SQLITE ROUTERS --> PROG --> SQLITE ROUTERS --> DOCS

Behalte dieses Bild im Hinterkopf — die Teile 2, 3 und 4 zoomen jeweils in einen Bereich davon hinein.

Der Tech-Stack und warum jedes Teil seinen Platz verdient hat

Die komplette Liste der Abhängigkeiten (Dependencies) lebt in der requirements.txt. Hier ist das, was wichtig ist, gruppiert nach Aufgabe:

Requests bearbeiten. FastAPI definiert die Endpoints und validiert jeden Request und jede Response mit Pydantic (einer Datenvalidierungs-Bibliothek — stell es dir wie einen strengen Zollbeamten für JSON vor). Uvicorn ist der ASGI-Server (Asynchronous Server Gateway Interface — der Python-Standard, der es einem Prozess erlaubt, viele gleichzeitige Requests zu jonglieren), der das Ganze am Ende ausführt.

Denken. Ollama hostet gemma4:e4b — das e4b-Tag steht für die Variante mit rund vier Milliarden effektiven Parametern, was ungefähr einem 9,6 GB Download entspricht — und embeddinggemma (ca. 622 MB). Das Agentenverhalten wird mit dem Strands Agents SDK gebaut, welches das Modell in einen Loop (Schleife) verpackt, in dem es Tools aufrufen, die Ergebnisse lesen und erst danach antworten kann. (Wo ich Ollama in Relation zu Docker laufen lasse, ist eine bewusste Entscheidung mit eigener Hintergrundgeschichte: .)

Dinge finden. FAISS (Facebook AI Similarity Search — Metas Vektorsuch-Bibliothek) kümmert sich um semantische Lookups; rank-bm25 kümmert sich um Keyword-Lookups; eine Formel namens Reciprocal Rank Fusion vereint die beiden. Teil 3 packt all das genauer aus.

Dokumente lesen. pypdf für PDFs, mit einem OCR-Fallback (Optical Character Recognition — verwandelt Bilder von Text in echten Text) für gescannte Seiten via pymupdf und Tesseract. Word, PowerPoint und Excel bekommen jeweils ihren eigenen Extractor. trafilatura zieht sauberen Artikeltext aus Webseiten.

Keine Arbeit verlieren. DBOS macht die Ingestion-Pipeline dauerhaft (durable) — jeder Schritt bekommt einen Checkpoint in PostgreSQL, sodass bei einem Absturz fortgesetzt statt von vorn begonnen wird. Teil 2 zeigt das in Aktion.

Sich erinnern. SQLite — eine vollwertige Datenbank-Engine, die in einer einzigen Datei namens progress.db lebt — hält deine Lernsitzungen, Errungenschaften (Achievements), Quizzes, Workshops, Karteikartendecks und Mindmaps fest.

Anhang: Abkürzungen in diesem Post

Das Versprechen dieser Serie ist “keine unerklärten Abkürzungen”, also ist hier die Tabelle, von der ich wünschte, sie wäre in jedem technischen Tutorial dabei.

Abkürzung	Volle Form	Bedeutung in einfachem Deutsch
LLM	Large Language Model	Ein neuronales Netz, das mit massenhaft Text trainiert wurde und Sprache lesen und generieren kann
RAG	Retrieval-Augmented Generation	Hole erst relevante Passagen aus deinen Dokumenten und lass das Modell daraus antworten — statt aus seinem Trainingsgedächtnis
API	Application Programming Interface	Die Menge an URLs, die das Frontend aufruft, um mit dem Backend zu sprechen
ASGI	Asynchronous Server Gateway Interface	Der Python-Standard, der es dem Server erlaubt, viele Anfragen gleichzeitig zu bearbeiten
JSON	JavaScript Object Notation	Das universelle Textformat für strukturierte Daten
NDJSON	Newline-Delimited JSON	Ein Stream, bei dem jede Zeile ein eigenes JSON-Objekt ist — ideal, um KI-Antworten Stück für Stück (Chunk für Chunk) zu streamen
FAISS	Facebook AI Similarity Search	Metas Bibliothek, um Vektoren zu speichern und die ähnlichsten schnell zu finden
BM25	Best Match 25	Eine klassische Keyword-Ranking-Formel — die 25. Ranking-Funktion, die im Okapi Information-Retrieval-System entwickelt wurde
RRF	Reciprocal Rank Fusion	Eine Formel zum Zusammenführen mehrerer gerankter Ergebnislisten, die nur die Ränge benutzt
ANN	Approximate Nearest Neighbour	Eine Geschwindigkeits-Abkürzung, die viele Vektordatenbanken nehmen. CogniVault nutzt stattdessen bewusst einen exakten Index — präzise und für eine persönliche Bibliothek völlig schnell genug
DBOS	Database-Oriented Operating System (das Forschungsprojekt, aus dem es entstand)	Eine Bibliothek, die Workflow-Schritte in einer Datenbank zwischenspeichert, sodass abgestürzte Jobs fortgesetzt werden können
SQL / SQLite	Structured Query Language / SQLite	Die Sprache von relationalen Datenbanken / eine winzige Datenbank, die in einer Datei lebt
OCR	Optical Character Recognition	Verwandelt Bilder von Text (Scans) in maschinenlesbaren Text
SHA-256	Secure Hash Algorithm, 256-bit	Eine Fingerabdruck-Funktion — jede Datei wird auf einen eindeutigen Hash abgebildet, genutzt um geänderte Dateien zu erkennen
CORS	Cross-Origin Resource Sharing	Browser-Regeln, die kontrollieren, welche Websites die API aufrufen dürfen
SSRF	Server-Side Request Forgery	Ein Angriff, bei dem ein Server ausgetrickst wird, interne URLs abzurufen — der URL-Import Endpoint schützt davor
MCQ	Multiple-Choice Question	Einer der beiden Quizfragen-Typen
KB	Knowledge Base	All deine eingelesenen, durchsuchbaren Dokumente

(Jede Behauptung in dieser Serie kann direkt im überprüft werden — die relevante Datei wird immer genannt, wenn es wichtig ist, und die Repository-README skizziert die komplette Architektur.)

Fazit

Nimm die Abkürzungen weg, und CogniVault ist ein kleines System: ein Webserver, eine Modell-Laufzeitumgebung, eine Haltbarkeits-Datenbank (Durability Database) und eine Handvoll Dateien. Die Raffinesse liegt nicht in der Anzahl der Teile — sie liegt darin, wie ein paar gut gewählte Teile zusammenarbeiten. Von dieser Zusammenarbeit handeln die nächsten drei Teile.

Als Nächstes: — wie ein 1.000-seitiges gescanntes PDF zu etwas wird, das die KI in Sekunden durchsuchen kann, und warum die Pipeline einen Absturz bei Seite 800 überlebt.

CogniVault Backend erklärt, Teil 2 · Von der Datei zum durchsuchbaren Wissen

Fri, 12 Jun 2026 00:00:00 +0000

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

Ein LLM kann dein PDF nicht “öffnen”. Dieser Satz überrascht viele Neulinge, also lass uns das kurz sacken lassen: Wenn du in CogniVault mit deinen Dokumenten chattest, fasst das Modell die Originaldateien nie an. Es muss etwas zwischen “Ich habe eine Datei in den Browser gezogen” und “Die KI hat mir gerade Seite 47 zitiert” passieren.

Dieses Etwas nennt man Ingestion (Datenaufnahme), und darum geht es in diesem Teil. In haben wir das große Ganze skizziert; heute zoomen wir in einen bestimmten Bereich – das Fließband, das Dateien in durchsuchbares Wissen verwandelt.

Das Fließband

Stell dir die Ingestion wie ein Fließband mit vier Stationen vor:

Extrahieren: Den Text aus jeder Datei herausholen – auch aus gescannten.
Chunken (Zerlegen): Den Text in Stücke zerschneiden, die klein genug sind, um in einen Prompt zu passen.
Embedden (Einbetten): Jeden Chunk in einen Vektor (eine Liste von Zahlen, die seine Bedeutung einfängt) verwandeln, damit ähnliche Ideen im Vektorraum nah beieinander landen.
Speichern: Vektoren und Metadaten so ablegen, dass sie später durchsucht werden können.

flowchart TD A["Upload
POST /upload
gespeichert in docs/"] --> B subgraph WF["DBOS dauerhafter Workflow"] B["Schritt 1
Welche Dateien haben sich geändert?
SHA-256 Fingerabdrücke"] --> C["Schritt 2
Text extrahieren
pro Format + OCR-Fallback"] C --> D["Chunking
1000 Zeichen, 100 Überlappung"] D --> E["Schritt 3
Embedden
embeddinggemma, 5er-Batches"] E --> F["Schritt 4
Speichern
FAISS Index + Metadaten JSON"] end F --> G["In-Memory Index neu laden
sofort durchsuchbar"]

Ziemlich simpel. Die spannende Ingenieursarbeit steckt in den Fehlerfällen – fangen wir also damit an.

Das Kassenbuch der Fabrik: Warum die Pipeline keine Arbeit verlieren darf

Das Embedden einer großen Bibliothek dauert Minuten. Was passiert, wenn dein Laptop bei Seite 800 eines 1.000-seitigen Handbuchs in den Ruhezustand geht? Bei einem einfachen Python-Skript fängt alles wieder bei Seite 1 an.

CogniVault schreibt die Pipeline stattdessen als einen dauerhaften DBOS-Workflow. Stell dir eine Fabrik vor, in der jede Station einen dauerhaften Stempel in ein Kassenbuch drückt, sobald sie eine Kiste fertiggestellt hat. Fällt der Strom aus, baut niemand fertige Kisten neu zusammen – die Arbeiter lesen das Buch und machen beim ersten ungestempelten Eintrag weiter.

DBOS ist dieses Buch, und PostgreSQL ist das Papier, auf dem es geschrieben steht. Jede Station der Pipeline ist ein mit Checkpoints versehener Schritt; nach einem Neustart liefern abgeschlossene Schritte sofort ihre aufgezeichneten Ergebnisse zurück und die Ausführung geht beim ersten unfertigen Schritt weiter. Ein fehlgeschlagener Embedding-Batch wird einfach nochmal probiert.

Das ist auch der Mechanismus hinter der Live-Fortschrittsanzeige in der UI: Der Start einer Ingestion liefert eine workflow_id zurück, und das Frontend fragt regelmäßig einen Status-Endpoint ab, der meldet, welche Schritte abgeschlossen sind, welche laufen und welche noch warten.

Ich habe einen ausführlichen Deep-Dive über diesen Mechanismus geschrieben – inklusive dessen, was passiert, wenn du den Prozess mitten in der Ingestion mit kill -9 beendest – in .

Fingerabdrücke, kein Blindflug: SHA-256 Änderungserkennung

Deine komplette Bibliothek jedes Mal neu zu embedden, wenn du eine einzige Datei hinzufügst, wäre Verschwendung. Bevor also irgendwelche Arbeit passiert, berechnet die Pipeline für jede Datei einen SHA-256 Hash (einen Inhalts-Fingerabdruck – ändere ein Zeichen in der Datei, und der Fingerabdruck ändert sich komplett) und vergleicht ihn mit dem Fingerabdruck, der bei den vorhandenen Chunks der Datei gespeichert ist:

Noch nie gesehen → einlesen (ingest).
Fingerabdruck hat sich geändert → die alten Chunks werden soft-gelöscht und die Datei wird neu eingelesen.
Fingerabdruck identisch → komplett überspringen.

Warum “soft”-gelöscht? Weil der FAISS-Indextyp, den CogniVault nutzt, keine einzelnen Vektoren entfernen kann. Veraltete Chunks werden in den Metadaten einfach als deleted: true markiert; ihre Vektoren bleiben im Index, aber jede Suche filtert sie heraus. Das ist eine ehrliche, langweilige Lösung – und sie korrumpiert niemals den Index.

Jedes Format kriegt eine Sonderbehandlung

Hier ist ein Detail, das eine Demo von einem Produkt unterscheidet. Eine naive Pipeline extrahiert einfach “den ganzen Text” und macht dann Feierabend. Bei CogniVault bekommt jedes Format einen Extractor, der genau die Struktur beibehält, die das Retrieval später braucht:

Format	Strategie
PDF	Seite für Seite, wobei die Seitenzahlen behalten werden (diese werden später zu Quellenangaben). Jede Seite mit weniger als 50 Zeichen gilt als gescannt und wird an die OCR geschickt
Gescannte Seite	Die Seite wird mit etwa 144 dpi als Bild gerendert, dann extrahiert Tesseract OCR (Optical Character Recognition – Text aus Bildern auslesen) die Wörter
Markdown	Wird an Überschriften aufgeteilt; jeder Abschnitts-Chunk bekommt einen Breadcrumb-Präfix wie `[Section: Intro > Setup]`, damit sein Embedding die Dokumentenhierarchie in sich trägt
CSV	Zeilen werden in 20er-Gruppen gechunkt – und jeder Chunk bekommt die Kopfzeile vorangestellt, sodass das Modell immer die Spaltennamen kennt
Excel	Gleiches Zeilen-Gruppen-Prinzip pro Arbeitsblatt, mit dem Präfix `[Sheet: name]`
PowerPoint	Ein Chunk pro Folie
Word	Absätze plus Tabellenzellen
Webseiten	Werden bei Bedarf abgerufen und auf sauberen Artikeltext reduziert – geschützt durch einen SSRF-Guard (Schutz vor Server-Side Request Forgery: der Server weigert sich, private oder interne Adressen abzurufen)

Frag dich mal, warum das CSV-Detail wichtig ist. Wenn Chunk 14 eines Spreadsheets einfach nur zwanzig nackte Zahlenreihen enthält, wird keine Suche ihn jemals mit der Frage “Wie hoch war das Q3-Budget?” in Verbindung bringen. Stellst du die Kopfzeile voran, weiß der Chunk, dass er Budget-Spalten enthält. Struktur ist der Treibstoff fürs Retrieval.

Chunking: 1.000 Zeichen mit 100 Zeichen Sicherheitsnetz (Überlappung)

Lange Texte werden in Stücke von etwa 1.000 Zeichen zerlegt, wobei sich benachbarte Stücke um 100 Zeichen überlappen. Diese Überlappung ist eine Versicherung: Ein Satz, der genau an der Chunk-Grenze zerschnitten wird, taucht in einem der beiden Nachbarn immer noch als Ganzes auf, sodass keine Idee in die Lücke zwischen den Chunks fällt.

Embedden und Speichern

Chunks werden von embeddinggemma (via Ollama) in 5er-Batches embedded – jeder Chunk wird zu einem Vektor. Die Vektoren werden normalisiert und an einen FAISS-Index angehängt; daneben hält eine JSON-Datei für jeden Chunk den Quelldateinamen, die Seitenzahl, die Kategorie, den Fingerabdruck und den eigentlichen Text fest. Der Index speichert die Zahlen; das JSON speichert die Bedeutung.

Eine Designentscheidung, die man für Anfänger hervorheben sollte: Das hier ist ein exakter Index, kein approximativer. Viele Vektor-Datenbanken nutzen ANN (Approximate Nearest Neighbour)-Abkürzungen, die bei riesiger Skalierung ein wenig Genauigkeit gegen Geschwindigkeit tauschen. Im Maßstab einer persönlichen Bibliothek brauchst du diesen Kompromiss nicht – CogniVault prüft jeden Vektor bei jeder Suche und ist trotzdem schnell.

Die gesamte Reise, von Anfang bis Ende

%%{init: {'sequence': {'actorFontSize': 28, 'messageFontSize': 24, 'loopTextFontSize': 22, 'noteFontSize': 22}}}%% sequenceDiagram actor U as Du participant F as Frontend participant B as FastAPI participant W as DBOS Workflow participant O as Ollama (embeddinggemma) participant V as FAISS + Metadaten U->>F: Drag and Drop einer Datei, Kategorie wählen F->>B: POST /upload B->>B: Typ und Größe validieren, in docs/ speichern F->>B: POST /ingest B->>W: Dauerhaften Workflow starten B-->>F: workflow_id loop Status abfragen F->>B: GET /ingest/status/{workflow_id} B-->>F: Schrittliste (steuert die Fortschrittsanzeige) end W->>W: SHA-256 Änderungserkennung W->>W: Text extrahieren (pro Format, OCR falls gescannt) W->>W: Chunking (1000 Zeichen / 100 Überlappung) W->>O: Embedden in 5er-Batches O-->>W: Vektoren W->>V: Vektoren + Metadaten anhängen B-->>F: SUCCESS — Index neu geladen F-->>U: "Wissens-Sync abgeschlossen"

Fazit

Bei der Ingestion entscheidet sich meistens die eigentliche RAG-Qualität – lange bevor irgendwelches clevere Prompting ins Spiel kommt. Beibehaltene Seitenzahlen, Header, die in jeden Spreadsheet-Chunk kopiert werden, gerettete Scans durch OCR, und ein Kassenbuch, das das Ganze absturzsicher macht: Nichts davon ist glamourös, aber alles davon zeigt sich später in Form von Antworten, die die richtige Seite zitieren.

Anhang: Abkürzungen in diesem Post

Abkürzung	Volle Form	Bedeutung
LLM	Large Language Model	Ein neuronales Netz, trainiert mit riesigen Textmengen, das Sprache lesen und erzeugen kann
DBOS	Database-Oriented Operating System	Die Bibliothek, die Workflow-Schritte in PostgreSQL sichert, damit abgestürzte Jobs fortgesetzt werden können
SHA-256	Secure Hash Algorithm, 256-bit	Ein Inhalts-Fingerabdruck – ändere ein Byte einer Datei und der Hash ändert sich komplett
OCR	Optical Character Recognition	Text aus Bildern lesen – der Rettungsweg für gescannte PDF-Seiten
SSRF	Server-Side Request Forgery	Ein Angriff, bei dem ein Server ausgetrickst wird, interne URLs abzurufen; der URL-Importer blockiert dies
FAISS	Facebook AI Similarity Search	Der Vektor-Index, an den die Embeddings angehängt werden
ANN	Approximate Nearest Neighbour	Die Genauigkeit-gegen-Geschwindigkeit-Abkürzung, die CogniVault absichtlich nicht nimmt
dpi	Dots Per Inch	Bildauflösung – gescannte Seiten werden vor der OCR mit ca. 144 dpi gerendert
JSON	JavaScript Object Notation	Das Format der Chunk-Metadaten-Datei neben dem FAISS-Index
PDF / CSV	Portable Document Format / Comma-Separated Values	Zwei der acht+ unterstützten Dateiformate
API	Application Programming Interface	Die Endpoints (`/upload`, `/ingest`, `/ingest/status/…`), die den Ablauf steuern

Als Nächstes: — hybrides Retrieval, der 6-Tools-Agent und der 2-Phasen-Stream, der zeigt, wie das Modell denkt, bevor es antwortet.

CogniVault Backend erklärt, Teil 3 · Wie aus einer Frage eine belegte Antwort wird

Fri, 12 Jun 2026 00:00:00 +0000

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

Du tippst eine Frage ein. Ein paar Sekunden später bekommst du eine Antwort mit Fußnoten — genaue Angabe der Dokumente und Seiten, aus denen sie stammt. Dieser Teil geht alles durch, was dazwischen passiert.

In haben wir die Wissensbasis aufgebaut: jedes Dokument gechunkt, embedded und indiziert. Jetzt fangen wir an, sie zu nutzen — und hier hört CogniVault auf, nur eine Pipeline zu sein, und fängt an, spannend zu werden.

Zwei Bibliothekare, weil einer dich immer wieder hängen lässt

Stell dir eine Bibliothek vor mit einer Bibliothekarin, die alles nach Vibes ordnet. Frag sie nach “Prozeduren bei Server-Ausfall” und sie ist genial — sie versteht, was du meinst, und findet Dokumente, die das Konzept diskutieren, egal welche Wörter sie benutzen. Aber frag sie nach “Fehlercode 404B”, zuckt sie mit den Schultern und reicht dir allgemeine Netzwerk-Guides. Mit exakten Zeichenketten kann sie nichts anfangen.

Am Ende des Flurs sitzt ein zweiter Bibliothekar mit einem Zettelkasten. Er findet den genauen String “404B” sofort — aber stell ihm eine konzeptionelle Frage, die anders formuliert ist als im Quelltext, und er findet überhaupt nichts.

Das sind die zwei Hälften der Suche:

Semantische Suche (FAISS) — deine Frage wird in einen Vektor umgewandelt (embedded), und der Index findet Chunks, deren Vektoren in die gleiche Richtung zeigen (technisch gesehen: Cosinus-Ähnlichkeit — wie gut zwei Pfeile übereinstimmen). Super für die Bedeutung, blind für exakte Identifikatoren.
Keyword-Suche (BM25) — eine Bewertungsformel (Scoring), die Chunks belohnt, die deine exakten Wörter enthalten, gewichtet danach, wie markant diese Wörter sind. Super für Identifikatoren, blind für Synonyme.

CogniVault fragt jedes Mal beide Bibliothekare, und verschmilzt dann ihre Antworten mit Reciprocal Rank Fusion (RRF) — einer Formel, die gerankte Listen kombiniert, indem sie nur die Positionen nutzt:

score(chunk) = summe aus beiden Listen von 1 / (60 + rang)

Ein Chunk, der von einem der beiden Bibliothekare hoch gerankt wird, punktet gut; ein Chunk, den beide gut fanden, schwimmt ganz nach oben. Die Eleganz liegt darin, was fehlt: Du musst niemals die Ähnlichkeits-Scores von FAISS mit der komplett anderen Skala von BM25 abgleichen, weil Ränge (Ranks) der einzige Input sind. Die Konstante 60 stammt direkt aus dem ursprünglichen Research-Paper von 2009, und ja, sie ist auch im Code zitiert.

Ein paar Implementierungsdetails, die du kennen solltest: Beide Suchen holen absichtlich zu viel (mindestens 20 Kandidaten jeweils), damit die Fusion Material zum Arbeiten hat; sehr schwache semantische Treffer werden fallengelassen, aber ein perfekt auf Keywords passender Chunk kann durch die Fusion trotzdem noch gerettet werden; und die finale Antwort nutzt die Top-7-Chunks. Ich habe dieses ganze Setup in gegen eine reine Vektorsuche gebenchmarkt, falls du die Kriegsgeschichten dazu lesen willst.

Der Agent: Ein Modell, das selbst entscheidet

Hier ist der zweite Punkt, der Anfänger oft ins Straucheln bringt: Der Chat von CogniVault ist nicht einfach “Kopiere Chunks in einen Prompt, bekomme eine Antwort.” Es ist ein Agent — ein Modell, das in einer Schleife läuft, in der es sich entscheiden kann, Tools aufzurufen, deren Ergebnisse zu lesen und erst dann zu antworten.

Gebaut mit dem Strands Agents SDK, bekommt der Agent sechs Tools:

Tool	Aufgabe
`search_knowledge_base`	Das Kern-RAG-Tool — führt die hybride Suche von oben aus, liefert Chunks mit Quelle und Seite zurück
`list_documents`	Nachschauen, was im Vault (Tresor) liegt
`analyze_document`	Strukturierte Analyse eines Dokuments: Themen, Entitäten, Fakten, Zusammenfassung
`compare_documents`	Beantwortung einer Frage durch den direkten Vergleich von zwei Dokumenten
`calculator`	Sicheres Rechnen — der Ausdruck wird in einen Syntaxbaum (AST) geparst und nur erlaubte Operatoren werden ausgeführt. Niemals `eval()`
`current_time`	Datum und Uhrzeit

Es gibt hier kein fest programmiertes Routing. Das Modell liest deine Frage und entscheidet, welche Tools es aufruft, geleitet von seinem System-Prompt. Fragst du “Vergleiche die zwei Verträge hinsichtlich der Kündigungsklauseln”, greift es zum compare_documents; fragst du “Was sind 15% von 2.340”, nutzt es den Taschenrechner, anstatt Mathematik zu halluzinieren.

Zwei Sicherheitsdetails, auf die Anfänger achten sollten, weil sie den Unterschied zwischen einem Spielzeug und einem Produkt ausmachen: Für jeden Request wird ein frischer Agent gebaut (kein geteilter State, der zwischen parallelen Chats überspricht), und die Dokumentenanalyse-Tools rufen das Modell direkt auf statt über den Agenten — sonst könnte ein Agent, der ein Tool aufruft, das wiederum den Agenten aufruft, in einer Endlosschleife feststecken.

Dem Modell beim Denken zusehen

Wenn du eine Nachricht absendest, streamt die Antwort als NDJSON (Newline-Delimited JSON — jede Zeile des Streams ist ein eigenes kleines JSON-Objekt). Und das passiert in zwei Phasen:

Phase 1 — Denken. Gemmas Argumentationskette (Reasoning Chain) streamt zuerst und wird im aufklappbaren Panel über der Antwort gerendert. Es ist absichtlich so gebaut, dass es nicht zwingend klappen muss (Best-Effort): Falls es aus irgendeinem Grund fehlschlägt, kommt die Antwort trotzdem.

Phase 2 — Die Agenten-Antwort. Tools laufen, Zitate (Quellenangaben) tauchen im Quellen-Panel auf, sobald die Suche abgeschlossen ist — bevor die Antwort fertig geschrieben ist — und der Antworttext streamt herein.

flowchart TB Q["Deine Frage
(plus optionale Bilder, Dateien, Scope)"] --> P1 subgraph STREAM["POST /rag — ein NDJSON-Stream"] P1["Phase 1: Denken
Reasoning-Chunks streamen zuerst"] P1 --> P2["Phase 2: Agent
frisch pro Request, Historie wiederhergestellt"] P2 -->|"entscheidet sich aufzurufen"| T["search_knowledge_base"] T --> D["FAISS
semantisch"] T --> S["BM25
Keywords"] D --> RRF["RRF Fusion — Top 7 Chunks"] S --> RRF RRF -->|"Chunks + Quellenangaben"| P2 P2 --> OUT["Quellenangaben, dann Antworttext,
dann ein Speicher-Nutzungs-Report"] end

Jede Zeile im Stream ist typisiert: thinking, metadata (eine Quelle/Zitat), text (Antwort), memory (wie voll das Konversations-Budget ist) oder error. Das Frontend liest einfach die Zeilen und leitet sie in das richtige Panel weiter. Ich habe dieses Design zerlegt — und erklärt, warum das Denken vor den Tool-Aufrufen kommt — in .

Ein Speicher-Budget, kein fassloses Loch

Gemmas Context Window (die Textmenge, die das Modell auf einmal betrachten kann) beträgt 128K Token, aber CogniVault lässt den Chatverlauf nicht über das komplette Fenster wuchern. Jede Chat-Session bekommt ein Budget von 48.000 Zeichen — grob 12.000 Token. Überschreitest du es, fällt das älteste Frage-Antwort-Paar leise als erstes heraus. So bleibt der Großteil des Fensters frei für das, was wirklich zählt: deine aktuelle Frage und die abgerufenen Chunks.

Zwei Resilienz-Tricks, die du für deine eigenen Projekte klauen solltest:

Reboots überleben. In-Memory-Verlauf stirbt mit dem Prozess. Deshalb baut die erste Nachricht in einer Session nach einem Backend-Neustart ihren Verlauf aus dem Chat-Log wieder auf, den das Frontend persistiert hat. Multi-Turn-Gedächtnis überlebt Neustarts.
Bearbeiten und neu generieren. Wenn du eine frühere Nachricht bearbeitest, wird der gespeicherte Verlauf auf genau diesen Punkt zurückgespult, bevor neu gefragt wird — das Modell vergisst buchstäblich die Zeitlinie, die jetzt nicht mehr existiert.

Scope: Die KI auf bestimmte Dokumente festnageln

Noch ein letztes Feature, und eine Lektion über kleine lokale Modelle. Du kannst einen Chat auf bestimmte Dateien oder eine Kategorie pinnen (Scope). Dieser Filter reist mit dem Request und eine zwingende Such-Anweisung wird sowohl in den System-Prompt als auch in deine eigentliche Nutzer-Nachricht injiziert.

Warum in beide? Weil kleine Modelle manchmal Anweisungen ignorieren, die nur im System-Prompt stehen — aber sie können nicht ignorieren, was direkt in der Frage steckt. Gürtel und Hosenträger. Wenn du mit 4-Milliarden-Parameter-Modellen arbeitest statt mit den größten Frontrunnern, lernst du, Anweisungen so zu platzieren, dass man sie unmöglich übersehen kann, anstatt nur zu hoffen, dass sie befolgt werden.

Fazit

Eine belegte Antwort ist das Zusammenspiel von vier Systemen: Zwei Retriever decken gegenseitig ihre blinden Flecken ab, eine Fusionsformel, die nichts weiter braucht als Ränge, ein Agent, der sich seine Tools selbst aussucht, und ein Stream, der seinen Lösungsweg offenlegt. Keines der vier ist für sich genommen exotisch — das eigentliche Produkt ist ihre Zusammenarbeit.

Anhang: Abkürzungen in diesem Post

Abkürzung	Volle Form	Bedeutung
RAG	Retrieval-Augmented Generation	Hole erst relevante Passagen aus deinen eigenen Dokumenten; lass das Modell daraus antworten
FAISS	Facebook AI Similarity Search	Die semantische (bedeutungsbasierte) Hälfte der hybriden Suche
BM25	Best Match 25	Die Keyword-Hälfte — eine klassische Ranking-Formel aus dem Okapi Information-Retrieval-System
RRF	Reciprocal Rank Fusion	Vereint die beiden gerankten Listen und nutzt dafür nur den Rang jedes Chunks: `score = Σ 1/(60 + rang)`
NDJSON	Newline-Delimited JSON	Ein Stream, bei dem jede Zeile ein eigenes komplettes JSON-Objekt ist — das Format der Chat-Antwort
JSON	JavaScript Object Notation	Das universelle Textformat für strukturierte Daten
AST	Abstract Syntax Tree	Die geparste Form eines Ausdrucks — wie der Taschenrechner rechnet, ohne `eval()` zu nutzen
LLM	Large Language Model	Ein neuronales Netz, trainiert mit riesigen Textmengen, das Sprache lesen und erzeugen kann
SDK	Software Development Kit	Eine Bibliothek von Bausteinen — hier Strands, das die Agenten-Schleife bereitstellt
K (in 128K)	Kilo (Tausend)	128K Token ≈ 128.000 Token — Gemmas Context Window

Als Nächstes: — die gleiche Maschinerie, aber ausgerichtet auf das Erstellen von Quizzes, Workshops, Karteikarten und Mindmaps, plus eine Tabelle mit jedem Byte, das die App speichert und wo genau es lebt.

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

Fri, 12 Jun 2026 00:00:00 +0000

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

In 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:

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.
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.
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 .
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.
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:

%%{init: {'sequence': {'actorFontSize': 28, 'messageFontSize': 24, 'loopTextFontSize': 22, 'noteFontSize': 22}}}%% sequenceDiagram actor U as Du participant F as Study Hub UI participant B as FastAPI participant V as VectorDB participant O as Ollama (gemma4:e4b) participant S as SQLite U->>F: Scope, Schwierigkeit, Fragenanzahl wählen F->>B: POST /api/study/quiz/generate B->>V: Hybride Suche, eingeschränkt auf deine Dokumente V-->>B: Bis zu 15 repräsentative Chunks B->>B: Render das quiz.md Prompt-Template B->>O: chat(format="json", niedrige Temperature) O-->>B: Grammatikgebundenes JSON B->>B: Jede Frage validieren, schlechte verwerfen B->>S: Quiz speichern (später fortsetzbar) B-->>F: Typisierte Antwort F-->>U: Spielen, einreichen, punkten — und vielleicht ein neues Badge

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

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: .

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:

Daten	Speicherort	Format
Deine hochgeladenen Dateien	Ordner `docs/`	Die Originaldateien
Suchvektoren	`vector_store.faiss`	FAISS Binär-Index
Chunk-Text und Metadaten	`vector_store.json`	JSON
Datei-zu-Kategorie-Zuweisung	`categories.json`	JSON
Chat-Sessions	`chat_history.json`	JSON
Sessions, Badges, Quizzes, Workshops, Decks, Mindmaps	`progress.db`	SQLite
Ingestion Checkpoints	PostgreSQL (lokales Docker-Volume)	DBOS Systemtabellen
Die KI-Modelle selbst	Ollamas lokaler Model-Store	Modell-Gewichte

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 dokumentiert.

Fazit der Serie

Vier Teile, eine Architektur:

— Drei Prozesse, vier Schichten und ein Decoder-Ring für den Jargon
— Eine dauerhafte, formatbewusste Pipeline, die jedes Dokument in durchsuchbare Vektoren verwandelt
— Zwei Retriever, die gegenseitig ihre blinden Flecken abdecken, durch Rang fusioniert und von einem Agenten gesteuert werden
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

Abkürzung	Volle Form	Bedeutung
JSON	JavaScript Object Notation	Das strukturierte Format, das die Generatoren vom Modell erzwingen
SQLite / SQL	(SQL = Structured Query Language)	Eine komplette relationale Datenbank, die in einer einzigen Datei lebt (`progress.db`)
MCQ	Multiple-Choice Question	Einer der beiden Quiz-Fragentypen (der andere ist Wahr/Falsch)
CPU	Central Processing Unit	Hier läuft Whisper — keine Grafikkarte notwendig
int8	8-bit integer (Quantisierung)	Modellgewichte als kleine Integer speichern: kleiner, schneller, genau genug
KI	Künstliche Intelligenz (AI)	Software, die Aufgaben ausführt, die normalerweise menschliche Intelligenz erfordern
API	Application Programming Interface	Die Endpunkte, die der Study Hub und das Dashboard aufrufen
FAISS	Facebook AI Similarity Search	Der Vektor-Index in der Privacy-Tabelle
DBOS	Database-Oriented Operating System	Die Durable-Workflow-Bibliothek, deren Checkpoints in PostgreSQL leben
SSRF	Server-Side Request Forgery	Die Art von Angriff, vor dem der URL-Importer schützt
PNG / PDF	Portable Network Graphics / Portable Document Format	Zwei der Export-Formate für Mindmaps (neben Markdown)
SVG	Scalable Vector Graphics	Das Zeichenformat im Browser, das hinter dem interaktiven Mindmap-Rendering steckt

Nächste Schritte: Klone 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 knüpft genau da an, wo dieser Rundgang endet.