Claude : Claude memory guide (CLAUDE.md, MEMORY.md)

Claude Code 메모리 시스템 정리

Claude가 동작하는 순서

1. 시스템 프롬프트 — Anthropic이 정의한 Claude Code 기본 동작 지침
2. CLAUDE.md — 프로젝트/유저 레벨 추가 지침 (있다면 자동 로드)
3. MEMORY.md — 유저 메모리 인덱스 (자동 로드)
4. 유저 요청 처리

---

파일별 특성 비교

구분	자동 로드	범위	특징
~/.claude/CLAUDE.md	O	모든 프로젝트	가장 확실한 지침 전달
/프로젝트/CLAUDE.md	O	해당 프로젝트만	프로젝트별 지침
MEMORY.md	O	해당 프로젝트	인덱스만 자동 로드
개별 메모리 파일	X	해당 프로젝트	Claude가 필요 시 직접 읽음

---

CLAUDE.md

• 매 대화 시작 시 자동으로 컨텍스트에 포함
• ~/.claude/CLAUDE.md에 두면 모든 프로젝트에 적용
• 중요한 지침, 코딩 컨벤션, 작업 방식 등 안정적인 정보에 적합
• 내용이 변하지 않으면 프롬프트 캐싱이 적용되어 반복 토큰 소모 감소
• 파일 위치: ~/.claude/CLAUDE.md

---

MEMORY.md + 개별 메모리 파일

MEMORY.md (인덱스)

• 매 대화마다 자동으로 컨텍스트에 포함
• 개별 메모리 파일들의 목록과 한 줄 설명만 담음
• 내용이 많을수록 토큰 소모 증가
• 파일 위치: ~/.claude/projects/[프로젝트경로]/memory/MEMORY.md

개별 메모리 파일

• 자동 로드 아님 — Claude가 질문을 보고 "관련 있겠다" 판단할 때만 Read 툴로 읽어옴
• 판단 기준: MEMORY.md 인덱스의 한 줄 설명
• 적용이 보장되지 않음 (Claude의 판단에 의존)
• 유저 프로필, 피드백 등 동적으로 변하는 정보에 적합

개별 메모리 파일 적용 과정

유저 질문 수신
    → MEMORY.md 인덱스 확인
    → "이 질문은 [파일명] 내용과 관련 있겠다" 판단
    → Read 툴로 해당 파일 읽기
    → 내용 적용하여 응답

---

결론: 뭘 어디에 써야 하나?

CLAUDE.md에 써야 할 것

• 언제나 적용되어야 하는 중요한 지침
• 코딩 컨벤션, 작업 방식
• 안전 규칙, 금지 행동

메모리에 써야 할 것

• 대화 중 학습된 유저 성향
• 프로젝트별 맥락 정보
• 일시적이거나 동적으로 변하는 정보

---

파일 위치 요약

~/.claude/
├── CLAUDE.md                          # 글로벌 지침 (모든 프로젝트 적용) -> Global CLAUDE.md라고 함.
└── projects/
    └── [프로젝트경로]/
        └── memory/
            ├── MEMORY.md              # 메모리 인덱스 (자동 로드)
            └── [개별메모리파일].md        # 개별 메모리 (필요 시 로드)

/프로젝트경로/
└── CLAUDE.md                          # 프로젝트별 지침