ktx — 데이터/분석 에이전트를 위한 실행 가능한 컨텍스트 레이어 (자가 개선형 컨텍스트 레이어 오픈소스)

• AI 코딩 에이전트(Claude Code, Codex, Cursor, OpenCode)가 회사 데이터 웨어하우스를 직접 조회할 때 가장 먼저 부딪히는 벽은 '정확한 맥락'이다. 매 질문마다 스키마를 재탐색하고 매출·환불률 같은 지표 계산식을 제멋대로 지어내, 승인된 정의와 어긋난 수치를 반환하는 문제가 반복된다. 2026년 6월 현재, 이 문제를 자동으로 해결하는 오픈소스 도구가 등장했다. Kaelio/ktx*는 자가 개선형 컨텍스트 레이어로, 승인된 지표 정의·테이블 관계·업무 지식을 모아 에이전트에 공급한다. Apache-2.0 라이선스이며, 로컬에서 동작해 외부 호스팅 서비스로 데이터를 전송하지 않는다.

ktx가 해결하는 문제

일반 목적 에이전트는 데이터 태스크에서 본질적으로 약하다. 매번 웨어하우스를 재탐색하고, 자체 지표 로직을 발명하며, 승인된 정의와 맞지 않는 숫자를 돌려준다. 기존 시맨틱 레이어(semantic layer) 도 이 문제를 완전히 해결하지 못한다. 수동 유지보수가 끊임없이 필요하고, 회사 위키·Notion·팀 문서에 흩어진 지식은 흡수하지 못한다.

ktx는 두 가지를 자동으로 수행한다.

• 회사 지식 흡수: 위키 콘텐츠를 수집·정리하고 중복을 제거하며, 소스 간 모순은 사람 검토용으로 플래그한다
• 데이터 스택 매핑: 테이블을 샘플링하고 메타데이터·사용 패턴을 캡처하며, 결합 가능한 컬럼을 탐지해 에이전트가 더 나은 쿼리를 작성하도록 주석을 단다
• 시맨틱 레이어 구축: 원시 테이블과 상위 지표를 조인 그래프(join graph)로 결합해 chasm·fan 트랩(조인 과정에서 행이 중복돼 합계가 부풀려지는 집계 오류)을 자동 회피한다. 에이전트는 복잡한 조인 SQL을 직접 짤 필요 없이 지표 이름만 지정하면 정확한 결과를 얻는다
• 에이전트 실행 시점 서빙: CLI와 MCP(Model Context Protocol, 에이전트가 외부 도구를 호출하는 표준 인터페이스) 도구로 위키와 시맨틱 레이어 전반을 full-text + 의미 기반 검색으로 결합 제공한다

기존 방식과의 비교

| 기능 | 일반 에이전트 | 전통 시맨틱 레이어 | ktx |

|------|---------------|---------------------|---------|

| 웨어하우스 컨텍스트 자동 구축 | — | — | ✓ |

| 결합 가능 컬럼 탐지 + fan/chasm 트랩 해소 | — | 수동 | ✓ |

| 승인된 재사용 가능 지표 정의 | — | ✓ | ✓ |

| 위키/Notion/팀 지식 흡수 | — | — | ✓ |

| 소스 간 모순 플래그 | — | — | ✓ |

| 에이전트 실행용 CLI + MCP 제공 | 부분 | — | ✓ |

| 설계상 읽기 전용(read-only) | n/a | n/a | ✓ |

ktx는 단순히 시맨틱 레이어 위에 앉는 게 아니다. dbt/MetricFlow/LookML 시맨틱 레이어를 섭취해서 원시 테이블 인스펙션과 위키 콘텐츠와 결합한다. 에이전트는 세 개로 분리된 표면 대신 하나의 검색 가능한 표면을 얻는다.

빠른 시작

ktx는 npm으로 전역 설치한다.

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

ktx setup은 로컬 ktx 프로젝트를 생성하거나 재개하고, 프로바이더·연결을 설정하며, 컨텍스트를 빌드하고, 에이전트 통합을 설치한다. ktx status 출력 예시는 다음과 같다.

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)

이미 에이전트를 사용 중이라면 프로젝트 디렉토리에서 다음을 실행한다.

npx skills add Kaelio/ktx --skill ktx

그러면 ktx 스킬이 설치·설정되어 에이전트가 즉시 활용할 수 있다. ktx status가 ktx mcp start --project-dir ...를 출력하면 에이전트 클라이언트를 열기 전에 먼저 실행한다.

지원 환경

• 데이터베이스* — PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, SQLite (총 7개).

• 연동 도구* — dbt, MetricFlow, LookML, Looker, Metabase, Notion (총 6개).

• 에이전트* — Claude Code, Codex, Cursor, OpenCode (총 4개).

• LLM 백엔드* — Anthropic API, Google Vertex AI, AI Gateway, 로컬 Claude Code 세션(Claude Agent SDK 경유), 로컬 Codex 인증(Codex SDK 경유) (총 5개). 자체 LLM API 키나 Claude Code 기반 Claude Pro/Max 구독, 로컬 Codex 인증으로 실행 가능하다.

주요 명령어

| 명령어 | 용도 |

|--------|------|

| ktx setup | ktx 프로젝트 생성/재개/갱신 |

| ktx status | 프로젝트 준비 상태 확인 |

| ktx ingest | 설정된 모든 연결의 컨텍스트 빌드 |

| ktx sl "revenue" | 시맨틱 소스 검색 |

| ktx wiki "refund policy" | 로컬 위키 페이지 검색 |

| ktx mcp start | 에이전트 클라이언트용 MCP 서버 시작 |

프로젝트 레이아웃

ktx 프로젝트는 다음과 같은 구조를 가진다.

my-project/
├── ktx.yaml              # 프로젝트 설정
├── semantic-layer/connection-id/  # YAML 시맨틱 소스
├── wiki/global/          # 공유 비즈니스 컨텍스트
├── wiki/user/user-id/    # 사용자별 노트
├── raw-sources/connection-id/  # 수집 결과물과 리포트
└── .ktx/                 # 로컬 상태와 시크릿, git에서 제외

• 커밋 권장: ktx.yaml, semantic-layer/, wiki/. 로컬 유지*: .ktx/. 프로젝트 경로 해석 우선순위는 KTX_PROJECT_DIR 환경 변수 → 가장 가까운 ktx.yaml → 현재 디렉토리 순이다. 스크립팅 시 --project-dir path로 명시 지정한다.

FAQ 핵심

• Q: ktx가 스키마나 쿼리 결과를 호스티드 서비스로 전송하나?*

A: 아니다. ktx는 로컬에서 실행된다. 사용자가 설정한 LLM 프로바이더로 보내는 데이터만 머신을 떠난다.

• Q: 어떤 LLM 백엔드를 지원하나?*

A: Anthropic API, Google Vertex AI, AI Gateway, Claude Agent SDK 경유의 로컬 Claude Code 세션, Codex SDK 경유의 로컬 Codex 인증. 자세한 내용은 LLM configuration 참조.

• Q: dbt/MetricFlow 시맨틱 레이어와 어떻게 다른가?*

A: ktx는 그 레이어들을 섭취해서 원시 테이블 인스펙션과 위키 콘텐츠와 결합한다. 에이전트는 세 개로 분리된 표면 대신 하나의 검색 가능한 표면을 얻고, 소스 간 모순을 플래그한다.

ktx를 써야 하는 경우

다음 조건에 부합하면 ktx가 적합하다.

• Claude Code, Codex, Cursor, OpenCode 같은 에이전트가 승인된 지표 정의로 웨어하우스를 조회하길 원한다
• 비즈니스 지식이 dbt, Looker, Metabase, Notion, 팀 위키에 산재해 있다
• 에이전트가 매 프롬프트마다 SQL을 새로 발명하지 않고 정형 SQL을 재사용하길 원한다

반면 다음 경우에는 ktx가 필요 없다.

• SQL 웨어하우스가 없는 경우 (ktx는 그 위에 앉는 도구다)
• 단일 임시 쿼리만 필요한 경우 (psql이나 노트북이면 충분하다)

전망

ktx의 핵심 가치는 자동화 + 읽기 전용 + 로컬 실행의 세 가지에 있다. 수동 유지보수가 필요 없고, 데이터베이스에 기록하지 않으며, 외부 호스팅 없이 회사 내부에서 완결된다. 2026년 6월 기준으로 Apache-2.0 라이선스 오픈소스로 공개되어 있어, 데이터 팀은 표준 시맨틱 레이어 위에 자가 개선형 지식 레이어를 얹을 수 있다. AI 에이전트가 일상적으로 웨어하우스를 조회하는 시대에, ktx 같은 컨텍스트 레이어는 곧 에이전트 정합성의 표준이 될 가능성이 크다.

• 함께 보면 좋은 글* — CodeGraph: AI 코딩 에이전트를 위한 코드 지식 그래프 · Acontext: 클라우드 네이티브 AI 에이전트를 위한 컨텍스트 데이터 플랫폼 · AI 에이전트를 위한 효과적 컨텍스트 엔지니어링