MEMORY.md 완벽 정리(Claude code)

CLAUDE.md가 내가 Claude에게 주는 지시서라면, MEMORY.md는 Claude가 스스로 작성하는 업무 메모장이다.

 

1. MEMORY.md란 무엇인가

Claude Code에는 두 가지 기억 시스템이 있다. CLAUDE.md는 사용자가 작성하는 지시서이고, MEMORY.md는 Claude가 작업하면서 스스로 작성하는 노트다. 공식 명칭은 "자동 메모리(Auto Memory)"다.

Claude는 세션 중에 발견한 것들을 저장한다. 빌드 명령, 디버깅 인사이트, 아키텍처 노트, 코드 스타일 선호도, 워크플로우 습관 등. 핵심은 사용자가 아무것도 안 해도 Claude가 알아서 축적한다는 점이다.

단, 매 세션마다 무조건 저장하는 게 아니다. Claude가 "이 정보가 향후 대화에서 유용할까?"를 판단해서 기억할 가치가 있을 때만 저장한다.

---

2. 저장 위치와 구조

①경로

각 프로젝트의 자동 메모리는 아래 경로에 저장된다.

~/.claude/projects/<project>/memory/

<project> 경로는 git 저장소에서 파생된다. 따라서 같은 repo 안의 모든 worktree와 하위 디렉토리가 하나의 메모리 디렉토리를 공유한다. git 저장소 외부에서는 프로젝트 루트 경로가 대신 사용된다.

②파일 구조

~/.claude/projects/<project>/memory/
├── MEMORY.md          ← 인덱스 파일 (매 세션 로드)
├── debugging.md       ← 디버깅 패턴 상세 노트
├── api-conventions.md ← API 설계 결정
└── ...                ← Claude가 필요에 따라 만드는 주제 파일

MEMORY.md가 진입점이자 인덱스 역할을 한다. Claude는 이 파일을 통해 어떤 노트가 저장되어 있는지 추적한다. 상세한 내용은 별도 주제 파일로 분리해서 MEMORY.md를 간결하게 유지한다.

---

3. 로드 방식 — 200줄 제한

①세션 시작 시

MEMORY.md의 처음 200줄만 매 세션 시작 시 자동 로드된다. 200줄을 초과하는 내용은 시작 시 읽히지 않는다.

이 200줄 제한은 MEMORY.md에만 적용된다. CLAUDE.md는 길이와 무관하게 전체가 로드된다(다만 짧을수록 준수율이 좋다).

②주제 파일

debugging.md, api-conventions.md 같은 주제 파일은 세션 시작 시 로드되지 않는다. Claude가 작업 중 필요하다고 판단할 때 파일 도구를 사용해서 직접 읽는다. 즉, MEMORY.md가 인덱스이고 주제 파일은 필요 시 참조하는 구조다.

---

4. 저장 시점 — 언제 기록되나

Claude는 매 세션마다 저장하지 않는다. 다음과 같은 상황에서 저장이 발생한다.

Claude가 자체 판단으로 저장

작업 중 "이 정보가 다음 세션에서 유용하겠다"고 판단하면 Claude가 알아서 저장한다. 예를 들어:

• 빌드 시 특정 플래그가 필요하다는 걸 발견했을 때
• 디버깅 과정에서 프로젝트 특유의 패턴을 파악했을 때
• 사용자의 코드 스타일 선호도를 반복적으로 확인했을 때

Claude Code 인터페이스에서 "메모리 작성" 또는 "메모리 회상"이 표시되면 Claude가 메모리를 적극적으로 업데이트하거나 읽고 있는 것이다.

사용자가 명시적으로 요청

Claude에게 직접 기억을 요청할 수도 있다.

• "항상 npm이 아닌 pnpm을 사용해" → 자동 메모리에 저장
• "API 테스트에 로컬 Redis가 필요하다는 걸 기억해" → 자동 메모리에 저장

주의: "기억해줘"라고 하면 자동 메모리에 저장된다. CLAUDE.md에 넣고 싶으면 "이것을 CLAUDE.md에 추가해줘"라고 명시적으로 말해야 한다. 이 차이가 중요하다.

---

5. 관리 방법

/memory 명령어

세션에서 /memory를 실행하면:

• 현재 로드된 모든 CLAUDE.md 및 규칙 파일 목록 확인
• 자동 메모리 켜기/끄기 토글
• 자동 메모리 폴더를 열어서 직접 편집

직접 편집

자동 메모리 파일은 전부 일반 마크다운이다. 언제든지 에디터로 열어서 읽고, 수정하고, 삭제할 수 있다. Claude가 잘못 학습한 내용이 있으면 직접 고치면 된다.

비활성화

자동 메모리가 필요 없다면 끌 수 있다. 두 가지 방법:

프로젝트 설정 (.claude/settings.json):

{
  "autoMemoryEnabled": false
}

환경 변수:

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

기본값은 켜져 있다.

---

6. 특성과 제약

머신 로컬

자동 메모리는 해당 머신에서만 유효하다. 다른 컴퓨터나 클라우드 환경과 공유되지 않는다. 팀원과 공유가 필요한 정보라면 자동 메모리가 아니라 CLAUDE.md에 넣어야 한다.

git repo 단위 공유

같은 git 저장소 안의 모든 worktree와 하위 디렉토리는 하나의 자동 메모리 디렉토리를 공유한다. 브랜치나 worktree가 달라도 메모리는 동일하다.

Subagent 메모리

Subagent도 자신만의 자동 메모리를 유지할 수 있다. 메인 에이전트와 별도로 학습을 축적한다.

---

7. CLAUDE.md vs MEMORY.md — 뭘 어디에?

상황	어디에?
팀 코딩 표준, 아키텍처 규칙	CLAUDE.md
"커밋 메시지는 conventional commits"	CLAUDE.md
"응답은 한국어로"	CLAUDE.md (사용자 글로벌)
빌드 시 발견한 특정 플래그 필요	자동 메모리가 알아서
디버깅 중 발견한 프로젝트 특유 패턴	자동 메모리가 알아서
사용자의 코드 스타일 선호도	자동 메모리가 알아서

원칙: 의도적으로 통제해야 하는 규칙은 CLAUDE.md에, Claude가 작업하면서 자연스럽게 축적하는 학습은 자동 메모리에.

 

자동 메모리는 Claude Code를 "쓸수록 똑똑해지는 도구"로 만드는 장치다. 사용자가 아무것도 안 해도 Claude가 프로젝트를 점점 더 잘 이해하게 된다. 다만 주기적으로 /memory로 점검해서 잘못 학습한 내용이 없는지 확인하는 습관이 필요하다.