Claude Code 세션 메모리 CTX — 훅과 BM25 로컬 검색 점검표

본 가이드는 Claude Code 세션을 닫을 때 사라지는 컨텍스트를 다음 세션 시작 시 자동으로 복원해 주는 오픈소스 도구 CTX(Trigger-Driven Dynamic Context Loading for Code-Aware LLM Agents)의 동작 방식과 한국 개발 조직이 도입 전 점검할 항목을 정리합니다.

테스트 환경: macOS 또는 Linux, Python 3.10 이상, Claude Code 플러그인 시스템 지원 버전 기준입니다. CTX는 작자 jaytoone이 GitHub과 GeekNews에 2026-05-03(KST) 공개했고, 라이선스는 MIT입니다(GeekNews 토픽 #29124).

1. CTX란 무엇인가

Claude Code는 세션을 닫으면 작업 메모리, 즉 어제 어떤 결정을 했고 어떤 파일을 보고 있었는지를 모두 잃습니다. 다음 세션을 시작하면 같은 코드베이스라도 사용자가 직접 “어제까지 진행한 내용은 …”이라고 다시 설명해야 합니다.

CTX는 이 컨텍스트 손실을 Claude Code의 훅(hook) 시스템으로 해소합니다. 공식 GitHub 저장소(jaytoone/CTX)에 따르면 CTX는 세션을 가로지르는 retrieval 계층을 제공하며 LLM 호출 없이, 클라우드 의존 없이, 완전 로컬에서 동작합니다.

• 로컬 파일 시스템과 git 히스토리만 사용
• 외부 API 호출 0건 (모델 추론 비용 추가 없음)
• 라이선스 MIT — 사내 도구 통합 시 제약 적음

2. 동작 방식 — UserPromptSubmit 훅 3종

CTX는 Claude Code의 UserPromptSubmit 이벤트가 발생할 때마다 후크 스크립트를 호출해 세 종류의 컨텍스트 청크를 프롬프트에 자동 주입합니다. 공식 README 기준 주입 지연은 1ms 이내로 측정됩니다.

2-1. G1: git log 의사결정 타임라인

최근 커밋 메시지와 변경 파일을 시간 순서로 정렬해 “어제 왜 그 결정을 했는가”를 자연어 타임라인으로 재구성합니다. git이 이미 의사결정의 1차 기록 매체이므로, CTX는 별도 메타데이터를 강요하지 않습니다.

2-2. G2: BM25 코드·문서 검색

현재 사용자 프롬프트의 키워드를 토큰화한 뒤 BM25 점수로 관련 코드 파일과 문서를 추출합니다. 공식 README는 자체 평가에서 CTX가 BM25 대비 Token-Efficiency Score 기준 1.9배, 사용 토큰량은 5.2% 수준이며, 외부 코드베이스(Flask, FastAPI, Requests)에서 평균 R@5가 +0.163 향상되었다고 보고합니다.

임베딩 기반 RAG가 아닌 BM25를 1차 검색기로 둔 이유는 import 그래프를 함께 사용해 구조적 의존성을 잡기 위함입니다. README 기준 implicit dependency 쿼리에서 Recall@5가 1.0(BM25 단독은 0.4)이라고 명시되어 있습니다.

2-3. CM: 과거 대화 vault (SQLite FTS5)

이전 세션의 사용자·어시스턴트 메시지를 SQLite FTS5 인덱스에 보관하고, 옵션으로 임베딩 벡터를 병행합니다. 회사 코드베이스 외부로 데이터를 내보내지 않으므로 클라우드 RAG 대비 데이터 거버넌스 부담이 작은 편입니다.

3. 실측 수치와 한계

작자가 GitHub README와 GeekNews 게시물에 공개한 자체 측정 결과는 다음과 같습니다. 외부 재현 보고는 아직 확인되지 않으므로 어디까지나 작자 측 수치라는 점에 주의해야 합니다.

• 메모리 회상 정확도 0.880, 95% Wilson CI [0.762, 0.944] (MAB 평가, N=50, GeekNews 게시 기준)
• 베이스라인(컨텍스트 주입 없음) 0.00
• 활용률 39.6% (작자 본인 10,000+ 턴 사용 로그 기준)

한계로는 두 가지를 봐야 합니다. 첫째, BM25·FTS5 인덱스 갱신을 트리거하는 시점이 사용자 프롬프트 시점이라 큰 저장소에서는 첫 호출 지연이 1ms를 초과할 가능성이 있습니다. 둘째, MAB N=50 표본은 의사결정 신뢰성 평가용으로는 작은 편이라, 사내 코드베이스에 적용하기 전 별도 회상률 측정이 필요합니다.

4. 설치와 환경 요구

두 가지 설치 경로가 제공됩니다. 표준 Python 패키지로 받거나, Claude Code 플러그인 매니페스트로 받을 수 있습니다.

# 1) PyPI 설치 + 훅 자동 등록
pip install ctx-retriever
ctx-install

# 2) Claude Code 플러그인 명령 (CLI 내부)
/plugin install ctx@jaytoone

# 3) 소스에서 빌드 (개발자용)
git clone https://github.com/jaytoone/CTX
cd CTX
pip install -e .

설치가 끝나면 ~/.claude/hooks/ 디렉터리에 chat-memory.py, bm25-memory.py, git-memory.py 같은 훅이 등록되고, Claude Code 설정 파일의 UserPromptSubmit 항목이 갱신됩니다. 갱신 내용은 README 기준 명시되어 있어 기존 훅과 충돌 여부를 사전에 확인할 수 있습니다.

5. 한국 개발 조직 도입 점검표

로컬 도구라는 특성에도 불구하고 사내 도입 시 다음 항목은 사전에 정리해야 합니다.

• 대화 vault 보관 위치 — 기본값은 사용자 홈 디렉터리이며, 회사 디스크 암호화 정책 적용 범위 내인지 확인합니다.
• 인덱스 대상 경로 — 모노레포 환경에서는 보안 등급이 다른 디렉터리가 한 인덱스에 섞이지 않도록 CHAT_MEMORY_EXCLUDED_PROJECTS 등 환경 변수를 활용합니다.
• git log 노출 — git 메시지에 고객 정보·이슈 ID가 포함된 경우, 타임라인 자동 주입이 외부 모델로 흘러갈 위험을 검토합니다.
• 모델 입력량 — 컨텍스트 자동 주입은 토큰 사용량을 늘립니다. GitHub Copilot 청구 전환처럼 사용량 기반 과금 도구와 병행하면 비용 영향이 누적됩니다.
• 롤백 절차 — pip uninstall 또는 플러그인 비활성화로 즉시 회수 가능한지 사내에서 사전 검증합니다.

6. 정리 — 언제 쓰면 좋고, 언제 보류할까

도입을 권할 만한 상황은 다음과 같습니다. 첫째, 같은 코드베이스를 며칠~수주에 걸쳐 이어 작업하는 경우 git 의사결정 타임라인의 가치가 큽니다. 둘째, 보안상 코드를 클라우드 RAG에 올릴 수 없는 조직에 적합합니다. 셋째, Claude Code를 1차 IDE로 쓰는 팀이라면 설치 마찰이 작습니다.

반대로 보류해야 할 상황도 분명합니다. 단일 세션 안에서 끝나는 작업, 정적 분석 결과를 외부 인덱스에 남기는 것을 금지하는 컴플라이언스 환경, 그리고 Claude Code 외 IDE 중심으로 운영되는 팀이라면 자체 retrieval 파이프라인을 별도로 검토하는 편이 합리적입니다.

관련 글

Claude Code와 인접한 개발자 도구 트렌드를 함께 살펴두면 도입 판단에 도움이 됩니다.

• AI 코딩 도구의 사용량 과금이 본격화되면서 토큰을 효율적으로 쓰는 retrieval 전략의 가치가 커지고 있습니다 — GitHub Copilot 청구 전환 — AI Credits 시행 한국 개발자 점검표.
• LLM을 단순 코딩 보조가 아닌 상시 retrieval·자동화에 활용하는 사례를 함께 보면 CTX의 활용 시나리오 폭이 넓어집니다 — LLM 비전형 활용 7가지, 한국 개발자 실무 즉시 적용 가이드.
• Agent-first 워크플로 전환 흐름을 짚어두면 CTX 같은 훅 기반 도구의 운영 리스크 시야가 넓어집니다 — Warp 터미널 오픈소스 전환 — AGPL과 agent-first 도입 점검표.

---

📌 함께 보시면 좋은 글

• 개발자 커리어 체크리스트 →
• 개발 커리어 결정 가이드 →

※ 본 글은 AI(Claude)의 초안을 기반으로 편집자 검수를 거쳐 발행되었습니다. (한국 AI기본법 대응 고지)