클로드 코드 메모리 — 자동 저장 위치와 끄는 법
클로드 코드가 스스로 적어 두는 메모(자동 메모리)는 ~/.claude/projects/<프로젝트>/memory/ 폴더에 마크다운 파일로 저장됩니다. 프로젝트마다 폴더가 하나씩 생기고, 그 안의 MEMORY.md가 매 세션 시작 때 자동으로 읽힙니다. 무엇이 저장됐는지 보려면 /memory, 끄려면 설정의 autoMemoryEnabled를 false로 두거나 환경변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 주면 됩니다. 아래에서 저장 위치·로드 한도·삭제 방법을 순서대로 정리합니다. (Claude Code 2.1.x 기준 · 2026년 8월 5일 공식 문서 확인)
1. CLAUDE.md와 자동 메모리는 다른 것이다
둘 다 "메모리"라고 불려서 헷갈리는데, 쓰는 주체가 다릅니다. CLAUDE.md는 내가 써서 클로드에게 지시하는 파일이고, 자동 메모리는 클로드가 작업하면서 스스로 적어 두는 메모입니다. 공식 문서는 둘을 이렇게 갈라 놓습니다.
| CLAUDE.md | 자동 메모리 | |
|---|---|---|
| 누가 쓰나 | 내가 쓴다 | 클로드가 쓴다 |
| 내용 | 지시와 규칙 | 알아낸 것과 패턴 |
| 범위 | 프로젝트 · 사용자 · 조직 | 저장소 단위(워크트리끼리 공유) |
| 로드 | 매 세션, 길이 제한 없이 전체 | 매 세션, 앞 200줄 또는 25KB까지 |
| 쓰임 | 코딩 규칙·작업 절차·아키텍처 | 빌드 명령·디버깅 요령·발견한 선호 |
즉 동작을 강제하고 싶으면 CLAUDE.md, 매번 설명하기 귀찮은 걸 알아서 기억하게 하려면 자동 메모리입니다. CLAUDE.md를 어디에 두고 무엇을 적을지는 claude.md 작성법 글에 위치와 로드 순서까지 정리해 두었습니다.
PreToolUse 훅을 쓰라고 안내합니다.
2. 어디에 저장되나
프로젝트마다 폴더가 하나씩 생깁니다.
~/.claude/projects/<프로젝트>/memory/
├── MEMORY.md # 목차 역할. 매 세션 자동 로드
├── debugging.md # 주제별 상세 노트
├── api-conventions.md
└── ...내 컴퓨터에 어떤 프로젝트 메모리가 쌓여 있는지는 한 줄로 볼 수 있습니다.
ls -d ~/.claude/projects/*/memory여기서 알아 둘 점이 셋입니다.
<프로젝트>이름은 git 저장소를 기준으로 정해집니다. 그래서 같은 저장소의 워크트리와 하위 폴더는 메모리 폴더 하나를 같이 씁니다. git 저장소 밖에서 실행하면 그 폴더 자체가 기준이 됩니다.- 머신 로컬입니다. 다른 PC나 클라우드 환경으로 따라가지 않습니다. 팀원과 공유되지도 않습니다.
- 위치를 바꾸고 싶으면
settings.json에autoMemoryDirectory를 지정합니다. 값은 절대경로거나~/로 시작해야 합니다.
{
"autoMemoryDirectory": "~/my-custom-memory-dir"
}단, 이 값을 프로젝트 설정(.claude/settings.json)에 넣었다면 그 폴더의 워크스페이스 신뢰 대화상자를 수락한 뒤에야 적용됩니다. 훅과 같은 관문을 통과해야 한다는 뜻입니다.
3. 세션 시작 때 실제로 로드되는 양
메모리 폴더 전체가 매번 읽히는 게 아닙니다. MEMORY.md의 앞 200줄, 또는 25KB 중 먼저 걸리는 쪽까지만 세션 시작 시 로드됩니다. 그 뒤 내용은 안 들어갑니다.
| 파일 | 언제 읽히나 |
|---|---|
MEMORY.md |
매 세션 시작 (앞 200줄 / 25KB 한도) |
주제별 파일(debugging.md 등) |
시작 때 안 읽음. 필요할 때 클로드가 직접 열어 본다 |
그래서 MEMORY.md는 목차처럼 짧게 유지되고, 상세한 내용은 주제별 파일로 빠집니다. 한도를 넘기면 쓰기는 성공하지만 다음 로드 때 넘친 부분이 잘리므로, 클로드 코드가 인덱스를 다시 정리하라는 오류를 돌려줍니다.
참고로 YAML 프론트매터와 블록 주석은 한도 계산에서 빠집니다. 로드되는 본문만 재기 때문입니다. 이 계산 방식은 v2.1.211부터이고, 그 전에는 파일 원본을 그대로 재서 프론트매터 때문에 한도에 걸리는 일이 있었습니다.
세션 중에 무엇이 실제로 컨텍스트에 올라왔는지는 /context로 확인합니다. 컨텍스트가 어떻게 차고 어떻게 비우는지는 클로드 코드 컨텍스트 관리 글에서 /compact와 /clear를 갈라 정리했습니다.
4. 무엇이 저장됐는지 보고 지우는 법
저장된 것은 전부 평범한 마크다운 파일이라 언제든 열어 고치거나 지울 수 있습니다. 세션 안에서 보려면 /memory를 실행하고 자동 메모리 폴더를 고릅니다.
/memory가 하는 일은 셋입니다.
- CLAUDE.md·CLAUDE.local.md를 비롯한 메모리 파일 위치를 사용자·프로젝트 범위로 나열한다 (아직 없는 파일도 목록에 뜨고, 고르면 만들어 준다)
- 자동 메모리를 켜고 끄는 토글을 제공한다
- 자동 메모리 폴더를 열어 준다
통째로 지우고 싶으면 폴더째 삭제하면 됩니다. 특정 프로젝트만 초기화하려면 해당 폴더만 지웁니다.
# 먼저 무엇이 들었는지 눈으로 본다
ls -la ~/.claude/projects/<프로젝트>/memory/
# 확인한 뒤 그 프로젝트의 메모리만 지운다
rm -rf ~/.claude/projects/<프로젝트>/memory/rm -rf는 되돌릴 수 없습니다. 지우기 전에 ls로 대상 경로가 맞는지 반드시 확인하세요. ~/.claude/projects/ 아래에는 메모리 말고 세션 기록도 있으므로, 경로 끝의 /memory/까지 붙었는지 보고 실행합니다.
"항상 pnpm을 쓴다" 같은 걸 기억시키고 싶으면 그냥 대화에서 말하면 자동 메모리에 들어갑니다. 반대로 CLAUDE.md에 넣고 싶다면 "이건 CLAUDE.md에 추가해 줘"라고 짚어 말해야 합니다.
5. 자동 메모리 끄는 법 세 가지
기본값은 켜짐입니다. 끄는 방법이 범위별로 셋 있습니다.
| 방법 | 적용 범위 | 비고 |
|---|---|---|
/memory의 토글 |
사용자 전체 | ~/.claude/settings.json에 autoMemoryEnabled로 저장된다 |
"autoMemoryEnabled": false |
그 설정 파일의 범위 | 프로젝트 설정에 넣으면 그 프로젝트만 끈다 |
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 |
그 셸·프로세스 | 0으로 주면 반대로 강제로 켠다 |
# 이 프로젝트에서만 끄기 — .claude/settings.json
{
"autoMemoryEnabled": false
}
# 이번 실행에서만 끄기
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude환경변수의 0 쪽이 유용합니다. --bare 모드거나 설정에서 autoMemoryEnabled: false로 꺼 둔 상황에서도 이번만 켜서 쓸 수 있습니다. 껐을 때는 클로드가 메모리 파일을 만들지도, 읽지도 않습니다.
자주 묻는 질문 (FAQ)
Q. 다른 컴퓨터에서도 같은 메모리를 쓸 수 있나요?
아닙니다. 자동 메모리는 머신 로컬이라 PC가 바뀌면 따라가지 않습니다. 팀이나 여러 기기에서 공유해야 하는 내용이라면 저장소에 커밋되는 CLAUDE.md에 적는 쪽이 맞습니다.
Q. 워크트리를 여러 개 쓰면 메모리도 나뉘나요?
아닙니다. 경로가 git 저장소 기준으로 정해지므로 같은 저장소의 모든 워크트리와 하위 폴더가 메모리 폴더 하나를 공유합니다.
Q. 서브에이전트도 이 메모리를 보나요?
기본적으로 메인 대화의 자동 메모리는 서브에이전트에 로드되지 않습니다. 서브에이전트는 memory 필드로 자기 몫의 별도 폴더를 가질 수 있습니다. 서브에이전트를 만드는 법은 클로드 서브에이전트 사용법 글을 보세요.
Q. 클로드가 매 세션 뭔가를 저장하나요?
아닙니다. 공식 문서는 "미래 대화에 유용할지"를 기준으로 저장할지 말지 판단한다고만 설명합니다. 화면에 "Saved 2 memories" 같은 문구가 보이면 그때 메모리 폴더에 쓰고 있는 것입니다.
마무리
정리하면 이렇습니다. 자동 메모리는 ~/.claude/projects/<프로젝트>/memory/에 마크다운으로 쌓이고, 그중 MEMORY.md의 앞 200줄(또는 25KB)만 매 세션 로드됩니다. 저장소 단위라 워크트리끼리 공유되고, 머신 로컬이라 다른 PC로는 안 갑니다. 내용이 궁금하면 /memory, 끄려면 autoMemoryEnabled나 CLAUDE_CODE_DISABLE_AUTO_MEMORY입니다.
동작과 한도는 버전마다 조정되고 있으니, 지금 쓰는 버전은 claude --version으로 확인하고 세부 수치는 공식 문서에서 다시 보는 걸 권합니다.
📚 참고 출처 (2026년 8월 5일 확인)
· Claude Code Docs — How Claude remembers your project
· Claude Code Docs — Settings
· Claude Code Docs — Environment variables
· Claude Code Docs — Slash commands
COMMENTS