CTX v0.3.40 — Claude Code 세션 간 persistent memory (98명 사용자, 월 2,726 다운로드)

Show GN: CTX v0.3.40 — Claude Code 세션 간 persistent memory (98명 사용자, 월 2,726 다운로드)

Claude Code를 매일 쓰다 보면 한 가지 답답한 지점이 있습니다. 세션이 끊기면 이전 대화의 결정·맥락·파일 참조가 전부 사라진다는 점입니다. CTX v0.3.40은 이 문제를 UserPromptSubmit 훅 한 줄로 해결하는 가벼운 패키지로, 2026년 7월 1일 기준 누적 사용자 98명, 누적 세션 9,160개, PyPI 월간 다운로드 2,726회를 기록하고 있습니다.

> 핵심 한 줄: pip install ctx-retriever → ctx install → 다음 세션 시작 시 과거 결정/파일이 자동 주입.

CTX는 무엇인가

CTX는 Trigger-Driven Dynamic Context Loading 도구로, 개발자 질의를 4가지 트리거 유형(EXPLICIT_SYMBOL / SEMANTIC_CONCEPT / IMPLICIT_CONTEXT / TEMPORAL_HISTORY)으로 분류하고 각각에 특화된 검색 파이프라인으로 라우팅합니다. 특히 의존성 민감 질의에서는 코드베이스 import 그래프를 BFS로 순회해, 키워드·임베딩 검색이 놓치는 전이 의존성을 잡아냅니다.

벤치마크에서 CTX는 BM25 대비 Token-Efficiency Score 1.9배, 토큰 사용량 5.2%에 불과하면서 외부 코드베이스(Flask, FastAPI, Requests)에서 평균 R@5 +0.163 개선을 보였습니다. IMPLICIT_CONTEXT 트리거(예: "이 함수가 어디서 호출돼?")의 경우 R@5가 1.0으로 BM25(0.4)를 크게 앞섭니다.

어떻게 설치하나

pip install ctx-retriever
ctx install
# → 첫 Python 시작 시 훅이 자동 배선됨, Claude Code 재시작하면 끝

옵트아웃은 ctx-telemetry disable 또는 touch ~/.claude/ctx-telemetry-revoke로 즉시 가능합니다. 익명 사용 통계는 비식별 해시로만 수집되며 자세한 내용은 저장소의 PRIVACY.md에 공개되어 있습니다.

Claude Code 훅이 실제로 뭐를 주나

훅이 발화하면 다음 형태의 컨텍스트 블록이 매 프롬프트에 자동 주입됩니다.

[CTX] Trigger: IMPLICIT_CONTEXT | Query: AuthService | Confidence: 0.70 | Intent: dependency

Retrieved files (3/847 total):
• src/auth/service.py [score=1.000]
• src/auth/middleware.py [score=0.823]
• tests/test_auth.py [score=0.741]
(Use the prompt intent to decide how to treat this context.)

기본 검색은 BM25 + vec-daemon(multilingual-e5-small, 약 120MB)이고, 더 높은 품질이 필요하면 CTX_BGE_ENABLE=1을 ~/.claude/settings.json env 블록에 추가해 BGE 크로스 인코더(BAAI/bge-reranker-v2-m3, 약 2GB)를 켤 수 있습니다. 단, 4GB RAM 이하 또는 느린 인터넷 환경에서는 비권장입니다(첫 실행 시 모델 다운로드 발생).

트리거 4종 — 어떤 쿼리에 어떻게 반응하나

| 트리거 | 발동 조건 | 메커니즘 |

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

| EXPLICIT_SYMBOL | 클래스·함수명 직접 명시 | 심볼 인덱스 룩업 |

| SEMANTIC_CONCEPT | 개념·의도 설명 | BM25 키워드 스코어링 |

| IMPLICIT_CONTEXT | 의존성 질의("X를 쓰는 곳") | BFS 임포트 그래프 순회 |

| TEMPORAL_HISTORY | 최근 변경·히스토리 | 세션 파일 트래커 |

훅 지연은 순수 알고리즘(BM25 + BFS 인덱싱)이라 LLM 호출이 전혀 추가되지 않습니다.

| 프로젝트 규모 | 언어 | 파일 수 | 훅 지연 |

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

| 소규모 | Python | ~88 | ~40ms |

| 중규모 | Python | ~215 | ~165ms |

| 대규모 | TypeScript | ~651 | ~270ms |

| 초대규모 | 무관 | >2,000 | 자동 skip |

15자 미만 프롬프트, 슬래시 커맨드, [noctx] 태그, 3파일 미만 코드베이스에서는 훅이 자동 skip됩니다.

일반 RAG vs CTX — 뭐가 다른가

| 항목 | 일반 RAG | CTX |

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

| 목적 | 문서 검색 | 개발자 세션 연속성 |

| 지연 | 500ms~2s | <1ms (BM25 결정론적) |

| LLM 호출 | 임베딩 매번 | 선택적(vec-daemon) |

| 인덱싱 | 수동/배치 | 세션 종료 시 자동 |

| 비용 | API 호출 비용 | 로컬 무료 |

| 크로스세션 기억 | ✗ | ✅ |

| 코딩 에이전트 특화 | ✗ | ✅ |

v0.3.40 주요 변경

• BM25 + vec0 하이브리드 검색(α=0.5) 도입
• G1(의사결정 기억) + G2(코드베이스 파일 검색) 통합
• 설치 시 Turso URL 자동 감지 버그 수정
• vault.db → ~/.ctx/vault/ 경로 통합

제어 태그 — 프롬프트별 미세 조정

| 태그 | 효과 |

|---|---|

| [noctx] | 해당 프롬프트에 CTX 비활성 |

| [fix] | Fix/Replace 모드 — 기존(잘못된) 구현을 베끼지 않도록 anti-anchoring 리마인더 추가 |

[fix]는 fix: / bug: / refactor: / replace:로 시작하는 프롬프트에서도 자동 발화합니다.

실전 결과 — Synthetic 50 파일 / 166 쿼리

| 전략 | Recall@5 | 토큰 사용 | TES |

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

| Full Context | 0.075 | 100.0% | 0.019 |

| BM25 | 0.982 | 18.7% | 0.410 |

| LlamaIndex | 0.972 | 20.1% | 0.405 |

| CTX (Ours) | 0.874 | 5.2% | 0.776 |

• TES* = Recall@5 / ln(1 + files_loaded). 높을수록 토큰 효율이 좋습니다.

설치 전에 내 트랜스크립트로 가치 미리 측정

python3 benchmarks/ctx_validate.py --days 7

이 스크립트는 stdlib만 사용하며 ~/.claude/projects/*/.jsonl을 로컬에서 읽어 Wilson-95-CI 마크다운 리포트를 출력합니다. 업로드·가입·설치 없이 "CTX가 나에게 줄 수 있는 신호의 상한"을 26.9% [23.2%, 31.1%] 같은 신뢰구간으로 보여주므로, 설치 전 가성비 판정에 유용합니다.

요약

• 무엇: Claude Code용 결정·파일 persistent memory 도구(pip install ctx-retriever)
• 현재 지표: 98명 사용자 / 9,160 세션 / 월 2,726 PyPI 다운로드
• 핵심 성능: BM25 대비 TES 1.9×, 토큰 5.2%, IMPLICIT_CONTEXT R@5 = 1.0
• 운영 부담: 훅 지연 40~270ms(규모별), 4GB RAM 이상 권장
• 프리뷰 가능: 설치 전 ctx_validate.py로 내 트랜스크립트 기준 가치 측정

GitHub:

PyPI:

GeekNews 원문: