Kaelio/ktx: eine Kontextschicht, die Agents das Abfragen von Warehouses beibringt

Welches Problem ktx adressiert und für wen es gedacht ist

Allgemeine Agents scheitern an Datenaufgaben aus einem nachvollziehbaren Grund: Sie erkunden das Warehouse bei jeder Frage neu, erfinden dabei ihre eigene Metrik-Logik und liefern Zahlen, die nicht zu den genehmigten Definitionen passen. Das README benennt genau diese drei Symptome. Klassische Semantic Layers lösen nur einen Teil davon, weil sie manuell gepflegt werden müssen und das übrige Firmenwissen nicht aufnehmen.

Die Zielgruppe ist im README eng umrissen: Teams, die Claude Code, Codex, Cursor oder OpenCode auf ihr Warehouse zeigen lassen und dabei genehmigte Metriken statt improvisierter SQL wollen. Ebenso Teams, deren Wissen über dbt, Looker, Metabase, Notion und interne Wikis verteilt liegt. Wer kein SQL-Warehouse betreibt, ist ausdrücklich nicht adressiert, denn ktx setzt auf einem solchen auf. Für eine einzelne Ad-hoc-Abfrage verweist das README selbst auf psql oder ein Notebook. Das ist eine ehrliche Abgrenzung, und sie ist wichtiger als die Funktionsliste.

Ingestion: vom Warehouse-Sample zum Wiki-Markdown und Semantic-Layer-YAML

Der Ablauf zerfällt laut den beiden Flussdiagrammen im Repository in zwei Phasen. In der Ingestion zieht die Context Engine Inhalte aus Datenbanken, BI-Tools, Modeling-Code und Dokumentation über Source-Connectors. Danach folgen drei Stufen: der Context Builder, eine Reconciliation und eine Validierung. Das Ergebnis sind zwei Artefaktformen, Wiki-Markdown und Semantic-Layer-YAML. Diese Trennung ist architektonisch relevant, weil Prosa-Wissen und strukturierte Metrik-Definitionen unterschiedlich abgefragt werden.

Innerhalb der Ingestion beschreibt das README mehrere konkrete Schritte. Tabellen werden gesampelt, Metadaten und Nutzungsmuster erfasst, joinbare Spalten erkannt und Quellen annotiert. Aus rohen Tabellen und übergeordneten Metriken entsteht ein Join-Graph, der nach Angaben des READMEs Chasm- und Fan-Traps automatisch auflöst. Agents sollen Metriken dadurch deklarativ abrufen, statt kanonisches SQL jedes Mal neu zu schreiben. Der Reconciliation-Schritt organisiert Wiki-Inhalte, entfernt Duplikate und markiert Widersprüche zur menschlichen Prüfung. Ob diese Widerspruchserkennung in der Praxis präzise genug ist, lässt sich aus dem Material nicht beurteilen; das README nennt nur, dass markiert wird, nicht wie zuverlässig.

Serving: MCP-Suche, die in lesbares SQL mündet

Die zweite Phase beginnt, wenn ein Agent eine Frage stellt. Laut dem Serving-Diagramm läuft die Anfrage über MCP. ktx durchsucht dann sowohl das Wiki als auch den Semantic Layer, und zwar kombiniert volltext- und semantisch. Zurückgegeben werden genehmigte Metriken, die anschließend in lesbares SQL kompiliert und gegen das Warehouse ausgeführt werden. Das README bezeichnet das System als read-only by design, was für den Einsatz auf Produktionsdaten der entscheidende Punkt ist: Ein Agent kann keine schreibenden Statements absetzen.

Neben MCP stellt ktx eine CLI bereit. Die Suche ist dort in zwei getrennte Befehle aufgeteilt: ktx sl durchsucht semantische Quellen, ktx wiki durchsucht lokale Wiki-Seiten. Diese Trennung spiegelt die zwei Artefaktformen aus der Ingestion wider. Wer beides gleichzeitig braucht, muss die kombinierte Suche über MCP nutzen, denn die CLI trennt sie bewusst. Das ist eine Designentscheidung mit Folgen für Skripte und Automatisierung, die im README nicht weiter begründet wird.

Installation und die ersten Befehle

Der Einstieg ist ein globales npm-Paket. Das README zeigt drei Befehle: npm install -g @kaelio/ktx, danach ktx setup und ktx status. Setup legt ein lokales Projekt an oder setzt ein bestehendes fort, konfiguriert Provider und Verbindungen, baut Kontext auf und installiert die Agent-Integration. Der Statusbefehl gibt danach unter anderem aus, ob LLM und Embeddings bereit sind, welche Modelle konfiguriert wurden (im Beispiel claude-sonnet-4-6 und text-embedding-3-small), ob Datenbanken und Kontextquellen eingerichtet sind und ob die Agent-Integration steht.

Ein wichtiger Hinweis im README betrifft den MCP-Server: Wenn ktx status eine Zeile wie ktx mcp start --project-dir ... ausgibt, muss dieser Befehl laufen, bevor der Agent-Client geöffnet wird. Wer das überspringt, bekommt keinen Kontext, sondern nur einen Agenten ohne Anbindung. Für den Kontextaufbau nach Änderungen ist ktx ingest zuständig, es baut den Kontext für jede konfigurierte Verbindung neu auf. Updates laufen über npm install -g @kaelio/ktx@latest. Für Agents gibt es zusätzlich einen Skill-Weg: npx skills add Kaelio/ktx --skill ktx, den man Claude Code, Codex, Cursor oder OpenCode aus dem Projektverzeichnis heraus ausführen lässt.

Womit ktx läuft und womit nicht

Die Liste der unterstützten Warehouses ist breit: PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, SQLite, DuckDB, Amazon Athena und MongoDB. Auf der Modellierungsseite nennt das README dbt, MetricFlow, LookML, Looker, Metabase, Sigma, Notion und Google Drive. Diese Aufzählung ist eine reine Kompatibilitätsangabe, sie sagt nichts über die Tiefe der jeweiligen Integration. Wer etwa MetricFlow bereits produktiv nutzt, sollte vor dem Umstieg klären, wie ktx vorhandene Metrik-Definitionen übernimmt, statt sie parallel neu zu erzeugen. Genau dieser Punkt entscheidet darüber, ob zwei konkurrierende Definitionsquellen entstehen.

Eine zweite Einschränkung steckt im Betriebsmodell. ktx läuft mit eigenen LLM-API-Schlüsseln oder mit einem lokalen Agent-Login, etwa einem Claude Pro/Max-Abo über Claude Code oder der lokalen Codex-Authentifizierung. Das README betont, dass ktx selbst keine zusätzliche Nutzungsabrechnung erzeugt. Die Kosten liegen also beim Modellanbieter, und die Qualität des Kontextaufbaus hängt an dem Modell, das dort konfiguriert ist. Für Teams mit strengen Vorgaben zur Datenweitergabe ist das der kritische Punkt, denn Metadaten und Wiki-Inhalte werden an ein Modell geschickt.

Wo ktx das falsche Werkzeug ist

Die klarste Grenze nennt das README selbst: ohne SQL-Warehouse funktioniert ktx nicht, weil es auf einem solchen aufsetzt. Ebenso unnötig ist es für eine einzelne Ad-hoc-Abfrage. Daraus folgt ein dritter Fall, den das Material nicht explizit nennt, der aber aus der Architektur folgt: Wer bereits einen gepflegten Semantic Layer mit genehmigten Metriken und stabiler Governance betreibt, gewinnt durch ktx vor allem den Wiki-Teil. Der Aufwand für Ingestion, Reconciliation und Validierung fällt trotzdem an.

Ein weiterer wunder Punkt ist die Widerspruchserkennung. Das README beschreibt, dass Konflikte zwischen Quellen markiert und zur menschlichen Prüfung vorgelegt werden. Das ist ehrlich, bedeutet aber auch: ktx automatisiert die Erkennung, nicht die Entscheidung. Wer erwartet, dass das System widersprüchliche Kennzahlen stillschweigend auflöst, wird enttäuscht. Die menschliche Prüfung bleibt ein wiederkehrender Aufwandsposten, und das README macht keine Angabe dazu, wie viele Konflikte typischerweise entstehen.

Alternative: dbt MetricFlow statt einer eigenen Kontextschicht

Der naheliegende Vergleich ist dbt mit MetricFlow. Beide liefern genehmigte, wiederverwendbare Metrik-Definitionen, und beide können Agents bedienen. Der Unterschied liegt im Umfang der Quellen. MetricFlow-Definitionen entstehen in dbt selbst, also im Transformationscode. Alles, was nicht in dbt steht, etwa eine Notion-Seite zur Rückerstattungsrichtlinie oder ein Metabase-Dashboard, fließt nicht ein. ktx setzt genau dort an und zieht zusätzlich BI-Tools, Modeling-Code und Dokumentation ein.

Der Preis dafür ist ein zusätzliches System im Stack. MetricFlow nutzt man ohnehin, wenn dbt im Einsatz ist; ktx ist eine weitere Komponente mit eigenem Projektverzeichnis, eigenem Setup und eigenem Ingest-Zyklus. Wer sein Wissen bereits vollständig in dbt abbildet und keine externen Quellen hat, gewinnt durch ktx wenig und trägt zusätzliche Betriebsfläche. Wer dagegen regelmäßig erklärt, was eine Metrik bedeutet und wo sie definiert ist, spart durch die zentrale Ablage.

Wartung, Upgrade und Lizenz

Das Upgrade ist bewusst einfach gehalten: npm install -g @kaelio/ktx@latest. Das README nennt keinen Migrationsschritt und keine Kompatibilitätsmatrix zwischen Versionen. Bei den veröffentlichten Releases v0.14.0, v0.15.0 und v0.16.0 im Juni und Juli 2026 lagen teils nur Tage zwischen den Sprüngen. Wer ktx produktiv einsetzt, sollte die Release Notes vor jedem Update lesen, weil der Kontextaufbau an Konfiguration und Modellwahl hängt und ein Sprung in der Minor-Version das Format der generierten Artefakte betreffen kann.

Lizenziert ist das Projekt unter Apache-2.0. Diese Lizenz erlaubt kommerzielle Nutzung, Veränderung und Weitergabe, verlangt aber die Beibehaltung der Lizenzhinweise und enthält eine ausdrückliche Patentgewährung. Für die generierten Wiki-Markdown- und Semantic-Layer-YAML-Dateien im eigenen Projektverzeichnis ist das unkritisch; sie sind eigene Inhalte. Wer den Code selbst forkt und verändert weitergibt, muss die Bedingungen der Apache-2.0 einhalten. Das ist keine Rechtsberatung, sondern nur der Hinweis, dass die Lizenzfrage bei der Weitergabe von abgeleitetem Code relevant wird, nicht bei der Nutzung der erzeugten Kontexte.

Redaktionelles Fazit

ktx ist für Teams mit SQL-Warehouse und verstreutem Firmenwissen gedacht, nicht für Einzelabfragen oder Häuser ohne Warehouse. Wer es einsetzt, sollte zuerst prüfen, ob die Reconciliation die Widersprüche zwischen den Quellen tatsächlich auflöst, ob die erzeugten Metriken den bereits genehmigten Definitionen entsprechen und ob die Lizenz (Apache-2.0) für die geplante Verteilung der generierten YAML- und Markdown-Artefakte passt.

Offizielle Quellen

1. Kaelio/ktx on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases