Give Your Data Agents Approved Metrics With a Self-Building Context Layer

A general-purpose agent querying your warehouse re-explores the schema on every question, invents its own metric logic, and returns numbers that don't match the definitions your company already approved. Kaelio/ktx — a 2k-star context layer from YC-backed Kaelio — fixes the input side: it builds and maintains the metric definitions, joinable columns, and business knowledge agents should be using, then serves them back through CLI and MCP.

Why This Skill Matters

The README's diagnosis: traditional semantic layers demand constant manual upkeep and don't absorb the rest of your company's knowledge. ktx does both automatically. It learns from company knowledge — ingesting wiki content, organizing it, removing duplicates, and flagging contradictions for human review. It maps the data stack — sampling tables, capturing metadata and usage patterns, detecting joinable columns. It builds a semantic layer through a join graph that automatically resolves chasm and fan traps, so agents fetch metrics declaratively instead of rewriting canonical SQL each time. And it serves agents at execution with CLI and MCP tools offering combined full-text and semantic search across wiki and semantic-layer entities.

The README's own comparison table credits general-purpose agents with a single Partial — CLI + MCP for agent execution — and traditional semantic layers with approved metric definitions plus manual join-trap detection; ktx claims the full set, including read-only by design.

Installation

Install globally, then run setup:

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

ktx setup creates or resumes a local ktx project, configures providers and connections, builds context, and installs agent integration. A ready project's ktx status reports the LLM, embeddings, databases, context sources, and agent integration — for example Agent integration ready: yes (codex:project).

Already working inside an agent? The README's suggested prompt:

Run npx skills add Kaelio/ktx --skill ktx and use the ktx skill to install and configure ktx in this project.

ktx runs with your own LLM API keys or a local agent sign-in — a Claude Pro/Max subscription through Claude Code, or your local Codex authentication. No extra usage billing from ktx.

Real Workflow: Answer With Approved Metrics

1. Run ktx setup, connect your warehouse (PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, SQLite, DuckDB, Amazon Athena, and MongoDB are supported) and knowledge sources — dbt, MetricFlow, LookML, Looker, Metabase, Sigma, Notion, and Google Drive integrate.
2. Run ktx ingest to build context for every configured connection.
3. If ktx status prints ktx mcp start --project-dir ..., run it before opening your agent client — the MCP daemon runs on demand.
4. Ask your agent business questions. Behind the scenes it searches the wiki and semantic layer (ktx sl "revenue", ktx wiki "refund policy" are the CLI equivalents), gets approved metric definitions, and compiles them into read-only SQL against the warehouse.
5. Version the knowledge like code: commit ktx.yaml, semantic-layer/, and wiki/; keep .ktx/ (local state and secrets) out of git.

Real Workflow: Reconcile Contradicting Definitions

When the same metric is defined differently in dbt, Looker, and a Notion wiki page, ingestion doesn't pick a winner silently — ktx organizes wiki content, removes duplicates, and flags contradictions for human review. Run ktx ingest after connecting a new source and reconcile the flagged conflicts before your agents start citing either side.

Tips

• Connections are read-only — ktx never writes to your database. There is also no hosted service: ktx runs locally, and the only data leaving your machine is what you send to the LLM provider you configured.
• LLM backends: Anthropic API, Google Vertex AI, AI Gateway, the local Claude Code session through the Claude Agent SDK, and your local Codex authentication through the Codex SDK.
• Telemetry is privacy-conscious (no file paths, hostnames, SQL, or schema/table/column names in catalog events) with opt-out options documented on the telemetry docs page.
• First commands worth memorizing: ktx setup, ktx status, ktx ingest, ktx sl "...", ktx wiki "...", ktx mcp start.

When Not to Use This

The README names its own skip list: ktx sits on top of a SQL warehouse, so without one there is nothing for it to serve; and if you only need one ad-hoc query, psql or a notebook will do. Between those poles — a real warehouse, recurring agent questions, scattered definitions — is where it earns its setup cost.

See the leaderboard for more skills.