Claude의 메모리 관리

Claude Code는 세션 간에 지속되는 메모리 시스템을 제공하여, 프로젝트 패턴, 개인 선호도, 팀 규칙 등을 기억하고 활용할 수 있습니다. 크게 두 가지 종류의 메모리가 있습니다:

• Auto memory: Claude가 작업하면서 자동으로 저장하는 컨텍스트 (프로젝트 패턴, 디버깅 인사이트, 아키텍처 노트 등)
• CLAUDE.md 파일: 사용자가 직접 작성하고 관리하는 마크다운 파일 (지침, 규칙, 선호도)

가이드

• Keep CLAUDE.md minimal:
• Keep core memory files under 500 lines

해당 개념이 필요한 이유

• 컨텍스트 유지: 매번 같은 설명을 반복하지 않고, Claude가 프로젝트의 패턴과 규칙을 기억
• 팀 협업: 프로젝트 메모리를 source control에 커밋하여 팀원들과 공유
• 개인화: 전역 메모리로 개인의 코딩 스타일과 워크플로우 선호도를 모든 프로젝트에 적용
• 조직 정책: 회사 전체의 코딩 표준, 보안 정책을 중앙에서 관리

AS-IS

메모리 없이 작업할 경우, 매 세션마다 동일한 컨텍스트를 반복 설명해야 합니다.

sequenceDiagram
    autonumber
    participant User
    participant Claude

    User->>Claude: 프로젝트에서 npm 대신 pnpm 사용해
    Claude->>User: 알겠습니다
    Note over User,Claude: 세션 종료

    User->>Claude: [새 세션] 의존성 설치해줘
    Claude->>User: npm install 실행할까요?
    User->>Claude: 아니, pnpm 써야 한다고 했잖아...

TO-BE

메모리를 사용하면, Claude가 프로젝트 컨텍스트를 자동으로 기억합니다.

sequenceDiagram
    autonumber
    participant User
    participant Claude
    participant Memory

    User->>Claude: 이 프로젝트는 pnpm 사용해
    Claude->>Memory: "Use pnpm, not npm" 저장
    Note over User,Claude: 세션 종료

    Memory->>Claude: [새 세션 시작] MEMORY.md 로드
    User->>Claude: 의존성 설치해줘
    Claude->>User: pnpm install 실행합니다

메모리 타입 계층 구조

Claude Code는 6가지 메모리 타입을 제공하며, 각각 다른 범위와 목적을 가집니다. 더 구체적인 지침이 더 광범위한 지침보다 우선순위를 가집니다.

메모리 타입	범위	우선순위
Managed policy	조직 전체	1 (가장 낮음)
User memory	개인 (모든 프로젝트)	2
Project memory	프로젝트 팀 공유	3
Project rules	프로젝트 팀 공유 (모듈화)	3
Project memory (local)	개인 (특정 프로젝트)	4
Auto memory	개인 (프로젝트별 자동)	5 (가장 높음)

우선순위 충돌 예시

상황: Indentation 규칙이 각 메모리 레벨에서 다르게 정의됨

User memory (~/.claude/CLAUDE.md)
"모든 코드에서 tabs로 indent"

  ↓ 덮어씀 (프로젝트가 더 구체적)

Project memory (~/Documents/foo/CLAUDE.md)
"이 프로젝트는 spaces 2칸 indent"

  ↓ 부분적으로 덮어씀 (특정 경로에만 적용)

Project rules (~/Documents/foo/.claude/rules/frontend-style.md)
paths: ["src/main/frontend/**"]
"프론트엔드는 spaces 4칸 indent"

실제 적용:

• src/main/backend/** 파일: spaces 2칸 (Project memory 적용)
• src/main/frontend/** 파일: spaces 4칸 (Project rules의 path-specific 규칙 적용)

원칙: User memory (넓음) < Project memory (프로젝트 전체) < Project rules + paths (특정 영역, 가장 구체적)

~/Documents/foo에서 실행 시 메모리 위치 예시

~/Documents/foo 디렉토리에서 claude 명령을 실행했다고 가정하면, 각 메모리 타입의 실제 파일 위치는 다음과 같습니다:

1. Managed policy

항목	내용
위치	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)
용도	IT/DevOps 팀이 관리하는 조직 전체 정책 - 회사 코딩 표준 - 보안 정책 - 컴플라이언스 요구사항
공유 범위	조직의 모든 사용자

예시 내용:

# Company-wide Security Policy
- Never commit AWS credentials or API keys
- All API endpoints must use HTTPS
- Require code review for security-sensitive changes

2. User memory

항목	내용
위치	~/.claude/CLAUDE.md → /Users/username/.claude/CLAUDE.md
용도	개인의 모든 프로젝트에 적용되는 선호도 - 코드 스타일 선호도 - 개인 툴링 단축키 - 작업 방식
공유 범위	본인만 (모든 프로젝트)

예시 내용:

# My Personal Preferences
- I prefer functional programming style
- Use single quotes for strings in JavaScript
- When writing commit messages, use conventional commits format

3. Project memory

항목	내용
위치	~/Documents/foo/CLAUDE.md 또는 ~/Documents/foo/.claude/CLAUDE.md
용도	팀이 공유하는 프로젝트 지침 - 프로젝트 아키텍처 - 코딩 표준 - 공통 워크플로우
공유 범위	팀원 (source control을 통해)

예시 내용:

# Project Instructions
 
## Build Commands
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`
 
## Architecture
- Use Redux for state management
- API calls go through `src/api/` directory
- All components must have unit tests

4. Project rules

항목	내용
위치	~/Documents/foo/.claude/rules/*.md
용도	모듈화된 주제별 프로젝트 지침 - 언어별 가이드라인 - 테스트 컨벤션 - API 표준
공유 범위	팀원 (source control을 통해)

설명:

• paths가 없으면 **Project memory(전역 지침)**와 동일하게 항상 적용됨
• rules는 개발자가 주제별로 관리하기 쉽게 나누는 목적

간단 예시:

# .claude/rules/code-style.md
- Use 2-space indentation
- Use ESLint and Prettier

디렉토리 구조 예시:

~/Documents/foo/.claude/rules/
├── code-style.md
├── testing.md
└── security.md

path-specific rule 예시 (testing.md):

---
paths:
  - "src/**/*.test.ts"
  - "tests/**/*.ts"
---
 
# Testing Rules
- All test files must use Jest
- Use descriptive test names
- Mock external API calls

5. Project memory (local)

항목	내용
위치	~/Documents/foo/CLAUDE.local.md
용도	개인의 프로젝트별 선호도 (버전 관리 제외) - 개인 샌드박스 URL - 선호하는 테스트 데이터 - 로컬 개발 환경 설정
공유 범위	본인만 (현재 프로젝트)

예시 내용:

# My Local Preferences for this Project
- Use local API server at http://localhost:3001
- Test with user account: test@example.com
- My feature branch naming: feature/myname-TICKET-123

주의: CLAUDE.local.md는 자동으로 .gitignore에 추가되어 커밋되지 않습니다.

6. Auto memory

항목	내용
위치	~/.claude/projects/foo/memory/MEMORY.md
용도	Claude가 자동으로 기록하는 학습 내용 - 프로젝트 패턴 (빌드 명령, 테스트 컨벤션) - 디버깅 인사이트 (해결한 문제, 에러 원인) - 아키텍처 노트 (주요 파일, 모듈 관계) - 사용자 선호도 (소통 스타일, 워크플로우 습관)
공유 범위	본인만 (프로젝트별)

디렉토리 구조:

~/.claude/projects/foo/memory/
├── MEMORY.md           # 간결한 인덱스 (첫 200줄만 로드)
├── debugging.md        # 디버깅 패턴 상세 노트
├── api-conventions.md  # API 설계 결정사항
└── ...                 # Claude가 생성하는 추가 주제 파일

동작 방식:

• MEMORY.md의 첫 200줄만 매 세션 시작 시 시스템 프롬프트에 로드됨
• 200줄 초과 내용은 자동 로드되지 않음 (Claude가 간결하게 유지하도록 지시받음)
• debugging.md 같은 주제 파일들은 필요할 때 Claude가 직접 읽음

Project memory VS Project rules

두 가지 모두 팀이 공유하는 프로젝트 지침이지만, 구조와 사용 방식이 다릅니다.

Project memory (CLAUDE.md)

파일 위치: ./CLAUDE.md 또는 ./.claude/CLAUDE.md

특징:

• 단일 파일
• 프로젝트 전체에 적용
• 간단한 프로젝트에 적합
• /init 명령으로 부트스트랩 가능

언제 사용:

• 프로젝트가 작거나 중간 규모일 때
• 지침이 단순하고 한 파일로 관리 가능할 때
• 빠르게 시작하고 싶을 때

예시:

# My Project Instructions
 
## Build Commands
- Build: npm run build
- Test: npm test
 
## Code Style
- Use ESLint
- 2-space indentation

Project rules (.claude/rules/*.md)

파일 위치: ./.claude/rules/*.md (여러 파일)

특징:

• 여러 파일로 모듈화
• 주제별로 분리 (code-style.md, testing.md, security.md 등)
• path-specific rules 지원 (특정 파일 패턴에만 적용)
• 서브디렉토리로 구조화 가능
• 심볼릭 링크 지원 (공유 규칙 재사용)

언제 사용:

• 대규모 프로젝트일 때
• 지침이 복잡하고 주제별로 분리가 필요할 때
• 특정 파일 타입에만 적용되는 규칙이 있을 때 (예: TypeScript 파일에만 적용)
• 여러 프로젝트에서 공통 규칙을 재사용하고 싶을 때

예시 구조:

.claude/rules/
├── frontend/
│   ├── react.md       # React 컴포넌트 규칙
│   └── styles.md      # CSS/스타일 규칙
├── backend/
│   ├── api.md         # API 엔드포인트 규칙
│   └── database.md    # DB 쿼리 규칙
└── general.md         # 전반적인 코딩 표준

path-specific rule 예시:

---
paths:
  - "src/api/**/*.ts"
---
 
# API Development Rules
- All API endpoints must include input validation
- Use standard error response format
- Include OpenAPI documentation comments

비교표

항목	Project memory	Project rules
파일 개수	1개	여러 개
파일 위치	./CLAUDE.md	./.claude/rules/*.md
모듈화	불가능	주제별 분리 가능
path-specific	불가능	YAML frontmatter로 지원
우선순위	동일 (3)	동일 (3)
공유	Source control	Source control
적합한 규모	소~중	중~대

함께 사용 가능: 두 가지를 동시에 사용할 수 있습니다. 이 경우 둘 다 로드되며, 더 구체적인 지침(path-specific rule)이 우선순위를 가집니다.

메모리 동작 원리

로딩 메커니즘

flowchart TD
    A[Claude Code 시작] --> B{Git repo?}
    B -->|Yes| C[Git root 기준으로 프로젝트 식별]
    B -->|No| D[Working directory 기준]

    C --> E[메모리 파일 탐색]
    D --> E

    E --> F[Managed policy 로드]
    F --> G[User memory 로드]
    G --> H[현재 디렉토리부터 상위로 재귀 탐색]
    H --> I[CLAUDE.md / CLAUDE.local.md 발견 시 로드]
    I --> J{루트 도달?}
    J -->|No| H
    J -->|Yes| K[.claude/rules/*.md 로드]
    K --> L[Auto memory 첫 200줄 로드]
    L --> M[세션 시작]

우선순위 규칙

동일한 지침이 여러 메모리에 있을 경우, 더 구체적이고 좁은 범위의 지침이 우선합니다:

1. Auto memory (가장 높음) - 프로젝트별 자동 학습
2. Project memory (local) - 개인의 프로젝트별 선호도
3. Project rules / Project memory - 팀 공유 프로젝트 지침
4. User memory - 개인의 전역 선호도
5. Managed policy (가장 낮음) - 조직 전체 정책

예시:

• Managed policy에서 “4-space indentation” 지시
• User memory에서 “2-space indentation” 지시 → User memory가 우선 (더 구체적)

재귀적 탐색

Claude Code는 현재 작업 디렉토리(cwd)에서 시작하여 루트 디렉토리(/)까지 상위로 재귀적으로 탐색하며 CLAUDE.md / CLAUDE.local.md 파일을 찾습니다.

예시:

/Users/username/
└── projects/
    ├── CLAUDE.md              # ← 로드됨
    └── my-app/
        ├── CLAUDE.md          # ← 로드됨
        └── backend/
            ├── CLAUDE.md      # ← 로드됨 (cwd가 여기)
            └── api/
                └── [작업 위치]

/Users/username/projects/my-app/backend/api에서 실행 시:

• backend/CLAUDE.md 로드
• my-app/CLAUDE.md 로드
• projects/CLAUDE.md 로드

하위 디렉토리 메모리: 현재 cwd 아래의 CLAUDE.md는 시작 시 로드되지 않고, Claude가 해당 하위 디렉토리의 파일을 읽을 때만 로드됩니다.

Auto memory 동작 흐름

sequenceDiagram
    autonumber
    participant User
    participant Claude
    participant MEMORY.md
    participant Topic Files

    Note over Claude: 세션 시작
    MEMORY.md->>Claude: 첫 200줄 로드 (system prompt)

    User->>Claude: API 테스트는 로컬 Redis 필요해
    Claude->>MEMORY.md: MEMORY.md 읽기 (전체)
    Claude->>MEMORY.md: 인덱스에 "Testing" 항목 추가
    Claude->>Topic Files: testing.md에 상세 내용 저장

    Note over User,Claude: 다음 세션
    MEMORY.md->>Claude: 첫 200줄 로드 ("Testing" 인덱스 포함)
    User->>Claude: 테스트 실행해줘
    Claude->>Topic Files: testing.md 읽기 (Redis 요구사항 확인)
    Claude->>User: Redis 실행 중인지 확인하고 테스트 실행

Import 메커니즘

CLAUDE.md 파일은 @path/to/file 문법으로 다른 파일을 임포트할 수 있습니다.

예시:

See @README.md for project overview and @package.json for npm commands.
 
# Additional Instructions
- Git workflow @docs/git-instructions.md
- Personal settings @~/.claude/my-preferences.md

특징:

• 상대 경로 / 절대 경로 모두 지원
• 상대 경로는 임포트를 포함한 파일 기준 (working directory 아님)
• 최대 5단계까지 재귀 임포트 지원
• 코드 스팬/블록 내부의 @path는 임포트로 처리 안 됨
• 처음 사용 시 승인 다이얼로그 표시 (프로젝트당 1회)

Git worktrees와 Auto memory

일반적인 경우: 같은 Git repo의 모든 서브디렉토리는 하나의 auto memory 디렉토리를 공유합니다.

~/projects/my-app/            # Git root
├── frontend/                 # 여기서 실행해도
└── backend/                  # 여기서 실행해도
    → 둘 다 ~/.claude/projects/my-app/memory/ 사용

Git worktrees: 각 worktree는 별도의 auto memory 디렉토리를 가집니다.

~/projects/my-app/            # Main worktree
~/projects/my-app-hotfix/     # Worktree
    → ~/.claude/projects/my-app-hotfix/memory/ (별도 디렉토리)

메모리 파일 편집

/memory 명령

세션 중에 /memory 명령을 실행하면 파일 선택기가 열리며, auto memory entrypoint와 CLAUDE.md 파일들을 볼 수 있습니다. 선택한 파일이 시스템 에디터에서 열립니다.

직접 요청

Claude에게 직접 메모리 저장을 요청할 수 있습니다:

• “pnpm 사용한다는 거 기억해줘”
• “API 테스트는 로컬 Redis 필요하다고 메모리에 저장해줘”

/init 명령

프로젝트 메모리를 부트스트랩하려면:

> /init

이 명령은 프로젝트 구조를 분석하여 기본 CLAUDE.md 템플릿을 생성합니다.

환경 변수

Auto memory 제어

# Auto memory 강제 비활성화
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
 
# Auto memory 강제 활성화
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0

주의: 변수명이 이중 부정 로직을 사용합니다 (DISABLE=0은 “비활성화하지 않음” = 활성화)

추가 디렉토리의 CLAUDE.md 로드

--add-dir 플래그로 추가한 디렉토리의 CLAUDE.md 파일을 로드하려면:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

Best Practices

구체적으로 작성

❌ “코드를 잘 포맷하세요” ✅ “2-space indentation 사용”

구조화하여 정리

• 각 메모리를 bullet point로 작성
• 관련된 메모리들을 마크다운 헤딩으로 그룹화

# Build Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
 
# Code Style
- Use ESLint
- 2-space indentation
- Single quotes for strings

정기적으로 검토

프로젝트가 진화함에 따라 메모리도 업데이트하여, Claude가 항상 최신 정보를 사용하도록 합니다.

Project rules 전략

• 규칙을 집중화: 각 파일은 하나의 주제만 다루기 (예: testing.md, api-design.md)
• 설명적인 파일명: 파일명만 봐도 내용 파악 가능하게
• path-specific 규칙 신중히 사용: 정말 특정 파일에만 적용되는 경우에만 사용
• 서브디렉토리로 구조화: 관련 규칙 그룹화 (예: frontend/, backend/)

Symlink 활용

여러 프로젝트에서 공통 규칙을 재사용:

# 공유 규칙 디렉토리 symlink
ln -s ~/shared-claude-rules .claude/rules/shared
 
# 개별 규칙 파일 symlink
ln -s ~/company-standards/security.md .claude/rules/security.md

조직 수준 메모리 관리

조직은 모든 사용자에게 적용되는 중앙 관리형 CLAUDE.md를 배포할 수 있습니다.

설정 방법

1. Managed policy 위치에 파일 생성:

   • macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
   • Linux: /etc/claude-code/CLAUDE.md
   • Windows: C:\Program Files\ClaudeCode\CLAUDE.md

2. 구성 관리 시스템으로 배포:

   • MDM (Mobile Device Management)
   • Group Policy
   • Ansible
   • 기타 IT 배포 도구

3. 내용 예시:

# Company Security Policy
- Never commit credentials or API keys
- All API endpoints must use HTTPS
- Code review required for security changes
 
# Company Coding Standards
- Use conventional commits
- All PRs require 2 approvals
- Run tests before pushing

Glob 패턴 참조

Project rules의 path-specific 규칙에서 사용 가능한 glob 패턴:

패턴	매치 대상
**/*.ts	모든 디렉토리의 TypeScript 파일
src/**/*	src/ 아래 모든 파일
*.md	프로젝트 루트의 마크다운 파일
src/components/*.tsx	특정 디렉토리의 React 컴포넌트

Brace expansion 지원:

---
paths:
  - "src/**/*.{ts,tsx}"       # .ts와 .tsx 모두 매치
  - "{src,lib}/**/*.ts"       # src와 lib 디렉토리
---

참고 문서

• Official Documentation - Manage Claude’s memory