Claude Code 메모리 완전 가이드: CLAUDE.md · Auto Memory · claude-mem 플러그인 비교 및 실전 설정

Claude Code를 쓰다 보면 한 번쯤 이런 상황을 겪게 됩니다. 어제 두 시간 동안 ESM/CJS 혼용 이슈를 파헤쳐서 tsconfig.json 설정까지 다 잡아놨는데, 오늘 새 세션을 열면 Claude가 아무것도 모른다는 듯 처음부터 다시 질문합니다. 마치 매일 아침 새 팀원에게 온보딩을 반복하는 것 같은 피로감이랄까요.

Claude Code의 메모리 시스템은 이 문제를 해결하기 위해 존재합니다. 그런데 이게 단일 기능이 아니라 역할이 전혀 다른 세 가지 레이어로 구성되어 있어서, 처음엔 각각 뭘 해주는 건지 헷갈리기 쉽습니다. 저도 Auto Memory가 있는데 왜 CLAUDE.md를 따로 써야 하나 싶었고, claude-mem이라는 플러그인은 또 뭔가 싶었거든요.

이 글은 Claude Code를 이미 사용 중인 개발자를 대상으로, CLAUDE.md · Auto Memory · claude-mem 세 레이어가 각각 어떻게 다르고 실제 프로젝트에서 어떻게 조합해 쓸 수 있는지를 구체적인 예시와 함께 정리합니다.

핵심 개념

세 개의 레이어로 구성된 메모리 아키텍처

"Claude Mem"이라는 단어는 공식 기능 이름이 아니라, Claude Code 생태계의 메모리 레이어들을 통칭하는 표현입니다. 이름이 비슷한 claude-mem은 별도의 커뮤니티 플러그인입니다 — 뒤에서 따로 다룹니다. 레이어별 역할을 먼저 정리해두면 나머지 내용이 훨씬 쉽게 들어옵니다.

레이어 1: CLAUDE.md — 팀이 공유하는 정적 규칙

세션이 시작될 때 컨텍스트 윈도우에 자동으로 로드되는 마크다운 파일입니다. 빌드 명령어, 코딩 컨벤션, 아키텍처 결정처럼 변경 빈도가 낮고 팀 전체가 따라야 하는 규칙을 담기에 적합합니다.

# 프로젝트 규칙
 
## 빌드 & 테스트
- Build: `pnpm build` (npm 사용 금지)
- Test: `pnpm test`
 
## 코드 스타일
- TypeScript strict mode
- async/await 사용 (Promise.then() 금지)
- 2-space indentation
 
## 아키텍처
- NestJS: 비즈니스 로직은 Service에만, Controller는 thin 유지
- API 미들웨어 위치: src/middleware/auth.ts
 
## 알려진 이슈
- ESM/CJS 혼용: tsconfig.json의 moduleResolution 항상 확인

마크다운이라 vim으로 직접 고칠 수 있고, PR에 같이 올릴 수 있습니다. 모노레포라면 .claude/CLAUDE.md를 Git에 커밋해두면 팀원 전체가 동일한 컨텍스트로 시작합니다.

주의: 경험상 CLAUDE.md가 지나치게 길어지면 Claude가 후반부 내용을 덜 따르는 경향이 있습니다. "Claude가 모르면 안 되는 것"만 남기고 나머지는 별도 파일로 분리하는 편이 효과적입니다.

레이어 2: Auto Memory — Claude가 스스로 쓰는 일기

Claude가 세션 중에 배운 것들을 자동으로 마크다운 파일로 저장하는 기능입니다. 기본으로 활성화되어 있어 별도 설정이 필요 없습니다. 저장 위치는 ~/.claude/projects/<git-root>/memory/이고, 네 가지 카테고리로 분류됩니다.

~/.claude/projects/my-project/memory/
├── user_preferences.md      # 사용자 작업 스타일
├── feedback_testing.md      # 테스트 방식에 대한 피드백
├── project_auth_rewrite.md  # 진행 중인 프로젝트 컨텍스트
└── reference_grafana.md     # 외부 시스템 포인터

각 파일은 프론트매터 형식을 따르는데, description 필드가 특히 중요합니다.

---
name: 테스트 방식 피드백
description: 데이터베이스 관련 테스트에서 mock 사용 금지 결정
type: feedback
---
 
DB 테스트는 실제 DB를 사용해야 함. mock 테스트 통과 후 프로덕션 마이그레이션 실패 사례가 있었음.
 
**Why:** 지난 분기 mock/prod 환경 불일치로 인한 장애 경험
**How to apply:** DB 관련 테스트 코드 작성 시 항상 실제 DB 연결 사용

"벡터 DB 없이 어떻게 관련 메모리를 찾나요?" — 솔직히 저도 처음엔 이 부분이 의아했습니다. 비결은 Sonnet 모델이 각 메모리 파일의 description 필드를 읽고 현재 세션과의 semantic relevance를 직접 판단한다는 점입니다. 외부 임베딩 서비스나 벡터 DB 없이, 언어 모델 자체의 이해 능력으로 관련 파일을 골라냅니다.

Database-Free Memory 아키텍처: 운영 복잡도가 낮다는 게 최대 장점이지만, 메모리 파일이 수백 개를 넘어서면 선택 품질이 저하될 수 있습니다. 대규모 팀이라면 Milvus 같은 벡터 검색 레이어 추가를 고려해볼 수 있습니다.

레이어 3: claude-mem 플러그인 — 전체 세션 아카이브

커뮤니티에서 개발한 MCP 플러그인으로, Auto Memory와는 목적이 다릅니다. Auto Memory가 "지금 프로젝트에서 Claude가 배운 것"을 저장한다면, claude-mem은 "모든 세션의 전체 대화"를 SQLite3 DB에 아카이브하고, 다음 세션 시작 시 관련 컨텍스트를 재주입합니다. 머신 간 이동이 잦거나 세션이 매우 많이 쌓인 상황에서 특히 유용합니다.

부가 기능: Auto Dream — 메모리 통합 정리

2026년 3월에 공개된 기능으로, 쌓인 메모리를 주기적으로 정리·통합합니다. 실무에서 가장 체감되는 동작은 두 가지입니다.

첫째, 상대 날짜를 절대 날짜로 변환합니다.

변환 전: "어제 Express에서 Fastify로 전환"
변환 후: "2026-03-15에 Express에서 Fastify로 전환"

둘째, 모순된 항목을 감지해 정리합니다. Express → Fastify 전환 후에도 구 항목이 남아있는 경우, 더 최근 항목을 기준으로 이전 항목을 삭제하거나 업데이트합니다. 다만 충돌 해소 로직이 완벽하지는 않아서, 중요한 내용은 여전히 주기적 수동 검토가 필요합니다.

실전 적용

기본 설정

예시 1: 멀티세션 코드베이스 컨텍스트 유지

20개 세션에 걸쳐 쌓인 디버깅 인사이트를 매번 재설명하지 않아도 되는 가장 기본적인 패턴입니다. CLAUDE.md에 알려진 이슈를 명시해두면 새 세션에서도 Claude가 이 맥락을 가지고 시작합니다.

# CLAUDE.md — 프로젝트 루트에 위치
 
## Known Issues & Gotchas
- **ESM/CJS 혼용**: 이 프로젝트는 일부 패키지가 CJS only.
  증상: `ERR_REQUIRE_ESM` 런타임 에러
  해결: tsconfig.json의 `moduleResolution: "bundler"` 설정 확인
  
- **환경변수 로딩 순서**: dotenv는 반드시 앱 진입점 최상단에서 로드.
  위반 시: 일부 서비스에서 undefined 환경변수 발생
 
## 디렉터리 구조
- 테스트: `__tests__/` (Jest)
- API 미들웨어: `src/middleware/`
- 타입 정의: `src/types/`

Auto Memory가 자동으로 추가로 저장하는 항목들은 대략 이런 모습입니다.

---
name: 빌드 도구 설정
description: 이 프로젝트의 패키지 매니저 및 빌드 명령어
type: project
---
 
빌드: pnpm build (npm 사용 불가 — workspace 호이스팅 충돌)
테스트: pnpm test --passWithNoTests
린트: pnpm lint (eslint + tsc --noEmit 순서로 실행)

예시 2: 팀 공유 CLAUDE.md (모노레포 패턴)

팀원마다 Claude에게 다른 설명을 하다 보면 결과물이 제각각이 되는 경험, 실무에서 자주 맞닥뜨리는 상황이죠. CLAUDE.md를 Git으로 공유하면 이 문제를 해결할 수 있습니다.

my-monorepo/
├── .claude/
│   └── CLAUDE.md          # 팀 공통 규칙 (Git 커밋)
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # 웹 앱 전용 규칙
│   └── api/
│       └── CLAUDE.md      # API 서버 전용 규칙
└── packages/

# .claude/CLAUDE.md — 모노레포 루트
 
## 패키지 매니저
pnpm workspace 사용. 개별 패키지 설치 시:
`pnpm --filter @myapp/web add <package>`
 
## 공통 타입 패키지
`@myapp/types` 패키지에서 공유 타입 임포트.
중복 타입 정의 금지.
 
## PR 규칙
- 브랜치: feature/*, fix/*, chore/*
- 커밋 메시지: 한글 가능, imperative mood
- 예: "인증 미들웨어에 JWT 갱신 로직 추가"

고급 설정

예시 3: claude-mem 플러그인 설정

3,400개 이상의 세션 기록을 두 서버 간에 공유한 실제 사례가 보고된 패턴입니다. 머신 간 이동이 잦은 개발자에게 유용합니다.

# claude-mem 설치
pnpm add -g claude-mem
 
# 초기화 (프로젝트별 DB 생성)
claude-mem init

// MCP 설정 파일에 claude-mem 등록
// ~/.claude/mcp_settings.json
{
  "mcpServers": {
    "claude-mem": {
      "command": "claude-mem",
      "args": ["serve"],
      "env": {
        "CLAUDE_MEM_DB_PATH": "/Users/yourname/.claude-mem/sessions.db"
      }
    }
  }
}

주의: JSON 환경변수에서 ~는 쉘 틸드 확장이 적용되지 않을 수 있습니다. ~ 대신 절대 경로를 직접 입력하는 것을 권장합니다.

서버 간 DB 파일을 옮기려면 scp로 복사할 수 있습니다. 단, 이 방식은 단방향 복사라 양쪽 서버에서 동시에 작업하면 나중에 덮어쓰는 쪽이 이깁니다.

# 로컬 → 리모트 단방향 복사
scp ~/.claude-mem/sessions.db user@remote-server:~/.claude-mem/sessions.db

PreToolUse 훅이 특히 유용한데, 이전에 읽은 파일이 있으면 실제 Read 툴 호출을 차단하고 캐시된 요약만 주입합니다. 중복 파일 읽기로 소비되는 토큰을 꽤 절약할 수 있습니다.

장단점 분석

솔직히 말씀드리면, 이 시스템이 항상 완벽하게 동작하는 건 아닙니다. 장점과 한계를 함께 알고 쓰는 편이 훨씬 낫습니다.

장점

단점 및 주의사항

컨텍스트 윈도우(Context Window): LLM이 한 번에 처리할 수 있는 텍스트의 최대 길이입니다. CLAUDE.md와 Auto Memory 파일들이 모두 여기 들어가므로, 내용이 많아질수록 실제 작업에 쓸 수 있는 공간이 줄고 앞쪽 내용의 영향력도 감소합니다.

Auto Memory ≠ Fine-tuning: 메모리 저장이 모델 가중치를 업데이트하는 게 아닙니다. 컨텍스트 주입 방식이라 세션마다 관련 메모리를 선택적으로 로드해야 효과가 있습니다.

실무에서 가장 흔한 실수

1. CLAUDE.md에 모든 것을 담으려는 시도 — 프로젝트 위키 수준으로 작성하다 보면 오히려 중요한 규칙이 무시됩니다. "Claude가 모르면 안 되는 것"만 남기는 게 훨씬 효과적입니다.

2. Auto Memory와 CLAUDE.md의 역할 혼동 — CLAUDE.md는 팀이 의도적으로 정의한 규칙, Auto Memory는 Claude가 경험에서 배운 것입니다. Auto Memory를 직접 편집하는 건 가능하지만, 팀 규칙은 반드시 CLAUDE.md에 명시적으로 적어두는 편이 좋습니다.

3. 메모리 파일 방치 — Auto Memory가 알아서 잘 해줄 거라 믿고 수십 세션 동안 방치하면, 초기에 저장된 잘못된 가정이 계속 주입될 수 있습니다. 한 달에 한 번 정도 ~/.claude/projects/ 아래를 직접 열어서 낡은 항목을 정리해보시는 것을 권장합니다.

마치며

Claude Code 메모리 시스템의 핵심은 "복잡한 인프라 없이 마크다운 파일만으로 세션 간 컨텍스트를 유지한다"는 점입니다. 지금 당장 CLAUDE.md 하나만 만들어도 다음 세션부터 체감 차이가 납니다. 경험상 초기 컨텍스트 설명 시간을 꽤 줄일 수 있었습니다.

지금 바로 시작해볼 수 있는 3단계:

1. CLAUDE.md 생성: 현재 프로젝트 루트에 CLAUDE.md 파일을 만들고, 빌드 명령어·패키지 매니저·알려진 이슈 세 가지만 먼저 적어보시면 됩니다. echo "# 프로젝트 규칙\n\n- Build: pnpm build" > CLAUDE.md로 시작하셔도 충분합니다.

2. Auto Memory 확인: Claude Code로 한 세션 작업한 뒤 ~/.claude/projects/ 아래를 직접 탐색해보시면 Claude가 무엇을 기억했는지 확인할 수 있습니다. 잘못된 내용이 있다면 마크다운 파일을 직접 편집하시면 됩니다.

3. 팀 적용: 혼자 검증이 됐다면 git add .claude/CLAUDE.md && git commit -m "프로젝트 Claude 컨텍스트 규칙 추가"로 팀 전체가 동일한 컨텍스트를 공유할 수 있습니다.

다음 글: Claude Code 메모리를 넘어, 여러 에이전트가 각자의 메모리를 독립적으로 유지하면서 공유 컨텍스트로 협업하는 멀티 에이전트 오케스트레이션 — A2A(Agent-to-Agent) 프로토콜과 공유 메모리 설계 전략

참고 자료

공식 문서

• How Claude remembers your project - Claude Code Docs
• Memory Tool - Claude API Docs

심층 분석

• Claude Code Memory System Explained: 4 Layers, 5 Limits, and a Fix - Milvus Blog
• Inside Claude Code: The "Database-Free" Memory Architecture - Medium
• Claude Code Deep Dive Part 4: Why It Uses Markdown Files Instead of Vector DBs - DEV Community
• Auto Memory and Auto Dream: how Claude Code learns and consolidates its memory
• Claude Code Memory Guide (2026): CLAUDE.md vs Auto Memory vs Plugins - LaoZhang AI Blog
• Claude Code Source Leak: The Three-Layer Memory Architecture - MindStudio

커뮤니티 사례

• GitHub - thedotmack/claude-mem
• Adding Persistent Memory to Claude Code with claude-mem - DEV Community
• What Is Claude Code Auto-Memory? - MindStudio Blog
• State of AI Agent Memory 2026 - Mem0 Blog
• Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory - arXiv