클로드 코드 자동 메모리: AI가 스스로 배우고 기억하는 법

클로드 코드에는 두 가지 메모리 시스템이 있습니다. 개발자가 직접 작성하는 CLAUDE.md와 Claude가 스스로 학습하는 자동 메모리(auto memory)입니다. CLAUDE.md가 “이렇게 해”라는 명시적인 지시라면, 자동 메모리는 Claude가 작업하면서 “아, 이 프로젝트에서는 이렇게 하는구나”하고 스스로 메모하는 노트에 가깝습니다.

이 글에서는 자동 메모리의 동작 원리와 실전 활용법을 자세히 알아보겠습니다.

자동 메모리란?

자동 메모리는 2026년 2월 v2.1.32에서 처음 도입된 기능입니다. Claude가 세션 중에 “이건 나중에도 쓸모 있겠다” 싶은 정보를 알아서 저장하는 기능이에요. 이후 v2.1.59에서 /memory 커맨드가 추가되면서 메모리를 확인하고 관리하는 것도 편해졌습니다.

매 세션마다 무조건 저장하는 게 아니라, 여러 세션에 걸쳐 반복적으로 유용할 만한 정보만 골라서 기록해둡니다.

어떤 것들이 저장될까요? 개발자가 교정해준 내용이 대표적입니다. “이 프로젝트에서는 npm 말고 bun을 써”라고 고쳐주면, 다음 세션부터는 알아서 bun을 씁니다. 디버깅 과정에서 얻은 교훈도 저장됩니다. “이 API는 content-type을 명시하지 않으면 400을 반환하더라” 같은 것들이요. 프로젝트의 아키텍처 패턴, 자주 쓰는 유틸리티 함수의 위치, 테스트 실행 방법 등도 기억해둡니다.

반면 세션에서만 의미 있는 일시적인 정보는 저장하지 않습니다. “방금 작업 중인 파일 경로”나 “현재 디버깅 중인 에러 메시지” 같은 것은 메모리에 남지 않아요.

저장 위치와 디렉토리 구조

자동 메모리는 ~/.claude/projects/ 하위에 프로젝트별로 저장됩니다. 경로는 Git 저장소에서 파생되기 때문에 같은 저장소의 모든 워크트리와 하위 디렉토리가 하나의 메모리 디렉토리를 공유합니다.

~/.claude/projects/-Users-dale-work-my-project/memory/
├── MEMORY.md          # 인덱스 파일, 매 세션 자동 로드
├── debugging.md       # 디버깅 패턴 상세 노트
├── patterns.md        # 코드 패턴과 컨벤션
├── api-conventions.md # API 설계 관련 메모
└── ...                # Claude가 필요에 따라 만드는 주제 파일

디렉토리 이름이 좀 길죠? 프로젝트의 절대 경로에서 /를 -로 치환한 형태입니다. 터미널에서 직접 찾아갈 수도 있지만, /memory 커맨드를 쓰면 바로 열 수 있어서 경로를 외울 필요는 없습니다.

MEMORY.md: 메모리의 인덱스

MEMORY.md는 자동 메모리 시스템의 핵심입니다. Claude가 세션을 시작할 때 이 파일의 처음 200줄을 자동으로 읽어들입니다. 200줄이 넘는 내용은 시작 시 로드되지 않아요.

그래서 Claude는 MEMORY.md를 간결한 인덱스로 유지하려고 합니다. 핵심 정보의 요약만 담아두고, 상세한 내용은 별도 주제 파일로 분리하는 식이죠. 예를 들면 이런 모습입니다.

# 프로젝트 메모리

## 빌드 환경
- 패키지 매니저: bun (npm 아님)
- 테스트: `bun run test` (Playwright)
- 개발 서버와 테스트를 별도 터미널에서 실행

## 코드 패턴
- 상세 내용은 patterns.md 참조
- getAllTags() 유틸리티로 태그 추출 (인라인 패턴 금지)

## 디버깅 노트
- 상세 내용은 debugging.md 참조
- Astro 이미지 최적화는 src/assets/images/ 경로만 적용

주제 파일(debugging.md, patterns.md 등)은 세션 시작 시 로드되지 않습니다. Claude가 관련 작업을 하다가 필요할 때 직접 파일 도구로 읽어요. MEMORY.md에 “상세 내용은 debugging.md 참조”라고 적어둔 덕분에 어디를 찾아봐야 하는지 알 수 있는 겁니다.

메모리가 저장되는 시점

Claude가 메모리를 저장할 때 클로드 코드 인터페이스에 “Writing memory”라는 메시지가 나타납니다. 반대로 저장된 메모리를 읽을 때는 “Recalled memory”가 표시돼요.

저장이 일어나는 대표적인 상황이 있습니다.

개발자가 Claude의 행동을 교정했을 때입니다. “그거 말고 이렇게 해”라고 피드백을 주면, Claude는 그 교정 내용을 기억해둡니다. 같은 실수를 반복하지 않기 위해서요.

세션 중에 프로젝트의 중요한 패턴을 발견했을 때도 저장합니다. 코드베이스를 탐색하면서 “이 프로젝트는 에러 처리를 이런 방식으로 하는구나” 같은 패턴을 파악하면 메모해둡니다.

개발자가 명시적으로 “이거 기억해”라고 요청할 때도 물론 저장합니다. “항상 pnpm을 사용해, npm 말고”라고 말하면 메모리에 남겨요. 다만 이런 규칙성 지시는 CLAUDE.md에 넣는 게 더 확실합니다. 자동 메모리는 Claude가 관리하는 것이고 CLAUDE.md는 개발자가 직접 관리하는 것이라 안정성 면에서 차이가 있거든요.

메모리 직접 관리하기

자동 메모리 파일은 전부 일반 마크다운이라서 언제든 직접 열어서 수정하거나 삭제할 수 있습니다.

/memory 커맨드를 실행하면 현재 세션에 로드된 모든 CLAUDE.md와 규칙 파일 목록이 나타나고, 자동 메모리 폴더를 여는 링크도 제공됩니다. 파일을 선택하면 에디터에서 바로 열 수 있어요.

Claude에게 직접 요청할 수도 있습니다. “이 메모리 지워줘”, “메모리에서 빌드 관련 내용 업데이트해줘”라고 말하면 Claude가 메모리 파일을 수정합니다. “이걸 CLAUDE.md에 추가해줘”라고 명시하면 자동 메모리 대신 CLAUDE.md에 넣어주기도 해요.

주기적으로 메모리를 정리하는 것도 좋습니다. 프로젝트가 발전하면서 더 이상 맞지 않는 메모리가 쌓일 수 있거든요. 예를 들어 패키지 매니저를 npm에서 bun으로 바꿨는데 예전 메모리에 npm 관련 내용이 남아있으면 혼란을 줄 수 있습니다.

뭘 저장하고 뭘 저장하지 않을까

자동 메모리에 저장하기 좋은 정보와 그렇지 않은 정보가 있습니다.

저장하기 좋은 것들은 여러 세션에 걸쳐 안정적으로 유효한 정보입니다. 프로젝트의 빌드/테스트 명령어, 아키텍처 결정사항, 자주 빠지는 함정과 해결법, 개발자의 워크플로우 선호 같은 것들이요.

반면 저장하기 적합하지 않은 것들도 있습니다. 현재 작업 중인 태스크의 세부 사항, 진행 중인 디버깅의 임시 상태, 아직 검증되지 않은 추측, 한 번만 필요한 일회성 정보 같은 것들은 메모리에 남기지 않는 게 좋아요.

Claude는 보통 이 기준을 알아서 잘 지키지만, 가끔 불필요한 내용을 저장하거나 중요한 내용을 빠뜨릴 수 있습니다. 그럴 때는 /memory에서 직접 편집하면 됩니다.

자동 메모리 끄기

자동 메모리는 기본적으로 켜져 있습니다. 끄고 싶다면 세 가지 방법이 있어요.

/memory 커맨드에서 토글하는 게 가장 간단합니다. 설정 파일에서 비활성화할 수도 있고요.

{
  "autoMemoryEnabled": false
}

환경 변수로도 비활성화할 수 있습니다.

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

다만 자동 메모리를 끄더라도 CLAUDE.md는 정상적으로 동작합니다. 둘은 독립적인 시스템이니까요.

CLAUDE.md vs 자동 메모리, 어디에 넣을까

같은 정보라도 CLAUDE.md에 넣느냐 자동 메모리에 넣느냐에 따라 성격이 달라집니다.

팀 전체가 공유해야 하는 규칙은 CLAUDE.md에 넣으세요. 코딩 컨벤션, 브랜치 전략, PR 규칙 같은 것들이요. Git에 커밋되니까 팀원 모두에게 적용됩니다.

나만의 선호나 작업 패턴은 자동 메모리에 맡기는 게 편합니다. “이 프로젝트에서 자주 쓰는 디버깅 패턴”, “내가 선호하는 에러 메시지 스타일” 같은 것들은 Claude가 알아서 학습하도록 두면 돼요.

확실히 지켜져야 하는 규칙은 CLAUDE.md가 더 안정적입니다. 자동 메모리는 Claude가 관리하는 것이라 가끔 정리 과정에서 내용이 바뀔 수 있거든요. “절대 main 브랜치에 직접 푸시하지 마”처럼 반드시 지켜야 하는 규칙은 CLAUDE.md에 명시하는 게 좋습니다.

마치며

자동 메모리는 Claude와 오래 작업할수록 빛을 발합니다. 처음 몇 세션은 Claude가 프로젝트를 파악하느라 많이 저장하고, 시간이 지나면서 점점 안정적인 컨텍스트가 쌓이죠. 가끔 /memory에서 저장된 내용을 들여다보면서 틀린 정보는 고치고, 빠진 내용은 직접 추가해주면 됩니다.

CLAUDE.md 작성 가이드에서 명시적인 지시 파일을 잘 작성해두고, 자동 메모리가 세션마다 학습을 쌓아가면 Claude와의 협업이 세션을 거듭할수록 더 매끄러워질 겁니다. 세션을 넘나드는 작업 관리가 필요하다면 클로드 코드 Tasks도 참고해보세요.