The context layer for data agents

---

ktx is a self-improving context layer that teaches agents how to query your warehouse accurately - from approved metric definitions, joinable columns, and business knowledge it builds and maintains for you.

Works with PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, and SQLite. Integrates with dbt, MetricFlow, LookML, Looker, Metabase, and Notion.

Runs with your own LLM API keys or a Claude Pro/Max subscription - no extra usage billing from ktx.

Why ktx

General-purpose agents struggle on data tasks. They re-explore your warehouse on every question, invent their own metric logic, and return numbers that don't match approved definitions.

Traditional semantic layers don't fix this. They demand constant manual upkeep and don't absorb the rest of your company's knowledge.

ktx does both, automatically:

• Learns from company knowledge. Ingests wiki content, organizes it, removes duplicates, and flags contradictions for human review.
• Maps the data stack. Samples tables, captures metadata and usage patterns, detects joinable columns, and annotates sources so agents write better queries.
• Builds a semantic layer. Combines raw tables and high-level metrics through a join graph that automatically resolves chasm and fan traps, so agents fetch metrics declaratively instead of rewriting canonical SQL each time.
• Serves agents at execution. Exposes CLI and MCP tools with combined full-text and semantic search across wiki and semantic-layer entities.

Agents can run raw SQL when they need it, or compose semantic-layer queries when they want approved metrics with reliable joins.

Agent Setup

Ask an agent such as Claude Code, Codex, Cursor, or OpenCode to install and configure ktx from your project directory:

Follow instructions from
https://docs.kaelio.com/ktx/docs/agents-setup.md
to install and configure ktx

Quick Start

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.

Example ktx status output after setup:

ktx project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Databases configured: yes (warehouse)
Context sources configured: yes (dbt_main)
ktx context built: yes
Agent integration ready: yes (codex:project)

Telemetry

ktx collects anonymous usage telemetry from interactive CLI runs to improve setup, command reliability, and data-agent workflows. See Telemetry for the event catalog, privacy details, and opt-out options.

Common Commands

Command	Purpose
ktx setup	Create, resume, or update a ktx project
ktx status	Check project readiness
ktx connection	List configured connections
ktx connection test	Test every configured connection
ktx connection test <id>	Test one connection
ktx ingest	Build context for every configured connection
ktx ingest <id>	Build context for one connection
ktx ingest --text "..."	Capture free-form notes into memory
ktx ingest --file notes.md --connection-id <id>	Capture a text file into memory
ktx sl	List semantic sources
ktx sl "revenue"	Search semantic sources
ktx sl validate <source> --connection-id <id>	Validate a semantic source
ktx sl query --measure <measure> --format sql	Compile semantic-layer SQL
ktx sql --connection <id> "select 1"	Execute read-only SQL
ktx wiki	List local wiki pages
ktx wiki "revenue definition"	Search local wiki pages
ktx mcp	Show MCP daemon status
ktx mcp start	Start the local MCP server for agent clients

Project resolution defaults to KTX_PROJECT_DIR, then the nearest ktx.yaml, then the current directory. Pass --project-dir <path> when scripting.

Project Layout

my-project/
├── ktx.yaml                         # Project configuration
├── semantic-layer/<connection-id>/  # YAML semantic sources
├── wiki/global/                     # Shared business context
├── wiki/user/<user-id>/             # User-scoped notes
├── raw-sources/<connection-id>/     # Ingest artifacts and reports
└── .ktx/                            # Local state and secrets, git-ignored

Commit ktx.yaml, semantic-layer/, and wiki/. Keep .ktx/ local.

Agent Usage

Install ktx integration for Claude Code, Claude Desktop, Codex, Cursor, OpenCode, and generic .agents clients:

ktx setup --agents

Pass --target <target> to install or repair one specific integration.

A typical agent workflow combines wiki and semantic-layer search before querying:

ktx sl "revenue" --json
ktx wiki "refund policy" --json
ktx sl query --connection-id warehouse --measure orders.revenue --format sql

During setup, choose Ask data questions with ktx MCP for agent clients. Choose Ask data questions + manage ktx with CLI commands when an operator agent also needs pinned ktx admin commands.

After setup, ktx prints Required before using agents with the exact commands to run. If the output includes ktx mcp start --project-dir ..., run it before opening your agent. Claude Desktop uses its own launcher and prints separate skill upload steps under .ktx/agents/claude/.

Workspace layout

Path	Purpose
packages/cli	TypeScript CLI package and published npm package source
packages/cli/src/context	Core context engine
packages/cli/src/llm	LLM and embedding providers
packages/cli/src/connectors	Database scan connectors
python/ktx-sl	Semantic-layer query planning
python/ktx-daemon	Portable compute service

Development

git clone https://github.com/kaelio/ktx.git
cd ktx
pnpm install
uv sync --all-groups
pnpm run build
pnpm run check

Use the development CLI locally:

pnpm run setup:dev
pnpm run link:dev
ktx-dev --help

ktx is a pnpm + uv workspace:

• TypeScript packages live in packages/*
• CLI source lives in packages/cli
• Python runtime source lives in python/ktx-sl and python/ktx-daemon
• Public docs live in docs-site/content/docs

Useful checks:

pnpm run type-check
pnpm run test
pnpm run dead-code
uv run pytest -q

Docs

• Quickstart
• CLI Reference
• Building Context
• Community & Support
• Contributing

Community

• Slack — ask questions, share what you're building, and chat with maintainers and other users.
• GitHub Issues — report bugs and request features.
• Contributing guide — set up the repo, run tests, and open a PR.

See Community & Support for the full guide on where to ask what.

License

ktx is licensed under the Apache License, Version 2.0. See LICENSE.