Claude Code MEMORY.md는 어떻게 동작할까?

클로드 코드 메모리(MEMORY.md)는 어떻게 동작하나, 직접 써보며 정리한 구조와 한계

클로드 코드를 며칠만 써보면 누구나 겪는 불편이 하나 있다. 세션을 닫고 다음 날 다시 열면, 클로드가 어제 일을 깨끗하게 잊고 있다는 것. 프로젝트 빌드 명령, 배포에서 빼야 하는 모듈, "스크립트 짜지 말고 파일 직접 고쳐줘" 같은 작업 방식을 매번 다시 설명하게 된다.

이 핸드오프를 매끄럽게 만들어 주는 게 클로드 코드의 메모리 기능이다. 그중에서도 클로드가 스스로 메모를 남기는 오토 메모리(auto memory)는 동작 방식이 꽤 독특해서, 한 번 제대로 이해해 두면 활용도가 달라진다. 이 글에서는 현재 클로드 생태계에 어떤 메모리 개념들이 돌아가고 있는지 짧게 정리한 뒤, 오토 메모리의 저장 구조와 로드 시점, 그리고 가장 많이 오해하는 한계까지 직접 써본 경험을 기준으로 풀어본다.

지금 클로드에 돌아가는 메모리 개념들

먼저 큰 그림부터. "메모리"라는 이름이 붙은 기능이 여러 군데 흩어져 있어서 헷갈리기 쉬운데, 쓰는 제품에 따라 갈린다.

클로드 앱(claude.ai)의 채팅 메모리 — 일반 사용자용이다. 대화를 거치며 사용자의 취향이나 역할 같은 걸 기억해 다음 대화에 반영한다. 프로젝트별로 메모리 공간을 분리할 수 있고, 기억을 남기고 싶지 않을 땐 시크릿 모드를 쓰면 된다.

클로드 코드의 CLAUDE.md — 개발자가 직접 쓰는 지시문 파일이다. 빌드 명령, 코딩 컨벤션, "항상 X 하라" 같은 규칙을 적어두면 매 세션 시작 때 클로드가 읽는다. 내가 쓰고, 내가 관리한다.

클로드 코드의 오토 메모리(MEMORY.md) — 이 글의 주인공이다. CLAUDE.md와 반대로, 클로드가 작업하면서 스스로 판단해 메모를 남긴다. 사용자의 교정과 선호를 학습해 두는 일종의 자동 스크래치패드다.

API 메모리 툴 — 클로드로 앱을 만드는 개발자가 자기 애플리케이션에 영속적 개인화 기능을 붙일 때 쓴다.

여기서 핵심은 CLAUDE.md와 오토 메모리가 서로 보완 관계라는 점이다. 둘 다 매 대화 시작 시 컨텍스트로 올라가지만, 하나는 "내가 클로드에게 지시하는 규칙"이고 다른 하나는 "클로드가 자기 자신에게 남기는 학습 노트"다. 참고로 오토 메모리는 클로드 코드 v2.1.59 이상에서 동작한다.

메모리 시스템은 어떻게 동작하나

이제 오토 메모리 내부로 들어가 보자.

저장 구조: 철저히 파일 기반

오토 메모리는 데이터베이스가 아니라 평범한 마크다운 파일 더미다. 프로젝트마다 별도 폴더가 생긴다. 윈도우 기준 경로는 이런 식이다.

C:\Users\JSon\.claude\projects\D--04-github-P\memory\
├── 📄 MEMORY.md          ← 인덱스 (매 세션 자동 로드)
├── 📄 feedback_*.md      ← 사실 1개당 파일 1개
├── 📄 project_*.md
└── 📄 server_*.md

폴더 이름(D--04-github-P)은 git 저장소를 기준으로 만들어지기 때문에, 같은 레포의 여러 워크트리나 하위 디렉터리는 메모리 폴더 하나를 공유한다. 그리고 이 파일들은 머신 로컬이다. 다른 컴퓨터나 클라우드 환경으로 따라오지 않는다.

구조의 두 가지 포인트.

• 개별 메모리 파일은 frontmatter(name / description / type) + 본문 한 덩어리로 되어 있다. 사실 하나당 파일 하나가 원칙이다.
• MEMORY.md는 본문을 담지 않는다. "제목 + 한 줄 요약"만 있는 한 줄짜리 목차다. 실제 내용은 각 토픽 파일에 들어가 있고, MEMORY.md는 그게 어디 있는지만 가리킨다.

4가지 타입

남기는 메모는 성격에 따라 네 부류로 나뉜다.

• user: 사용자가 누구인지. 역할과 선호.
• feedback: 일하는 방식에 대한 지침. Why와 How to apply까지 함께 적힌다.
• project: 코드나 git에는 안 드러나는 진행 맥락과 제약. 예를 들어 "lap-log-analyzer는 배포에서 제외" 같은 것.
• reference: 외부 자원 포인터. 서버 접속 정보 같은 것.

코드만 봐서는 알 수 없는 것들, 그러니까 "이 모듈은 왜 손대면 안 되는지", "이 사람은 스크립트보다 직접 편집을 선호하는지"가 project와 feedback에 쌓인다. 이게 오토 메모리의 진짜 가치다.

 

실제 사용MEMORY 정보

로드 시점이 핵심이다

여기를 이해 못 하면 메모리를 헛 쓴다.

1. 매 세션 시작 시 MEMORY.md 인덱스가 컨텍스트에 올라온다. 정확히는 앞에서부터 200줄 또는 25KB까지, 둘 중 먼저 닿는 한계까지만 로드된다. 그래서 MEMORY.md를 한 줄 요약만으로 짧게 유지하는 거다. 길어지면 뒤쪽은 아예 안 읽힌다.
2. 개별 토픽 파일은 세션 시작 때 안 올라온다. 작업 중 관련 있는 메모리가 필요해지면 그때 <system-reminder> 블록으로 떠오른다. 이건 어디까지나 배경 참고이지 지시가 아니고, 무엇보다 작성 당시 시점의 스냅샷이라는 점이 중요하다.

이 스냅샷 성격 때문에 실제로 사고가 난다. 얼마 전 한 프로젝트에서 메모리에 저장된 파일 경로(lap-store 경로)를 그대로 믿고 작업했다가 어긋난 적이 있다. 메모를 남긴 지 열흘이 지나는 동안 코드가 바뀌었기 때문이다. 그래서 MEMORY.md를 다시 읽었을 때 거기엔 "10일 됨 — 코드 동작과 파일 경로는 현재 코드로 재확인하라"는 경고가 붙어 있었다. 메모리는 과거의 메모이지 현재의 사실이 아니다. 경로나 동작처럼 잘 바뀌는 정보는 메모리를 출발점으로만 쓰고, 실제 작업 전엔 현재 코드로 한 번 더 확인하는 게 안전하다.

메모리끼리 연결한다

본문에서 다른 메모리를 [[feedback_no_auto_doc_update]]처럼 위키 링크로 엮을 수 있다. 한 실수 패턴이 떠오르면 관련된 메모도 같이 참조되도록 미리 연결해 두는 식이다. 이렇게 해두면 "스크립트 짜지 말고 직접 편집"이라는 피드백이 떠오를 때, 그와 얽힌 다른 교훈도 함께 끌려 올라온다.

가장 큰 오해 메모리는 강제가 아니다

이 부분을 짚고 넘어가야 한다. 메모리는 "다음 세션의 나에게 보내는 메모"이지, 코드처럼 자동 실행되는 규칙이 아니다.

공식 문서도 같은 말을 한다. CLAUDE.md든 오토 메모리든 둘 다 컨텍스트로 전달될 뿐, 강제된 설정(enforced configuration)이 아니라고. 즉 다음 세션에서 읽히기는 하지만, "반드시 X 하기 전엔 Y를 하라" 같은 강제 동작은 메모리로 보장되지 않는다. 클로드가 그 메모를 읽고 따르려 하긴 해도, 엄격한 준수가 보증되는 건 아니다.

특정 시점에 무조건 실행돼야 하는 동작, 예를 들어 "커밋 전엔 반드시 린트를 돌려라" 같은 규칙이라면 메모리가 아니라 settings.json의 훅(hook)으로 처리해야 한다. 훅은 정해진 라이프사이클 시점에 셸 명령으로 실행되기 때문에, 클로드의 판단과 무관하게 하네스(harness)가 실제로 돌려준다. PreToolUse 훅을 걸면 클로드가 어떻게 결정하든 특정 동작을 막을 수 있다.

정리하면 이렇다.

• 행동을 유도하고 싶다 → CLAUDE.md 또는 오토 메모리
• 행동을 강제하고 싶다 → settings.json의 훅

이번에 얻은 교훈을 "매번 무조건" 강제하고 싶다면 메모리보다 훅 설정이 확실하다.

실무에서 챙길 것

1. 오토 메모리는 기본적으로 켜져 있다.

2. 세션 안에서 /memory를 치면 현재 로드된 메모리 파일을 전부 보고, 켜고 끄고, 폴더를 열어 직접 편집할 수 있다.

    - 클로드가 뭘 저장했는지 모르겠다 싶으면 여기서 폴더를 열어 확인하면 된다.

3. 오래된 메모리는 의심하자. 인덱스에 날짜 경고가 붙어 있다면 그건 신호다

 

결국 오토 메모리의 정체는 단순하다. 매 세션 리셋되는 클로드가 자기 자신에게 남기는 쪽지 묶음. 그 쪽지가 어디에 어떻게 쌓이고, 언제 읽히고, 어디까지 믿을 수 있는지만 알면 충분히 잘 쓸 수 있다.