자동 메모리(Auto memory)

확인 날짜 안내

원본 날짜 미상. 공식 문서 수집일(2026-10-18) 기준이다. 설정 키와 버전 조건은 빨리 바뀔 수 있다.

정의#

Claude Code가 사용자가 아무것도 쓰지 않아도 세션(용어 사전)을 넘어 지식을 쌓게 하는 장치다. Claude가 일하면서 사용자의 교정과 선호를 바탕으로 스스로 노트를 쓴다. 사용자가 쓰는 메모리(CLAUDE.md)와 짝을 이루는 두 번째 메모리 시스템이다. Claude Code 메모리

무엇을 저장하는가#

Claude는 네 종류의 노트를 저장하고, 종류를 메모리 파일 frontmatter의 type 필드에 적는다. Claude Code 메모리

• 저장하지 않는 것: 코드베이스에서 알 수 있는 것(아키텍처, 파일 경로, 디버깅 수정)과 CLAUDE.md에 이미 있는 것. Claude Code 메모리
• 매 세션 무언가를 저장하지는 않는다. 앞으로의 대화에 쓸모가 있는지를 보고 Claude가 정한다. Claude Code 메모리
• Claude에게 "항상 npm 말고 pnpm을 써", "API 테스트에는 로컬 Redis가 필요하다는 걸 기억해"처럼 기억하라고 하면 자동 메모리에 저장된다. CLAUDE.md에 넣고 싶으면 "CLAUDE.md에 추가해"라고 직접 말한다. Claude Code 메모리

어디에 저장되는가 (2026-10-18 기준)#

• 프로젝트마다 ~/.claude/projects/<project>/memory/ 디렉터리가 생긴다. <project>는 git 저장소에서 정해지므로 같은 저장소의 워크트리와 하위 디렉터리는 하나의 메모리 디렉터리를 공유한다. git 저장소 밖이면 프로젝트 루트를 쓴다. Claude Code 메모리

• 디렉터리에는 색인 MEMORY.md와 메모리 하나당 주제 파일 하나가 있다(예: user_role.md, feedback_testing.md). Claude Code 메모리

• 기계 로컬이다. 다른 기계나 클라우드 환경과 공유되지 않는다. Claude Code 메모리

• 오래된 세션 기록은 cleanupPeriodDays 기간이 지나면 지워지지만 메모리 파일은 그 정리 대상에서 빠진다. 사용자나 Claude가 고치거나 지울 때까지 남는다. Claude Code 메모리

• 다른 위치에 두려면 settings.json에 autoMemoryDirectory를 설정한다. 값은 절대 경로이거나 ~/로 시작해야 한다. Claude Code 메모리 (2026-10-21 기준) settings reference: 기본값은 ~/.claude/projects/<project>/memory/이고, project·local 파일에 둔 값은 클론한 저장소가 줄 수 있으므로 훅과 같은 작업 공간 신뢰 규칙을 따른다. permissions.blockReadsOutsideWorkingDirectories가 켜진 상태에서 이 값이 저장소 설정에서 오면 그 디렉터리에서 자동 메모리를 읽지도 쓰지도 않는다. Claude Code 설정 키 전체 레퍼런스

• 권한: .claude는 쓰기를 자동 승인하지 않는 보호 경로지만, 프로젝트 자동 메모리 디렉터리(예: ~/.claude/projects/<project>/memory/)의 마크다운 파일은 --restricted 없이 시작한 세션에서 예외다. Claude Code 권한 모드 → 권한 모드

어떻게 로드되는가#

• MEMORY.md의 앞 200줄 또는 25KB 중 먼저 닿는 쪽까지만 매 대화 시작 때 로드된다. 그 뒤 내용은 시작 때 로드되지 않는다. Claude Code 메모리
• 그래서 Claude는 MEMORY.md를 한 항목 한 줄로 짧게 두고 세부는 주제 파일로 옮긴다. 한도에 가까워지면 Claude Code가 줄이라고 알려 주고, 한도를 넘으면 쓰기는 되지만 색인을 다시 쓰라는 오류를 돌려준다. 한도를 넘는 부분은 다음 로드 때 버려지기 때문이다. Claude Code 메모리
• 주제 파일은 시작 때 로드되지 않는다. Claude가 필요할 때 일반 파일 도구로 읽는다. Claude Code 메모리
• 이 200줄·25KB 한도는 MEMORY.md에만 적용된다. CLAUDE.md는 4 MiB까지 전부 로드된다. Claude Code 메모리
• 메인 대화의 자동 메모리는 서브에이전트에 로드되지 않는다. 예외는 부모 대화를 그대로 잇는 포크다. 서브에이전트는 정의의 memory 필드로 자기 자동 메모리(별도 디렉터리)를 가질 수 있다. Claude Code 메모리
• (2026-10-18 기준) 공식 서브에이전트 문서의 memory 필드 범위: user(~/.claude/agent-memory/<name-of-agent>/), project(.claude/agent-memory/<name-of-agent>/, 버전 관리로 공유, 원본의 권장 기본값), local(.claude/agent-memory-local/<name-of-agent>/, 버전 관리 제외). 켜면 시스템 프롬프트에 메모리 읽기·쓰기 지시와 그 디렉터리 MEMORY.md 앞 200줄 또는 25KB(먼저 닿는 쪽)가 들어가고 Read·Write·Edit 도구가 자동으로 켜진다. 서브에이전트 메모리는 자동 메모리의 일부라, autoMemoryEnabled나 CLAUDE_CODE_DISABLE_AUTO_MEMORY로 자동 메모리를 끄면 이 필드도 효과가 없다. Claude Code 서브에이전트 → Claude Code 서브에이전트 만들기·운영
• 공식 작동 방식 문서도 같은 한도를 적고, 자동 메모리를 "작업하며 Claude가 자동으로 저장하는 학습(예: 선호)"으로, 세션은 이전 대화 없이 시작하므로 세션을 넘는 학습을 잇는 장치로 설명한다. Claude Code 작동 방식
• 공식 컨텍스트 창 문서도 같은 한도(앞 200줄 또는 25KB 중 먼저 닿는 쪽)와 서브에이전트 규칙을 확인한다. 자동 메모리는 입력 전에 로드되고 터미널에는 보이지 않으며, 컴팩션 뒤에는 디스크에서 다시 주입된다. Claude Code 컨텍스트 창 → 장기 작업 컨텍스트 관리
• 어떤 자동 메모리 파일이 로드됐는지는 /context로, 내용은 /memory로 열어 확인한다. Claude Code 컨텍스트 창
• 화면에 "Saved 2 memories", "Recalled 2 memories" 같은 메시지가 보이면 Claude가 메모리 디렉터리를 쓰거나 읽는 중이다. Claude Code 메모리
• frontmatter가 있는 메모리 파일을 Claude가 쓰면 Claude Code가 modified 필드에 쓴 시각(ISO 8601)을 기록한다. 그 사실이 얼마나 최신인지 사용자와 Claude가 알 수 있다. v2.1.214 이상. Claude Code 메모리

(편집자 해석) 색인 파일 하나를 짧게 유지하고 세부는 주제 파일에 둔 뒤 필요할 때 읽는 구조는, 컨텍스트 엔지니어링의 "가벼운 식별자만 들고 있다가 필요할 때 불러오기"와 index·log 운영의 index.md 방식과 같은 방향으로 볼 수 있다. 근거 문장: 메모리 문서의 "MEMORY.md acts as an index of the memory directory"와 "Claude reads them on demand". 메모리 문서는 이 두 개념을 언급하지 않는다. Claude Code 메모리

켜고 끄기#

• 로컬 세션에서는 기본으로 켜져 있다. 자체 호스팅 환경의 세션은 Claude Tag 세션을 빼면 기본으로 꺼져 있다. Claude Code 메모리
• 세션에서 /memory를 열어 토글한다. 이 설정은 ~/.claude/settings.json의 autoMemoryEnabled에 저장된다. Claude Code 메모리
• 백그라운드 세션이나 다른 Claude Code 세션이 띄운 세션에서는 토글로 끌 수는 있어도 다시 켤 수 없다. 터미널에서 claude를 직접 실행한 세션에서 켠다. Claude Code 메모리
• 한 프로젝트만 끄려면 그 프로젝트 설정에 "autoMemoryEnabled": false, 환경 변수로 끄려면 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Claude Code 메모리 (2026-10-21 기준) settings reference: autoMemoryEnabled 기본값은 true, Scope는 Any file이다. 환경 변수는 그 세션에서 이 키보다 양방향으로 우선하고, --bare와 safe mode도 자동 메모리를 끈다. Claude Code 설정 키 전체 레퍼런스

확인하고 고치기#

• 메모리 파일은 언제든 고치거나 지울 수 있는 일반 마크다운이다. /memory에서 자동 메모리 폴더를 열어 무엇이 저장됐는지 본다. Claude Code 메모리

관련#

• CLAUDE.md와의 비교 표: 메모리(CLAUDE.md)
• 창 밖에 노트를 써 두고 나중에 다시 읽는 일반 기법(구조화된 노트): 장기 작업 컨텍스트 관리