Kaelio ktx: an executable context layer that sits between your warehouse and your coding agent

The failure mode ktx was built to interrupt

A general-purpose coding agent asked a revenue question will explore the warehouse from scratch. It lists tables, guesses which column is the amount, guesses whether refunds are netted, and writes SQL that runs but does not match the number the finance team reports. The README states this plainly: agents 're-explore your warehouse on every question, invent their own metric logic, and return numbers that don't match approved definitions.' ktx is aimed at that gap, and at a second one the README raises against traditional semantic layers, which it says 'demand constant manual upkeep and don't absorb the rest of your company's knowledge.' The target user is an analytics or data engineering team that already has approved metrics somewhere (dbt models, Looker, MetricFlow, Metabase, Sigma) and wants agents to reuse them instead of regenerating them per prompt. The README's own skip list is unusually direct: no SQL warehouse means ktx is the wrong tool, and one ad-hoc query means psql or a notebook is enough.

Two pipelines: ingestion builds the context, MCP serves it

The repository's own diagrams split the system in two. The ingestion flow runs source connectors and a context builder through reconciliation and validation, and writes two artifact types: wiki Markdown and semantic-layer YAML. Reconciliation is where duplicates get merged and contradictions get flagged for a human rather than silently resolved, which is the design decision worth noticing. The serving flow is separate: an agent queries ktx over MCP, ktx searches the wiki and semantic layer, returns approved metrics, and compiles them into read-only SQL that runs against the warehouse. That read-only constraint is listed as a feature in the comparison table, and it is the reason ktx can be pointed at a production warehouse without granting write scope. The semantic layer is not just a metric list. The README describes a join graph that 'automatically resolves chasm and fan traps', which is the classic failure of joining a fact table to two dimension tables at different grains and then summing. Whether the resolution is correct in your schema is something you have to check against your own data, not something the README can settle.

Getting it running: three commands and a status readout

Installation is a global npm package, then an interactive setup, then a readiness check:

npm install -g @kaelio/ktx ktx setup ktx status

The README says ktx setup 'creates or resumes a local ktx project, configures providers and connections, builds context, and installs agent integration.' The example status output is the useful part, because it tells you what has to be true before an agent can answer anything: a project path, an LLM provider (the sample shows claude-sonnet-4-6), an embeddings model (text-embedding-3-small), at least one configured database, at least one configured context source, a built context, and an agent integration. Every one of those lines is a place setup can stall. The README also carries a warning that matters operationally: if ktx status prints a ktx mcp start command with a project directory, run that before opening your agent client. Miss it and the agent has no server to talk to. Day-to-day commands include ktx ingest to rebuild context, ktx sl "revenue" to search semantic sources, and ktx wiki "refund policy" to search local wiki pages. The README notes that ktx runs on your own LLM API keys or a local agent sign-in, so usage billing does not pass through Kaelio.

The contradiction queue is the honest part and the expensive part

Flagging contradictions for human review is the right call, and it is also where the maintenance burden lands. An ingestion pipeline that merges wiki prose, dbt models and a BI tool's metric definitions will find places where two sources disagree about what revenue means. ktx surfaces those instead of picking a winner. That means somebody has to pick. If your team cannot staff that review loop, the semantic layer accumulates unresolved conflicts and agents get a context that is technically rich and practically ambiguous. The README does not describe a resolution workflow, an owner field, or a queue interface, so treat the reconciliation step as a process you will have to design around whatever ktx exposes in the CLI. There is a second limit worth stating: ktx sits on top of a warehouse, so it inherits that warehouse's permissions model and its query costs. Compiling a metric into read-only SQL still runs a query, and a fan-trap resolution that is wrong will still scan the tables it joins. The read-only guarantee protects your data, not your compute budget.

Where a hand-written semantic layer still wins

The obvious alternative is a semantic layer you maintain by hand, whether that is dbt metrics, MetricFlow or LookML. The difference is not the output format, it is who does the discovery. A hand-maintained layer is accurate exactly to the extent that someone wrote each definition deliberately, and it covers only the entities someone remembered to define. ktx inverts that: it samples tables, captures metadata and usage patterns, detects joinable columns, and annotates sources first, then assembles metrics from what it found. You get broader coverage faster and less certainty per entity. The README's comparison table makes the split visible, marking automatic warehouse context and automatic fan/chasm resolution as ktx-only, and approved reusable metric definitions as shared with traditional layers. So the honest framing is not that ktx replaces MetricFlow. It is that ktx adds an ingestion and retrieval layer in front of whatever definitions you already trust, and if those definitions are already complete and current, you are paying for machinery you may not need.

Version cadence, licence and the upgrade path

The project is TypeScript, licensed Apache-2.0, and not archived. The recent release list shows v0.14.0, v0.15.0 and v0.16.0 all dated between 2026-06-30 and 2026-07-03, which is a tight cluster of minor bumps three days apart. Pre-1.0 versioning plus that cadence means you should expect the CLI surface and the on-disk project format to move, and you should read release notes before upgrading rather than after. The documented upgrade is a single command, npm install -g @kaelio/ktx@latest. Apache-2.0 permits commercial use and modification and includes a patent grant, but it also means no warranty, and it does not cover the hosted documentation or any Kaelio service you might connect to. This is a description of the licence text, not legal advice; if you are embedding ktx in a product you ship, have counsel read the NOTICE and patent clauses rather than this paragraph.

Who should install it, and the one check to run first

Install ktx if you run PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, SQLite, DuckDB, Athena or MongoDB, and if your business logic is already spread across dbt, Looker, MetricFlow, LookML, Metabase, Sigma, Notion or Google Drive, because the ingestion pipeline is what converts that sprawl into something an agent can query without guessing. Skip it if you have no warehouse, if you need one query, or if your metric definitions are already complete, current and enforced by a tool your team trusts. The first thing to verify is not the search quality, it is whether the agent integration line in ktx status names the client you actually use. The sample output shows codex:project, and the README lists Claude Code, Codex, Cursor and OpenCode as supported, so confirm yours appears there and that the ktx mcp start command it prints is running before you ask an agent anything about revenue.

Editorial conclusion

Adopt ktx if you already run a SQL warehouse and your metric definitions live in more than one place, because the ingestion pipeline is the part that saves work. Do not adopt it for a single ad-hoc query, and do not adopt it if you have no warehouse at all, since ktx has nothing to sit on. Before committing, run ktx setup against one connection, then ktx status, and confirm the line reading 'Agent integration ready' names the client you actually use rather than a default you will never open.

Official sources

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