메모리 시스템

Claude Code는 세션이 끝나면 대화 내용을 기억하지 않습니다. 하지만 이를 보완하는 6가지 메모리 계층이 있습니다. 이 시스템을 잘 활용하면 매번 처음부터 설명하는 번거로움 없이 일관된 AI 파트너를 유지할 수 있습니다.

메모리 계층 구조

┌─────────────────────────────────────────────────────────────┐
│  관리형 정책      (시스템 경로/CLAUDE.md)                      │
│  ─ 조직 전체 강제, IT/DevOps 관리, 최고 우선순위              │
├─────────────────────────────────────────────────────────────┤
│  사용자 메모리    (~/.claude/CLAUDE.md, ~/.claude/rules/)     │
│  ─ 개인 전역 설정, 모든 프로젝트에 적용                       │
├─────────────────────────────────────────────────────────────┤
│  프로젝트 메모리  (./CLAUDE.md, .claude/CLAUDE.md)            │
│  ─ 팀 전체 공유, git 커밋, 영구 유지                         │
├─────────────────────────────────────────────────────────────┤
│  프로젝트 규칙    (.claude/rules/*.md)                        │
│  ─ 모듈화된 주제별 규칙, 경로별 조건부 적용                    │
├─────────────────────────────────────────────────────────────┤
│  로컬 메모리      (./CLAUDE.local.md)                         │
│  ─ 개인 프로젝트별, git 미추적                               │
├─────────────────────────────────────────────────────────────┤
│  자동 메모리      (~/.claude/projects/<project>/memory/)      │
│  ─ Claude가 자동으로 저장, 프로젝트별 학습 결과               │
└─────────────────────────────────────────────────────────────┘

모든 메모리는 세션 시작 시 자동 로드됩니다. 더 구체적인(좁은 범위의) 지시가 더 넓은 범위의 지시보다 우선합니다.

1. 관리형 정책 (Enterprise)

조직 관리자가 시스템 레벨에서 배포하는 CLAUDE.md입니다. 모든 사용자에게 강제 적용되며, 어떤 설정으로도 재정의할 수 없습니다.

OS	경로
macOS	`/Library/Application Support/ClaudeCode/CLAUDE.md`
Linux	`/etc/claude-code/CLAUDE.md`
Windows	`C:\Program Files\ClaudeCode\CLAUDE.md`

MDM, Group Policy, Ansible 등의 구성 관리 시스템으로 배포합니다.

2. 사용자 메모리

저장 위치: ~/.claude/CLAUDE.md (Windows: C:\Users\{이름}\.claude\CLAUDE.md) 유지 기간: 영구 적용 범위: 내 모든 프로젝트

사용자 메모리에 저장할 것

# 개인 설정

## 코딩 스타일 선호
- 함수형 프로그래밍 선호
- 짧은 변수명 싫어함 (i, j, k 같은 것 피해줘)
- 주석은 "왜"에 집중 (무엇은 코드로 표현)

## 소통 방식
- 코드 변경 전 반드시 계획 먼저 설명해줘
- 한 번에 너무 많이 바꾸지 말고 단계적으로

## 자주 쓰는 기술
- Next.js, TypeScript, Prisma 주로 씀
- 테스트는 Vitest 선호
- 스타일은 Tailwind CSS

사용자 레벨 규칙

~/.claude/rules/에 개인 규칙 파일을 만들면 모든 프로젝트에 적용됩니다:

~/.claude/rules/
├── preferences.md    # 개인 코딩 선호도
└── workflows.md      # 선호 워크플로우

전역 메모리 초기 설정

처음 Claude Code를 설치했다면 전역 CLAUDE.md부터 만드세요:

mkdir -p ~/.claude
claude
> 내 코딩 스타일과 선호도 인터뷰해줘. ~/.claude/CLAUDE.md에 저장해줘.

Claude Code가 몇 가지 질문을 하고 전역 설정을 만들어줍니다.

3. 프로젝트 메모리: CLAUDE.md

저장 위치: {프로젝트 루트}/CLAUDE.md 또는 .claude/CLAUDE.md 유지 기간: 영구 (git에 커밋) 적용 범위: 해당 프로젝트의 모든 팀원

CLAUDE.md 작성법 챕터에서 자세히 다룹니다.

프로젝트 메모리에 저장할 것

# My Project

## 기술 스택
[영구적인 기술 스택 정보]

## 팀 컨벤션
[팀 전체가 공유해야 할 규칙]

## 아키텍처 결정사항 (ADR)
[중요한 기술 결정과 이유]

## 빌드/테스트 커맨드
[자주 사용하는 명령어 — 반복 검색 방지]

/init으로 자동 생성

/init 커맨드로 현재 프로젝트에 맞는 CLAUDE.md를 자동 생성할 수 있습니다.

4. 프로젝트 규칙: `.claude/rules/`

대규모 프로젝트에서는 하나의 CLAUDE.md 대신 모듈화된 규칙 파일로 관리합니다.

.claude/rules/
├── code-style.md      # 코드 스타일
├── testing.md         # 테스트 규칙
├── frontend/
│   ├── react.md       # React 컨벤션
│   └── styles.md      # 스타일 가이드
└── backend/
    └── api.md         # API 규칙

YAML frontmatter의 paths 필드로 특정 파일에서만 적용되는 조건부 규칙도 가능합니다:

---
paths:
  - "src/api/**/*.ts"
---

# API 개발 규칙
- 모든 엔드포인트에 입력 검증 포함
- 표준 에러 응답 형식 사용

자세한 내용은 CLAUDE.md 작성법 → .claude/rules/ 섹션을 참고하세요.

5. 로컬 메모리: CLAUDE.local.md

저장 위치: {프로젝트 루트}/CLAUDE.local.md 유지 기간: 영구 (로컬에서만) 적용 범위: 나만, 이 프로젝트에서만

자동으로 .gitignore에 추가되므로 개인 정보를 안전하게 저장할 수 있습니다. 팀에 공유하기 전에 지시사항을 테스트하거나, 머신별 설정을 저장할 때 유용합니다.

6. Auto Memory: Claude의 자동 메모리

Auto Memory는 Claude가 작업하면서 스스로 발견한 학습·패턴·인사이트를 자동으로 저장하는 기능입니다. CLAUDE.md와 달리 사용자가 작성하는 것이 아니라 Claude가 자신을 위해 기록하는 노트입니다.

기본 활성화

Auto Memory는 기본으로 활성화되어 있습니다. /memory 커맨드에서 토글로 켜고 끌 수 있습니다.

Claude가 기억하는 것

프로젝트 패턴: 빌드 커맨드, 테스트 컨벤션, 코드 스타일
디버깅 인사이트: 까다로운 문제의 해결책, 흔한 에러 원인
아키텍처 노트: 핵심 파일, 모듈 관계, 중요한 추상화
사용자 선호: 소통 스타일, 워크플로우 습관, 도구 선택

Auto Memory 파일 구조

각 프로젝트마다 별도의 메모리 디렉토리를 가집니다:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 간결한 인덱스 (세션마다 자동 로드)
├── debugging.md       # 디버깅 패턴 상세 노트
├── api-conventions.md # API 설계 결정사항
└── ...                # Claude가 필요에 따라 생성

<project> 경로는 git 저장소 루트에서 파생됩니다. 같은 git 저장소의 모든 워크트리와 서브디렉토리는 하나의 Auto Memory 디렉토리를 공유합니다.

MEMORY.md의 200줄 제한

MEMORY.md의 처음 200줄만 세션 시작 시 자동 로드됩니다. 200줄을 초과하는 내용은 로드되지 않습니다. Claude는 자동으로 상세 노트를 별도 주제 파일(예: debugging.md, patterns.md)로 분리하여 MEMORY.md를 간결하게 유지합니다.

주제 파일은 세션 시작 시 로드되지 않고, Claude가 필요할 때 직접 읽어옵니다.

Auto Memory 관리

/memory     # 메모리 파일 열기 + 토글

Claude에게 직접 저장을 지시할 수도 있습니다:

> pnpm을 사용하는 프로젝트라는 거 기억해줘
> API 테스트에 로컬 Redis가 필요하다는 거 메모리에 저장해줘

Auto Memory 비활성화

// ~/.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  # 강제 활성화

Auto-dream: 메모리 자동 정리 (비공식·미문서 기능)

공식 미문서 + UI 토글 회수 정황 (2026-04-23 기준)

Auto-dream은 앤트로픽 공식 문서(code.claude.com/docs/en/memory·/settings·/changelog v2.1.117까지)에 등재되지 않은 기능입니다. Anthropic의 출시 계획·롤아웃 정책은 미발표 — 본 챕터는 외부 사용자 보고와 GitHub Issue를 종합한 것입니다.

관찰된 노출 변화 (CEO 직접 확인):

시점	환경	`/memory` 토글
약 1개월 전 (v2.1.81 무렵)	macOS	✅ "Auto-dream: on · never · /dream to run" 표시
현재 (v2.1.117)	Windows	❌ "Auto-memory: on"만 표시, Auto-dream 토글 사라짐

changelog에는 회수·deprecation 공지 없음. settings.json autoDreamEnabled 키만 잔존하나 작동 여부 불명. 시청자 환경에서 토글이 안 보이는 게 일반적이라고 가정하는 게 안전합니다.

Auto Memory가 학습 내용을 저장한다면, Auto-dream은 쌓인 메모리를 정리하는 백그라운드 작업입니다. 중복 제거·관련 내용 병합·오래된 정보 통합을 자동 수행합니다.

현재 확인된 상태:

항목	상태
백그라운드 메모리 정리 동작	✅ 작동 확인됨 (사용자 보고 다수)
`~/.claude/settings.json`에 `autoDreamEnabled: true` 키	✅ 일부 환경에서 인식
`/memory` 메뉴 "AutoDream" 토글 노출	⚠️ 사용자별 차이 (Anthropic 노출 기준 미공개)
상태바 `dreaming` 표시	❌ 미구현·버그 보고됨 (Issue #38461)
수동 트리거 `/dream` 명령	❌ "Unknown skill" 반환 — 미구현 (Issue #38426)

활성화 시도 방법:

/memory 명령 실행 → "AutoDream" 토글이 보이면 켜기
토글이 안 보이는 경우 ~/.claude/settings.json에 직접 추가:
```
{ "autoDreamEnabled": true }
```
일부 환경에서는 위 설정만으로 동작하지 않을 수 있음 (Anthropic 활성화 조건 미공개)

동작 메커니즘 (외부 보고 종합 — 공식 확인 없음):

시스템 프롬프트에 "You are performing a dream — a reflective pass over your memory files" 문구가 빌드되어 있다고 보고됨 (출처: Sakeeb Rahman Threads 분석)
백그라운드에서 서브에이전트가 메모리 파일 review → 중복 제거 → 최신화 → 토픽 파일 재구성 (출처: 다수 외부 빌더 보고)
트리거 조건: 세션 수 + 시간 이중 조건 보고 (출처: Tessl·Skool 블로그)
소요 시간 예시: 913 세션 메모리 통합에 약 8~9분 보고 사례 1건 (출처: Antonio Cortes 블로그 게시)

위 4건 모두 외부 사용자·빌더 보고로 Anthropic 공식 확인이 없습니다. 환경·버전에 따라 다를 수 있습니다.

확인된 외부 보고 출처:

v2.1.83+ 사용자 환경에서 /memory 토글 노출 보고 다수
Tessl 블로그: "Anthropic tests 'auto dream'" (테스트 단계 표현)
영어권 빌더 콘텐츠 10여 건 확인됨 (한국어 시장 점유 여부는 미조사)

영상·콘텐츠 인용 시 필수 표기

Auto-dream은 공식 출시 기능이 아닙니다 (Anthropic 공식 docs·news·changelog·support 어디에도 등재 없음, 2026-04-22 기준). 인용 시 다음 3가지를 반드시 함께 표기해야 안전합니다:

"공식 미문서·점진 롤아웃 중"
"환경에 따라 토글이 안 보일 수 있음"
"수동 트리거 /dream·상태바 표시는 현재 버그 상태 (GitHub Issues 38461·38426)"

안정 기능처럼 가르치면 시청자·독자 환경에서 재현 안 돼 신뢰도 손상 위험.

세션 메모리: 대화 컨텍스트

현재 대화창의 내용입니다. 세션이 끝나면 사라집니다.

세션 메모리를 영구화하는 패턴

중요한 결정이나 정보는 세션이 끝나기 전에 저장하세요:

> 오늘 결제 모듈 완성했어.
  중요한 결정사항 있으면 CLAUDE.md에 업데이트해줘.

Claude: CLAUDE.md를 업데이트했습니다:
- 환불 정책: 72시간 내, Stripe API 직접 호출
- 웹훅 시크릿: 환경변수 STRIPE_WEBHOOK_SECRET
- 결제 실패 재시도: 3회, exponential backoff

메모리 계층별 활용 전략

팀 프로젝트

관리형 정책 (IT/DevOps)
  └─ 조직 보안 정책, 코딩 표준

프로젝트 CLAUDE.md (git 커밋)
  └─ 팀 컨벤션, 기술 스택, 아키텍처

.claude/rules/ (git 커밋)
  └─ 주제별 세분화된 규칙

개인 ~/.claude/CLAUDE.md
  └─ 개인 코딩 스타일, 소통 방식

CLAUDE.local.md
  └─ 개인 테스트 환경, 로컬 설정

Auto Memory
  └─ 각자의 작업 패턴, 디버깅 경험

개인 프로젝트

프로젝트 CLAUDE.md
  └─ 프로젝트 현황, 기술 결정사항

개인 ~/.claude/CLAUDE.md
  └─ 전역 설정 (모든 프로젝트에 적용)

Auto Memory
  └─ 프로젝트 패턴, 학습 내용

메모리 관리 팁

`/memory`로 확인과 편집

/memory

/memory 커맨드는 시스템 에디터에서 메모리 파일을 열어주며, Auto Memory 토글도 포함합니다. 로드된 모든 메모리 파일 목록을 확인할 수 있습니다.

정기적으로 CLAUDE.md 업데이트

작업이 완료될 때마다 현황을 업데이트하세요:

> 오늘 작업 끝. CLAUDE.md 현황 섹션 업데이트해줘.

오래된 정보 정리

메모리가 쌓이면 오히려 혼란이 생깁니다:

> CLAUDE.md에서 완료된 항목들 정리해줘.
  현재 진행 중인 것만 남겨.

추가 디렉토리 메모리 로드

--add-dir로 추가한 디렉토리의 CLAUDE.md는 기본적으로 로드되지 않습니다. 로드하려면:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config