[공식문서읽기] Claude Code 메모리 관리 완벽 가이드 - Auto Memory와 CLAUDE.md 활용법

개요

Claude Code를 사용하다 보면 매번 같은 지시를 반복하는 자신을 발견하게 됩니다. "우리 프로젝트는 pnpm을 써", "테스트는 vitest로 돌려" 같은 말을 세션마다 반복하고 있다면, Claude Code의 메모리 기능을 활용할 때입니다.

Claude Code는 세션 간에 지속되는 두 가지 메모리 시스템을 제공합니다. 하나는 개발자가 직접 작성하는 CLAUDE.md 파일이고, 다른 하나는 Claude가 스스로 학습 내용을 기록하는 Auto Memory입니다. 이 글에서는 공식 문서를 바탕으로 두 메모리 시스템의 구조, 활용법, 그리고 실전 팁까지 상세히 다뤄보겠습니다.

---

Claude Code의 두 가지 메모리 타입

Claude Code는 세션이 끝나도 사라지지 않는 두 가지 메모리를 가지고 있습니다.

CLAUDE.md 파일

개발자가 직접 작성하고 관리하는 마크다운 파일입니다. Claude에게 지시할 규칙, 프로젝트 컨벤션, 자주 쓰는 명령어 등을 기록해두면 매 세션 시작 시 자동으로 로드됩니다.

• 프로젝트 아키텍처 설명
• 코딩 스타일 규칙
• 빌드/테스트/린트 명령어
• 팀 공통 워크플로우

Auto Memory

Claude가 작업하면서 스스로 기록하는 자동 메모리입니다. CLAUDE.md가 "개발자가 Claude에게 쓰는 지시"라면, Auto Memory는 "Claude가 자기 자신에게 쓰는 메모"입니다.

• 프로젝트 패턴: 빌드 명령어, 테스트 컨벤션, 코드 스타일
• 디버깅 인사이트: 까다로운 문제의 해결책, 자주 발생하는 에러 원인
• 아키텍처 노트: 주요 파일, 모듈 관계, 중요한 추상화
• 개발자 선호: 커뮤니케이션 스타일, 워크플로우 습관, 도구 선택

Auto Memory는 기본적으로 활성화되어 있으며, /memory 명령으로 켜고 끌 수 있습니다.

• 위치: ~/.claude/projects/<project>/memory/
• 용도: 프로젝트 패턴, 디버깅 인사이트, 아키텍처 노트

---

Auto Memory 작동 방식 상세

저장 구조

각 프로젝트마다 고유한 메모리 디렉토리를 가집니다. <project> 경로는 git 저장소 루트에서 파생되므로, 같은 저장소 내의 모든 하위 디렉토리가 하나의 Auto Memory 디렉토리를 공유합니다.

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 핵심 인덱스 (매 세션 로드)
├── debugging.md       # 디버깅 패턴 상세 노트
├── api-conventions.md # API 설계 결정 사항
└── ...                # Claude가 생성하는 추가 토픽 파일

로딩 메커니즘

• MEMORY.md의 처음 200줄만 매 세션 시작 시 시스템 프롬프트에 로드됩니다
• 200줄을 초과하는 내용은 자동 로드되지 않습니다
• debugging.md, patterns.md 같은 토픽 파일은 시작 시 로드되지 않고, Claude가 필요할 때 파일 도구로 읽습니다
• MEMORY.md는 메모리 디렉토리의 인덱스 역할을 합니다

관리 방법

Auto Memory 파일은 일반 마크다운 파일이므로 언제든 직접 편집할 수 있습니다. (/memory 명령 활용)

세션 중 /memory 명령을 사용하면 시스템 에디터에서 메모리 파일을 열 수 있습니다. CLAUDE.md 파일과 Auto Memory 항목이 함께 표시되며, Auto Memory 토글도 포함되어 있습니다.

 

Claude에게 직접 지시

특정 내용을 기억하게 하려면 직접 말하면 됩니다.

"pnpm을 사용한다고 기억해"
"API 테스트에 로컬 Redis 인스턴스가 필요하다고 메모리에 저장해"

 

설정으로 비활성화

모든 프로젝트에서 비활성화하려면 사용자 설정에 추가합니다.

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

특정 프로젝트에서만 비활성화하려면 프로젝트 설정에 추가합니다.

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

환경 변수로 모든 설정을 오버라이드할 수도 있습니다. CI나 관리형 환경에 유용합니다.

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1  # 강제 비활성화
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0  # 강제 활성화

---

마무리

Claude Code의 메모리 시스템은 단순한 설정 파일을 넘어서, 개발 워크플로우의 지속적인 개선을 가능하게 합니다. CLAUDE.md로 팀의 컨벤션을 공유하고, Auto Memory로 Claude가 프로젝트를 점점 더 잘 이해하게 만들 수 있습니다.

이 메모리 시스템을 제대로 활용하면, Claude Code는 세션이 바뀌어도 마치 같은 팀원처럼 프로젝트를 이해하고 일관된 결과를 제공할 것입니다.

---

참고 자료

• Manage Claude's memory - Claude Code 공식 문서
• Claude Code GitHub Repository

이 글은 Claude Code를 활용하여 작성되었습니다.