Claude Code 공식 문서는 이 기능을 auto memory라고 부릅니다. 개발자가 자기 애플리케이션에서 파일 저장 동작을 구현해 쓰는 Claude API의 Memory tool과는 다른 기능입니다.
auto memory가 해결하는 문제
매 세션 시작 시 같은 컨텍스트를 다시 설명해야 하는 비효율이 있습니다. auto memory는 사용자, 프로젝트의 잘 변하지 않는 사실과 반복 피드백을 영구 저장하여, 다음 세션에서 자동 복원합니다.
저장 위치
~/.claude/projects/<project>/memory/
├── MEMORY.md # 인덱스 (메모리마다 1줄, 매 세션 로드)
├── user_role.md # 메모리 1개
├── feedback_testing.md # 메모리 1개
└── ... # Claude가 만드는 기타 토픽 파일
<project>는 git 저장소 기준으로 정해집니다. 같은 저장소의 하위 디렉토리와 worktree는 하나의 메모리 디렉토리를 공유하고, git 저장소가 아니면 프로젝트 루트를 기준으로 합니다.- 다른 위치에 저장하려면
settings.json에autoMemoryDirectory를 지정합니다. - auto memory는 해당 머신에만 저장되며 다른 머신이나 클라우드 환경과 공유되지 않습니다.
- 메모리 종류는 각 파일 frontmatter의
type필드(user,feedback,project,reference)로 기록됩니다.
MEMORY.md 로드 범위
세션 시작 시 MEMORY.md의 앞 200줄 또는 앞 25KB 중 먼저 닿는 지점까지만 로드됩니다. 그 뒤 내용은 시작 시 로드되지 않으므로, Claude는 인덱스를 항목당 1줄로 유지하고 자세한 내용은 토픽 파일로 옮깁니다. 인덱스가 한도를 넘으면 Claude Code가 인덱스를 다시 쓰라는 오류를 Claude에게 돌려줍니다. user_role.md 같은 토픽 파일은 시작 시 로드되지 않고, Claude가 필요할 때 읽습니다.
메인 대화의 auto memory는 subagent에 로드되지 않습니다(부모 대화를 이어받는 fork는 예외). subagent 자체의 메모리는 subagent 정의의 memory 필드로 따로 켭니다.
자동 저장되는 정보
사용자 (user)
역할, 전문 분야, 작업 선호
- 예: “데이터 사이언티스트, 현재 관측성과 로깅에 집중”
피드백 (feedback)
교정 내역과 사용자가 확인한 접근 방식
- 예: “통합 테스트는 mock DB 대신 실제 DB 사용 — 작년 마이그레이션 실패 사례”
프로젝트 (project)
코드나 git 이력으로 알 수 없는 진행 중인 작업, 마감, 결정
- 예: “2026-03-05부터 모바일 릴리스 컷을 위한 머지 프리즈”
참조 (reference)
이슈 트래커, 대시보드처럼 프로젝트 밖에서 정보를 찾을 곳
- 예: “파이프라인 버그는 Linear의 INGEST 프로젝트에서 추적”
Claude가 매 세션 무언가를 저장하지는 않습니다. 이후 대화에 쓸모가 있는지를 기준으로 저장 여부를 정합니다.
저장하지 않는 정보
- 아키텍처, 파일 경로처럼 코드에서 알 수 있는 정보
- git 이력으로 알 수 있는 변경 내역
- 디버깅 해결책 (코드와 커밋 메시지에 남음)
- CLAUDE.md에 이미 적혀 있는 내용
직접 추가, 삭제
이 결정 기억해줘: 결제 프로세서로 Stripe 사용. PayPal은 예전에 검토했지만 한국 법인 처리 한계로 제외.
Claude가 auto memory에 저장합니다. CLAUDE.md에 넣고 싶으면 “CLAUDE.md에 추가해줘”처럼 명시합니다.
Stripe 결정 메모리 삭제해줘
해당 메모리를 찾아 제거합니다.
또는 메모리 디렉토리에서 .md 파일을 직접 편집하거나 삭제할 수 있습니다.
메모리 확인과 끄기
/memory
CLAUDE.md, CLAUDE.local.md와 메모리 파일 위치를 목록으로 보여주고, auto memory 켜기와 끄기 토글, auto memory 폴더 열기를 제공합니다. 파일을 선택하면 편집기에서 열립니다.
끄는 방법은 세 가지입니다.
| 방법 | 범위 |
|---|---|
/memory의 auto memory 토글 | ~/.claude/settings.json의 autoMemoryEnabled에 저장 (사용자 전체) |
프로젝트 설정에 "autoMemoryEnabled": false | 해당 프로젝트 |
환경 변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 | 그 환경에서 실행한 세션 |
좋은 메모리의 특징
- 비명시적 사실 — 코드만으로 알 수 없는 결정, 배경
- 이유 포함 — “왜 그렇게 정했는지”가 같이 적혀 있음
- 절대 날짜 — “내일”, “다음 주” 대신
2026-05-15 - 간결 — 인덱스 1줄 + 본문 짧은 단락
활용 패턴
팀 규칙은 CLAUDE.md에
“우리 팀은 PR 머지 전에 항상 Plan mode로 검토” 같은 팀 규칙은 메모리가 아니라 프로젝트 CLAUDE.md에 둡니다. auto memory는 해당 머신에만 저장되어 팀원과 공유되지 않고, 공식 문서는 코딩 표준과 워크플로를 CLAUDE.md의 용도로 안내합니다. 메모리와 CLAUDE.md 모두 강제 설정이 아니라 컨텍스트로 다뤄지므로, 반드시 막아야 하는 동작은 PreToolUse 훅으로 차단합니다(CLAUDE.md 잘 쓰는 법, Hook으로 자동화 워크플로 만들기).
사고 사후 기록
인시던트 후 “X 마이그레이션은 항상 Y 도구로 검증” 같은 교훈을 메모리에 저장하면 재발 방지에 도움.
외부 시스템 매핑
“디자인 리뷰는 Figma의 ‘Design QA’ 채널에서” 같은 매핑을 저장해두면 Claude가 관련 작업 시 바로 안내.
다음 단계
- claude-mem — 더 적극적인 세션 간 메모리 압축
- Claude Code Setup — 프로젝트 분석 후 Memory, Skill, Hook 자동 추천
- CLAUDE.md 잘 쓰는 법 — 정적 컨텍스트(CLAUDE.md)와 동적 메모리의 역할 분리
- 메모리 공식 문서 — CLAUDE.md와 auto memory의 최신 동작