02-구조

02. 구조 — 세 가지 메모리 층

Claude Code가 다루는 “메모리”는 한 가지가 아니다. 적어도 세 층이다.

1) 휘발 메모리 — 메시지 히스토리

세션 안에서만 유효. messages.create에 매번 첨부되는 사용자/모델/도구 결과의 누적. 컨텍스트 예산을 가장 많이 먹는 부분.

조작 도구:

• /compact — 사용자가 명시 호출. 모델이 직접 대화를 요약해 새 짧은 메시지로 대체.
• auto-compact — 컨텍스트 사용량 임계치 도달 시 하네스가 자동 호출.
• 새 세션 — 가장 강력한 비움. 단, 영속 메모리는 살아남는다.

2) 영속 메모리 — CLAUDE.md와 메모리 파일

세션이 바뀌어도 살아남는다. 매 세션 시작 시 시스템 프롬프트의 일부로 다시 들어간다.

• 글로벌: ~/.claude/CLAUDE.md (모든 프로젝트 공통)
• 프로젝트: <repo>/CLAUDE.md (저장소별)
• 추가 메모리: 자동 학습 결과(~/.claude/projects/.../memory/MEMORY.md 류)

3) 외부 메모리 — 파일시스템 자체

모든 파일이 잠재적 메모리다. 모델이 Read로 끌어 쓸 수 있는 만큼이 메모리. 한 번 읽고 잊는다는 점에서 휘발이지만, 원하면 언제든 다시 읽을 수 있다는 점에서 사실상 영속.

이 셋의 무게 분배가 본 챕터의 핵심 손잡이다.

auto-compact 트리거: 64~75% 가설

Matsuoka의 측정에 따르면 Claude Code는 약 64~75% 사용 시점에 auto-compact를 발동한다 (정확한 수치는 빌드마다 다름). 90%+에서 발동하던 과거에 비해 훨씬 일찍 끊는다. 이 보수성이 추론 품질을 지킨다.

/compact가 실제로 하는 일

대략의 과정:

1. 현재까지의 메시지 히스토리를 모델에게 “이 대화를 짧게 요약하라”고 시킨다.
2. 시스템 프롬프트와 영속 메모리는 그대로 둔다.
3. 메시지 히스토리를 그 요약 한 메시지로 교체한다.
4. 진행 중인 도구 호출 결과나 todo 목록 같은 핵심 상태는 유지한다.

즉 /compact는 휘발 메모리만 압축한다. CLAUDE.md나 외부 파일은 건드리지 않는다.