Claude Code v2.1.89 기준 (2026.04.01)
Claude Code Auto Memory 써봤더니
— 믿었던 게 달랐습니다
“이제 세션마다 같은 설명 안 해도 된다”는 말, 맞습니다. 근데 메모리가 200줄 넘으면 스스로 잘립니다. --bare 모드에서는 아예 꺼집니다. 공식 문서로 직접 확인한 내용들입니다.
Auto Memory가 생기기 전,
매 세션이 얼마나 불편했나
Claude Code는 세션이 시작될 때마다 컨텍스트를 완전히 초기화합니다. 어제 “이 프로젝트는 npm 대신 pnpm 써야 해”라고 50번 말했어도, 오늘 새 세션을 열면 Claude는 그 사실을 모릅니다. pnpm을 쓰라고 또 말해야 하고, 2-space indent 쓰라고 또 말해야 하고, API 핸들러는 src/api/handlers/에 두라고 또 말해야 합니다.
이 구조적 문제를 해결하기 위해 Anthropic은 두 가지 시스템을 제공합니다. 하나는 CLAUDE.md, 다른 하나가 이번에 살펴볼 Auto Memory입니다. Claude Code v2.1.74(2026년 3월 12일)에서 autoMemoryDirectory 설정이 공식 추가되며 Auto Memory 아키텍처가 확립됐고, v2.1.83에서 MEMORY.md 절단 기준이 강화됐습니다. 공식 문서에 딱 이렇게 나옵니다: “Auto memory lets Claude accumulate knowledge across sessions without you writing anything.”
들으면 편리해 보입니다. 근데 막상 써보면 다릅니다. 편하긴 한데, 동작 방식을 오해하면 메모리가 쌓인다고 믿다가 정작 중요한 맥락이 잘려 나가는 상황을 만납니다.
Auto Memory 작동 구조 —
공식 문서로 확인한 것들
Auto Memory는 기본값으로 켜져 있습니다. 꺼야 한다면 설정 파일에 "autoMemoryEnabled": false를 추가하거나, 환경변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 설정하면 됩니다. (출처: Anthropic 공식 문서, 2026.04.01 기준)
저장 위치는 ~/.claude/projects/<project>/memory/입니다. <project>는 git 저장소 기반으로 결정되기 때문에, 같은 레포 안에서 여러 워크트리나 서브디렉토리를 쓰더라도 메모리는 하나로 공유됩니다. 다른 PC나 클라우드 환경에는 동기화되지 않습니다. 로컬 전용입니다.
Claude는 세션 안에서 메모리를 저장할지 스스로 판단합니다. 매 세션마다 뭔가 쓰는 게 아닙니다. 공식 문서 원문은 이렇습니다: “Claude doesn’t save something every session. It decides what’s worth remembering based on whether the information would be useful in a future conversation.” 이 문장을 읽으면 “적당히 걸러서 저장한다”는 뜻인데, 역으로 말하면 Claude가 중요하다고 판단하지 않으면 저장 안 됩니다. 중요한 설정인데 안 저장될 수도 있다는 뜻입니다.
200줄 넘으면 잘린다 —
알고 쓰는 것과 모르고 쓰는 것
💡 공식 발표문과 실제 로드 동작을 같이 놓고 보니 이런 차이가 보였습니다 — 메모리가 “무한정 쌓인다”고 믿으면, 어느 시점 이후부터 맥락이 조용히 잘리고 있을 수 있습니다.
Auto Memory의 핵심인 MEMORY.md는 세션 시작마다 자동으로 로드됩니다. 그런데 로드되는 양에 상한이 있습니다. 공식 문서는 명확히 이렇게 밝히고 있습니다:
“The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation. Content beyond that threshold is not loaded at session start.”
(출처: Anthropic 공식 문서 — Claude Code Memory, 2026.04.01)
200줄 또는 25KB, 둘 중 먼저 도달하는 쪽에서 잘립니다. 이게 의미하는 건 간단합니다 — 메모리를 오래 쓸수록, Claude가 여러 프로젝트에 걸쳐 많은 내용을 축적할수록, MEMORY.md 하단에 기록된 내용은 세션 시작 시 읽히지 않을 수 있습니다. Claude가 “기억한다”고 저장해 뒀지만, 실제로는 그 기억이 열리지 않는 상태가 됩니다.
이 문제를 해결하는 방법은 두 가지입니다. 하나는 Claude가 자동으로 처리합니다 — 상세한 내용은 debugging.md, api-conventions.md 같은 토픽 파일로 분리해서 MEMORY.md는 인덱스 역할만 하게 됩니다. 다른 하나는 사람이 직접 합니다 — /memory 명령어로 저장된 파일 목록을 열어 불필요한 항목을 지우거나 줄이는 것입니다. Auto Memory 파일은 평문 마크다운이라 언제든 편집하거나 삭제할 수 있습니다.
v2.1.83 changelog에는 “Memory: MEMORY.md index now truncates at 25KB as well as 200 lines”라고 명시돼 있습니다. 이전에는 200줄 기준만 있었는데, 이 버전에서 25KB 기준이 추가됐습니다. 한 줄이 길수록(코드 스니펫 등) 줄 수가 적어도 25KB에 먼저 도달할 수 있으니 주의가 필요합니다. (출처: Claude Code Changelog v2.1.83, 2026.03.25)
CLAUDE.md와 Auto Memory,
역할이 반대입니다
💡 공식 문서 비교표를 보고 나서야 보였습니다 — 두 시스템은 “같은 기능의 두 가지 방식”이 아니라, 정보의 흐름 방향이 서로 반대입니다.
많은 글이 CLAUDE.md와 Auto Memory를 “둘 다 기억을 저장하는 방법”으로 설명합니다. 기능만 보면 비슷해 보이지만, 공식 문서의 비교표를 보면 방향이 다릅니다:
| 항목 | CLAUDE.md | Auto Memory |
|---|---|---|
| 누가 쓰나 | 사람(개발자) | Claude 자신 |
| 무엇을 담나 | 지침·규칙 | Claude가 배운 것들 |
| 범위 | 프로젝트·유저·조직 | 워킹트리 단위 |
| 용도 | 코딩 표준, 아키텍처 지침 | 빌드 명령어, 디버깅 패턴, 선호도 |
이 차이가 실전에서 뭘 바꾸냐 하면, “팀이 지켜야 할 규칙은 CLAUDE.md에, Claude가 자연스럽게 학습해야 할 패턴은 Auto Memory에” 라는 역할 분리가 생깁니다. CLAUDE.md에 “pnpm 쓸 것”을 명시하면 모든 세션에 강제됩니다. Auto Memory에 “이 프로젝트는 pnpm 씁니다”가 저장되면 Claude가 기억하지만, MEMORY.md가 꽉 차면 그 기억이 로드되지 않을 수도 있습니다. 절대 지켜야 할 규칙은 CLAUDE.md에 두는 이유가 여기 있습니다.
–bare 모드에서 메모리가
통째로 꺼지는 이유
Claude Code v2.1.81(2026년 3월 20일)에 --bare 플래그가 추가됐습니다. CI/CD 파이프라인이나 자동화 스크립트에서 Claude Code를 가볍게 호출할 때 쓰는 옵션인데, 이 모드에서는 Auto Memory가 완전히 비활성화됩니다.
“auto-memory fully disabled”
(출처: Claude Code Changelog v2.1.81, 2026.03.20)
당연하다면 당연한 설계입니다. --bare 모드는 OAuth와 키체인 인증이 비활성화되고 ANTHROPIC_API_KEY 또는 apiKeyHelper만 허용하는 헤드리스 모드입니다. 훅, LSP, 플러그인 동기화도 모두 스킵됩니다. 메모리 쓰기·읽기가 없으니 스크립트 실행이 깔끔해지지만, CI에서 Claude Code를 돌린다고 해서 프로젝트 메모리가 쌓이거나 누적된다는 기대를 하면 안 됩니다.
반대로 말하면, CI/CD에서 Claude Code를 자동화 목적으로 쓸 때 이전 인터랙티브 세션의 맥락이 우연히 섞여 들어오지 않는다는 뜻이기도 합니다. 자동화 환경에서는 오히려 이쪽이 안전합니다. --bare -p 조합은 API 요청까지 약 14% 빠릅니다. (출처: Claude Code Changelog v2.1.83, 2026.03.25)
메모리를 직접 관리하는
현실적인 방법
Auto Memory를 믿고만 있으면 안 되는 상황이 생깁니다. 세션에서 /memory 명령어를 치면 현재 로드된 CLAUDE.md 파일 목록과 Auto Memory 폴더 링크가 나옵니다. Auto Memory 토글도 여기서 켜고 끌 수 있습니다. 관리를 위해 주기적으로 확인하는 게 좋습니다.
CLI 인터페이스에서 “Writing memory” 또는 “Recalled memory” 문구가 보이면, Claude가 ~/.claude/projects/<project>/memory/에 실시간으로 읽거나 쓰고 있다는 신호입니다. 인터페이스 텍스트가 아니라 실제 파일 I/O가 발생하는 순간입니다.
메모리 저장 위치를 바꾸고 싶다면 autoMemoryDirectory 설정을 user 또는 local 설정에 추가하면 됩니다. 단, 프로젝트 공유 설정(.claude/settings.json)에서는 이 항목이 허용되지 않습니다. 공유 저장소를 통해 민감한 위치로 메모리 쓰기가 리다이렉트되는 것을 막기 위해서입니다. (출처: Anthropic 공식 문서)
v2.1.87에서는 MEMORY.md 내 파일명에 마우스를 올리면 하이라이트되고 클릭하면 파일이 열리는 기능이 추가됐습니다. 이제 메모리 파일이 어떻게 쌓이고 있는지 눈으로 확인하면서 관리할 수 있습니다. (출처: Claude Code Changelog v2.1.87, 2026.03.29)
📌 실전 관리 체크리스트
- 세션 안에서
/memory로 현재 로드된 파일 목록 주기적 확인 - MEMORY.md가 200줄 또는 25KB에 근접하면 불필요 항목 직접 삭제
- 절대 잊으면 안 되는 규칙은 CLAUDE.md에 별도 기재
- CI/CD에서 Claude Code 사용 시
--bare모드로 메모리 간섭 차단 - 멀티 워크트리 환경에서는 같은 git 레포면 메모리가 공유된다는 점 인지
Q&A
마치며
Claude Code Auto Memory는 분명히 편합니다. 세션마다 같은 설명을 반복하는 불편함이 줄어드는 건 사실입니다. 근데 “메모리가 무한정 쌓인다”는 착각으로 쓰면, 어느 순간 MEMORY.md 200줄/25KB 상한에 걸려 정작 중요한 맥락이 읽히지 않는 상황이 옵니다.
솔직히 말하면, 지금 Auto Memory의 가장 큰 실용적 가치는 “Claude가 스스로 배운다”는 자율성보다는, 개발자가 /memory로 주기적으로 감사하고 관리하는 워크플로우를 만들었을 때 발휘됩니다. 자동이라는 말에 완전히 기대면 오히려 허점이 생깁니다.
v2.1.87에서 MEMORY.md 파일명 클릭 기능이 추가됐고, v2.1.89에서는 메모리 관련 LRU 캐시 누수도 수정됐습니다. 아직 빠르게 업데이트되는 기능입니다. 공식 문서와 changelog를 주기적으로 확인하는 게 가장 정확합니다.
본 포스팅 참고 자료
- Anthropic 공식 Claude Code Memory 문서 — https://docs.anthropic.com/en/docs/claude-code/memory
- Claude Code 공식 Changelog (v2.1.74~v2.1.89) — https://docs.anthropic.com/en/docs/claude-code/changelog
- Claude Code 2026년 3월 업데이트 총정리 — dev.to (2026.03.21)
본 포스팅은 Claude Code v2.1.89 기준(2026.04.01)으로 작성됐습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 최신 내용은 Anthropic 공식 문서에서 확인하시기 바랍니다.
댓글 남기기