만약 Claude Code를 어느 정도 사용해 본 적이 있다면, 이 불편함을 알고 있을 겁니다. 새로운 세션을 열면 어제 가르쳐준 모든 것을 잊어버립니다. 저는 반복해서 '내 글에 너무 많은 이모지를 넣지 말라'고 이야기하는데, 이게 너무 AI 같아 보인다고요. 그런데 다음 날 아침, 새 세션에서는 또 온통 이모지로 가득합니다.

알고 보니 바로 이런 것을 위해 Auto Memory라는 기능이 만들어졌습니다. 저는 이미 수동으로 프로젝트 규칙을 설정하는 방법에 대해 CLAUDE.md에 대해 작성한 적이 있지만, Claude Code의 메모리 시스템은 단순히 CLAUDE.md보다 훨씬 광범위합니다. Auto Memory는 사용자가 작업하는 동안 수정 사항과 선호 사항을 조용히 기록하여, 다음 세션에서 다시 말할 필요가 없게 만듭니다.

Auto Memory는 Claude Code v2.1.59 이상이 필요합니다. claude --version으로 확인하세요.

Auto Memory 대 CLAUDE.md

많은 사람들이 이 두 가지를 혼동하므로, 먼저 명확히 하겠습니다.

요약하자면: CLAUDE.md는 사용자가 의도적으로 Claude에게 규칙을 작성해 주는 것입니다. 예를 들어, '2칸 들여쓰기를 사용하라', '커밋 메시지는 영어로 작성하라' 같은 식입니다. Auto Memory는 Claude가 사용자와 함께 작업하는 동안 스스로 습득하는 것입니다. 사용자가 쓰는 것이 아니라, Claude가 합니다.

Auto Memory가 실제로 하는 일

Auto Memory는 기본적으로 Claude가 자체적인 메모를 취하는 것과 같습니다. 사용자가 수정하거나 특정 접근 방식이 효과적이었는지 알려주면, Claude는 그것을 나중에 기억할 가치가 있다고 판단합니다. 만약 그렇다면, 이를 저장합니다.

그래서 제가 이렇게 말했을 때:

너무 많은 이모지를 쓰지 마라, 너무 AI 같아 보인다

Claude는 이것을 메모 파일로 저장했고, 모든 새로운 세션에서 다시 불러옵니다. 이제 저는 이모지로 가득 찬 것을 좋아하지 않는다는 것을 기억합니다.

하지만 모든 것을 저장하는 것은 아닙니다. 일회성 대화나 미래 작업과 관련 없는 내용은 기록되지 않습니다.

저장되는 위치 (이 부분이 헷갈립니다)

모두를 혼란스럽게 만드는 지점이 바로 여기입니다. 프로젝트에는 .claude/ 폴더가 있지만, 자동 메모리 (Auto Memory) 파일은 그 안에 없습니다. 프로젝트의 .claude/ 폴더는 설정 (settings.json, settings.local.json)과 규칙 (rules)만을 보관합니다.

실제 메모리는 사용자의 홈 디렉토리 아래에 존재합니다:

/Users/ray/my-project/.claude/                              <- 프로젝트 설정, 리포지토리(repo) 내부
/Users/ray/.claude/projects/-Users-ray-my-project/memory/   <- 자동 메모리 (Auto Memory), 홈 디렉토리 아래

두 경로 모두 .claude를 포함하고 있지만, 하나는 프로젝트 내에 있고 하나는 홈 디렉토리에 있습니다. 이 둘을 혼동하지 마세요. 프로젝트의 .claude/를 살펴봤을 때 settings.local.json만 발견된다면, 그것은 정상입니다. 메모리는 애초에 그곳에 있지 않았기 때문입니다.

메모리 경로는 Git 리포지토리로부터 파생되므로, 동일한 리포지토리의 하위 디렉토리와 워크트리 (worktrees)는 하나의 메모리를 공유합니다. 또한 이는 머신 로컬 (machine-local) 방식입니다. 즉, 다른 머신이나 클라우드 환경으로 동기화되지 않습니다.

만약 다른 곳에 저장하고 싶다면, autoMemoryDirectory를 설정하세요 (Policy / Local / User 레벨에서만 가능하며, 의도적으로 프로젝트 레벨에서는 불가능하게 설계되었습니다. 이는 공유 리포지토리가 사용자의 메모리를 수상한 곳으로 리다이렉트하는 것을 방지하기 위함입니다):

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

디렉토리 구조

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 인덱스 (index), 매 세션마다 로드됨
├── debugging.md       # 디버깅 노트 (debugging notes)
...

MEMORY.md는 인덱스 역할을 합니다. Claude는 이를 사용하여 어떤 메모리가 존재하는지, 그리고 각 메모리가 어떤 파일에 들어있는지를 추적합니다. 세션 시작 시에는 MEMORY.md의 처음 200줄 / 25KB만 로드되므로, Claude는 이를 가볍게 유지하고 상세 내용은 별도의 주제 파일 (topic files)로 넘깁니다. 이러한 주제 파일들은 시작 시 로드되지 않으며, Claude가 필요할 때 (on demand) 읽어들입니다. 따라서 메모리가 커지더라도 매번 컨텍스트 (context)가 비대해지지 않고 성장할 수 있습니다.

(이 200줄 제한은 MEMORY.md에만 적용됩니다. CLAUDE.md는 항상 전체가 로드되지만, 짧을수록 지시 사항 준수 능력이 더 좋아집니다.)

메모리가 작성되고 있는지 어떻게 알 수 있나요?

Claude Code UI에서 "Writing memory" 또는 "Recalled memory"라는 문구가 보인다면, 이는 메모리 파일을 업데이트하거나 읽고 있다는 뜻입니다. 사용자가 별도로 할 일은 없으며, 시스템이 알아서 처리합니다.

관리 방법

• /memory — 주요 진입점입니다. 로드된 내용을 확인하고, 자동 메모리 (Auto Memory)를 켜거나 끌 수 있으며, 메모리 폴더를 열거나 에디터에서 파일을 바로 열 수 있습니다.
• 그냥 요청하기 — "remember: always use pnpm, never npm"과 같이 말하면 메모리가 저장됩니다. "forget the rule about pnpm"이라고 하면 해당 규칙을 업데이트하거나 삭제합니다.
• 수동 편집 — 메모리는 ~/.claude/projects/ 경로 아래에 있는 일반 Markdown 파일입니다. 원하는 내용을 자유롭게 추가, 수정 또는 삭제할 수 있습니다.
• 끄기 — /memory에서 토글하거나, "autoMemoryEnabled": false로 설정하거나, CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 환경 변수를 설정하여 끌 수 있습니다.

혹시 궁금해하실 분들을 위해 덧붙이자면: /compact 명령어를 사용해도 메모리가 삭제되지 않습니다. 파일은 대화 내용이 아닌 디스크에 저장되어 있기 때문입니다. 컴팩팅 (Compacting)은 채팅 기록만 압축하며, 그 이후에 MEMORY.md와 CLAUDE.md를 디스크에서 다시 읽어와 주입합니다.

이것이 전부입니다. 작은 기능이지만, 매 세션마다 같은 말을 반복하지 않게 되면 다시 이전으로 돌아가기 어려울 것입니다.