메모리 시스템 (Memory)
기준일: 2026-07-13 난이도: 중급 공식 기준: How Claude remembers your project, Manage sessions
Claude Code의 메모리는 별도 memory 하위 명령군으로 관리하지 않습니다. 공식 흐름은 사람이 작성하는 CLAUDE.md 계열 지침, 경로별 .claude/rules/, Claude가 직접 기록하는 auto memory, 그리고 세션 안의 /memory 명령입니다.
핵심 개념
| 영역 | 공식 표면 | 용도 |
|---|---|---|
| 프로젝트 지침 | ./CLAUDE.md, ./.claude/CLAUDE.md |
저장소 구조, 빌드 명령, 팀 규칙처럼 모든 세션에 필요한 기준 |
| 개인 지침 | ~/.claude/CLAUDE.md, ./CLAUDE.local.md |
개인 선호, 로컬 URL, 개인 워크플로우 |
| 조직 지침 | 관리 정책 위치의 CLAUDE.md 또는 managed settings의 claudeMd |
회사 공통 보안·품질 지침 |
| 경로별 규칙 | .claude/rules/*.md |
특정 파일 패턴을 열 때만 필요한 지침 |
| 자동 메모리 | ~/.claude/projects/<project>/memory/ |
Claude가 반복 학습한 빌드 명령, 디버깅 패턴, 선호도 |
| 세션 전환 | /memory |
로드된 지침 확인, auto memory 토글, 메모리 폴더 열기 |
CLAUDE.md와 auto memory는 모두 컨텍스트로 주입됩니다. 강제 정책이 아니므로, 반드시 막아야 하는 동작은 hooks나 permissions 같은 별도 제어면으로 다룹니다.
선택 기준
| 필요한 것 | 추천 방식 |
|---|---|
| 모든 팀원이 알아야 하는 빌드·테스트 명령 | 프로젝트 CLAUDE.md |
| 특정 디렉터리나 파일 확장자에만 적용되는 규칙 | .claude/rules/의 paths frontmatter |
| 개인 로컬 환경 경로나 개인 선호 | CLAUDE.local.md 또는 사용자 수준 지침 |
| Claude가 반복해서 배운 디버깅 사실 | auto memory |
| 현재 어떤 지침이 로드됐는지 확인 | /memory |
| 긴 대화에서 컨텍스트가 비대해졌을 때 | /context, /compact, 필요하면 /clear |
| 이전 작업 대화로 돌아가기 | claude --continue, claude --resume, /resume |
CLAUDE.md 운영
위치와 로드 순서
Claude Code는 현재 작업 디렉터리에서 위쪽으로 올라가며 CLAUDE.md와 CLAUDE.local.md를 찾습니다. 넓은 범위의 지침이 먼저 들어가고, 작업 디렉터리에 가까운 지침이 나중에 들어갑니다. 하위 디렉터리의 지침은 해당 파일을 읽을 때 필요한 경우 로드됩니다.
대표 위치:
~/.claude/CLAUDE.md # 사용자 전체
./CLAUDE.md # 프로젝트 공유 지침
./.claude/CLAUDE.md # 프로젝트 공유 지침의 대체 위치
./CLAUDE.local.md # gitignore 대상 개인 지침
./.claude/rules/*.md # 경로별 또는 주제별 규칙
저장소가 이미 AGENTS.md를 사용한다면 중복 작성보다 import를 우선합니다.
@AGENTS.md
## Claude Code
- 이 저장소에서는 pnpm만 사용한다.
- 큰 변경 전에는 `/plan`을 사용한다.
imports
CLAUDE.md는 @path/to/file 구문으로 다른 파일을 가져올 수 있습니다. 상대 경로는 import를 적은 파일 기준으로 해석되고, 중첩 import는 최대 네 단계까지 확장됩니다.
# Project Context
@README.md
@docs/testing.md
@~/.claude/my-shared-preferences.md
문서 안에 파일 경로를 글자로만 남기고 싶다면 백틱으로 감쌉니다.
`@README.md`는 import가 아니라 예시 텍스트입니다.
auto memory 운영
Auto memory는 기본적으로 켜져 있으며, Claude가 미래 세션에 유용하다고 판단한 내용을 프로젝트별 메모리 폴더에 plain markdown으로 저장합니다.
~/.claude/projects/<project>/memory/
├── MEMORY.md
├── debugging.md
└── ...
중요한 제한:
- auto memory는 Claude Code v2.1.59 이상에서 동작합니다.
MEMORY.md의 처음 200줄 또는 25KB 중 작은 범위만 세션 시작 시 로드됩니다.- 세부 내용은 별도 topic 파일로 이동될 수 있습니다.
- git 저장소 안에서는 같은 repository의 worktree와 하위 디렉터리가 auto memory를 공유합니다.
- 로컬 머신 기준 기능이며 cloud 환경이나 다른 컴퓨터로 자동 공유되지 않습니다.
끄거나 위치를 바꾸는 공식 방법:
{
"autoMemoryEnabled": false,
"autoMemoryDirectory": "~/my-custom-memory-dir"
}
환경 변수로 끌 수도 있습니다.
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude
세션과 컨텍스트
세션은 프로젝트 디렉터리에 연결된 저장 대화입니다. 세션 내용은 대화 중 계속 저장되며, 다음 공식 표면으로 돌아갈 수 있습니다.
claude --continue
claude --resume
claude --resume auth-refactor
claude --resume <session-id>
세션 내부에서는 다음 명령을 사용합니다.
/resume
/clear
/compact keep only the plan and current diff
/context
/export
세션 transcript는 기본적으로 ~/.claude/projects/<project>/<session-id>.jsonl에 저장되지만 내부 형식은 버전별로 바뀔 수 있습니다. 사람이 읽을 기록은 /export를 사용하고, 스크립트는 claude -p --output-format json 또는 claude -p --resume <session-id>처럼 공식 구조화 출력 표면을 사용합니다.
실습
프로젝트 지침을 정리합니다.
/memory
- 로드된
CLAUDE.md,CLAUDE.local.md, rules 파일을 확인합니다. - auto memory 폴더를 열어 Claude가 저장한 내용을 검토합니다.
- 팀 규칙은
CLAUDE.md로, 경로별 규칙은.claude/rules/로, 반복 학습은 auto memory로 분리합니다. - 200줄을 넘는
CLAUDE.md는 path-scoped rules나 imports로 구조를 나눕니다.
도구에 입력할 프롬프트
이 저장소의 Claude Code 메모리 구성을 점검해줘.
/memory에서 로드된 CLAUDE.md, CLAUDE.local.md, .claude/rules, auto memory를 기준으로
중복, 충돌, 너무 긴 지침, path-scoped rule 후보를 찾아줘.
공식 문서에 없는 memory 하위 명령군은 사용하지 마.
체크리스트
- 프로젝트 공통 규칙은
CLAUDE.md또는.claude/CLAUDE.md에 있다. - 개인 경로와 비밀은
CLAUDE.local.md나 로컬 설정에만 있다. - 반복 실수는 구체적이고 검증 가능한 문장으로 적었다.
- 긴 절차는 항상 로드되는 지침이 아니라 skill이나 path-scoped rule로 옮겼다.
-
/memory에서 실제 로드 여부를 확인했다. - auto memory 폴더를 검토해 오래되거나 민감한 내용을 제거했다.
- 세션 재개는
--continue,--resume,/resume만 사용한다.
다음 단계
- CLI 참조에서
--continue,--resume,--safe-mode를 확인합니다. - 명령어와 Skills에서
/memory,/context,/compact를 함께 봅니다. - 문제 해결에서 지침이 적용되지 않을 때의 점검 순서를 확인합니다.