Auto Memory란? — CLAUDE.md와 결정적으로 다른 점

클로드 코드 Auto Memory는 2026년 2월 말 v2.1.32 업데이트와 함께 기본 활성화 상태로 조용히 배포된 기능입니다. 핵심은 단순하지만 강력합니다. 개발자가 직접 지시 사항을 작성하는 CLAUDE.md와 달리, Claude가 세션 중에 스스로 학습한 내용을 MEMORY.md에 자동으로 기록하고 다음 세션에서 자동으로 불러오는 방식입니다.

많은 바이브코더들이 CLAUDE.md에 프로젝트 규칙, 코딩 스타일, 빌드 명령어를 꼼꼼하게 써 두고 “이 정도면 충분하다”고 생각합니다. 하지만 CLAUDE.md는 어디까지나 사람이 작성한 정적 지침서입니다. 세션 중에 Claude가 직접 발견한 버그 패턴, 특정 라이브러리의 quirk(이상한 동작), 팀만 아는 암묵적 규칙은 CLAUDE.md에 자동으로 반영되지 않습니다.

Auto Memory가 채우는 공백이 바로 이 지점입니다. Claude는 디버깅 중에 발견한 “A 로직 체크는 반드시 B보다 먼저 실행해야 Test X가 통과됨” 같은 실전 인사이트를 MEMORY.md에 남깁니다. 개발자의 개입 없이 이루어지기 때문에, 알게 모르게 Claude의 세션 간 지식이 누적되고 있는 것입니다.

▲ 목차로 돌아가기

MEMORY.md 파일 구조와 저장 위치 완전 해부

Auto Memory의 저장 위치를 정확히 알고 있으면, 불필요한 메모리가 쌓였을 때 직접 편집하거나 삭제할 수 있습니다. Claude Code는 프로젝트별로 독립된 메모리 디렉터리를 생성합니다. 경로는 ~/.claude/projects/<project>/memory/ 이며, 여기서 <project>는 Git 저장소 경로를 기반으로 자동 결정됩니다.

이 디렉터리 안에는 MEMORY.md(인덱스 파일)가 반드시 존재하며, Claude가 필요하다고 판단하면 debugging.md, api-conventions.md처럼 주제별 하위 파일을 추가로 만들기도 합니다. MEMORY.md는 “무엇이 어느 파일에 있는지”를 추적하는 인덱스 역할을 합니다.

주제별 하위 파일들은 세션 시작 시 자동으로 불러오지 않습니다. Claude가 필요하다고 판단하는 순간, 즉 관련 파일을 열거나 특정 컨텍스트가 필요할 때 온디맨드 방식으로 읽어들입니다. 이 덕분에 컨텍스트 창 낭비 없이 방대한 프로젝트 지식을 체계적으로 관리할 수 있습니다.

memory/
├── MEMORY.md          # 인덱스 파일 — 매 세션 시작 시 첫 200줄 로드
├── debugging.md       # 디버깅 패턴 — 온디맨드 로드
├── api-conventions.md # API 설계 결정 — 온디맨드 로드
└── build-quirks.md    # 빌드 시스템 특이사항 — 온디맨드 로드

▲ 목차로 돌아가기

Auto Memory가 저장하는 것 vs 저장하지 않는 것

Auto Memory의 가장 큰 오해 중 하나는 “매 세션마다 뭔가를 기록한다”는 생각입니다. 실제로는 그렇지 않습니다. Claude는 “다음 대화에서 다시 알면 유용한 정보인가?”를 스스로 판단해서 기록 여부를 결정합니다. 모든 대화를 무차별적으로 저장하는 ChatGPT 식의 메모리와 근본적으로 다른 철학입니다.

✅ 저장되는 것 (실전에서 자주 기록됨)

• 빌드·테스트 명령어 — npm run build:prod처럼 프로젝트별로 다른 명령어
• 디버깅 인사이트 — “이 에러는 Redis 로컬 인스턴스가 실행 중일 때만 발생함”
• 아키텍처 quirk — “A 함수 호출 전에 반드시 B 로직을 먼저 실행해야 Test 47이 통과됨”
• 코드 스타일 선호도 — 사용자가 특정 방식을 선호한다고 교정했을 때
• 워크플로우 패턴 — 사용자가 반복적으로 요청하는 작업 절차

❌ 저장되지 않는 것

• 파일 간 의존 관계(import 구조) — 코드가 바뀌면 陳舊해지므로 저장 안 함
• 단순 일반 지식 — Claude가 이미 학습한 내용은 기록할 이유 없음
• 일회성 작업 — “이번만 이렇게 해줘” 같은 임시 요청
• 개인 정보나 민감 데이터 — 보안상 자동 배제

▲ 목차로 돌아가기

활성화·비활성화·커스텀 설정 방법

Auto Memory는 기본적으로 ON 상태입니다. 별도로 설정하지 않아도 지금 이 순간부터 Claude가 알아서 기억을 쌓고 있을 수 있습니다. 이 사실을 모른 채 기존 방식대로만 사용하면, 자신도 모르는 사이에 의도하지 않은 설정이 누적될 수 있습니다. 따라서 Auto Memory를 의도적으로 관리하는 습관이 필요합니다.

① 세션 내에서 토글하기

가장 간단한 방법입니다. Claude Code 세션 안에서 /memory 명령어를 입력하면 현재 로드된 CLAUDE.md 파일 목록과 함께 Auto Memory 토글 버튼이 나타납니다. 이 버튼으로 즉시 켜고 끌 수 있으며, 현재 저장된 메모리 파일 폴더로 직접 이동하는 링크도 제공됩니다.

② settings.json으로 영구 비활성화

{
"autoMemoryEnabled": false
}

③ 환경변수로 비활성화

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

④ 저장 위치 커스텀 (v2.1.75 이후)

보안 정책이 엄격한 기업 환경이나, 별도의 Obsidian 볼트와 연동하고 싶은 경우 저장 경로를 변경할 수 있습니다. user 또는 local 설정 파일에서만 적용되며, 프로젝트 설정(.claude/settings.json)에서는 보안 상 이유로 허용되지 않습니다.

{
"autoMemoryDirectory": "~/my-obsidian-vault/claude-memory"
}

▲ 목차로 돌아가기

200줄 제한의 함정 — 어떻게 관리해야 하나

Auto Memory에는 중요한 제약이 있습니다. 세션 시작 시 MEMORY.md의 첫 200줄만 컨텍스트 창에 로드됩니다. 200줄을 초과하는 내용은 세션 시작 시 읽히지 않습니다. 장기 프로젝트를 진행하다 보면 메모리가 점점 쌓여서 이 한계에 도달하는 경우가 충분히 발생할 수 있습니다.

Claude는 MEMORY.md가 200줄에 가까워지면 요약, 불필요한 항목 삭제, 세부 내용을 주제별 파일로 분리하는 방식으로 스스로 관리합니다. 하지만 이 과정이 항상 완벽하지는 않습니다. 실제 Reddit 커뮤니티에서는 “오래된 정보가 새 정보를 밀어내서 중요한 규칙이 200줄 밖으로 밀려났다”는 사례가 보고되고 있습니다.

따라서 주기적인 수동 감사(Audit)가 필수입니다. /memory 명령어를 입력하고 Auto Memory 폴더를 열어 MEMORY.md를 직접 확인하세요. 낡은 내용, 더 이상 유효하지 않은 규칙은 과감히 삭제합니다. Auto Memory 파일은 단순 마크다운 파일이므로 일반 텍스트 편집기로 언제든지 수정할 수 있습니다.

▲ 목차로 돌아가기

v2.1.75 최신 업데이트: 타임스탬프와 Git 워크트리 공유

2026년 3월 9일, Claude Code v5(v2.1.75)가 배포되면서 Auto Memory에 중요한 개선이 이루어졌습니다. 가장 눈에 띄는 변화는 메모리 파일에 마지막 수정 타임스탬프가 표시된다는 점입니다. 이제 Claude는 저장된 기억을 불러올 때 “이 정보가 얼마나 오래됐는가”를 스스로 판단해서 최신 정보에 더 높은 우선순위를 부여할 수 있게 됐습니다.

두 번째 변화는 Git 워크트리 공유 공식화입니다. 같은 Git 저장소를 기반으로 여러 워크트리를 운영하는 경우(예: feature 브랜치를 워크트리로 분리해서 병렬 개발하는 워크플로우), 모든 워크트리가 동일한 Auto Memory 디렉터리를 공유합니다. 브랜치마다 메모리 설정을 따로 관리할 필요가 없어졌습니다.

이 업데이트의 의미는 단순한 편의 개선 이상입니다. 타임스탬프 기반 우선순위 판단은 장기 프로젝트에서 Claude가 스스로 “낡은 기억”을 배제하고 “최신 맥락”에 집중할 수 있게 해줍니다. 수개월 전에 저장된 구버전 API 스펙이 현재 세션을 오염시키는 문제를 근본적으로 해결하는 접근입니다.

▲ 목차로 돌아가기

실전 활용 전략 — 바이브코더라면 이렇게 쓰세요

Auto Memory의 존재를 아는 것만으로는 부족합니다. 이 기능을 최대한 활용하려면 CLAUDE.md와 Auto Memory의 역할을 의식적으로 분리하는 습관이 필요합니다. 개인적으로는 다음과 같은 3단계 전략을 권장합니다.

▲ 목차로 돌아가기

자주 묻는 질문 Q&A

▲ 목차로 돌아가기

마치며 — 총평

Claude Code Auto Memory는 바이브코딩 생태계에서 조용히 일어나고 있는 패러다임 전환의 상징적인 기능입니다. 기존 AI 코딩 도구들이 “사용자가 프롬프트를 잘 써야 좋은 결과가 나온다”는 전제 위에 있었다면, Auto Memory는 “Claude가 경험을 통해 스스로 더 나은 조력자가 된다”는 방향으로 진화하고 있음을 보여 줍니다.

물론 현재의 구현에는 한계도 있습니다. 200줄 제한, 팀 공유 불가, 파일 간 의존 관계 미추적 등은 실전에서 아쉬운 부분입니다. 하지만 v2.1.75에서 타임스탬프 기반 정보 신선도 판단이 추가된 것을 보면, Anthropic이 이 기능을 꾸준히 개선하고 있다는 것을 알 수 있습니다.

결론적으로 CLAUDE.md와 Auto Memory를 함께 쓰되, 각각의 역할을 명확히 구분하는 것이 핵심입니다. CLAUDE.md는 팀의 공통 규칙, Auto Memory는 Claude의 개인 경험 노트입니다. 이 두 시스템을 이해하고 의식적으로 관리하는 개발자가 그렇지 않은 개발자보다 훨씬 빠르게 AI와 호흡을 맞출 수 있게 됩니다.

▲ 목차로 돌아가기