Claude Code 는 실제로 세션 사이에 프로젝트를 기억한다. 하지만 그것은 하나의 거대한 영구 memory 저장소로 작동하는 것이 아니다. Anthropic 문서를 2026년 4월 8일 기준으로 확인하면, 내장 memory 는 크게 두 층으로 나뉜다. 직접 쓰는 CLAUDE.md 와, 반복 교정을 통해 Claude 가 학습하는 auto memory 다.
문제가 생기는 지점은 Claude Code memory 라는 말 안에 전혀 다른 세 가지 작업을 집어넣을 때다. 어떤 정보는 명시 규칙으로 써야 하고, 어떤 정보는 반복 수정에서 학습시키는 편이 맞으며, 어떤 요구는 애초에 Claude Code 내장 memory 가 아니라 외부 memory layer 의 문제다. 이 셋을 분리하면 memory 는 막연한 개념이 아니라 설정 가능한 운영 도구가 된다.
실무 기준은 단순하다. 잃어버리면 곤란한 규칙은 CLAUDE.md 에 적는다. 반복 교정으로 충분한 것은 auto memory 에 맡긴다. 크로스 툴, 크로스 머신, 더 넓은 retrieval 이 필요할 때만 외부 레이어를 검토한다. Claude 가 잊었다고 느껴지면 먼저 /memory 와 /context 로 실제 로드 상태부터 확인해야 한다.
Claude Code 가 기억해야 하는 것과 아닌 것
유용한 질문은 "memory 가 있나?"가 아니라 "무엇을 어느 층에 맡겨야 하나?"다.
CLAUDE.md 는 명시 규칙 층이다. 저장소 워크플로, 필수 테스트, 위험한 작업 경계, 수정 금지 디렉터리, 리뷰 기준처럼 세션 시작부터 보여야 하는 것은 여기에 둔다. 다만 Anthropic 문서가 분명히 말하는 한계도 있다. CLAUDE.md 는 hard enforcement 가 아니라 context 다. 너무 길거나 모호하거나 서로 충돌하면 Claude 는 여전히 흔들릴 수 있다.
auto memory 는 학습 층이다. 반복 수정으로 길러지는 습관, 예를 들어 먼저 어떤 테스트를 돌리는지, 어떤 약어를 쓰는지, 리뷰 코멘트를 어떻게 구성하는지가 여기에 더 잘 맞는다. 편리하지만 machine-local 이라는 경계도 같이 따라온다. 여기서부터 클라우드 동기화형 영구 기억을 기대하면 금방 어긋난다.
플러그인이나 외부 memory layer 는 세 번째 범주다. Anthropic marketplace 에 memory 확장 도구가 있는 것은 사실이지만, 그렇다고 플러그인이 Claude Code memory 의 기본 답이라는 뜻은 아니다. 먼저 built-in 층을 제대로 쓰고, 그 경계가 실제로 workflow 를 막을 때만 외부 레이어를 올리는 편이 안전하다.
한 줄로 줄이면 이렇다. 반드시 남겨야 할 것은 써 두고, 반복에서 학습 가능한 것은 학습시키고, 진짜 경계를 넘을 때만 밖으로 나간다.
시작할 때 무엇이 로드되고 무엇이 로드되지 않는가
많은 기억 문제는 이 지점에서 생긴다. 모든 memory 파일이 시작 시 같은 방식으로 context 에 들어온다고 생각하기 때문이다.
Anthropic 현재 문서에 따르면 CLAUDE.md 는 각 대화 시작 시 로드된다. 그래서 첫 턴부터 반드시 보여야 하는 규칙은 여기 있어야 한다. 나중에 우연히 읽히길 기대하는 자리가 아니다.
반면 auto memory 쪽은 더 제한적이다. memory 폴더에는 MEMORY.md 와 topic 파일이 있고, 시작 시 로드되는 것은 MEMORY.md 의 앞 200줄 또는 25KB 까지다. topic 파일은 필요할 때 읽힌다. 즉 파일이 존재한다는 사실과 현재 세션에 들어와 있다는 사실은 다르다.
이 차이를 가장 빨리 확인하는 명령이 /memory 와 /context 다. /memory 는 어떤 CLAUDE.md, CLAUDE.local.md, rules 파일이 실제로 로드되었는지 보여 준다. /context 는 현재 context budget 이 어떻게 구성되어 있는지 보여 준다. Claude 가 잊은 것처럼 보이면, 먼저 정말 로드된 적이 있었는지 확인하는 편이 빠르다.
또 하나 초반에 분명히 말해야 할 것은 machine-local 경계다. Anthropic 이 공개한 저장 경로는 로컬 홈 디렉터리 아래다. inspect 하기에는 좋지만, 자동으로 다른 머신까지 따라가는 universal memory 는 아니라는 뜻이다.
CLAUDE.md 를 큰 잡동사니 파일로 만들지 않는 방법
좋은 CLAUDE.md 는 가장 긴 파일이 아니라 역할이 분명한 파일이다.
project 수준 CLAUDE.md 에는 팀과 저장소가 매번 알아야 하는 규칙을 둔다. 테스트 흐름, 변경 전 확인, 건드리면 안 되는 디렉터리, 아키텍처 제약처럼 저장소 전체 규칙이 여기에 해당한다. 이 파일을 모든 예외의 창고로 만들면 오히려 중요한 규칙이 흐려진다. Anthropic 이 짧고 선명한 구성을 권하는 이유도 여기에 있다.
user 수준 ~/.claude/CLAUDE.md 는 개인 기본값에 적합하다. 어떤 설명 톤을 선호하는지, 언제 먼저 물어보길 원하는지, 여러 프로젝트에 공통되는 개인 습관을 여기에 둔다.
CLAUDE.local.md 는 버전 관리에 올리고 싶지 않은 로컬 메모에 잘 맞는다. 특정 머신에서만 필요한 제약이나 임시 프로젝트 메모를 넣는 곳이지, 두 번째 거대한 규칙 파일을 만드는 자리는 아니다.
어떤 규칙이 특정 경로나 좁은 workflow 에만 관계된다면 .claude/rules/ 로 분리하는 편이 낫다. 하나의 큰 파일에 모든 규칙을 우겨 넣는 것보다, 필요한 문맥에서 필요한 규칙만 보이는 편이 더 낫기 때문이다.
그리고 자주 놓치는 것이 AGENTS.md 다. Claude Code 는 AGENTS.md 를 직접 읽지 않는다. Anthropic 권장은 CLAUDE.md 에서 import 하는 방식이다. 이 연결을 하지 않으면 "저장소에 규칙은 있는데 왜 Claude 가 모르지?" 같은 혼란이 생긴다.
설치나 인증 자체가 아직 불안정하다면 먼저 Claude Code 설치 가이드 부터 정리하는 것이 낫다. memory 구조화는 기반이 안정적일수록 쉬워진다.
auto memory 의 실제 한계
auto memory 를 "자동으로 다 기억하는 층"으로 생각하면 실망하기 쉽다. 더 정확하게는, 보고 정리하고 끌 수 있는 학습 층이다.
공식 docs 에는 기본 저장 위치, MEMORY.md, topic 파일 구조가 명시돼 있다. 즉 블랙박스가 아니다. 무엇을 배웠는지 inspect 할 수 있으므로, memory 품질이 떨어질 때는 model 문제보다 memory layer 가 지저분해진 것부터 의심해야 한다.
동시에 한계도 분명하다. 시작 시 로드되는 것은 MEMORY.md 일부뿐이고, topic 파일은 on demand 다. 항상 보여야 하는 규칙을 topic 파일 안쪽에 숨겨 두면 안 되고, 그럴수록 CLAUDE.md 로 되돌리는 편이 맞다.
또한 Anthropic 문서에는 /memory, autoMemoryEnabled: false, CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 같은 제어 방법도 있다. 이것은 memory 를 끄라는 뜻이 아니라, built-in 경계 문제와 설정 문제를 분리해서 볼 수 있게 해 주는 control surface 다.
/compact 뒤나 다음 세션에서 Claude 가 잊는 이유
Claude 가 잊은 것처럼 보일 때, 원인은 대개 네 가지다.
첫째는 아예 로드되지 않은 경우다. /memory 를 보면 많은 착각이 여기서 끝난다.
둘째는 규칙이 모호하거나 충돌하는 경우다. CLAUDE.md 가 context 인 이상, 흐릿한 문장과 상충하는 지시는 "memory 가 망가졌다"처럼 보이는 결과를 만든다.
셋째는 대화 속에만 존재하던 정보다. Anthropic troubleshooting 의 핵심 규칙은 이것이다. /compact 뒤에 사라졌다면, 그 정보는 대화 안에만 있었을 가능성이 높다. 오래 남아야 한다면 써 두어야 한다.
넷째는 정말 built-in 경계를 넘은 경우다. 크로스 툴, 크로스 머신, 더 넓은 retrieval 이 필요하다면 그때 플러그인을 고려할 수 있다. 하지만 그 결론은 로드, 규칙 품질, 대화 의존 문제를 먼저 배제한 뒤에 나와야 한다.
안전한 점검 순서는 이렇다.
/memory로 실제 로드 상태를 본다.- 그 정보가
CLAUDE.md에 있어야 하는지 다시 판단한다. - 모호하거나 충돌하는 규칙을 줄이고 다시 쓴다.
/context로 세션 과부하 여부를 본다.- 마지막에만 외부 memory layer 가 필요한지 묻는다.
실제 문제의 중심이 usage 나 context inflation 이라면, Claude Code usage 가이드 가 더 직접적인 해결책이 된다.
플러그인이 진짜 필요한 때와 아직 이른 때
플러그인은 질문 자체가 Claude Code built-in memory 보다 커졌을 때 의미가 있다. 여러 도구 사이의 연속성, 여러 머신 간 공유, 더 넓은 retrieval, 팀 지식 레이어가 필요하다면 외부 memory layer 는 합리적이다.
반대로 아직 이른 때는 built-in 도 정리되지 않았을 때다. CLAUDE.md 와 auto memory 분담이 흐릿하고, /memory 도 안 보고, 대화만 믿고 있다면 플러그인은 문제를 해결하기보다 숨길 가능성이 높다.
가장 보수적인 전략이 가장 실용적이다. 먼저 built-in 을 제대로 쓰고, 정말 막히는 경계를 말로 설명할 수 있을 때만 외부 레이어로 올라간다.
자주 묻는 질문
Claude Code 는 세션 사이에 프로젝트를 기억하나?
그렇다. 다만 하나의 거대한 영구 memory 가 아니라 CLAUDE.md 와 auto memory 의 분담으로 이어진다.
무엇을 CLAUDE.md 에 써야 하나?
잃으면 곤란한 명시 규칙이다. 워크플로, 테스트, 위험한 작업 경계, 중요한 개발 규칙이 여기에 해당한다.
MEMORY.md 는 어디에 있나?
현재 공식 docs 기준으로 ~/.claude/projects/<project>/memory/ 아래다. machine-local 경계를 가진다.
왜 /compact 뒤에 잊어버리나?
대화에만 있던 내용은 compaction 뒤에 사라질 수 있다. 오래 남겨야 하면 CLAUDE.md 에 써야 한다.
memory 플러그인이 필요한가?
대부분은 아니다. 먼저 built-in 층을 올바르게 쓰고, 그 다음에 경계가 실제로 문제인지 판단하는 편이 낫다.
Claude Code memory 를 가장 잘 쓰는 방법은 그것을 하나의 거대한 뇌로 상상하지 않는 것이다. 규칙은 쓰고, 습관은 학습시키고, 경계를 넘는 요구만 외부화하면 된다. 이 분리가 보이면 memory 는 훨씬 다루기 쉬워진다.