Memory.md란 무엇인가? Claude Code Auto Memory 시스템 완전 정리 (2026)

Memory.md란 무엇인가? Claude Code Auto Memory 시스템 완전 정리 (2026)

한 줄 요약

MEMORY.md는 Claude Code가 프로젝트 작업 중 학습한 내용을 저장하는 지속형 프로젝트 기억(Persistent Project Memory) 파일이다. CLAUDE.md가 사람이 작성하는 규칙이라면, MEMORY.md는 Claude가 작업하면서 축적하는 경험 데이터에 가깝다. (code.claude.com)

---

이 글에서 다루는 내용

• MEMORY.md란?
• CLAUDE.md와 차이
• Auto Memory 동작 방식
• 실제 예제
• 프로젝트 기억 구조
• 실무 Best Practice
• Context Engineering 관점
• FAQ

---

MEMORY.md란?

많은 사람들이 아직 모른다.

Claude Code에는:

CLAUDE.md
+
MEMORY.md

두 개의 기억 시스템이 존재한다.

---

차이

CLAUDE.md

사람이 작성

규칙
정책
아키텍처

---

MEMORY.md

Claude가 축적

실수
선호
프로젝트 지식

---

Anthropic 공식 문서에서도:

CLAUDE.md = persistent instructions
MEMORY.md = accumulated learnings

구조로 설명한다. (Claude Code)

---

왜 MEMORY.md가 중요한가?

반응형

예를 들어:

첫날:

Prisma 사용

설명.

---

둘째날:

또 설명

---

셋째날:

또 설명

---

이러면 Claude는 매번:

콜드 스타트

상태다.

---

MEMORY.md가 있으면:

프로젝트 경험 저장
↓
다음 세션 활용

---

최근 가이드에서도 MEMORY.md를:

"프로젝트 장기 기억 계층"

으로 설명한다. (Dr. Amit Ray)

---

Claude Memory 구조

Claude Code는 여러 레벨의 Memory 계층을 가진다.

Global Memory
↓
Project Memory
↓
Rules
↓
Auto Memory

---

Anthropic 공식 문서 기준:

CLAUDE.md
+
Auto Memory

조합이 핵심 구조다. (Claude Code)

---

실제 MEMORY.md 예제

예:

# Project Learnings

## Backend

Uses NestJS

## Database

Prisma ORM

## Notes

Transactions handled in services

---

더 발전하면:

# Last Session

Completed:
- Auth API

Next:
- Role permissions

Known Issues:
- JWT refresh bug

---

실제 Memory 시스템 가이드에서도:

Completed
In Progress
Next

구조를 추천한다. (Young Leaders)

---

CLAUDE.md vs MEMORY.md

이거 진짜 중요하다.

항목CLAUDE.mdMEMORY.md

작성자	사람	Claude
역할	규칙	경험
목적	행동 제어	기억 유지
변경	수동	자동 가능
내용	정책	학습 내용

---

쉽게 말하면:

CLAUDE.md = 법
MEMORY.md = 경험

---

Auto Memory는 어떻게 동작하나?

Claude Code는:

사용자 수정
↓
반복 패턴 발견
↓
Memory 기록

가능하다.

---

Anthropic 공식 문서:

Claude can accumulate learnings automatically. (Claude Code)

---

예:

사용자가 반복해서:

Controller는 validation만

수정.

---

Claude:

패턴 인식
↓
Memory 저장

---

실제 많이 쓰는 Memory 구조

1. Project State

Current Status

Completed:
...

---

2. Known Issues

Known Bugs

---

3. Architecture Notes

Uses CQRS

---

4. Team Preferences

Small commits preferred

---

Context Engineering 관점

2026 핵심:

Prompt Engineering → Memory Engineering

---

예전:

프롬프트 입력

---

지금:

Memory
+
Context
+
Rules

---

실제 Claude Code 실무 흐름도:

CLAUDE.md
↓
MEMORY.md
↓
Rules
↓
Skills

형태로 진화 중이다. (codewithmukesh.com)

---

MEMORY.md Best Practice TOP 5

1. 상태 기록

좋음:

Completed:

---

2. 다음 작업 기록

Next:

---

3. Known Issue 저장

Known Problems

---

4. 짧게 유지

너무 길면:

Context 오염

---

최근 가이드들도:

요약 중심

Memory 운영을 권장한다. (Medium)

---

5. 규칙은 CLAUDE.md에

실수:

MEMORY.md에 정책 저장

---

추천:

정책 → CLAUDE.md
경험 → MEMORY.md

---

MEMORY.md 실제 프로젝트 구조

repo/

CLAUDE.md

.claude/

MEMORY.md

skills/
context/

---

또는:

.claude/

memory/
 ├── backend.md
 ├── auth.md
 └── deployment.md

---

최근 가이드에서는:

Topic Memory

방식도 증가 중이다. (Serenities AI)

---

AGENTS.md + CLAUDE.md + MEMORY.md 관계

2026 실무 표준은 거의 이 구조다.

AGENTS.md
↓
Repository Rules

CLAUDE.md
↓
Claude Behavior

MEMORY.md
↓
Project Knowledge

---

연구에서 나온 흥미로운 점

최근 연구들에서는:

• Agent Manifest
• Memory Files
• Context Files

품질이 Agent 성능에 큰 영향을 준다고 분석한다. (arXiv)

---

특히:

Architecture
Rules
Operational Notes

비중이 높게 나타난다. (arXiv)

---

FAQ

Q. MEMORY.md는 자동 생성되나요?

가능하다.

Claude Code Auto Memory 기능이 존재한다. (Claude Code)

---

Q. Git에 올려야 하나요?

보통:

프로젝트 Memory

는 공유.

---

개인 Memory는:

gitignore

처리.

---

Q. MEMORY.md가 CLAUDE.md를 대체하나요?

아니다.

CLAUDE.md = 규칙

MEMORY.md = 경험

---

둘 다 필요.

---

핵심 요약

• MEMORY.md는 Claude의 프로젝트 기억
• CLAUDE.md는 규칙, MEMORY.md는 경험
• Auto Memory 기능 존재
• 상태·이슈·다음 작업 기록에 강력
• Context Engineering 핵심 요소
• AGENTS.md + CLAUDE.md + MEMORY.md 조합이 가장 강력

---

출처

• Claude Code Memory 공식 문서 (Claude Code)
• Claude Code Best Practices (Claude Code)
• CLAUDE.md Memory Hierarchy 가이드 (Serenities AI)
• Agentic Coding Manifest 연구 (arXiv)
• AI Coding Agent Efficiency 연구 (arXiv)

---

MEMORYmd, ClaudeCode, CLAUDEmd, AGENTSmd, ContextEngineering, AI개발, AgenticAI, LLM개발, AI코딩, 2026AI