Claude Code 자동 메모리란 무엇인가? MEMORY.md 저장 위치, 세션별 로드 범위 및 비활성화 방법 (2026)

Claude Code에는 두 가지 메모리 시스템이 있습니다. Anthropic의 문서에 따르면 "두 시스템 모두 모든 대화가 시작될 때 로드됩니다." 차이점은 누가 작성하느냐에 있습니다.

• CLAUDE.md 파일. 사용자가 작성합니다. 코딩 표준, 워크플로우, 프로젝트 아키텍처와 같은 지침과 규칙을 담고 있습니다.
• 자동 메모리. Claude가 작성합니다. 학습 내용과 패턴을 담고 있습니다: "사용자의 선호도, 사용자가 Claude에게 준 수정 사항, Claude가 코드에서 도출할 수 없는 프로젝트 컨텍스트(context)".

둘 다 설정(configuration)이 아닌 컨텍스트입니다. Anthropic은 Claude가 이를 "강제된 설정이 아닌 컨텍스트로 취급한다"고 말합니다. 어떤 상황에서도 강제되어야 하는 사항이 필요하다면, 문서는 대신 훅(hook)을 사용할 것을 권장합니다.

작업을 수행하면서 Claude는 네 가지 종류의 노트를 저장하며, 각 노트는 메모리 파일에 유형(type) 필드로 기록됩니다.

• user: "사용자의 역할, 전문성 및 작업 선호도"
• feedback: "사용자가 Claude에게 준 수정 사항 및 사용자가 확인한 접근 방식"
• project: "진행 중인 작업, 마감일, 그리고 Claude가 코드나 git 기록에서 도출할 수 없는 결정 사항"
• reference: "이슈 트래커나 대시보드와 같이 프로젝트 외부에서 정보를 찾을 수 있는 위치"

또한 의도적으로 제외하는 항목도 있습니다. "Claude는 아키텍처, 파일 경로 또는 디버깅 수정 사항과 같이 코드베이스에서 도출할 수 있는 모든 항목을 건너뜁니다. 또한 CLAUDE.md 파일에 이미 명시된 내용도 건너뜁니다."

그리고 매 세션마다 저장하는 것도 아닙니다. "Claude는 모든 세션에서 저장하지 않습니다. 해당 정보가 향후 대화에서 유용할지 여부에 따라 기억할 가치가 있는지를 결정합니다."

직접 요청할 수도 있습니다. Anthropic의 예시에 따르면, npm 대신 항상 pnpm을 사용하라는 것과 같이 무언가를 기억해 달라고 요청하면 "Claude는 이를 자동 메모리에 저장합니다". 대신 지침을 CLAUDE.md에 넣으려면 명시적으로 요청하거나 직접 파일을 편집하십시오.

"각 프로젝트는 ~/.claude/projects/<project>/memory/에 자체 메모리 디렉토리를 갖습니다." 프로젝트 경로는 git 저장소에서 가져오므로 "동일한 저장소 내의 모든 작업 트리(worktrees)와 하위 디렉토리는 하나의 자동 메모리 디렉토리를 공유합니다". git 저장소 외부인 경우 프로젝트 루트가 사용됩니다.

디렉토리 내부에서 MEMORY.md는 인덱스 역할을 하며 메모리당 한 줄씩 기록되고, 각 메모리는 고유한 토픽 파일을 가집니다. Anthropic은 MEMORY.md를 "메모리 디렉토리의 인덱스 역할"을 하는 것으로 설명합니다.

해당 폴더의 세 가지 특징은 알아둘 가치가 있습니다.

• 머신 로컬(Machine-local)입니다. "파일은 머신 간 또는 클라우드 환경 간에 공유되지 않습니다." Claude Code가 다른 머신에서 모든 것을 잊어버리는 이유에 대한 가이드에서 이것이 실제적으로 무엇을 의미하는지 다룹니다.
• 작업 트리 간에 공유됩니다. 하나의 저장소, 하나의 메모리 폴더를 사용하며, 얼마나 많은 작업 트리를 열든 상관없습니다. 작업 트리가 메모리를 공유하는지에 대한 가이드에서 각 작업 트리 세션이 로드하는 내용을 다룹니다.
• 기록(transcripts)과 함께 삭제되지 않습니다. Claude Code는 보관 기간이 지나면 오래된 세션 기록을 삭제하지만, 메모리 파일은 제외됩니다. "MEMORY.md와 토픽 파일은 사용자나 Claude가 편집하거나 삭제할 때까지 유지됩니다."

다른 위치로 이동하기

자동 메모리를 다른 위치에 저장하려면 설정에서 autoMemoryDirectory를 설정하십시오. 문서에 따르면 값은 "절대 경로여야 하거나 ~/로 시작해야 합니다". 프로젝트 설정 파일에 설정된 경우, Claude Code는 훅에 사용하는 것과 동일한 작업 공간 신뢰 규칙을 적용합니다.

자동 메모리의 모든 내용이 한 번에 로드되는 것은 아닙니다. "모든 대화가 시작될 때 MEMORY.md의 처음 200행 또는 처음 25KB 중 먼저 도달하는 기준까지 로드됩니다. 해당 임계값을 넘는 콘텐츠는 세션 시작 시 로드되지 않습니다."

토픽 파일은 다르게 작동합니다. "Claude Code는 시작 시 user_role.md나 feedback_testing.md와 같은 토픽 파일을 로드하지 않습니다. Claude는 정보가 필요할 때 표준 파일 도구를 사용하여 요청 시(on demand) 이를 읽습니다."

인덱스를 제한 내로 유지하기

Claude Code는 인덱스 크기를 모니터링합니다. Claude가 MEMORY.md에 기록한 후, Claude Code는 200행 및 25KB 제한을 확인합니다. 제한에 가까워지면 Claude에게 파일을 단축하도록 알립니다: 항목당 한 줄로 줄이고, 세부 사항은 토픽 파일로 이동하며, 오래된 항목은 병합하거나 삭제합니다. 제한을 초과하더라도 기록은 성공하지만, Claude는 인덱스를 다시 작성하라는 지시를 받습니다. "제한을 넘는 모든 내용은 다음 로드 시 삭제되기 때문입니다."

이 제한은 MEMORY.md에만 해당됩니다. Anthropic은 Claude가 실행 시 로드되는 각 CLAUDE.md 파일의 전체 내용(최대 4 MiB)을 가져온다고 명시합니다. 하위 디렉토리의 CLAUDE.md 파일과 경로 범위 규칙은 자체적인 더 작은 제한을 가집니다. 하위 디렉토리 CLAUDE.md 제한에 대한 가이드에서 이를 다룹니다.

서브에이전트 및 포크(Forks)

"메인 대화의 자동 메모리는 서브에이전트에 로드되지 않습니다. 예외는 포크(fork)로, 부모 대화와 시스템 프롬프트를 상속받습니다." 서브에이전트는 별도의 디렉토리에 메모리 필드를 활성화하여 자체 자동 메모리를 가질 수 있습니다.

인터페이스가 알려주는 정보

Claude가 메모리를 읽거나 쓸 때 이를 확인할 수 있습니다. Anthropic은 'Saved 2 memories' 또는 'Recalled 2 memories'와 같은 인터페이스 메시지가 Claude가 메모리 폴더를 "활발하게 업데이트하거나 읽고 있음"을 의미한다고 말합니다. 프런트매터(frontmatter)가 있는 각 메모리 파일에는 수정된 타임스탬프도 포함되어 있어, "사용자와 Claude 모두에게 해당 사실이 얼마나 최신인지"를 보여줍니다.

"자동 메모리는 로컬 세션에서 기본적으로 켜져 있습니다." 자체 호스팅 환경의 세션은 Claude Tag 세션을 제외하고 기본적으로 꺼진 상태로 실행됩니다.

비활성화하는 세 가지 방법이 있습니다.

• /memory 토글. 세션에서 /memory를 열고 자동 메모리 토글을 사용합니다. 이는 사용자 설정에 autoMemoryEnabled를 저장합니다.
• 프로젝트별 설정. 해당 프로젝트의 설정에서 autoMemoryEnabled를 false로 설정합니다.
• 환경 변수. CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 설정합니다.

토글로 다시 켤 수 없는 이유

알아두어야 할 한 가지 사례가 있습니다. 토글로 자동 메모리를 끌 수는 있지만, 백그라운드 세션이나 다른 Claude Code 세션이 시작한 세션에서는 다시 켤 수 없습니다. 이 경우 토글에는 off · can't be turned on here; use a session started outside Claude Code라고 표시됩니다. 다시 켜려면 터미널에서 Claude Code를 직접 실행하고 거기서 /memory를 사용하십시오.

"자동 메모리 파일은 언제든지 편집하거나 삭제할 수 있는 일반 마크다운입니다." /memory를 실행하여 파일을 찾아보고 열 수 있습니다. 여기에는 CLAUDE.md 파일과 메모리 위치가 나열되며, 자동 메모리를 토글할 수 있고 자동 메모리 폴더를 여는 옵션이 있습니다.

자동 메모리에 무엇이 저장되었는지 확실하지 않은 경우, Anthropic의 문제 해결 답변은 명확합니다. " /memory를 실행하고 자동 메모리 폴더를 선택하여 Claude가 저장한 내용을 찾아보십시오."

VS Code 확장 프로그램의 Customize 메뉴에는 자동 메모리 토글, 저장된 메모리 및 메모리 폴더를 보여주는 Memory 항목이 있습니다.

Anthropic의 구분은 유용한 규칙입니다. "Claude의 행동을 가이드하고 싶을 때는 CLAUDE.md 파일을 사용하십시오. 자동 메모리는 수동 작업 없이도 Claude가 사용자의 수정 사항으로부터 학습할 수 있게 해줍니다."

• 팀 규칙 및 표준은 CLAUDE.md에 속하며, 체크인되어 모든 사람이 공유할 수 있어야 합니다. 일부 파일에만 적용되는 규칙의 경우, Claude Code 규칙에 대한 가이드에서 경로 범위 로딩을 다룹니다.
• 사용자의 선호도 및 수정 사항은 사용자의 머신에 있는 자동 메모리에 적합합니다.
• AGENTS.md를 사용하는 저장소는 자체 로딩 규칙을 따릅니다. Claude Code 및 AGENTS.md에 대한 가이드에서 언제 읽히는지 설명합니다.

이 세션에서 꺼져 있습니다. /memory를 확인하십시오. 백그라운드 세션 및 다른 Claude Code 세션에 의해 시작된 세션은 이를 다시 켤 수 없습니다.

다른 저장소 경로에 있습니다. 폴더는 저장소별로 생성됩니다. 다른 위치에 있는 동일한 코드의 별도 클론은 다른 폴더를 가질 수 있습니다.

다른 머신에 있습니다. 자동 메모리는 머신 간 또는 클라우드 환경으로 동기화되지 않습니다.

인덱스가 제한을 초과했습니다. MEMORY.md의 처음 200행 또는 25KB를 넘는 내용은 로드되지 않습니다.

서브에이전트에 있습니다. 서브에이전트는 포크가 아닌 한 메인 대화의 자동 메모리를 로드하지 않습니다.

Claude가 저장할 가치가 없다고 판단했습니다. 모든 세션에서 저장되지는 않습니다. 명시적으로 무언가를 기억해 달라고 요청하십시오. 이전 세션에서 논의한 내용을 찾으려면, Claude Code 세션 기록 찾기 가이드에서 기록 저장 위치를 확인하십시오.

MEMORY.md를 CLAUDE.md처럼 편집하는 것. 작동은 하지만, MEMORY.md는 Claude가 유지 관리하는 인덱스입니다. 준수되기를 원하는 규칙은 CLAUDE.md에 있어야 합니다.

인덱스가 계속 커지게 두는 것. 200행 또는 25KB를 넘으면 나머지는 세션 시작 시 로드되지 않습니다.

두 번째 머신에서도 메모리가 있을 것이라 기대하는 것. 폴더는 머신 로컬입니다.

백그라운드 세션에서 다시 켜려고 시도하는 것. 거기서는 켤 수 없습니다. 터미널에서 직접 시작한 세션을 사용하십시오.

기록을 삭제하면 메모리도 함께 삭제된다고 가정하는 것. 메모리 파일은 기록 정리 대상에서 제외됩니다.

1단계: 저장된 내용 확인

/memory를 실행하고 자동 메모리 폴더를 열어 MEMORY.md를 읽어보십시오. 각 줄이 여전히 유효한지 확인하십시오. 오래된 내용은 삭제하십시오. 파일은 일반 마크다운입니다.

2단계: 규칙을 CLAUDE.md로 이동

프로젝트의 모든 사람에게 적용되어야 하거나 매번 준수되어야 하는 사항은 CLAUDE.md에 속합니다. Claude에게 거기에 추가해 달라고 요청하거나 /memory를 통해 파일을 편집하십시오.

3단계: 이동해야 할 항목 결정

자동 메모리는 하나의 머신과 하나의 저장소에 머뭅니다. 머신, 저장소 또는 도구 전반에 걸쳐 필요한 선호도와 결정 사항은 이 폴더에 묶이지 않은 다른 곳에 복사본을 보관하십시오.

자동 메모리는 한 머신의 한 저장소 내에서 잘 작동합니다. 하지만 그 한계도 동일한 설계에서 비롯됩니다. 폴더는 저장소별로 존재하며, 머신을 벗어나지 않고, 인덱스의 첫 부분만 로드됩니다. 어디서나 필요한 선호도와 결정 사항은 자동 메모리와 함께 이동하지 않습니다.

MemoryLake는 이러한 사항들을 사용자가 관리하는 하나의 리스트로 유지하고, Claude Code뿐만 아니라 ChatGPT, Codex 등 연결된 다른 어시스턴트에서도 사용할 수 있게 해주는 메모리 레이어입니다.

사용자는 자신의 언어로 직접 항목을 작성합니다. 사용자의 자동 메모리 폴더, MEMORY.md, CLAUDE.md 파일 또는 어떤 벤더의 저장소에서도 내용을 읽거나 쓰거나 삭제하지 않습니다. 자동 메모리는 Anthropic이 설명한 방식 그대로 계속 작동합니다.

1단계: API 키 생성

로그인 후 대시보드에서 키를 생성하십시오. 이 키는 MemoryLake 워크스페이스에 속하며 Claude 계정과는 별개입니다.

2단계: 첫 번째 메모리 업로드

해결책의 3단계에서 식별한 내용, 즉 단일 저장소를 넘어 필요한 선호도와 결정 사항부터 시작하십시오. 각 항목은 한 점씩 작성하고 날짜를 기입하여 각 항목이 언제 최신이었는지 명확하게 하십시오.

3단계: AI 및 에이전트 연결

Claude Code와 사용하는 다른 어시스턴트를 연결하십시오. 동일한 사실을 다른 머신, 다른 저장소 또는 다른 도구에서도 사용할 수 있습니다.

첫 번째 차이점은 자동 메모리가 더 이상 블랙박스가 아니라는 점입니다. 그것이 어디에 있는지, 무엇을 저장하는지, 그리고 얼마나 로드되는지 알게 됩니다.

두 번째는 오작동할 때 이를 수정할 수 있다는 점입니다. 대부분의 문제는 토글, 저장소 경로, 머신, 인덱스 제한 또는 서브에이전트에서 비롯됩니다.

세 번째는 각 종류의 컨텍스트가 가장 잘 작동하는 위치에 배치된다는 점입니다. 규칙은 CLAUDE.md에, 개인적인 수정 사항은 자동 메모리에, 그리고 이동해야 하는 모든 것은 그 자체의 공간에 저장됩니다.

가끔 MEMORY.md를 읽어보십시오. 일반 마크다운이며, 오래된 줄은 컨텍스트 비용을 발생시킵니다.

인덱스를 짧게 유지하십시오. 처음 200행 또는 25KB만 로드됩니다.

팀 규칙은 CLAUDE.md에 넣으십시오. 자동 메모리는 머신별, 사용자별로 적용됩니다.

Claude에게 명시적으로 기억해 달라고 요청하십시오. 모든 세션에서 저장되는 것은 아닙니다.

하나의 저장소 경로를 사용하십시오. 메모리는 git 저장소에 고정됩니다.

직접 세션에서 다시 켜십시오. 백그라운드 세션은 끄는 것만 가능합니다.

다른 머신에 대비하십시오. 자동 메모리는 동기화되지 않습니다.

Claude Code 자동 메모리는 Claude가 사용자의 선호도, 수정 사항, 프로젝트 컨텍스트 및 참조 사항을 스스로 기록하는 노트 세트입니다. 이는 사용자의 머신에 있는 저장소별 폴더에 저장되며, MEMORY.md가 인덱스 역할을 합니다. 해당 인덱스의 처음 200행 또는 25KB가 모든 대화 시작 시 로드되며, 토픽 파일은 필요할 때 읽힙니다.

로컬 세션에서는 기본적으로 켜져 있으며, /memory, 프로젝트 설정 또는 환경 변수로 끌 수 있습니다. 제대로 작동하지 않는 것 같으면 토글, 저장소, 머신, 인덱스 크기 및 서브에이전트 여부를 확인하십시오. 규칙은 CLAUDE.md에 보관하고 인덱스는 짧게 유지하십시오.