e6f0d9cd51
- require non-empty `vertex.location` in the project schema instead of defaulting to an empty string with a description that promised SDK fallback the resolver never honored - log YAML parse failures from `SemanticLayerService.loadSource` and `KnowledgeWikiService.readPage` so corrupted overlays aren't silently treated as "does not exist" by ingest/agent tools - push directory-listing errors in `loadAllSources` and `listPageKeys` into the load-error / log path instead of returning empty success - accept an `embeddingProvider` in `createLocalProjectMemoryIngest` and plumb the resolved CLI provider through `mcp-server-factory`; warn in both the memory and bundle runtimes when they fall back to `NoopEmbeddingPort` while the project config requests an active embedding backend - clarify `embeddings.dimensions` description as a placeholder valid only with `backend: none`, and tighten the sentence-transformers `base_url` description to call out that managed-daemon resolution is CLI-only |
||
|---|---|---|
| .github | ||
| assets | ||
| docs | ||
| docs-site | ||
| examples | ||
| packages | ||
| python | ||
| scripts | ||
| website | ||
| .gitignore | ||
| .pre-commit-config.yaml | ||
| .releaserc.cjs | ||
| AGENTS.md | ||
| biome.json | ||
| CLAUDE.md | ||
| codecov.yml | ||
| conductor.json | ||
| CONTRIBUTING.md | ||
| GEMINI.md | ||
| knip.json | ||
| LICENSE | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| pyproject.toml | ||
| README.md | ||
| release-policy.json | ||
| SECURITY.md | ||
| tsconfig.base.json | ||
| uv.lock | ||
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)
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 client agents.
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 packages
| Package | Purpose |
|---|---|
packages/cli |
CLI entry point |
packages/context |
Core context engine |
packages/llm |
LLM and embedding providers |
packages/connector-bigquery |
BigQuery scan connector |
packages/connector-clickhouse |
ClickHouse scan connector |
packages/connector-mysql |
MySQL scan connector |
packages/connector-postgres |
Postgres scan connector |
packages/connector-snowflake |
Snowflake scan connector |
packages/connector-sqlite |
SQLite scan connector |
packages/connector-sqlserver |
SQL Server scan connector |
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-slandpython/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
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.