Claude Code 메모리 기능 정리 — CLAUDE.md와 자동 메모리(MEMORY.md) 차이부터 활용까지

Claude Code를 쓰다 보면 같은 설명을 매 세션 반복하게 됩니다. "이 프로젝트는 pnpm 씁니다", "커밋 전에 테스트 돌려주세요" 같은 말을 새 대화를 열 때마다 다시 하고 있다면, 메모리 기능을 안 쓰고 있을 가능성이 높습니다.

이 글은 Claude Code의 메모리가 실제로 어떻게 생겼는지 — 어디에 무엇이 저장되고, 어떻게 확인하고 지우는지 — 제 머신에서 직접 열어본 내용 기준으로 정리한 것입니다.

한 가지 먼저 짚을 점. 여기서 다루는 건 Claude Code(터미널 CLI 도구)의 메모리입니다. claude.ai 웹 챗의 대화 메모리와는 별개 시스템이라, 웹에서 본 설명과 섞이면 헷갈립니다.

메모리는 하나가 아니라 둘입니다

Claude Code의 메모리는 두 가지이고, 역할이 다릅니다.

CLAUDE.md자동 메모리 (MEMORY.md)

누가 쓰나	내가 직접	Claude가 스스로
내용	지시·규칙 ("항상 X 해라")	작업하며 배운 것 (빌드 명령, 디버깅 인사이트, 내 선호)
위치	프로젝트 루트 등	~/.claude/projects/<프로젝트>/memory/

둘 다 매 세션 시작 시 자동으로 로드됩니다. 공식 문서가 명확히 해두는 부분인데, 둘 다 "강제 설정"이 아니라 컨텍스트입니다. Claude가 반드시 따른다는 보장은 없고, 무조건 차단해야 하는 동작은 hook이라는 별도 장치를 써야 합니다.

CLAUDE.md — 내가 쓰는 규칙

CLAUDE.md는 그냥 마크다운 파일입니다. 프로젝트 루트에 만들면 그 프로젝트에서 Claude Code를 열 때마다 읽힙니다.

위치별로 적용 범위가 다릅니다:

~/.claude/CLAUDE.md — 내 모든 프로젝트 공통 (개인 취향)
./CLAUDE.md — 이 프로젝트 (git으로 팀과 공유)
./CLAUDE.local.md — 이 프로젝트, 나만 (.gitignore에 추가)

언제 추가하면 되는지에 대한 공식 가이드 기준이 실용적입니다 — 같은 교정을 두 번째로 입력하게 될 때. Claude가 같은 실수를 반복하거나, 지난 세션에 했던 설명을 또 치고 있다면 그 내용이 CLAUDE.md에 들어갈 후보입니다.

주의할 점 하나: 공식 권장 크기는 200줄 이하입니다. 길어질수록 컨텍스트를 더 먹고, 오히려 준수율이 떨어집니다. 규칙이 많아지면 .claude/rules/ 디렉토리로 주제별로 쪼개고, 특정 파일 패턴에서만 로드되게 스코프를 걸 수 있습니다.

자동 메모리 — Claude가 스스로 쓰는 노트

여기가 이 글에서 제일 보여드리고 싶은 부분입니다. Claude Code v2.1.59 이상이면 자동 메모리가 기본으로 켜져 있고, Claude가 작업하면서 스스로 노트를 남깁니다.

저장 위치는 ~/.claude/projects/<프로젝트>/memory/ 입니다. 직접 열어보면 이렇게 생겼습니다:

memory/
├── MEMORY.md          # 인덱스 (매 세션 로드)
├── feedback_backup_rsync.md
├── feedback_inbox_archived.md
└── ...                # 주제별 토픽 파일

제 머신의 한 프로젝트를 열어보면 MEMORY.md 44줄에 토픽 파일이 43개 쌓여 있습니다. 내용을 보면 이런 식입니다 — "macOS 한글 경로 백업 시 zip 대신 rsync 사용". 언젠가 한 번 백업이 깨져서 교정해줬던 내용인데, 그 뒤로는 매 세션 자동으로 반영됩니다. 같은 말을 다시 한 적이 없습니다.

구조도 단순합니다. MEMORY.md는 처음 200줄(또는 25KB)까지만 세션 시작 시 로드됩니다. 그래서 Claude가 MEMORY.md를 한 줄짜리 인덱스로 짧게 유지하고, 상세 내용은 토픽 파일로 분리해 필요할 때만 읽습니다.

전부 일반 마크다운이라서 직접 열어 읽고, 고치고, 지울 수 있습니다. 블랙박스가 아닙니다.

확인·수정·끄기 — /memory 명령

세션 안에서 /memory를 입력하면:

지금 세션에 로드된 CLAUDE.md·rules 파일 목록 확인
자동 메모리 켜기/끄기 토글
메모리 폴더 바로 열기

저장 내용을 지우고 싶으면 대화로 "이 메모리 지워줘"라고 해도 되고, 파일을 직접 지워도 됩니다.

자동 메모리를 끄는 방법은 세 가지입니다:

/memory에서 토글
settings.json에 "autoMemoryEnabled": false
환경변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

참고로 자동 메모리는 머신 로컬입니다. 다른 컴퓨터나 클라우드와 공유되지 않고, git 저장소 단위로 디렉토리가 잡혀서 같은 repo의 worktree들은 메모리를 공유합니다.

자주 하는 실수

1. CLAUDE.md에 전부 때려넣기. 다단계 절차나 특정 영역에서만 필요한 내용까지 CLAUDE.md에 쌓으면 200줄을 금방 넘깁니다. 매 세션 필요한 사실만 남기고, 나머지는 rules나 skill로 분리하는 게 공식 가이드 방향입니다.

2. 메모리에 저장됐는지 확인 안 하기. "기억해줘"라고 말하면 자동 메모리로, "CLAUDE.md에 추가해줘"라고 명시하면 CLAUDE.md로 갑니다. 어디 저장됐는지 애매하면 /memory로 확인하는 습관이 안전합니다.

3. claude.ai 메모리와 혼동. 웹 챗의 대화 메모리 설명을 보고 Claude Code 동작을 추측하면 어긋납니다. 별개 시스템입니다.

4. 메모리를 강제 규칙으로 착각. 메모리는 컨텍스트일 뿐, 차단 장치가 아닙니다. "절대 하면 안 되는 것"은 hook으로 거는 게 맞습니다.

정리

Claude Code 메모리 = CLAUDE.md(내가 쓰는 규칙) + 자동 메모리(Claude가 쓰는 노트), 매 세션 자동 로드
자동 메모리는 ~/.claude/projects/<프로젝트>/memory/에 일반 마크다운으로 저장 — 열어보고 수정 가능
시작은 간단합니다: 프로젝트 루트에 CLAUDE.md 하나 만들고, 같은 설명을 두 번 하게 되는 순간마다 한 줄씩 옮기면 됩니다

버전 확인은 claude --version (자동 메모리는 v2.1.59 이상), 상세 동작은 공식 문서(code.claude.com/docs/en/memory)에 정리돼 있습니다.

정보를 알려주는 블로그