자동 메모리

Claude Code의 지속 기억은 두 체계로 나뉩니다. CLAUDE.md는 사용자가 작성하는 지시와 규칙이고, 자동 메모리(auto memory) 는 Claude가 작업 중 발견한 빌드 명령, 디버깅 단서, 아키텍처 메모, 코드 스타일 선호처럼 다음 대화에도 유용한 사실을 스스로 기록하는 기능입니다.

두 체계 모두 대화 시작 시 컨텍스트로 제공되지만 강제 정책은 아닙니다. 어떤 명령이나 파일 접근을 반드시 막아야 한다면 권한 규칙, 샌드박스, PreToolUse 훅 같은 집행 수단을 사용해야 합니다.

CLAUDE.md와 자동 메모리 비교

| 항목 | CLAUDE.md | 자동 메모리 | |---|---|---| | 작성자 | 사용자 또는 팀 | Claude | | 내용 | 코딩 규칙, 워크플로, 프로젝트 설명 | 작업 중 발견한 학습 내용과 반복 패턴 | | 범위 | 조직·사용자·프로젝트·로컬 | Git 저장소별, 같은 저장소의 worktree가 공유 | | 공유 방식 | 버전 관리 가능 | 기본적으로 머신 로컬 | | 관리 진입점 | 직접 편집, /memory | /memory, 일반 Markdown 파일 편집 |

팀원이 반드시 알아야 할 규칙은 CLAUDE.md에 둡니다. 특정 머신에서 반복적으로 발견되는 빌드 요령이나 디버깅 단서는 자동 메모리에 적합합니다. 자동 메모리를 팀 문서의 대체물로 사용하면 다른 머신과 CI 환경에서는 같은 정보를 볼 수 없다는 점에 주의해야 합니다.

저장 구조와 로딩 흐름

저장소마다 기본적으로 다음 디렉터리가 생성됩니다.

~/.claude/projects/<project>/memory/
├── MEMORY.md             # 짧은 인덱스: 매 대화 시작 시 일부 로드
├── debugging.md          # 상세 디버깅 기록: 필요할 때 읽음
├── api-conventions.md    # API 설계 결정: 필요할 때 읽음
└── ...                   # Claude가 만든 기타 주제 파일

새 대화 시작
    │
    ▼
┌─────────────────────────────────────────┐
│ MEMORY.md 앞 200줄 또는 25KB 중 작은 쪽 │
└───────────────────┬─────────────────────┘
                    │ 인덱스에서 관련 주제 발견
                    ▼
           필요한 주제 파일만 Read

MEMORY.md는 전체 지식을 담는 문서가 아니라 주제 파일을 찾기 위한 간결한 색인입니다. 시작 시에는 첫 200줄 또는 첫 25KB 중 먼저 도달한 범위만 로드됩니다. 그 뒤 내용은 자동으로 보이지 않으므로, 상세 설명은 별도 파일로 옮기고 MEMORY.md에는 한 줄 요약과 파일 포인터를 남기는 방식이 적절합니다.

주제 파일은 시작 시 모두 로드되지 않습니다. Claude가 현재 작업에 필요하다고 판단할 때 일반 파일 도구로 읽습니다. 이 분리는 시작 컨텍스트를 작게 유지하면서도 자세한 기록을 보존하기 위한 설계입니다.

활성화와 저장 위치

자동 메모리는 기본적으로 켜져 있습니다. 대화 안에서 /memory를 실행해 토글하거나, 특정 프로젝트 설정에서 끌 수 있습니다.

{
  "autoMemoryEnabled": false
}

환경 변수로 비활성화해야 하는 실행 환경에서는 다음 값을 사용합니다.

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

기본 경로 대신 별도 위치를 쓰려면 절대 경로나 ~/로 시작하는 경로를 지정합니다.

{
  "autoMemoryDirectory": "~/claude-memory/my-project"
}

프로젝트 설정에서 저장 위치를 바꾸는 값은 workspace trust를 승인한 뒤에 적용됩니다. 저장소 하위 디렉터리와 worktree는 같은 저장소에서 파생된 메모리 디렉터리를 공유하므로, 특정 worktree에만 해당하는 임시 사실을 저장할 때는 범위를 분명히 적어야 합니다.

무엇을 저장하고 무엇을 제외할까

좋은 자동 메모리는 이후 작업에서 다시 확인할 비용을 줄입니다.

재현 가능한 빌드·테스트 명령과 필요한 사전 조건
반복해서 발견된 디버깅 원인과 확인 순서
저장소 고유의 아키텍처 결정과 파일 위치
사용자가 여러 번 교정한 스타일 또는 워크플로 선호

반대로 다음 정보는 저장하지 않는 편이 안전합니다.

비밀번호, API 키, 토큰 같은 비밀
한 번의 작업에만 유효한 임시 상태
출처를 확인하지 않은 추측
이미 바뀐 버전이나 해결된 장애를 현재 사실처럼 서술한 내용

메모리는 일반 Markdown 파일이므로 언제든지 감사·수정·삭제할 수 있습니다. Claude가 저장했다는 사실만으로 내용이 영구적으로 정확해지는 것은 아닙니다. 버전, 가격, 정책처럼 변동 가능한 사실에는 확인 날짜와 출처를 남기고, 다음 사용 시 다시 검증해야 합니다.

`/memory`와 `/context`로 감사하기

/memory는 현재 적용 가능한 CLAUDE.md, 로컬 지시 파일, 자동 메모리 위치를 보여주고 파일을 편집기로 열 수 있습니다. 자동 메모리 토글과 메모리 폴더 열기도 여기서 수행합니다.

/context는 실제로 현재 대화에 로드된 메모리 파일을 확인하는 데 사용합니다. 파일이 디스크에 존재한다는 사실과 현재 컨텍스트에 포함됐다는 사실은 다르므로, 지시가 적용되지 않는 문제를 진단할 때 두 명령을 구분해야 합니다.

기억이 적용되지 않음
   ├─ /context: 실제 로드 여부 확인
   ├─ /memory: 위치·내용·활성화 상태 확인
   ├─ MEMORY.md: 200줄/25KB 범위 안의 색인 확인
   └─ 오래된 항목: 수정하거나 제거

서브에이전트와 포크

메인 대화의 자동 메모리는 일반 서브에이전트에 그대로 로드되지 않습니다. 부모 대화와 시스템 프롬프트를 상속하는 포크는 예외입니다. 서브에이전트 정의의 memory 필드로 별도 자동 메모리를 활성화한 경우에는 그 에이전트만의 디렉터리를 사용합니다. 따라서 하위 에이전트가 반드시 알아야 하는 규칙은 메인 자동 메모리에만 의존하지 말고 프롬프트, CLAUDE.md, 스킬 또는 에이전트 정의에 명시해야 합니다.

핵심 정리

CLAUDE.md는 사용자가 작성하는 지시이고, 자동 메모리는 Claude가 저장하는 저장소별 학습 기록입니다.
자동 메모리는 기본적으로 켜져 있고 ~/.claude/projects/<project>/memory/ 아래에 저장됩니다.
시작 시 MEMORY.md의 첫 200줄 또는 25KB만 로드되며 상세 주제 파일은 필요할 때 읽습니다.
/memory로 위치와 내용을 관리하고 /context로 실제 로드 여부를 확인합니다.
자동 메모리는 머신 로컬 컨텍스트이지 보안 정책이나 팀 문서의 대체물이 아닙니다.