TL;DR

로컬에 흩어진 코딩 에이전트의 과거 세션을 재활용하지 못해 같은 실패를 반복하거나 결정의 근거를 잃는 문제가 존재했고 ctx는 Rust로 작성된 CLI로서 해당 기록을 발견해 세션·이벤트·파일 메타데이터로 정규화해 SQLite에 색인함으로써 자연어 검색으로 과거 작업을 빠르게 조회하게 한다. 검색 결과는 일치하는 스니펫과 세션/이벤트 식별자를 함께 반환해 출처 추적과 재현성을 보장하며, 문서의 차트는 ctx 검색이 raw transcript 검색보다 토큰 사용량을 대폭 줄여 응답 효율을 확보했음을 보여준다. 인덱스와 검색은 로컬에서만 동작하며 클라우드 전송이나 API 키를 요구하지 않아 민감한 기록을 외부에 노출하지 않으면서 기존 에이전트 메모리나 코드베이스 그래프와는 다른 '과거 세션의 원문 근거 기반' 검색을 제공한다.

주요 기능

• 색인하여 검색할 수 있다. ctx는 로컬에 분산된 에이전트 기록 파일을 발견해 세션, 이벤트, 터치된 파일 메타데이터로 정규화해 SQLite에 저장한다. 이 저장 방식은 반복적인 원문 스캔을 피하고 쿼리 응답 시 관련 스니펫과 출처 ID를 함께 반환해 재현성을 높인다.
• 자연어로 검색할 수 있다. 사용자는 자연어 문장이나 파일 지정, 다중 용어 조합으로 이전 작업의 실패 사례나 명령어를 조회할 수 있다. 검색 결과는 일치하는 스니펫과 세션/이벤트 식별자를 포함해 에이전트가 맥락을 확인할 수 있게 한다.
• 로컬 전용 색인을 유지할 수 있다. ctx는 기본적으로 인덱스를 로컬에 저장하고 외부 모델 API 호출이나 클라우드 전송을 요구하지 않는다. 설치된 바이너리는 서명된 업그레이드 기능을 제공하나 소스 빌드나 패키지 설치판은 자동 업그레이드 대상이 아니다.
• SQL로 내부 데이터를 조회할 수 있다. ctx는 색인된 SQLite DB에 대해 읽기 전용 SQL 쿼리를 허용해 통계나 맞춤 집계를 수행할 수 있다. 이 접근은 디버깅, 감사, 또는 파이프라인 통합 시 유연성을 제공한다.

어떻게 동작하는가

로컬에 존재하는 에이전트 하네스의 지속 기록 파일을 검색해 원본 레코드를 가져오고 세션·이벤트·터치된 파일 메타데이터로 정규화해 SQLite 색인을 구성한다. 색인된 필드와 랭킹된 인용 매칭을 반환하도록 검색 경로를 최적화해 원시 전체 대화 검색에 비해 반환되는 토큰 수를 크게 줄인다. 바이너리 자체는 Rust로 작성되어 별도의 백그라운드 서비스 없이 단일 명령형 CLI로 동작한다.

해결 문제

코딩 에이전트는 종종 이전 대화와 시도들을 복구하지 못해 같은 실패를 반복하거나 과거의 결정 근거를 파악하지 못하는 문제가 존재한다. ctx는 로컬에 흩어진 에이전트 세션을 색인해 해당 시도와 명령, 패치, 테스트 결과를 세션 단위로 검색 가능하게 함으로써 중복 작업과 지식 손실을 줄인다. 색인된 검색 결과는 원본 스니펫과 세션/이벤트 ID를 함께 제공해 재현성과 출처 추적을 보장한다.

차별점

• 세션 단위 인용 검색을 제공한다. 많은 에이전트 메모리는 요약이나 벡터만 저장해 출처 추적이 어렵지만 ctx는 일치 스니펫과 세션/이벤트 식별자를 함께 반환해 어떤 발화가 근거인지 명확히 연결한다. 이는 명령 실패나 거부된 접근법의 원인을 확인할 때 직접적인 근거 추적을 가능하게 한다.
• 로컬 전용, 서비스 불필요 모델을 지향한다. ctx는 색인을 로컬 SQLite에 보관하고 외부 모델 API나 클라우드 전송을 요구하지 않으므로 민감한 원문을 외부에 노출하지 않는다. 설치판은 서명된 자동 업그레이드를 제공하나 소스 빌드와 패키지 설치는 통제된 방식으로 유지된다.
• 다수 에이전트 하네스에 대한 디스커버리와 플러그인 확장성을 갖췄다. README에 명시된 Codex, Claude Code, Cursor 등 여러 하네스의 기록을 직접 가져올 수 있으며 플러그인으로 미지원 포맷을 어댑터화할 수 있다. 이 구조는 조직별로 다양한 에이전트 도구를 혼용하는 환경에서도 일관된 검색 경험을 제공한다.

사용 사례

• 과거 실패 원인 확인에 사용한다. 개발자가 이전 에이전트 세션에서 발생한 마이그레이션 실패나 테스트 실패의 정확한 명령과 출력을 찾아 재현 가능한 디버깅 단서를 확보할 수 있다. 검색 결과의 인용 정보로 원문을 검토해 안전하게 재적용할 수 있다.
• 에이전트 연속 작업 시 컨텍스트 보강용으로 사용한다. 현재 에이전트가 파일을 수정하거나 리펙터링할 때 이전 에이전트의 의도와 거부된 접근법을 빠르게 참조해 불필요한 반복을 줄인다. 세션·이벤트 단위의 메타데이터는 어떤 파일를 누가 언제 건드렸는지 파악하는 데 도움을 준다.
• 자동화 파이프라인의 감사 로그로 활용한다. 색인된 세션과 이벤트는 변경 내역과 명령 실행의 근거를 보관하므로 코드 변경과 에이전트 행동을 추적하는 감사용 검색 인터페이스로 활용할 수 있다. SQLite 기반 접근은 외부 분석 도구와 통합하기 쉬운 형태로 데이터를 노출한다.

시작하기

공식 설치 스크립트 실행으로 바이너리를 설치한 뒤 ctx setup 명령으로 로컬에 존재하는 에이전트 세션을 색인하여 SQLite DB를 초기화해야 한다. 색인 후에는 ctx search "쿼리" 형태로 자연어 검색을 실행해 세션과 이벤트를 조회할 수 있으며 ctx show event <ctx-event-id> 또는 ctx show session <ctx-session-id>로 원문 스니펫이나 전체 세션을 확인한다. 에이전트 스킬로의 통합이 필요한 경우 npx skills add ctxrs/ctx 또는 문서에 명시된 플랫폼별 설치 절차를 따르면 된다.

요구사항

• 로컬 파일 시스템에 접근 가능한 환경과 POSIX 호환 셸이 필요하다.
• Rust로 작성된 바이너리 실행 권한이 필요하며 설치 스크립트나 패키지 매니저 방식에 따라 curl, sh 또는 패키지 매니저가 요구될 수 있다.
• 에이전트 하네스의 기록 파일이 로컬에 존재해야 하며 각 하네스에 대한 디스커버리 권한이 필요하다.

벤치마크

이미지 분석