Claude Code 메모리 시스템 활용

들어가며

21차시에서는 CLAUDE.md를 다뤘다. 사용자가 직접 적어두는 영속적 지시 — 빌드 명령, 코딩 컨벤션, 폴더 구조 같은 것들이다.

그런데 Claude Code에는 또 한 가지 메모리가 있다. Claude가 스스로 쓰는 Auto memory다. 대화 중에 “앞으로 이 프로젝트에서는 pnpm만 써줘” 라고 말하면, Claude는 이 선호를 기억해두고 다음 세션에서도 반영한다. 사용자가 같은 정정을 반복하지 않아도 되게 한다.

이번 차시는 Claude Code의 메모리 시스템 전체를 정리한다. 두 메모리(CLAUDE.md와 Auto memory)가 어떻게 다른지, Auto memory는 어디에 어떤 구조로 저장되는지, 로드에 걸리는 200줄/25KB 한계는 왜 있는지, 켜고 끄는 방법과 저장 위치 바꾸는 방법은 무엇인지, /compact 이후 어떤 게 살아남고 어떤 게 사라지는지, 서브에이전트도 자신만의 메모리를 쓸 수 있다는 점까지 다룬다.

Auto memory는 Claude Code v2.1.59 이상에서 사용할 수 있다. claude --version으로 확인한다.

두 가지 메모리

Claude Code의 메모리는 두 축으로 구성된다. 작성 주체와 로드 방식이 다르다.

두 시스템 모두 매 세션 시작 시 컨텍스트로 로드된다. 둘 다 강제 설정이 아니라 컨텍스트로 취급되기 때문에, 구체적이고 간결할수록 Claude가 잘 따른다.

CLAUDE.md가 “내가 매번 설명하기 귀찮은 것들을 미리 적어두는 곳”이라면, Auto memory는 “Claude가 대화 중에 배운 걸 다음 대화를 위해 적어두는 곳”이다. 서로 대체재가 아니라 보완재다.

Auto memory란

Auto memory는 Claude가 사용자의 정정과 선호를 기반으로 스스로 메모를 적는 시스템이다. 빌드 명령, 디버깅에서 얻은 인사이트, 아키텍처 노트, 코드 스타일 선호, 반복되는 워크플로 습관 같은 것들이 저장된다.

Claude가 매 세션에서 뭔가를 기록하는 건 아니다. “미래 대화에서 유용할지”를 판단해서 저장할 만한 가치가 있을 때만 기록한다.

세션 중에 다음 같은 문구가 뜬다면 실제 동작 중이라는 뜻이다.

• Writing memory — 현재 Claude가 메모리 파일에 쓰는 중
• Recalled memory — Claude가 메모리 파일을 읽어서 참조하는 중

무엇이 어디에 저장되는가

각 프로젝트는 별도의 메모리 디렉토리를 가진다. 기본 위치는 다음과 같다.

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

<project> 부분은 git 저장소에서 파생된다. 같은 저장소의 모든 worktree와 하위 디렉토리가 하나의 auto memory 디렉토리를 공유한다. git 저장소 밖에서 Claude Code를 실행하면 프로젝트 루트가 기준이 된다.

Auto memory는 머신-로컬이다. 머신 간, 클라우드 환경 간 공유되지 않는다. Git으로 push해서 팀원과 공유할 수도 없다. 이게 팀 공유가 필요한 지시는 CLAUDE.md에 두어야 하는 이유다.

MEMORY.md 인덱스와 토픽 파일

메모리 디렉토리 안은 MEMORY.md 인덱스 파일과 여러 개의 토픽 파일로 구성된다.

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 간결한 인덱스, 매 세션에 로드
├── debugging.md       # 디버깅 패턴 상세 노트
├── api-conventions.md # API 설계 결정
└── ...                # Claude가 만든 기타 토픽 파일

MEMORY.md는 어떤 토픽 파일이 있는지 요약하는 인덱스 역할을 한다. 상세 내용은 별도 파일로 분리된다. Claude는 세션 내내 이 디렉토리의 파일을 읽고 쓴다. MEMORY.md는 이 구조의 진입점이다.

200줄/25KB 로드 한계

매 세션 시작 시 로드되는 건 MEMORY.md의 첫 200줄 또는 첫 25KB, 먼저 오는 것까지만이다. 초과하는 부분은 세션 시작 시점에 로드되지 않는다. 그래서 Claude는 MEMORY.md를 간결하게 유지하고, 상세 노트는 토픽 파일로 분리하도록 설계됐다.

MEMORY.md 앞 200줄 또는 25KB → 시작 시 로드
토픽 파일 (debugging.md, api-conventions.md 등) → 필요할 때 on-demand

이 제한은 MEMORY.md에만 적용된다. CLAUDE.md 파일은 길이와 무관하게 전체 로드된다(단, 21차시에서 봤듯 200줄 이하로 유지하는 게 준수율에 좋다).

토픽 파일은 Claude가 세션 도중 필요하다고 판단할 때 Read 도구로 읽는다. 그래서 디버깅 이력이나 예전 결정 같은 긴 노트를 많이 쌓아두어도 매 세션의 시작 컨텍스트를 무겁게 만들지는 않는다.

활성화와 비활성화

Auto memory는 기본값이 on이다. 끄는 방법은 세 가지가 있다.

1. /memory 명령어에서 토글

세션 안에서 /memory를 실행하면 auto memory 토글 UI가 나온다. 가장 빠른 방법이다.

> /memory

2. 설정 파일

프로젝트 설정에 다음을 추가한다.

{
  "autoMemoryEnabled": false
}

3. 환경 변수

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

반대로 점진적 롤아웃 중 강제로 활성화하려면 CLAUDE_CODE_DISABLE_AUTO_MEMORY=0으로 둔다.

저장 위치 바꾸기

기본 경로(~/.claude/projects/<project>/memory/) 말고 다른 곳에 저장하고 싶다면 autoMemoryDirectory 설정을 사용한다.

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

이 설정은 user, local, policy 레이어에서만 허용된다. project settings(.claude/settings.json)에서는 거부된다. 공유 프로젝트가 민감한 위치로 메모리 쓰기를 리다이렉트하는 것을 막기 위한 보안 장치다.

예를 들어 .claude/settings.json에 autoMemoryDirectory를 넣어서 커밋하면 Claude Code가 무시한다. 개인 머신에만 적용하려면 .claude/settings.local.json이나 ~/.claude/settings.json에 둬야 한다.

/memory 명령어

21차시에서 /memory를 “어떤 파일이 로드됐는지 확인하는 용도”로 짧게 소개했다. 실제로는 네 가지 일을 한다.

1. 로드된 파일 목록 표시 — 현재 세션의 모든 CLAUDE.md, CLAUDE.local.md, rules 파일
2. Auto memory 토글 on/off
3. Auto memory 폴더 열기 링크 — ~/.claude/projects/<project>/memory/ 바로 열기
4. 파일 편집 — 목록에서 선택하면 에디터로 열기

CLAUDE.md가 안 먹는 것 같을 때도 /memory로 먼저 점검하고, Claude가 뭘 기억했는지 확인하고 싶을 때도 /memory로 폴더 열기 링크를 따라가서 파일을 직접 읽는다. auto memory 파일은 모두 plain markdown이라 읽기/편집/삭제가 자유롭다.

”기억해줘” vs “CLAUDE.md에 추가해줘”

대화 중에 “기억해줘” 류의 지시를 하면 Claude는 기본적으로 auto memory에 저장한다. 아래 두 경우 모두 auto memory로 간다.

> 앞으로 이 프로젝트에서는 항상 pnpm을 써줘
> API 테스트는 로컬 Redis가 필요하다는 걸 기억해둬

이게 CLAUDE.md에 들어가야 할 성질인 경우(팀 공유, 팀 컨벤션) 명시적으로 말해야 한다.

> 이걸 CLAUDE.md에 추가해줘

또는 /memory에서 CLAUDE.md 파일을 열어 직접 편집한다. 판단 기준은 단순하다.

• 팀이 공유해야 하는 규칙 → CLAUDE.md (Git에 커밋)
• 내가 반복하지 않으면 되는 것, 머신-로컬로 충분한 것 → Auto memory
• 본인만 쓰지만 규칙에 가까운 것 → CLAUDE.local.md 또는 ~/.claude/CLAUDE.md

/compact 이후 무엇이 살아남는가

21차시에서 /compact 후 프로젝트 루트 CLAUDE.md가 디스크에서 재주입된다고 간단히 언급했다. 실제 동작은 항목마다 다르다.

핵심은 두 가지다.

1. CLAUDE.md와 auto memory는 압축을 넘어 살아남는다. Claude가 메모리에 저장해둔 선호나 CLAUDE.md에 적힌 규칙은 /compact 후에도 유지된다.
2. 대화 중에만 준 지시는 사라질 수 있다. 영속시키고 싶으면 “CLAUDE.md에 추가해줘”나 “기억해줘”로 메모리 중 하나에 저장하도록 해야 한다.

서브에이전트 persistent memory

서브에이전트도 자신만의 메모리를 유지할 수 있다. 예를 들어 코드 리뷰어 서브에이전트가 프로젝트의 반복 이슈를 축적해두면, 다음 리뷰에서 그 지식을 바탕으로 더 정확한 피드백을 준다.

서브에이전트 정의 파일(.claude/agents/code-reviewer.md 같은)에 memory 필드를 추가한다.

---
name: code-reviewer
description: 코드 품질과 모범 사례 리뷰
memory: project
---

당신은 코드 리뷰어입니다. 리뷰하면서 발견한 패턴, 컨벤션, 반복 이슈를
agent memory에 업데이트하세요.

스코프는 세 가지다.

메인 Claude의 auto memory와 달리 서브에이전트 메모리는 project 스코프를 쓰면 Git으로 팀 공유가 가능하다. 정적 문서로 남기기엔 아쉬운 “경험”을 축적하는 용도로 유용하다.

메모리가 활성화되면 서브에이전트의 시스템 프롬프트에 메모리 디렉토리를 읽고 쓰는 지침이 자동으로 포함된다. MEMORY.md의 앞 200줄/25KB도 메인 Claude와 같은 규칙으로 로드된다. Read, Write, Edit 도구도 자동으로 활성화된다.

Auto memory는 v2.1.59 이상에서 도입됐다. 서브에이전트 persistent memory 기능도 최신 버전에서 사용 가능하다.

메모리 감사와 편집

Auto memory는 plain markdown 파일이다. 언제든 직접 열어서 읽거나, 수정하거나, 지울 수 있다.

# 기본 경로로 직접 열기
open ~/.claude/projects/<project>/memory/

또는 /memory로 세션 안에서 폴더 링크를 연다. 세 가지 상황에서 유용하다.

1. 민감한 정보가 들어갔는지 점검

의도치 않게 로컬 DB 자격 증명이나 API 키를 대화에서 언급했다면, auto memory에 저장됐을 수 있다. MEMORY.md나 토픽 파일을 직접 열어서 검토한다.

2. 잘못된 지식이 축적됐을 때

Claude가 어떤 것을 잘못 배웠다면 (예: 실제로는 사용하지 않는 라이브러리를 사용한다고 기록) 해당 메모리 파일을 편집해서 수정한다. 다음 세션부터 올바른 지식을 쓴다.

3. 프로젝트 변경 후 초기화

프로젝트의 기술 스택을 크게 바꿨거나 Claude가 저장한 디버깅 노트가 쓸모 없어졌을 때는 디렉토리 전체를 지워도 된다. Claude가 다시 처음부터 쌓는다.

트러블슈팅

원하지 않는 것이 저장됐다

/memory로 auto memory 폴더를 열고 해당 파일을 편집 또는 삭제한다. Auto memory 전체가 맘에 안 들면 autoMemoryEnabled: false로 끄고 필요한 지시만 CLAUDE.md로 옮긴다.

Auto memory가 동작하지 않는다

다음 순서로 점검한다.

1. 버전 확인 — claude --version으로 v2.1.59 이상인지 확인. 이전 버전에는 기능 자체가 없다
2. /memory — 세션 안에서 토글이 on인지 확인
3. 환경 변수 — echo $CLAUDE_CODE_DISABLE_AUTO_MEMORY로 1이 아닌지 확인
4. 설정 — autoMemoryEnabled가 false로 설정돼 있지 않은지 확인
5. 폴더 접근 권한 — ~/.claude/projects/에 쓰기 권한이 있는지

팀원과 auto memory를 공유하고 싶다

Auto memory는 머신-로컬이라 공유가 불가능하다. 팀 공유가 필요한 내용은 CLAUDE.md에 옮긴다.

> 방금 기억한 빌드 명령을 CLAUDE.md에도 추가해줘

또는 서브에이전트 메모리의 project 스코프를 쓰면 .claude/agent-memory/가 Git 트래킹 대상이 된다. 다만 이건 해당 서브에이전트 전용이고 메인 Claude의 컨텍스트에 들어가진 않는다.

CLAUDE.md와 auto memory 우선순위가 궁금하다

둘은 우선순위 관계가 아니라 보완 관계다. 공식 문서는 두 시스템이 모두 매 세션 시작 시 로드되며 함께 컨텍스트를 구성한다고 명시한다. 같은 주제에 대해 두 메모리가 충돌하는 지시를 담고 있다면 Claude는 임의로 하나를 고를 수 있으므로, 정기적으로 /memory로 양쪽을 검토해서 충돌을 제거한다.

정리

핵심 요점

1. Claude Code의 메모리는 두 축: 사용자가 쓰는 CLAUDE.md와 Claude가 쓰는 Auto memory. 서로 대체재가 아니라 보완재

2. Auto memory 저장 위치: ~/.claude/projects/<project>/memory/ — <project>는 git 저장소 기준. 머신-로컬이라 팀 공유 불가

3. MEMORY.md와 토픽 파일 구조: MEMORY.md는 인덱스, 상세 노트는 토픽 파일로 분리. MEMORY.md 앞 200줄/25KB만 세션 시작 시 로드, 토픽 파일은 on-demand

4. 활성화/비활성화 3가지 방법: /memory 토글, autoMemoryEnabled 설정, CLAUDE_CODE_DISABLE_AUTO_MEMORY 환경 변수

5. 저장 위치 변경: autoMemoryDirectory는 user/local/policy만 허용, project settings 거부 (보안)

6. “기억해줘” vs “CLAUDE.md에 추가해줘”: 팀 공유 필요하면 CLAUDE.md, 내 머신만이면 auto memory

7. /compact 이후: 프로젝트 루트 CLAUDE.md와 auto memory는 재주입, 중첩/경로 스코프와 대화 지시는 로스트

8. 서브에이전트 persistent memory: memory: user/project/local 필드로 활성화. project 스코프는 Git 공유 가능

9. 메모리 감사: plain markdown이라 직접 열어서 읽기/편집/삭제 자유. 민감 정보나 잘못된 학습은 수동으로 정리

확인해볼 링크

• 공식 문서: How Claude remembers your project (Memory)
• 공식 문서: Commands reference
• 공식 문서: Context window
• 공식 문서: Subagents
• 공식 문서: Environment variables

다음 단계

23차시에서는 .claude/rules/ 디렉토리로 규칙을 토픽별·경로별로 쪼개는 방법을 다룬다. CLAUDE.md가 너무 커졌을 때 어떻게 나눠두면 준수율이 유지되는지, paths: 프론트매터로 특정 파일을 만질 때만 로드되게 하는 방법, @ 멘션으로 문서를 참조하는 패턴, 그리고 팀 규칙 라이브러리를 공유하는 법까지 살펴본다.

참고 자료

• How Claude remembers your project (Memory)
• Commands reference
• Context window
• Create custom subagents
• Environment variables
• Settings