정보 오류 줄이는 클로드 코드 메모리 관리법

클로드 코드(Claude Code)의 메모리 기능은 편리하지만 오랜시간 이용하다 보면 주의해야 할 점이 생깁니다. 그건 바로 처음에는 의도된 대로 동작하지만 조금씩 틀린 정보가 계속 기억될 수 있다는 것입니다.

이 글에서는 Claude Code의 MEMORY.md와 Auto Memory가 어떻게 동작하는지 살펴보고, 실제로 오래된 정보가 메모리에 남아 있었던 문제를 어떻게 발견하고, 해결했는지 정리해 봤습니다. 또 직접 만든 memory-inventory skill을 이용해, 메모리를 점검하고 아카이브하는 법도 살펴보겠습니다. (다룰 내용이 많아, 글이 다소 길어졌지만 메모리 기능의 동작 방식부터, 문제 해결 과정, 관리 방법까지 한 편에서 살펴볼 수 있도록 정리했습니다!)

클로드 코드의 메모리(Memory)

Claude Code의 여러 기능중에 매우 편리한 기능이 하나 있는데요, 바로 Memory입니다. Memory는 이전 세션에서 작업한 내용을 기억해 두기 때문에, 매번 같은 내용을 다시 설명하지 않아도 되도록 기억을 해주는 기능입니다.

예를 들어, 이전 세션에서 다음과 같은 정보를 확인했다고 가정해 보겠습니다. API 테스트를 위해서는 로컬 Redis 인스턴스가 필요합니다. 다음 세션에서도 이 정보가 유지된다면 Claude는 프로젝트를 다시 분석하지 않고도 테스트 환경을 이해할 수 있습니다.

이런 기능을 처음 사용하면 상당히 편합니다. 저 역시 처음에는 비슷하게 생각했습니다.

“Claude가 이전 작업을 기억해 주니까, 메모리도 알아서 잘 관리해 주겠지.”

그런데 어느날 메모리 관련 정보를 직접 확인해 보면서 생각이 달라졌습니다. 이미 끝난 작업이 아직도 진행 중인 것처럼 기록되어 있었고, 해결된 문제에 대한 경고가 계속 남아 있었습니다.

예를 들면, 이런 내용입니다.

PR #142가 리뷰를 기다리고 있습니다.

하지만 GitHub에서의 해당 PR의 상태는:

PR #142 → Merged 였습니다.

또 이런 내용도 있었습니다.

인증 관련 이슈 X가 해결될 때까지 새로운 인증 플로우의 사용을 피하세요.

하지만 해당 Issue는 이미 해결되어 있었습니다. 이때부터 저는 Claude 메모리는 정기적으로 관리해야 하는 데이터라고 보게 됐습니다.

Claude Code 메모리의 기본 구조

Claude Code는 프로젝트와 세션에서 참고할 수 있는 여러 형태의 지속적인 지침과 메모리를 제공합니다. 공식 문서 기준으로, Claude Code가 세션 간 지식을 유지하는 방법은 크게 다음과 같습니다.

• CLAUDE.md 파일: Managed policy(조직 전체), User(개인 전역), Project(프로젝트 공용), Local(개인·프로젝트별) 등 4가지 범위로 배치 가능
• .claude/rules/: 특정 파일 패턴이나 하위 디렉토리에만 적용되는 규칙 파일
• Auto Memory: Claude가 작업 중 스스로 학습 내용을 기록하는 자동 메모리

이 중에서 자주 다루게 되는 것은 다음 두 가지입니다.

• CLAUDE.md
• Auto Memory

CLAUDE.md는 사용자가 직접 작성하는 프로젝트 지침에 가깝고, Auto Memory는 Claude가 작업하면서 유용하다고 판단한 정보를 지속적으로 기록하는 방식입니다.

먼저 CLAUDE.md의 구조를 조금 더 살펴보겠습니다. Auto Memory에 대해서는 그 다음에 이어서 설명합니다.

CLAUDE.md의 4가지 범위

CLAUDE.md 파일은 여러 위치에 둘 수 있으며, 각각 다른 범위를 가집니다. 공식 문서 기준으로 다음 네 가지로 나뉩니다.

세션이 시작되면 이 파일들은 덮어쓰기가 아니라 순서대로 결합되어 로드됩니다.

관리 정책 (시스템 경로)
↓
사용자 지침 (~/.claude/CLAUDE.md)
↓
프로젝트 루트 CLAUDE.md
↓
CLAUDE.local.md
↓
하위 디렉토리 CLAUDE.md (해당 파일 접근 시 지연 로드)

가장 광범위한 범위(관리 정책)부터 가장 구체적인 범위(로컬 지침) 순으로 로드되므로, 프로젝트 지침이 사용자 지침 이후에 컨텍스트에 나타납니다.

CLAUDE.local.md - 개인 설정을 팀과 분리하기

이 파일은 .gitignore에 추가하여 버전 관리에서 제외하도록 설계되어 있습니다. 팀이 공유하는 CLAUDE.md에는 넣기 어려운 개인 설정 — 예를 들어 로컬 샌드박스 URL, 선호하는 테스트 데이터, 개인 도구 경로 등 — 을 여기에 작성합니다.

같은 디렉토리의 CLAUDE.md와 CLAUDE.local.md가 모두 존재하면 둘 다 로드됩니다. 따라서 팀 규칙과 개인 설정이 충돌 없이 공존할 수 있습니다.

Auto Memory의 저장 구조

Claude Code 공식 문서에 따르면 Auto Memory는 프로젝트별 디렉토리 아래에 저장됩니다.

~/.claude/projects/<project>/memory/

일반적인 구조는 다음과 같습니다.

memory/
├── MEMORY.md                # 메모리 전체의 목차(인덱스), 세션마다 로드
├── user_role.md             # 사용자 역할·전문성·업무 스타일
├── feedback_testing.md      # 사용자가 Claude에게 준 피드백·교정 사항
└── ...                    

여기에서 MEMORY.md는 메모리 전체의 목차(인덱스) 역할을 하고, 나머지는 메모리 내용이 저장된 파일들입니다. (참고: 공식 문서)

MEMORY.md는 메모리의 목차

MEMORY.md에 실질적인 내용을 저장하는 대신 어떤 정보가 어디에 있는지 알려주는 인덱스로 사용합니다.

예를 들어,

# Project Memory
## Debugging
- Redis troubleshooting → debugging.md

## API
- API conventions → api-conventions.md

## Architecture
- Authentication design → architecture.md

구조적으로 보면 다음과 같습니다.

MEMORY.md
   ├── debugging.md
   ├── api-conventions.md
   └── architecture.md

쉽게 표현하면, 

MEMORY.md = 목차 topic file = 상세 내용이라고 생각하면 이해하기 쉽습니다.

MEMORY.md의 로딩 제한

공식 문서에 따르면 세션 시작 시 MEMORY.md는 최대 200줄 또는 25KB까지만 로드됩니다. 그 이후 내용은 잘립니다.

그래서 MEMORY.md는 간결한 인덱스로 유지하고, 상세한 내용은 각각의 topic 파일에 넣어 연결하는 방식이 좋습니다.

필요에 따라 읽는 Topic 파일

debugging.md, architecture.md 같은 topic 파일이 있다고 해서 세션 시작 시 모두 읽는 것은 아닙니다.Claude가 필요에 따라 파일 도구를 사용해 관련 파일을 읽습니다.

전체적인 흐름을 단순화하면 다음과 같습니다.

세션 시작
   ↓
MEMORY.md 확인
 ↓
필요한 메모리 탐색
   ↓
관련 topic file 읽기

그렇기 때문에 MEMORY.md에 좋은 인덱스를 만드는 것이 중요합니다.

메모리를 방치하면 생기는 문제

메모리가 쌓이면 컨텍스트가 커지고 성능이 떨어질 것이라고 생각하기 쉽습니다. 물론 메모리의 크기는 컨텍스트 구성과 관련된 요소입니다. 하지만 제가 실제로 더 문제라고 느낀 것은 성능이 아니라 잘못된 정보였습니다.

이미 끝난 PR이 계속 진행 중으로 남아 있었다

제 경우 아래와 같은 상황이 발생했습니다.

Current work:

- PR #142 리뷰 대기 중

- Issue #87 조사 진행 중

그런데 실제 상태를 확인해 보니,

PR #142 → Merged

Issue #87 → Closed

메모리 내용은 과거의 특정 시점에서는 맞았지만 현재는 틀린 상태였던 것입니다. Claude가 다음 세션에서 잘못된 정보를 가지고 의사결정을 할 수도 있다는 것이죠.

오래된 경고 메모리가 남아 있었다

또한 아래와 같은 조건부 경고 메모리도 있었습니다.

인증 관련 이슈 X가 해결될 때까지 새 인증 플로우 사용을 피할 것.

이 메모리는 기록 당시에는 매우 유용한 정보였을 것입니다. 하지만 해당 이슈가 해결된 현재에는 오히려 혼란을 야기 할 수 있는 상황이 되었습니다. 시간이 지나면서 상황이 다음과 같이 변한 겁니다.

문제 발생
  ↓
주의사항 기록
  ↓
문제 해결
  ↓
주의사항이 여전히 존재

이런 상황이 되었습니다. 결국 과거의 예외 상황이 현재의 일반적인 규칙처럼 남게 되는 것입니다. 이런 메모리는 “오래된 정보”보다 더 위험할 수 있다고 느꼈습니다.

없는 정보보다 오래된 기억이 더 나쁘다

이번 정리에서 제가 가장 크게 느낀 부분입니다. 메모리가 아예 없다면 Claude는 다시 확인할 가능성이 높습니다.

현재 PR 상태를 확인하겠습니다. 그리고 GitHub를 확인할 수 있습니다.

반면 오래된 메모리가 있다면,

PR #142 리뷰 대기 중

→ 아직 review 중이군요.라고 판단해서 잘못된 결론을 도출하게 됩니다. 그래서 저는 아래와 같이 생각했습니다.

없는 정보보다 오래된 잘못된 정보가 더 위험할 수 있다.

공식 도구로 메모리 관리하기: /memory와 Auto-dream

Claude Code는 메모리 관리를 위한 공식 기능을 두 가지 제공합니다.

/memory: 메모리 탐색과 수동 편집

/memory 명령을 실행하면 현재 프로젝트의 CLAUDE.md, CLAUDE.local.md, Auto Memory 파일 위치를 한눈에 확인할 수 있습니다.

/memory이 명령으로 할 수 있는 것:

• 메모리 파일 목록 확인 및 편집기에서 열기
• Auto Memory 폴더 탐색
• Auto Memory 및 Auto-dream ON/OFF 토글

다만 /memory는 탐색과 수동 편집 도구입니다. 중복 제거나 오래된 정보 정리 같은 자동화 작업은 포함되어 있지 않습니다.

Auto-dream: 백그라운드 메모리 정리

Auto-dream은 Claude가 백그라운드에서 자동으로 메모리를 정리하는 기능입니다. 마치 수면 중 기억을 정리하는 것에 비유할 수 있습니다. 중요한 점은 /dream이라는 슬래시 명령은 존재하지 않는다는 것입니다. 이전 버전의 /memory UI에 “/dream to run”이라는 힌트가 표시된 적이 있었지만, 실제로는 수동 실행 명령이 아닙니다(GitHub Issue #39135 참고).

Auto-dream을 사용하려면:

/memory → Auto-dream 토글 ON

토글을 켜두면 Claude가 백그라운드에서 자동으로 다음 작업을 수행합니다:

• 현재 메모리 구조 파악
• 최근 세션 트랜스크립트에서 새로운 인사이트 추출
• 중복 항목 병합
• 상대 날짜(“어제”, “지난주”)를 절대 날짜로 변환
• MEMORY.md 인덱스 재구축

공식 도구가 커버하지 못하는 영역

/memory와 Auto-dream은 메모리 내부의 구조 정리에는 효과적입니다. 하지만 3장에서 살펴본 것처럼, 실제로 더 위험한 문제는 메모리 안의 내용이 현재도 맞는지 여부였습니다.

즉, 공식 도구는 메모리 정리에는 강하지만 사실 검증과 안전한 삭제 정책은 별도로 마련해야 합니다. 그래서 저는 이 부분을 보완하기 위해 직접 skill을 만들어 보았습니다.

직접 만든 memory-inventory skill

그래서 직접 memory-inventory라는 Skill을 만들어 보았습니다.

삭제 대신 Archive

메모리 정리에서 가장 먼저 고민한 것은 “지우고 나서 되돌릴 수 있는가?”였습니다. 삭제는 돌이킬 수 없지만, archive로 이동하면 판단이 잘못됐을 때 복구할 수 있습니다. 그래서 다음과 같은 원칙을 세웠습니다.

예를 들어, Auto Memory에 다음과 같은 topic 파일들이 있다고 가정합니다.

memory/
├── MEMORY.md
├── user_role.md
└── project_auth.md

여기서 project_auth.md가 이미 완료된 인증 마이그레이션에 대한 내용이라면 바로 삭제하지 않습니다.

memory/
├── MEMORY.md
├── user_role.md
└── archive/
    └── project_auth.md

대신 이렇게 이동합니다. 이렇게 하면 나중에 판단이 잘못됐더라도 복구할 수 있습니다.

승인 레벨의 분리

AI에게 모든 판단을 맡기는 것도 위험했습니다. 그래서 작업을 다음과 같이 구분했습니다.

여기서 승인 수준의 차이는 다음과 같습니다.

• 비교적 안전: 원래 의미가 유지되는 문장 압축이므로, Claude가 자체 판단으로 진행해도 무방합니다.
• 사용자 확인: 변경 내용과 근거를 보여준 뒤 “맞습니까?”라고 확인을 받습니다. 사실 관계가 달라지기 때문입니다.
• 사용자 승인: 변경을 실행하기 전에 명시적으로 “승인”을 받습니다. 파일 이동이 수반되기 때문입니다.
• 명시적 승인: 여러 파일을 합치거나 삭제하는 작업이므로, 변경 범위와 영향을 상세히 제시한 뒤 승인을 받습니다. 되돌리기가 어렵기 때문입니다.

특히 다음 두 가지는 신중하게 다뤄야 합니다.

• 사실을 수정하는 것
• 정보를 없애는 것

AI 입장에서 중복처럼 보여도, 실제로는 다른 조건을 가진 정보일 수 있기 때문입니다.

실제 메모리 정리 프로세스

제가 사용한 정리 방법은 크게 다섯 단계로 나눌 수 있습니다.

Phase 0 백업
   ↓
Phase 1 현황 파악
   ↓
Phase 2 신선도 검증
   ↓
Phase 3 정리 제안
   ↓
Phase 4 사용자 승인
   ↓
Phase 5 반영 및 검증

Phase 0. 백업

메모리 정리를 시작하기 전에 원본을 백업합니다. 메모리 정리는 예상보다 많은 파일을 수정할 수 있기 때문에 백업은 필수 단계로 두는 것이 좋습니다.

Phase 1. 현황 파악

다음으로 메모리의 전체 크기를 파악합니다. 확인해야 할 항목은 다음과 같습니다.

처음에는 “메모리가 너무 큰 것 같다”는 막연한 느낌이었는데, 숫자로 확인하기 시작하니 전체 상황이 더 명확해졌습니다.

Phase 2. 신선도 검증

가장 중요한 단계입니다.

예를 들어, 메모리에 다음 내용이 있다고 가정합니다. 

PR #142가 리뷰를 기다리고 있습니다.

그러면 메모리만 보고 판단하지 않습니다. 실제 GitHub를 확인합니다.

gh pr view 142

• Issue를 확인하려면, gh issue view 87 
  Git 상태는, git status

• 최근 변경 사항은, git log --oneline -20

이런 방식으로 메모리의 내용과 실제 상태를 비교합니다.

네 가지 상태로 분류하기

각 메모리를 다음 네 가지 상태로 분류하면 관리하기 편합니다.

예를 들어,

메모리:

PR #142가 리뷰를 기다리고 있습니다.

GitHub status:

Merged

의 상황이라면, CONTRADICTED로 메모리 내용과 실제 상황을 비교해 분류하는 것입니다.

Phase 3. 정리 제안

검증이 끝났다고 바로 파일을 수정하지 않고, 다음과 같이 제안을 먼저 작성합니다.

유지
- 인증 아키텍처
- 데이터베이스 규칙

압축
- 중복된 Redis 트러블슈팅 노트

수정
- PR #142 상태

Archive
- 완료된 마이그레이션 프로젝트

통합
- 중복된 데이터베이스 설정 노트

이렇게 하면 각 변경이 왜 필요한지 알 수 있습니다.

Phase 4. 사용자 승인

특히 수정이나 이동이 필요한 항목은 사용자가 결정하도록 합니다.

예시:

PR #142 상태를 "Merged"로 수정할까요?
[승인]
[보류]

또는

project_auth.md를 archive로 이동할까요?
[이동]
[유지]

이 과정은 AI가 의도치 않게 내용을 수정하지 못하게 하는 안전장치의 의미가 있습니다.

Phase 5. 삭제보다 Archive(보존과 분리의 균형)

오래되었거나 작업이 완료된 메모리를 정리할 때, 가장 먼저 드는 고민은 “이걸 완전히 지워도 괜찮을까?” 하는 불안감입니다. 그렇다고 파일 자체를 완전히 삭제(rm)해 버리면, 몇 달 뒤 레거시 인증 이슈를 추적하거나 당시의 아키텍처 의사결정(ADR) 맥락을 확인해야 할 때 소중한 기록이 영구히 사라집니다.

그래서 권장하는 방식이 바로 archive/ 폴더 이동과 MEMORY.md 인덱스 정리입니다.

1) 활성 메모리 디렉터리에서 분리하기

완료된 topic 파일은 활성 디렉터리 루트에서 제외하여 archive/ 폴더로 이동시킵니다. 이렇게 물리적 경로를 분리해 두면, Claude가 새로운 메모리를 감지하고 병합하는 과정에서 과거의 레거시 파일이 활성 작업 컨텍스트와 뒤섞이는 것을 원천 차단할 수 있습니다.

2) MEMORY.md의 활성 인덱스에서 내리기

이 작업은 MEMORY.md에서 해당 파일을 ‘현재 활성 주제’ 목록에서 빼는 것입니다. Claude가 세션 시작 시 읽는 것은 MEMORY.md의 상위 200줄뿐이므로, 만약 기록을 남겨두고 싶다면 MEMORY.md 맨 아래에 최소한의 아카이브 경로만 한 줄 남겨둡니다.

## Archive

- 인증 마이그레이션 (2026-Q1 완료, 필요 시 참조) → archive/project_auth.md

이렇게 설정하면 Claude의 동작이 달라집니다.

• 일상 대화 중 불필요한 참조 차단: 활성 인덱스에 없기 때문에 일반적인 작업 도중 Claude가 멋대로 관련 토픽 메모리를 열람하지 않습니다.
• 명시적 요구 시에만 조회 가능: “예전 인증 마이그레이션 아카이브 기록 확인해줘”처럼 사용자가 명시적으로 이전 맥락을 요구할 때만 해당 아카이브 경로를 찾아 열람할 수 있습니다.
• 심리적 안전성 확보: 언제든 복구할 수 있으므로, 엔지니어가 메모리를 정리할 때 ‘혹시 지웠다가 문제 생기면 어쩌지’라는 망설임 없이 메모리 디렉터리를 쾌적하게 유지할 수 있습니다.

memory-inventory Skill 만들기

다음은 제가 사용한 스킬 입니다.

여기서 특히 눈여겨 볼 부분은 disable-model-invocation: true입니다. 메모리 정리는 파일을 실제로 변경하는 작업이기 때문에, 사용자가 명시적으로 실행했을 때만 동작하도록 만드는 편이 적절합니다.

실제로 가장 어려웠던 부분

메모리를 정리하며 가장 까다로웠던 건 삭제 대상 고르기가 아니라, **”이 정보가 지금도 사실인가?”**를 가려내는 일이었습니다. 한쪽 파일엔 “이슈 Y 때문에 기능 X는 쓰지 말 것”이라 적혀 있는데, 다른 파일에는 “배포 후 이슈 Y 해결됨”이라 적혀 있다면 어느 내용이 맞는지 알기가 어려웠습니다.

결국 Git 커밋이나 GitHub PR, 실제 배포 환경 같은 원본(Source of Truth)을 직접 대조해 봐야 했습니다. 메모리 정리에서 중요한 점은 시간이 흐름에 따라 현재와는 조금 다른 정보 상태를 동기화하는 작업이었습니다.

/memory와 custom Skill의 역할을 나누기

기본 명령인 /memory가 있는데 왜 굳이 커스텀 스킬을 따로 만들었을까요? 두 도구의 역할과 사용 주기가 다르기 때문입니다.

• /memory (기본 명령): 현재 로드된 메모리를 가볍게 들여다보거나 특정 문장을 즉시 고치는 일상적인 뷰어/편집기입니다.
• /memory-inventory (커스텀 스킬): Git 커밋과 GitHub PR을 대조해 사실 여부를 검증하고, 아카이브와 인덱스 동기화까지 안전하게 제안하는 정기 종합 점검 도구입니다.

평소에는 /memory로 가볍게 확인하고, 스프린트가 끝날 때마다 /memory-inventory로 묵은 메모리를 일괄 정리하는 투트랙 방식으로 운영하는 것이 가장 효과적입니다.

마치며

Claude Code의 Auto Memory는 세션이 바뀌어도 맥락을 이어주는 편리한 기능입니다. 처음에는 “알아서 기억하니 관리도 알아서 하겠지”라고 생각했습니다. 하지만 실제 메모리 관련 파일을 확인해 보니 이미 해결된 이슈 같은 기록들이 그대로 남아 있었고 이것이 문제가 될 수 있다고 생각했기에 주기적으로 검증하고 정리하는 것이 좋다는 결론을 내렸습니다.

이 글을 읽는 여러분들도 Claude Code를 사용하신다면 메모리 관련 정보에 대해 한 번쯤 점검해 보시길 바랍니다.

<참고>

• Claude Code Memory
• Claude Code Skills / Slash Commands
• Claude Code Tools Reference
• Claude Agent SDK — User Input / AskUserQuestion

ⓒ요즘IT의 모든 콘텐츠는 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다.