Claude Code의 컨텍스트 유실 문제를 해결하는 Claude Bootstrap v3.3 업데이트: Mnemos와 iCPG 도입

실용적 조언

Claude Code 세션이 길어질 경우 mnemos add goal 명령어로 현재 목표를 명시적으로 등록하여 압축 후 유실을 방지할 것
icpg bootstrap 명령어를 실행하여 기존 프로젝트의 Git 기록으로부터 코드 작성 의도를 자동으로 추출하고 관리할 것

섹션별 상세

Claude Code가 컨텍스트의 83%를 사용하면 자동 압축을 수행하며 이때 중요한 작업 목표나 제약 조건이 유실되는 현상이 발생한다. Mnemos는 SQLite 기반의 MnemoGraph를 사용하여 GoalNode와 ConstraintNode를 디스크에 영구 저장하고 압축 시에도 절대 삭제하지 않는 정책을 적용한다. 이를 통해 에이전트가 세션 중간에 방향성을 잃지 않고 작업을 지속할 수 있는 환경을 제공한다.

코드의 기능뿐만 아니라 작성 의도를 추적하기 위해 iCPG(Intent-Augmented Code Property Graph)를 도입했다. 모든 코드 변경 사항을 ReasonNode와 연결하여 의도, 사후 조건, 불변성을 캡처하고 에이전트가 파일을 수정하기 전 기존 제약 사항을 자동으로 조회하게 한다. icpg drift 명령어를 통해 실제 코드와 원래 의도 사이의 괴리를 6개 차원에서 탐지하여 코드 품질을 유지한다.

bash

icpg query prior "implement auth"
icpg query constraints src/api/users.ts
icpg drift
icpg bootstrap

iCPG를 사용하여 이전 구현 의도를 검색하거나 코드의 제약 사항 및 드리프트를 확인하는 CLI 명령어 예시

컨텍스트 압축이 일어나기 전 에이전트의 상태를 파악하기 위해 4가지 지표를 활용한 피로도 모니터링을 수행한다. 토큰 활용도(40%), 스코프 분산(25%), 재읽기 비율(20%), 에러 밀도(15%)를 합산하여 FLOW에서 EMERGENCY까지의 상태를 정의한다. 피로도가 0.6에 도달하면 시스템이 자동으로 체크포인트를 생성하여 0.83에서 발생하는 하드 압축에 대비한다.

bash

mnemos add goal "what you're building"
mnemos add constraint "don't break the API"

Mnemos 시스템에 작업 목표와 제약 조건을 추가하여 영구 메모리에 등록하는 명령어

압축 후 상태 복구를 위해 PreCompact와 PreToolUse 훅을 결합한 2단계 복구 레이어를 구현했다. 압축 직전 긴급 체크포인트를 작성하고 디스크에 마커 파일을 생성하며, 압축 후 첫 번째 도구 호출 시 이 마커를 감지하여 저장된 상태를 컨텍스트에 강제 주입한다. 이 방식은 LLM 요약 모델의 성능에 의존하지 않고 디스크에서 직접 데이터를 읽어오므로 복구 성공률이 보장된다.

용어 해설

컨텍스트 압축(Context Compaction): — LLM의 컨텍스트 윈도우가 가득 찼을 때 이전 대화 내용을 요약하여 공간을 확보하는 과정이다. Claude Code에서는 약 83% 지점에서 발생하며, 이 과정에서 중요한 작업 목표나 제약 조건이 유실되는 문제가 발생할 수 있다.
코드 속성 그래프(Code Property Graph): — 코드의 구조, 제어 흐름, 데이터 흐름을 그래프 형태로 표현하여 분석하는 기법이다. 본문에서는 iCPG를 통해 코드의 기능뿐만 아니라 '왜' 해당 코드가 존재하는지에 대한 의도(Intent)를 노드로 연결하여 관리한다.
벡터 검색(Vector Search): — 데이터를 수치 벡터로 변환하여 유사도를 기반으로 정보를 찾는 기술이다. iCPG에서 특정 기능을 구현하기 전 기존 코드베이스에 유사한 의도의 구현이 이미 존재하는지 확인하여 중복 개발을 방지하는 데 사용된다.
훅(Hook): — 특정 이벤트가 발생했을 때 자동으로 실행되는 코드 조각이나 메커니즘이다. Claude Code의 도구 사용 전후나 세션 시작 시점에 Mnemos 시스템이 개입하여 메모리를 저장하거나 복구하는 통로로 활용된다.
SQLite: — 서버 없이 파일 형태로 작동하는 경량 관계형 데이터베이스 관리 시스템이다. Mnemos 시스템에서 작업 목표, 제약 조건, 결과물 등의 메모리 그래프를 디스크에 영구적으로 저장하고 세션 간에 유지하는 저장소 역할을 한다.

언급된 도구

Claude Bootstrap추천

Claude Code 프로젝트 초기화 및 메모리 관리 자동화 도구

ChromaDB중립

iCPG의 의도 검색을 위한 선택적 벡터 데이터베이스

SQLite추천

Mnemos 메모리 그래프의 영구 저장을 위한 로컬 데이터베이스

언급된 리소스

GitHubClaude Bootstrap GitHub Repository