Claude Code 메모리

한 줄 요약: Claude Code 공식 문서 "How Claude remembers your project". 세션을 넘어 지식을 잇는 두 장치, 사용자가 쓰는 CLAUDE.md(또는 AGENTS.md)와 Claude가 스스로 쓰는 자동 메모리(auto memory)를 설명한다. CLAUDE.md를 둘 위치와 로드 순서, 잘 쓰는 법, @path import, .claude/rules/의 경로별 규칙, 조직 단위 관리, AGENTS.md 읽기 설정, 자동 메모리의 저장 위치와 로드 한도, 문제 해결을 다룬다.

원본 정보#

• 제목: How Claude remembers your project
• 발행: Anthropic, Claude Code 공식 문서 (원본 날짜 미상)
• URL: https://code.claude.com/docs/en/memory (새 창)
• 수집(fetch)일: 2026-10-18. 본문에 나오는 버전 조건(v2.1.2xx)과 설정 키는 이 날짜 기준이다.

핵심 주장#

1. 세션은 매번 빈 컨텍스트 창으로 시작하고, 지식을 잇는 장치는 둘이다. CLAUDE.md는 사용자가 쓰는 지시와 규칙, 자동 메모리는 Claude가 사용자의 교정과 선호를 바탕으로 스스로 쓰는 노트다. 둘 다 매 대화 시작 때 로드되며, Claude는 이를 강제 설정이 아니라 컨텍스트로 다룬다. 행동을 확실히 막으려면 PreToolUse 훅을 쓴다. → 메모리(CLAUDE.md), 자동 메모리(Auto memory), 훅
2. 지시는 구체적이고 짧을수록 일관되게 지켜진다. "코드를 잘 정리하라" 대신 "2칸 들여쓰기", "변경을 테스트하라" 대신 "커밋 전에 npm test를 돌려라"처럼 확인할 수 있게 쓴다. 파일당 200줄 이하를 목표로 하며, 길수록 컨텍스트를 더 쓰고 지시 준수가 떨어진다. → CLAUDE.md 작성·구성
3. CLAUDE.md는 덮어쓰지 않고 이어 붙는다. 작업 디렉터리와 그 위의 CLAUDE.md·CLAUDE.local.md는 시작할 때 로드되고, 하위 디렉터리 것은 Claude가 그 디렉터리 파일을 다룰 때 로드된다. 루트에서 작업 디렉터리 쪽으로 순서대로 붙으므로 시작 위치에 가까운 지시가 마지막에 읽힌다. → 메모리(CLAUDE.md)
4. 일부에만 필요한 지시는 .claude/rules/의 경로별 규칙이나 스킬로 뺀다. paths frontmatter를 단 규칙은 맞는 파일을 다룰 때만 로드된다. @path import는 긴 파일을 정리하는 데는 도움이 되지만 컨텍스트 비용은 줄이지 않는다. 가져온 파일도 시작 때 로드되기 때문이다. → 컨텍스트 비용, 스킬
5. Claude Code는 AGENTS.md를 프로젝트 지시로 읽을 수 있다. 기본값으로 CLAUDE.md가 없을 때만 AGENTS.md를 읽고, /config의 Project instructions 설정으로 둘 다 읽게 바꿀 수 있다(v2.1.277 이상). → AGENTS.md와 CLAUDE.md 함께 쓰기, 스키마 파일

원본의 숫자·설정값 (2026-10-18 기준)#

• CLAUDE.md 권장 크기: 파일당 200줄 이하. Claude Code는 4 MiB까지의 CLAUDE.md를 전부 로드하고 그보다 큰 파일은 건너뛴다.
• 자동 메모리 MEMORY.md: 매 대화 시작 때 앞 200줄 또는 25KB 중 먼저 닿는 쪽까지만 로드된다.
• @path import: 재귀 import는 최대 4단계(hop)까지.
• 경로별 규칙의 paths 목록: 중괄호 확장 결과가 패턴 1,000개와 4 MiB 예산을 공유한다.
• 버전 조건: AGENTS.md 직접 읽기 v2.1.277 이상, /doctor prompt-audit v2.1.283 이상, /import v2.1.213 이상, 자동 메모리 modified 필드 v2.1.214 이상.
• CLAUDE.md 내용은 시스템 프롬프트 일부가 아니라 시스템 프롬프트 뒤의 사용자 메시지로 전달된다.