ktx는 AI 에이전트가 데이터 웨어하우스를 정확히 질의할 수 있도록 승인된 메트릭 정의, 조인 가능한 컬럼, 비즈니스 지식을 제공하는 자가 개선형 컨텍스트 레이어(context layer)입니다.
개요
일반 목적 AI 에이전트는 데이터 작업에 취약합니다. 질의할 때마다 웨어하우스 스키마를 처음부터 다시 탐색하고, 자체적으로 메트릭 로직을 생성하며, 승인된 정의와 일치하지 않는 결과를 반환하는 경향이 있습니다. 전통적인 시맨틱 레이어(semantic layer)는 지속적인 수동 유지보수가 필요하고 회사의 분산된 지식을 흡수하지 못한다는 한계가 있습니다.
ktx는 이러한 문제를 해결하기 위해 데이터베이스, BI 도구, 모델링 코드, 문서 등 여러 소스에서 컨텍스트를 자동으로 수집하고 통합합니다. 수집된 정보는 위키 마크다운과 시맨틱 레이어 YAML로 구성되어 AI 에이전트(Claude Code, Codex, Cursor, OpenCode 등)가 MCP(Model Context Protocol)를 통해 사용할 수 있습니다.
작동 방식
컨텍스트 수집(Ingestion)
ktx는 다음 소스에서 컨텍스트를 수집합니다:
- 데이터베이스(PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, SQLite)
- dbt, MetricFlow, LookML, Looker, Metabase
- Notion, 위키 문서
컨텍스트 엔진은 소스 연결(Connector)을 통해 데이터를 가져와 빌드하고, 검증 및 중복 제거를 수행한 후 위키 마크다운(wiki/)과 시맨틱 레이어 YAML(semantic-layer/)로 저장합니다.
에이전트 서빙(Serving)
에이전트는 MCP 프로토콜을 통해 ktx에 질의합니다:
- 에이전트가 자연어로 질문을 보냄
- ktx MCP 서버가 위키와 시맨틱 레이어를 검색(전문 검색 + 시맨틱 검색)
- 승인된 메트릭과 관련 컨텍스트를 반환
- 읽기 전용(read-only) SQL로 컴파일되어 웨어하우스에 실행
ktx는 로컬에서 실행되며, MCP 데몬은 ktx mcp start 명령어로 필요 시에만 가동됩니다.
주요 기능
- 회사 지식 학습: 위키, Notion 등에서 컨텍스트를 수집하고 정리하며 중복을 제거하고 모순을 플래그합니다.
- 데이터 스택 매핑: 테이블 샘플링, 메타데이터 수집, 사용 패턴 분석, 조인 가능한 컬럼 감지, 소스 어노테이션을 수행합니다.
- 시맨틱 레이어 구축: 조인 그래프(join graph)를 통해 raw 테이블과 고수준 메트릭을 연결하며, chasm trap과 fan trap을 자동으로 해결합니다.
- 에이전트 서빙: CLI 및 MCP 도구를 통해 전체 텍스트 검색과 시맨틱 검색을 결합한 인터페이스를 제공합니다.
CLI 명령어
| 명령어 | 목적 |
|---|---|
ktx setup | ktx 프로젝트 생성, 재개, 업데이트 |
ktx status | 프로젝트 준비 상태 확인 |
ktx ingest | 모든 설정된 연결에 대해 컨텍스트 빌드 |
ktx sl "revenue" | 시맨틱 소스 검색 |
ktx wiki "refund policy" | 로컬 위키 페이지 검색 |
ktx mcp start | MCP 서버 시작 |
프로젝트 구조
my-project/
├── ktx.yaml # 프로젝트 설정
├── semantic-layer/<connection-id>/ # YAML 시맨틱 소스
├── wiki/global/ # 공유 비즈니스 컨텍스트
├── wiki/user/<user-id>/ # 사용자 범위 메모
├── raw-sources/<connection-id>/ # 수집 아티팩트 및 보고서
└── .ktx/ # 로컬 상태 및 시크릿 (git-ignored)
ktx.yaml, semantic-layer/, wiki/는 커밋하고, .ktx/는 로컬에 유지합니다.
보안 및 아키텍처
- 로컬 실행: ktx는 호스티드 서비스가 아닌 로컬에서 실행됩니다. 스키마나 질의 결과가 외부로 전송되지 않습니다.
- 읽기 전용: 데이터베이스 연결은 읽기 전용이며, ktx는 데이터베이스에 쓰지 않습니다.
- LLM 백엔드: Anthropic API, Google Vertex AI, AI Gateway, Claude Code 세션, Codex SDK 등 다양한 LLM을 지원합니다.
- 익명 텔레메트리: 선택적 익명 사용 통계 수집 (파일 경로, 호스트명, SQL, 스키마 이름 등 미포함)