CTX: Claude Code 세션 간 메모리 — 개발자가 알아야 할 핵심 정리

CTX: Claude Code에 세션 간 메모리를 더하다

CTX: Claude Code 세션 간 메모리 — 개발자가 알아야 할 핵심 정리

Claude Code는 세션을 닫으면 모든 컨텍스트를 잊는다. 어제 내린 아키텍처 결정, 버그의 근본 원인, 사용자가 설명한 코드 컨벤션 — 전부 다음 세션에서 사라진다. CTX는 이 문제를 해결하는 Claude Code 플러그인으로, SQLite 기반 지식 그래프에 구조화된 메모리를 쌓고 세션 시작 시 자동으로 주입한다.

CTX란 무엇인가

CTX는 Claude Code의 UserPromptSubmit 훅에 개입하는 플러그인이다. 사용자의 프롬프트가 모델에 도달하기 전, 관련 과거 결정·코드·문서를 로컬에서 조회해 자동으로 컨텍스트에주입한다. 클라우드 호출 없이, LLM 호출 없이, 완전 로컬에서 동작한다.

핵심 설치 방법은 두 가지다:

# 방법 1: Claude Code 내부에서 (권장)/plugin install ctx@jaytoone# 방법 2: pip으로 설치pip install ctx-retriever && ctx-install

설치가 완료되면 첫 세션에서 ctx 바이너리가 자동 다운로드되고 데이터베이스가 초기화된다. 이후 매 세션 자동으로 메모리가 주입되며, /ctx:status로 저장된 내용을 확인할 수 있다.

3가지 컨텍스트 주입 구조

CTX가 주입하는 정보는 세 가지 그룹으로 나뉜다.

그룹	내용	활용 사례
G1: 의사결정 타임라인	git log 기반 결정 이력	특정 구조를 선택한 이유, 기각된 대안
G2: 코드/문서 검색	BM25 기반.symbol name·의존성·개념 검색	관련 함수, 파일, 문서를 자동 주입
CM: 과거 대화	SQLite FTS5 + 선택적 벡터 검색	이전에 설명한 정책, 사용자별상하문

G2의 검색은 단순 풀텍스트 서치를 넘어선다. 네 가지 트리거 타입으로 쿼리를 라우팅한다:

• Symbol Name: 정확한 함수/변수 명

• Concept Search: 의미 기반 개념 매칭

• Dependency Analysis: import 그래프 BFS로 "이걸 사용하는 파일은?" 유형의 쿼리

• Temporal History: 시간 기반 히스토리

특히 의존성 분석은 텍스트 검색만으로는 놓칠 수 있는 "이 모듈을 임포트하는 파일은 어디냐"류형적 질의에 BFS로 답변한다는 점에서 순수 벡터 검색과 차별화된다.

실측 성능 수치

공식 벤치마크 데이터는 꽤 인상적이다:

• 메모리 회상 정확도: 0.880 (MAB N=50, Wilson CI 95%: [0.762, 0.944])

• 베이스라인(없음): 0.00

• 10,000+ 턴 실제 활용률: 39.6%

• 채팅 메모리 활용률: 52.6%

• LLM 호출: 없음 | 클라우드: 없음 | 완전 로컬

합성 벤치마크에서는 Recall@5가 0.874, 토큰 사용량 5.2%, TES 0.776을 기록했다. 외부 코드베이스(Flask, FastAPI, Requests)에서의 BM25 대비 평균 Recall@5 향상폭은 +0.163이었다.

다만 CodeSearchNet Python에서는 CTX Adaptive Trigger의 Recall@5가 0.740으로, BM25의 0.980에 졌다. 이 결과는 오히려 CTX의 적정 사용장경을 보여준다. 익숙한 코드베이스에서 심볼·의존성 기반 검색은 강하지만, "X를 하는 코드를 찾아줘" 같은 자연어 쿼리에는 Dense Embedding이나 Hybrid 방식이 우세하다.

메모리 타입과 계층

CTX는 저장하는 정보의 종류와 중요도에 따라 두 가지 차원으로 분류한다.

노드 타입:

• fact: 안정적 지식, 사용자 선호도, 컨벤션

• decision: 이유가 포함된 선택지

• pattern: 반복적으로 쓰이는 기법

• observation: 디버깅 인사이트, 근본 원인

• hypothesis: 재방문할 가치 있는 아이디어

• open-question: 미해결 질문

계층(Tier):

• pinned: 항상 주입 — 핵심 사실, 기반 결정, 활성 컨벤션

• reference: 자동 주입 없음 — /ctx:recall로만 조회하는 내구적 지식

• working: 현재 태스트용 — 임시 디버깅, 가설

• off-context: 보관됨 — 쿼리시나이카기리 로드 안 됨

중요한 규칙: "매 세션 로드해야 하는가?" → pinned. "언젠가 필요할 수 있는가?" → reference. "현재 작업 중인가?" → working.

MEMORY.md와 어떻게 다른가

Claude Code는 기본적으로 ~/.claude/projects//memory/에 MEMORY.md를 제공한다. CTX는 이것과 중복되지 않게 설계되었다.

MEMORY.md가 적합한 경우:

• 짧은 알림, 1~2줄 팩트

• 프로젝트 특정 노트

• 빠른 컨벤션 기록

CTX가 적합한 경우:

• 이유가 포함된 상세 결정

• 구조화된 패턴과 관찰

• 크로스 프로젝트 지식

• 쿼리할 수 있는 모든 것

규칙으로 정리하면: 결정·패턴·관찰이라면 CTX, 빠른 프로젝트 노트라면 MEMORY.md에 저장한다.

설치 시 고려사항

CTX가 모든 사람에게 적합한 것은 아니다. 설치 전 알아야 할 제약이 있다.

훅 충돌 위험: ctx-install은 기존 훅을 덮어쓰지 않고 문자열 기반으로 중복을 제거하지만, 이미 다른 훅을 사용 중이라면 ~/.claude/settings.json의 diff를 직접 확인해야 한다.

주입 바이어스: 자동 주입은 편리하지만,과기된 결정이나 잘못된 구현을 이어받을 위험이 있다. 특히 버그 수정 태스크에서 과거 컨텍스트가 너무 강하면 모델이 기존 잘못된 설계를 재사용하는방향발전할 수 있다. README에서 [fix] 태그로 이러한 앵커링을 억제할 수 있다.

규모 제약: 2,000개 이상의 파일이 있는 코드베이스에서는 자동 스킵된다.중소 규모 프로젝트에서 반복적으로 과거 결정과 관련 파일을 설명해야 하는 상황에 적합하다.대형 monorepo나 생소한 코드베이스 탐색에는 AST 기반 인덱서나 전용 RAG 시스템을 권장한다.

한국어 검색에 대한의론: Reddit 댓글에서 BM25 레이어의 토크나이저가 기본 공백 기반이라는 점이 지적되었다. "검색하다"/"검색하는"이 별도 토큰이 되어 한국어 주석과 docstring 검색에서 리콜이 감소할 수 있다. multilingual-e5-small 폴백이 있긴 하지만 BM25 레이어 자체의 CJK 처리 계획은 아직 명확하지 않다.

Claude Code 메모리 도구 비교

최근 6개월간 등장한 메모리 도구들은 각각 다른 문제를 풀고 있다.

도구	주입 방식	저장소	크로스 세션
CLAUDE.md	세션 시작 시 자동 로드	프로젝트 파일	O (수동 업데이트)
Claude Code auto-memory	세션 시작 시 자동 로드	~/.claude/projects/	O (대화에서 자동 축적)
CTX	훅 주입 (매 프롬프트 전)	git / 소스 코드 / SQLite	부분 (채팅 히스토리만)
YourMemory	MCP store/recall	SQLite + Vector DB	O (망각 곡선 기반)
WUPHF	MCP wiki read/write	Markdown + Git	O (멀티 에이전트 공유)
Cloudflare Agent Memory	API	Durable Objects + Vectorize	O (매니지드, 4개 카테고리)

크로스 세션 메모리 도구는 크게 검색 지향형과 지속 지향형으로 나뉜다. CTX는 완전 검색 지향형으로, 매 프롬프트 전에 관련 조각을 가져올 뿐 자체적으로 새 메모리를 작성하는 메커니즘은 없다. 한편 지속 지향형 도구들은 서로 저장 대상과 방식이 다르다 — auto-memory는 프로젝트별로 격리되어 축적되고, CLAUDE.md는 정적 규칙과 템플릿의 집합이며, YourMemory는 망각 곡선으로 오래된 기억의 점수를 낮춰 가비지 축적 문제를 풀고, WUPHF는 멀티 에이전트 협업용 위키로 Git 히스토리를 통해 누가 무엇을 썼는지 추적한다.

실용 적용 가이드

개인 프로젝트에서 Claude Code를 쓴다면, CLAUDE.md와 auto-memory가 대부분의 마찰을 해소한다. 프로젝트 컨벤션과 템플릿은 CLAUDE.md에, 사용자 피드백과 선호도는 auto-memory가 자동으로 처리한다. 별도 설치 없이 동작한다.

개선이 필요한 영역은 코드 컨텍스트의 크로스 세션 유지다. 어제 읽었던 파일, 디버깅했던 버그, 선택했던 아키텍처 결정 — 이 정보들은 현재로서는 세션이 끝나면 사라진다. CTX는 이 간극을 메운다.

중소규모 프로젝트에서 효과적:

• 최대 ~2,000개 파일 이하의 코드베이스

• 반복적으로 같은 타입의 작업오루

• 과거 디버깅 결정과 코드 검색을 자동화하고 싶은 경우

설치우선순위:

1. /plugin install ctx@jaytoone (Claude Code 내부에서)

2. pip install ctx-retriever && ctx-install (대안)

설치 후에는 /ctx:status로 노드 수와 계층을 확인하고, /ctx:cleanup으로 MEMORY.md와 중복 항목을 정리하는 것을 권장한다.

핵심 정리

CTX는 Claude Code의 상태리스 한계를 SQLite 기반 지식 그래프로 극복하는 로컬 플러그인이다. git log 결정 이력·코드 검색·채팅 히스토리를 UserPromptSubmit 훅을 통해 매 프롬프트 전 자동 주입하며, LLM 호출과 클라우드 없이 완전 로컬에서 동작한다. 메모리 회상 정확도 0.880, 실제 활용률 39.6%의 실측 성능을 보여주며, 2,000개 파일 이하의중소규모 프로젝트에 적합하다. 다만 한국어 BM25 검색의 한계, 주입 바이어스 위험, 자동 메모리 작성 기능 부재 등 고려할 점이 있으므로 도입 전 사용장경을 충분히 평가하길 권장한다.

---

📚 출처

• CTX: GeekNews — CTX: Claude Code 세션 간 메모리
• GitHub: Zate/cc-plugins/ctx