Claude Code 메모리 시스템 심화: 세션을 넘어서 기억하는 AI

Claude Code 메모리 시스템 심화: 세션을 넘어서 기억하는 AI

Claude Code는 단순한 일회성 챗봇이 아닙니다. CLAUDE.md, Auto Memory, 컨텍스트 윈도우, 세션 히스토리로 이루어진 다층 메모리 시스템을 통해 프로젝트를 이해하고 학습합니다. 이 글에서는 메모리 시스템의 전체 아키텍처부터 최적화 전략까지 깊이 있게 다룹니다.

Claude Code 메모리 시스템 심화

---

1. 메모리 시스템 전체 아키텍처

Claude Code의 메모리는 3계층 구조로 되어 있습니다. 각 계층은 수명과 용도가 다릅니다.

3계층 메모리 구조

계층	메모리 타입	수명	용도
영구 메모리	CLAUDE.md	영구 (삭제 전까지)	프로젝트 규칙, 지침
학습 메모리	Auto Memory	세션 간 지속	발견한 패턴, 학습 내용
세션 메모리	컨텍스트 윈도우	현재 세션만	대화, 파일 내용, 실행 결과

메모리 로드 순서

세션이 시작되면 다음 순서로 메모리가 로드됩니다.

1. 관리 정책 CLAUDE.md (조직 IT 관리)
2. 프로젝트 CLAUDE.md (Git 공유)
3. 개인 CLAUDE.md (~/.claude/)
4. CLAUDE.local.md (개인, .gitignore)
5. .claude/rules/ 규칙 파일들
6. Auto Memory (MEMORY.md + 주제별 파일)
7. 세션 대화 시작

모든 메모리가 로드된 후에야 첫 프롬프트를 처리합니다. 그래서 CLAUDE.md가 길면 시작부터 컨텍스트를 많이 소비합니다.

3계층 메모리 구조

---

2. Auto Memory 심화

5편에서 간략히 소개한 Auto Memory를 깊이 있게 살펴봅니다.

자동 저장 메커니즘

Claude는 세션 중 유용한 패턴을 발견하면 자동으로 메모리에 저장합니다.

저장 시점	저장 내용	예시
빌드 성공 시	올바른 빌드 명령	"npm run build:prod가 정확한 명령"
에러 해결 후	디버깅 패턴	"CORS 에러는 proxy 설정으로 해결"
코드 스타일 발견	프로젝트 관례	"const 선호, var 미사용"
아키텍처 파악	구조 이해	"미들웨어는 /middleware에 위치"
사용자 선호 확인	작업 방식	"커밋 메시지에 이모지 사용"

저장소 구조

~/.claude/projects/<프로젝트명>/memory/
├── MEMORY.md              ← 핵심 메모리 (매 세션마다 로드)
├── debugging.md           ← 디버깅 패턴 모음
├── patterns.md            ← 코딩 패턴
├── api-conventions.md     ← API 설계 결정
└── [기타 주제별 파일]

MEMORY.md의 200줄 제한

MEMORY.md는 매 세션 시작 시 자동으로 컨텍스트에 로드됩니다. 컨텍스트 절약을 위해 200줄로 제한됩니다.

• 200줄 초과 시: Claude가 자동으로 주제별 파일로 분산
• 주제별 파일은 필요할 때만 참조 (항상 로드되지 않음)
• MEMORY.md에는 가장 중요한 정보만 유지

자동 저장되는 정보 vs 저장되지 않는 정보

자동 저장됨	저장되지 않음
빌드 명령어	코드 내용 자체
코딩 스타일 규칙	API 키/비밀번호
반복 에러와 해결책	기본 언어 문법
아키텍처 결정	개인 정보
사용자 작업 선호도	임시 디버깅 로그

Auto Memory 활성화/비활성화

// .claude/settings.json
{
  "autoMemoryEnabled": false
}

또는 환경 변수:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

대부분의 경우 Auto Memory를 켜두는 것이 유리합니다. Claude가 프로젝트를 점점 더 잘 이해하게 됩니다.

 

Auto Memory 심화

---

3. 컨텍스트 윈도우 관리

Claude Code는 200K 토큰 컨텍스트 윈도우를 사용합니다. 이 공간을 어떻게 관리하느냐가 성능에 직접 영향을 미칩니다.

컨텍스트 분배 현황

구성 요소	예상 토큰	비고
시스템 프롬프트	~10K	Claude Code 핵심 지침
CLAUDE.md 파일들	1~5K	짧을수록 좋음
Auto Memory	1~3K	MEMORY.md 200줄
MCP 도구 정의	0~10K	연결된 서버 수에 비례
사용 가능한 공간	~170K	대화, 파일, 결과에 사용

/context 커맨드

현재 컨텍스트 사용량을 시각적으로 확인합니다.

> /context

컨텍스트 사용량: 45,000 / 200,000 토큰 (22%)
├── 시스템 프롬프트: 10,000
├── CLAUDE.md: 2,500
├── Auto Memory: 1,200
├── 도구 정의: 5,300
└── 대화 기록: 26,000

/compact 커맨드의 동작 원리

/compact는 3단계로 대화를 압축합니다.

1단계: 분석

• 현재 대화에서 중요한 결정, 코드 변경, 컨텍스트를 식별

2단계: 요약

• 중요한 내용은 보존하고, 반복적이거나 불필요한 대화를 요약

3단계: 교체

• 기존 대화를 요약본으로 교체하여 컨텍스트 확보

포커스 지시 활용

/compact에 포커스 지시를 주면 특정 주제만 보존합니다.

> /compact API 인증 관련 결정만 유지

> /compact 데이터베이스 스키마 변경사항에 집중

> /compact 테스트 실패 원인 분석만 남기기

포커스 지시가 없으면 Claude가 자동으로 중요도를 판단합니다.

자동 압축 (Auto-Compaction)

컨텍스트가 95% 이상 차면 Claude가 자동으로 압축합니다.

• 수동 /compact와 동일한 방식으로 동작
• 중요한 결정과 코드 변경은 보존
• 반복적인 대화, 긴 파일 출력 등은 요약

팁: 자동 압축에 의존하기보다 적절한 시점에 수동으로 /compact를 실행하는 것이 좋습니다. 포커스 지시를 줄 수 있어서 원하는 내용을 더 정확히 보존할 수 있습니다.

 

컨텍스트 윈도우 관리

---

4. 세션 간 메모리 지속성

Claude Code에서 세션이 끝나면 무엇이 유지되고 무엇이 사라지는지 이해하는 것이 중요합니다.

세션 종료 시 유지/소멸

유지됨	소멸됨
CLAUDE.md 파일	대화 컨텍스트
Auto Memory (MEMORY.md 등)	파일 읽기 결과
세션 히스토리 (로그)	명령 실행 결과
파일 변경사항 (디스크)	중간 사고 과정
Git 커밋	임시 변수, 상태

세션 재개 (/resume)

/resume으로 이전 세션을 재개하면:

1. 세션 히스토리 로드: 이전 대화 내용을 컨텍스트에 복원
2. CLAUDE.md 재로드: 최신 버전으로 다시 읽기
3. Auto Memory 재로드: 이전 세션에서 저장된 학습 포함

# 최근 세션 바로 이어서
$ claude -c

# 이름으로 세션 찾기
$ claude --resume auth-fix

# 세션 목록에서 선택
$ claude --resume

세션 히스토리 관리

세션 히스토리는 ~/.claude/projects/<프로젝트>/ 디렉토리에 JSONL 형식으로 저장됩니다.

항목	설명
저장 형식	JSONL (한 줄 JSON)
저장 위치	~/.claude/projects/<프로젝트>/
세션 이름	/rename으로 지정 가능
검색	/resume에서 키워드 검색
삭제	파일 직접 삭제

세션 간 메모리 지속성

---

5. /memory 커맨드 상세

/memory는 Claude Code의 메모리 상태를 확인하고 관리하는 통합 인터페이스입니다.

주요 기능

기능	설명
로드된 파일 확인	현재 세션에 로드된 모든 CLAUDE.md와 메모리 파일 목록
파일 편집	에디터로 CLAUDE.md나 MEMORY.md 열기
메모리 폴더 열기	Auto Memory 저장소 직접 탐색
Auto Memory 토글	자동 메모리 활성화/비활성화

사용 예시

> /memory

로드된 메모리 파일:
1. ./CLAUDE.md (프로젝트)
2. ~/.claude/CLAUDE.md (개인)
3. ~/.claude/projects/myapp/memory/MEMORY.md (자동 메모리)

[1] 편집  [2] 편집  [3] 편집  [A] Auto Memory 토글  [F] 폴더 열기

메모리 직접 편집

Auto Memory가 잘못된 정보를 저장했을 때:

> /memory
→ MEMORY.md 선택
→ 에디터에서 잘못된 내용 수정 또는 삭제
→ 저장

Claude에게 "이 정보를 기억해줘" 또는 "이 정보를 잊어줘"라고 직접 요청할 수도 있습니다.

 

메모리 커맨드

---

6. 메모리 스코프: 프로젝트 vs 개인 vs 조직

3가지 메모리 스코프

스코프	저장 위치	적용 범위	관리자
조직	/etc/claude-code/	모든 사용자	IT 관리자
개인	~/.claude/	모든 프로젝트	본인
프로젝트	./CLAUDE.md, .claude/	현재 프로젝트	팀원 모두

팀에서의 메모리 관리 전략

신규 팀원 온보딩

# CLAUDE.md - 신규 팀원이 바로 사용 가능

## 빌드
- npm install → npm run dev

## 핵심 규칙
- TypeScript strict mode
- PR 전 lint 통과 필수

## 아키텍처
- 프론트: src/components/
- API: src/api/
- 모델: src/models/

신규 팀원이 claude를 실행하면 바로 프로젝트 규칙을 파악합니다.

팀 규칙 + 개인 설정 분리

팀 공유 (Git 커밋)         개인 설정 (.gitignore)
├── CLAUDE.md              ├── CLAUDE.local.md
├── .claude/rules/         └── ~/.claude/CLAUDE.md
│   ├── code-style.md
│   └── testing.md

조직 정책 배포

대규모 팀에서는 관리 정책으로 보안 규칙을 강제합니다.

# Linux/macOS
/etc/claude-code/CLAUDE.md

# Windows
C:\Program Files\ClaudeCode\CLAUDE.md

• MDM, Ansible, Group Policy 등으로 배포
• 개인이 제외할 수 없음 (최우선 적용)

메모리 스코프

---

7. 메모리 최적화 팁

컨텍스트 절약 7가지 방법

방법	절약 효과	설명
CLAUDE.md 간결하게	높음	200줄 미만 유지
불필요한 MCP 제거	높음	도구 정의가 컨텍스트 소비
서브에이전트 활용	높음	탐색 작업을 별도 컨텍스트에서
/compact 정기 사용	중간	불필요한 대화 기록 정리
@import로 분리	중간	필요한 내용만 선택적 로드
큰 파일 부분 읽기	중간	파일 전체 대신 필요한 부분만
Auto Memory 정리	낮음	오래된 학습 내용 제거

서브에이전트 활용

코드 탐색 작업을 서브에이전트에 위임하면, 메인 컨텍스트를 절약할 수 있습니다.

# 서브에이전트에게 탐색 위임
> 이 프로젝트의 인증 로직을 분석해줘

Claude가 자동으로 서브에이전트 생성
→ 서브에이전트가 별도 컨텍스트에서 파일 탐색
→ 결과 요약만 메인 컨텍스트에 반영

서브에이전트는 독립된 컨텍스트 윈도우를 사용하므로, 수십 개 파일을 읽어도 메인 컨텍스트에는 요약만 전달됩니다.

불필요한 MCP 서버 제거

MCP 서버를 연결하면 각 서버의 도구 정의가 컨텍스트를 소비합니다.

// .claude/settings.json - 필요한 서버만 유지
{
  "mcpServers": {
    "github": { ... },     // 필수: GitHub 연동
    // "slack": { ... },   // 불필요: 제거
    // "notion": { ... },  // 불필요: 제거
  }
}

사용하지 않는 MCP 서버는 제거하세요. 서버당 1~5K 토큰을 절약할 수 있습니다.

 

메모리 최적화

 

---

8. 메모리 관련 트러블슈팅

Claude가 규칙을 무시해요

원인 진단:
1. /memory → 파일이 로드되었는지 확인
2. 규칙이 모호하지 않은지 검토
3. CLAUDE.md 길이 확인 (200줄 초과?)
4. 상충하는 규칙이 없는지 확인
5. 컨텍스트가 가득 차서 압축된 건 아닌지 확인

해결:
→ 규칙을 더 구체적으로 작성
→ CLAUDE.md를 간결하게 줄이기
→ 중요한 규칙은 settings.json으로 강제

컨텍스트가 부족해요

즉시 대응:
1. /context → 사용량 확인
2. /compact [포커스 지시] → 불필요한 기록 정리
3. 새 세션 시작 (/clear)

예방:
→ 큰 파일은 부분만 읽기 요청
→ 서브에이전트로 탐색 위임
→ 불필요한 MCP 서버 제거
→ CLAUDE.md 간결하게 유지

Auto Memory에 잘못된 정보가 있어요

방법 1: /memory → 파일 직접 편집 → 잘못된 내용 삭제

방법 2: Claude에게 요청
> "MEMORY.md에서 Python 3.8 관련 정보를 삭제해줘.
   이 프로젝트는 Python 3.11을 사용해."

방법 3: 파일 시스템에서 직접 수정
~/.claude/projects/<프로젝트>/memory/MEMORY.md

세션 재개가 안 돼요

1. claude --resume → 세션 목록 확인
2. 세션 이름이 있다면: claude --resume 세션이름
3. 히스토리 폴더 확인:
   ~/.claude/projects/<프로젝트>/
4. 파일이 없다면: 세션이 정상 종료되지 않았을 수 있음

---

9. 메모리 시스템의 한계와 주의점

CLAUDE.md는 강제가 아닌 권장

CLAUDE.md에 "절대 .env를 읽지 마세요"라고 써도, Claude가 100% 따르는 것은 보장되지 않습니다.

방법	강제력	예시
CLAUDE.md	권장 (따르려 노력)	".env 읽지 마세요"
settings.json	강제 (물리적 차단)	deny: ["Read(.env*)"]
Hooks	강제 (실행 차단)	PreToolUse에서 차단

정말 중요한 규칙은 CLAUDE.md + settings.json + Hooks를 함께 사용하세요.

컨텍스트 윈도우 한계

• 200K 토큰은 넉넉해 보이지만, 큰 파일 몇 개를 읽으면 금방 찹니다
• 시스템 프롬프트, CLAUDE.md, MCP 도구 정의 등이 기본으로 소비
• 실제 대화에 사용 가능한 공간은 ~170K 정도

세션 간 완벽한 연속성은 없음

• /resume으로 세션을 재개해도, 이전 세션의 모든 맥락이 복원되지는 않습니다
• 매우 긴 세션은 재개 시 일부가 요약될 수 있음
• 중요한 결정이나 맥락은 CLAUDE.md나 Auto Memory에 저장해두는 것이 안전

한계

---

10. 메모리 관리 체크리스트

프로젝트 시작 시

□ /init으로 CLAUDE.md 생성
□ 프로젝트 특수 규칙 추가
□ .gitignore에 CLAUDE.local.md 추가
□ 팀원과 CLAUDE.md 공유 (Git 커밋)
□ 불필요한 MCP 서버 제거

주간 유지보수

□ /memory로 Auto Memory 확인
□ 잘못된 학습 내용 수정
□ CLAUDE.md 길이 확인 (200줄 미만?)
□ /context로 컨텍스트 효율 점검

장기 관리

□ 프로젝트 변화에 따라 CLAUDE.md 업데이트
□ 오래된 .claude/rules/ 파일 정리
□ Auto Memory 주제별 파일 정리
□ 팀 규칙 변경 시 CLAUDE.md 반영

메모리 관리 체크리스트

---

마무리

Claude Code 메모리 시스템의 핵심을 정리하면:

1. 3계층 구조: 영구(CLAUDE.md) → 학습(Auto Memory) → 세션(컨텍스트)
2. Auto Memory: Claude가 자동으로 학습, MEMORY.md 200줄 제한, 주제별 분산
3. 컨텍스트 관리: /context로 확인, /compact로 압축, 포커스 지시 활용
4. 세션 지속성: CLAUDE.md와 Auto Memory는 유지, 대화 컨텍스트는 소멸
5. 최적화: CLAUDE.md 간결하게, MCP 서버 정리, 서브에이전트 활용

메모리 시스템을 잘 활용하면 Claude Code가 프로젝트를 깊이 이해하는 장기 파트너가 됩니다. 세션이 바뀌어도 프로젝트 규칙, 코딩 패턴, 아키텍처 결정을 기억하고 일관된 작업을 수행합니다.

다음 편에서는 권한 시스템 완전정리를 다룹니다. Normal, Auto-Accept, Plan 모드의 차이와 세밀한 권한 설정 방법을 살펴봅니다.

---

이전 글: [5편] CLAUDE.md 작성법: 프로젝트 맞춤 AI 만들기
다음 글: [7편] 권한 시스템 완전정리: 안전하게 AI와 협업하기

---

면책 조항: 본 글은 교육 목적의 정보 제공용이며, Claude Code의 기능 및 요금제는 Anthropic의 정책에 따라 변경될 수 있습니다. 최신 정보는 공식 문서(docs.anthropic.com)를 참고하세요.