Claude Code Auto-Memory 완전정복:
매번 반복 설명, 이제 진짜 끝냈습니다
Claude Code를 쓸 때마다 “이 프로젝트는 TypeScript로 작성하고, 들여쓰기는 2칸이며, pnpm을 사용합니다”를 반복해서 설명하고 계신가요?
2026년 2월 말 Anthropic이 공식 출시한 Auto-Memory(MEMORY.md) 기능을 제대로 이해하면,
Claude가 스스로 학습하고 세션이 끊겨도 기억을 유지합니다.
공식 문서 기반으로 설정부터 실전 활용까지 한 번에 정리했습니다.
🔖 공식 Docs 기반
⚡ Auto-Memory 완전정복
🛠️ MEMORY.md 실전 설정
🧠 Auto-Memory가 뭔지 3줄 요약부터
Claude Code는 기본적으로 매 세션이 시작될 때마다 컨텍스트 창이 초기화됩니다.
이전에 나눈 대화, 내렸던 코딩 결정, 디버깅 과정에서 발견한 패턴 — 모두 세션이 끝나면 사라집니다.
이 문제를 해결하기 위해 Anthropic이 2026년 2월 공식 출시한 것이 바로 Auto-Memory입니다.
한 줄로 정의하면, Auto-Memory는 “Claude가 스스로 자기 업무 일지를 쓰는 기능”입니다.
여러분이 Claude에게 무언가를 수정하거나 피드백을 주면, Claude는 그 학습 내용을 프로젝트별
MEMORY.md 파일에 자동으로 기록합니다. 다음 세션이 시작되면 이 파일을 읽고
이전 맥락을 그대로 이어받아 작업합니다.
특히 주목할 점은 Auto-Memory가 기존의 CLAUDE.md와 완전히 별개의 시스템이라는 겁니다.
두 시스템은 역할이 다르고, 함께 쓸 때 시너지가 극대화됩니다.
이 차이를 정확히 이해하는 것이 Claude Code 활용의 핵심입니다.
Auto-Memory는 Claude가 쓰는 “성장 일지”입니다. 여러분이 직접 규칙을 적는 CLAUDE.md와 달리,
Claude가 일하면서 스스로 배운 내용을 축적합니다. 두 시스템을 동시에 운영할 때 가장 강력합니다.
📋 CLAUDE.md vs Auto-Memory: 결정적 차이
많은 분들이 CLAUDE.md와 Auto-Memory(MEMORY.md)를 같은 것으로 혼동합니다.
하지만 이 둘은 작성 주체, 내용의 성격, 저장 위치가 완전히 다릅니다.
LinkedIn에서 화제가 된 표현을 빌리자면,
“CLAUDE.md는 내가 쓰는 규칙서, Auto-Memory는 Claude가 쓰는 업무 일지”입니다.
| 구분 | CLAUDE.md | Auto-Memory (MEMORY.md) |
|---|---|---|
| 작성자 | 개발자(사람) | Claude(AI) |
| 내용 | 지시사항 · 규칙 | 학습 내용 · 패턴 · 디버깅 인사이트 |
| 적용 범위 | 프로젝트 / 사용자 / 조직 전체 | 워킹 트리 단위 (git repo 기준) |
| 세션 로드 | 전체 파일 로드 | MEMORY.md 상위 200줄만 로드 |
| 버전 관리 | Git에 커밋 가능 (팀 공유) | 로컬 전용 (Git 비포함, 개인 보관) |
| 주요 용도 | 코딩 표준, 아키텍처 결정, 워크플로우 | 빌드 명령어, 디버깅 패턴, 개인 선호도 |
언제 무엇을 써야 하나요?
CLAUDE.md를 써야 하는 상황: 팀 전체가 공유해야 하는 코딩 컨벤션, 프로젝트 아키텍처 결정,
보안 정책처럼 “모든 세션에서 반드시 따라야 하는 규칙”을 적을 때 사용합니다.
이 파일은 Git에 올려 팀원 모두와 공유할 수 있습니다.
Auto-Memory를 활용해야 하는 상황: 반면 “이 프로젝트에서 pnpm run build를 실행하면 dist 폴더 오류가 나서
항상 npm run build로 대체한다”처럼 Claude가 직접 경험하며 터득한 패턴은 Auto-Memory에 자동 저장됩니다.
여러분이 따로 적지 않아도 Claude가 알아서 기록합니다.
두 시스템을 동시에 운영하면 “규칙(CLAUDE.md) + 경험(MEMORY.md)”이 결합되어 Claude가 프로젝트 전문가처럼 행동합니다.
CLAUDE.md에 핵심 규칙만 200줄 이하로 짧게 유지하고, 세부 패턴은 Auto-Memory에 맡기는 것이 가장 효율적인 구성입니다.
🗂️ MEMORY.md 저장 구조와 작동 원리
Auto-Memory가 실제로 어떤 구조로 저장되는지 이해하면 훨씬 잘 활용할 수 있습니다.
Anthropic 공식 문서에 따르면, Auto-Memory는 프로젝트별로 독립된 디렉토리에 저장됩니다.
경로는 아래와 같습니다.
~/.claude/projects/<project>/memory/
├── MEMORY.md # 인덱스 파일 — 매 세션 첫 200줄 로드
├── debugging.md # 디버깅 패턴 세부 노트
├── api-conventions.md # API 설계 결정 사항
└── …기타 토픽 파일들 # Claude가 필요시 자동 생성
3가지 핵심 작동 규칙
MEMORY.md는 인덱스입니다.
상세 내용은 topic 파일(debugging.md 등)에 저장하고, MEMORY.md는 “어디에 무엇이 있는지”를 추적하는 목차 역할을 합니다.
이 덕분에 MEMORY.md는 200줄 이하로 간결하게 유지됩니다.
200줄 이후는 자동 로드되지 않습니다.
MEMORY.md의 상위 200줄만 매 세션 시작 시 자동으로 로드됩니다.
토픽 파일들(debugging.md 등)은 Claude가 필요하다고 판단할 때 도구로 직접 읽어옵니다.
같은 git repo의 모든 워킹 트리는 하나의 memory 폴더를 공유합니다.
git repo를 기반으로 project 경로가 결정되므로, 같은 저장소에서 작업하는 한 어떤 디렉토리에서 Claude Code를 실행해도 동일한 메모리를 씁니다.
단, 이 파일들은 로컬 전용이라 다른 컴퓨터나 클라우드 환경과는 공유되지 않습니다.
Claude는 언제 메모리에 기록하나요?
Auto-Memory는 매 세션마다 무조건 기록하지 않습니다. Claude가 “이 정보는 다음 세션에서도 유용할 것”이라고 판단했을 때만 저장합니다.
빌드 명령어 수정, 반복되는 디버깅 패턴, 여러분이 명시적으로 선호를 표현했을 때 등이 주요 기록 트리거입니다.
Claude Code 인터페이스에서 “Writing memory” 또는 “Recalled memory” 메시지가 보이면
Claude가 현재 메모리를 읽거나 쓰고 있는 것입니다.
⚙️ Auto-Memory 활성화·비활성화 설정법
Auto-Memory는 Claude Code 설치 시 기본값이 ON입니다.
대부분의 경우 그냥 켜 두는 게 이득입니다만, 보안이 민감한 프로젝트나 공유 환경에서는 끄고 싶을 수도 있습니다.
Anthropic 공식 문서 기준으로 3가지 방법을 제공합니다.
방법 1 — 세션 내에서 토글
가장 간단한 방법입니다. Claude Code 세션이 열려 있는 상태에서 /memory 커맨드를 입력하면
Auto-Memory 토글 버튼이 표시됩니다. 클릭 한 번으로 켜고 끌 수 있습니다.
방법 2 — 프로젝트 설정 파일로 비활성화
프로젝트 단위로 Auto-Memory를 끄고 싶다면, 프로젝트 루트의 .claude/settings.json에 다음 값을 추가합니다.
“autoMemoryEnabled”: false
}
방법 3 — 환경변수로 전역 비활성화
모든 프로젝트에서 일괄적으로 Auto-Memory를 끄고 싶다면, 환경변수를 설정합니다.
~/.bashrc 또는 ~/.zshrc에 아래 줄을 추가하면 됩니다.
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
저는 Auto-Memory를 끄는 것을 추천하지 않습니다. 특히 혼자 개발하는 프리랜서나 1인 개발자라면,
메모리가 로컬에만 저장되기 때문에 보안 위험도 거의 없습니다. 기록된 내용이 마음에 안 들면
/memory로 언제든지 직접 수정·삭제할 수 있습니다.
✏️ 실전 MEMORY.md 예시 & 직접 편집하는 법
Auto-Memory가 실제로 생성하는 MEMORY.md는 어떻게 생겼을까요?
아래는 Node.js 풀스택 프로젝트에서 며칠간 작업한 후 Claude가 자동으로 기록한
MEMORY.md의 실제 구조를 재현한 예시입니다.
## 프로젝트 환경
– 패키지 매니저: pnpm (npm 사용 시 lock 파일 충돌 발생)
– 빌드: `pnpm run build` → dist/ 폴더 생성
– 테스트: `pnpm test` (vitest 기반, Redis 로컬 인스턴스 필요)
## 디버깅 인사이트
– 인증 미들웨어 오류 → 세부 내용: ./debugging.md#auth-middleware
– DB 연결 timeout: POSTGRES_CONNECTION_TIMEOUT=30 으로 해결
## 코딩 선호도
– TypeScript strict 모드 ON
– 들여쓰기 2칸, 세미콜론 없음
– API 핸들러는 src/api/handlers/ 에 위치
## 상세 노트 위치
– 디버깅 패턴: ./debugging.md
– API 컨벤션: ./api-conventions.md
내가 원하는 내용을 직접 기억시키는 법
Claude에게 구체적인 내용을 기억시키고 싶다면, 대화 중에 자연어로 요청하면 됩니다.
아래 같은 표현이 효과적으로 작동합니다.
“항상 pnpm을 사용한다는 걸 기억해줘”
“Redis 로컬 인스턴스가 있어야 API 테스트가 된다는 걸 메모리에 저장해줘”
“이번 인증 버그 디버깅 과정을 기억해두고 다음에 유사한 상황에서 활용해줘”
직접 편집해도 되나요?
됩니다. Auto-Memory 파일들은 일반 마크다운 파일이기 때문에 언제든 텍스트 에디터로 직접 열어서 수정하거나 삭제할 수 있습니다.
잘못된 정보가 기록됐거나 오래된 내용을 지우고 싶을 때는 /memory 커맨드로 파일을 열어 직접 편집하면 됩니다.
Claude의 메모리를 사람이 직접 관리할 수 있다는 점은 이 시스템의 큰 장점입니다.
🔍 /memory 커맨드로 메모리 감사·관리하기
Claude Code 세션에서 /memory를 입력하면 메모리 관리 전용 인터페이스가 열립니다.
이 커맨드는 단순히 파일을 보여주는 것 이상의 기능을 제공합니다.
| /memory 커맨드 기능 | 설명 |
|---|---|
| 📋 현재 세션 로드된 파일 목록 | CLAUDE.md, rules 파일 등 현재 세션에서 읽힌 모든 메모리 파일 나열 |
| 🔀 Auto-Memory 토글 | 켜기/끄기 전환 — 설정 파일 없이 바로 적용 |
| 📂 Auto-Memory 폴더 열기 | ~/.claude/projects/<project>/memory/ 직접 탐색 링크 제공 |
| ✏️ 파일 선택 편집 | 목록에서 파일 선택 시 에디터로 즉시 오픈 |
왜 /memory 감사가 중요한가요?
Auto-Memory의 핵심 맹점은 Claude가 잘못된 내용을 기록할 수도 있다는 점입니다.
예를 들어, 일시적인 실험 코드에서 발생한 오류를 Claude가 “이 프로젝트의 영구적인 제약사항”으로 잘못 기억할 수 있습니다.
이런 오염된 메모리는 이후 세션에서 Claude를 계속 잘못된 방향으로 이끌 수 있습니다.
따라서 일주일에 한 번 정도는 /memory를 열어 저장된 내용이 여전히 정확한지 확인하는 습관을 들이는 것을 강력히 권장합니다.
메모리를 관리하는 데 걸리는 시간은 5분 이내지만, 그로 인해 절약되는 반복 설명 시간은 매우 큽니다.
“/memory”로 파일을 열었을 때 오래됐거나 틀린 내용을 발견했다면 즉시 삭제하세요.
Claude는 MEMORY.md에 적힌 내용을 맹목적으로 따르려 하기 때문에, 잘못된 기록 하나가 여러 세션에 걸쳐 문제를 만들 수 있습니다.
🚀 Auto-Memory를 200% 활용하는 4가지 전략
단순히 기능을 켜 두는 것을 넘어, Auto-Memory를 진짜 파워풀하게 활용하는 방법을 공유합니다.
수주에 걸쳐 Claude Code를 사용해 온 개발자들이 공유한 실전 인사이트를 정리했습니다.
CLAUDE.md가 200줄을 넘기 시작하면 Claude의 지시 준수율이 떨어집니다.
코어 규칙(들여쓰기, 언어, 패키지 매니저)만 CLAUDE.md에 넣고,
나머지 프로젝트 경험 기반 지식은 Claude가 Auto-Memory에 자연스럽게 축적하도록 두세요.
이렇게 역할을 분리하면 두 시스템 모두 최적의 퍼포먼스를 발휘합니다.
새 세션을 시작했을 때 “이 프로젝트에 대해 지금까지 뭘 기억하고 있어?”라고 물어보면
Claude가 MEMORY.md에서 읽어온 내용을 정리해서 알려줍니다.
이를 통해 메모리가 올바르게 로드됐는지 확인하고, 잘못된 내용이 있으면 바로 수정할 수 있습니다.
/compact로 대화 기록을 압축해도 CLAUDE.md와 MEMORY.md는 영향을 받지 않습니다./compact 실행 후 Claude는 디스크에서 두 파일을 다시 읽어 세션에 주입합니다.
따라서 컨텍스트를 공격적으로 압축하면서도 중요한 지식은 잃지 않을 수 있습니다.
Claude Code의 서브에이전트 기능을 활용하면, 각 서브에이전트가 독립적인 Auto-Memory를 유지하도록 설정할 수 있습니다.
이를 통해 대규모 프로젝트에서 “인증 담당 에이전트”, “UI 담당 에이전트” 각각이 자기 영역의 지식만 축적하는
전문화된 메모리 시스템을 구축할 수 있습니다. 공식 문서의 subagent configuration 섹션을 참고하세요.
❓ Q&A — 자주 묻는 질문 5가지
Auto-Memory 파일이 팀원에게 공유될 수 있나요?
~/.claude/projects/ 경로에 저장되는 로컬 전용 파일입니다.Git 저장소에 포함되지 않으며, 다른 컴퓨터나 클라우드 환경과 공유되지 않습니다.
팀원과 공유해야 하는 지식은 반드시
CLAUDE.md에 작성해서 Git에 올리세요.보안이 민감한 프로젝트에서는 Auto-Memory에 민감한 정보가 저장되지 않도록 주기적으로 감사하는 것이 좋습니다.
MEMORY.md가 200줄을 넘으면 어떻게 되나요?
Claude는 필요하다고 판단할 때 도구를 통해 직접 파일을 읽어옵니다.
이 때문에 Claude는 자동으로 MEMORY.md를 간결하게 유지하려 하고, 상세 내용은 별도 토픽 파일(debugging.md 등)로 분리합니다.
만약 MEMORY.md가 비대해졌다면
/memory로 열어 오래된 항목을 직접 정리해 주세요.
Claude가 틀린 내용을 MEMORY.md에 기록했을 때는 어떻게 하나요?
/memory 커맨드를 입력하면 Auto-Memory 폴더로 가는 링크가 제공됩니다.해당 파일을 텍스트 에디터로 열어 잘못된 내용을 수정하거나 삭제하면 됩니다.
또한 대화 중에 “방금 기록한 내용은 잘못됐어. 올바른 내용은 이렇게 고쳐줘”라고 요청하면
Claude가 MEMORY.md를 직접 업데이트합니다.
Auto-Memory는 Claude Code의 유료 플랜에서만 사용할 수 있나요?
다만 Auto-Memory 파일을 로드할 때 추가적인 컨텍스트 토큰이 소비됩니다.
특히
MEMORY.md 상위 200줄이 매 세션에 로드되므로, 약 1~3K 토큰 정도를 사용합니다.무료 플랜 사용자라면 MEMORY.md를 최대한 간결하게 유지해서 컨텍스트 소비를 최소화하는 것이 좋습니다.
CLAUDE.md와 MEMORY.md 중 어느 것이 우선순위가 높은가요?
우선순위를 따지기보다는 역할이 다르다고 이해하는 것이 정확합니다.
CLAUDE.md는 지시사항, MEMORY.md는 학습 기록입니다.
두 파일에 모순된 내용이 있다면 Claude가 임의로 선택할 수 있으므로, 상충하는 내용은 반드시 통일해야 합니다.
일반적으로 더 구체적인 지시가 더 잘 따라집니다.
💬 마치며 — Auto-Memory는 Claude Code의 진짜 실력을 끌어내는 열쇠입니다
솔직히 말씀드리면, Claude Code를 처음 쓸 때 가장 답답했던 점은 세션이 끊길 때마다 모든 걸 처음부터 설명해야 한다는 것이었습니다.
프로젝트 구조, 패키지 매니저, 코딩 스타일, 이전에 발견한 버그 패턴 — 매번 반복하다 보면 Claude를 쓰는 이득이 반감되는 느낌이 들었습니다.
Auto-Memory는 그 문제를 정면으로 해결합니다. Claude가 경험을 통해 스스로 학습하고 기록하는 구조는,
단순히 편리한 기능이 아니라 AI와 함께 일하는 방식 자체를 바꾸는 메커니즘입니다.
처음에는 별것 아닌 것 같아도, 2~3주 이상 같은 프로젝트를 작업하면 메모리가 축적되면서 Claude가 마치 “이 프로젝트를 오래 함께 한 팀원”처럼 행동하기 시작합니다.
핵심을 다시 정리합니다. CLAUDE.md에는 팀이 공유해야 하는 핵심 규칙만, 200줄 이내로 짧게.
나머지 경험 기반 지식은 Auto-Memory에 맡기세요. 그리고 일주일에 한 번은 /memory로 기록된 내용을 점검하세요.
이 세 가지 습관만 지켜도 Claude Code의 생산성이 체감할 수 있을 만큼 달라집니다.
※ 본 글은 Anthropic 공식 문서(docs.anthropic.com) 및 공개된 사용자 경험을 바탕으로 정보 제공 목적으로 작성됐습니다.
Claude Code의 기능·요금제·정책은 Anthropic의 업데이트에 따라 언제든 변경될 수 있으므로, 중요한 의사결정 전에는 반드시
공식 문서 최신 버전을 확인하시기 바랍니다.
댓글 남기기