버전 기준 명시
Claude Code Auto Memory, 써봤더니 이게 빠져있었습니다
Auto Memory가 생기면서 Claude Code가 알아서 기억한다는 말이 많이 퍼졌습니다. 그런데 공식 문서와 실사용 데이터를 같이 놓고 보니, “알아서”라는 단어 뒤에 숨어있는 조건이 꽤 많았습니다.
Auto Memory가 실제로 하는 일 — 공식 문서 원문 기준
Claude Code Auto Memory는 2026년 2월 26일 버전 2.1.59에서 정식 도입됐습니다. 공식 CHANGELOG에는 이렇게 적혀 있습니다. “Claude automatically saves useful context to auto-memory. Manage with /memory.” (출처: Anthropic GitHub claude-code CHANGELOG, 2026.02.26)
작동 방식은 간단합니다. 세션이 진행되는 동안 Claude가 “다음에도 쓸 것 같다”고 판단한 내용을 ~/.claude/projects/<project>/memory/MEMORY.md에 자동으로 기록합니다. 빌드 명령어, 반복되는 에러 패턴, 프로젝트별 API 컨벤션 같은 것들입니다. (출처: code.claude.com/docs/ko/memory)
이 파일은 다음 세션을 시작할 때 시스템 프롬프트에 자동으로 로드됩니다. “Recalled X memories (ctrl+o to expand)”라는 메시지가 보이면 그게 로드된 겁니다. 매 세션마다 같은 컨텍스트를 다시 설명하지 않아도 되니까, 실제로 꽤 편합니다.
💡 공식 문서와 실제 사용 흐름을 같이 놓고 보니, 로드 시점과 저장 경로가 생각과 달랐습니다.
MEMORY.md는 프로젝트 루트가 아니라 홈 디렉토리 아래 숨겨진 경로에 저장됩니다. git에 올라가지 않고, 팀원과 공유도 안 됩니다.
※ 이 글의 모든 수치·기능 설명은 Claude Code 2.1.59 기준입니다 (2026.02.26 출시).
MEMORY.md 200줄 한계, 생각보다 빠르게 찹니다
공식 문서에 딱 이렇게 나옵니다. “MEMORY.md는 200줄 제한이 있습니다. 200줄을 초과하면 Claude는 새 항목을 추가하는 대신 기존 파일을 요약·정리합니다.” (출처: code.claude.com/docs/ko/memory, 2026.03 기준) 이 말인즉, 200줄이 넘는 순간부터 오래된 기억은 조용히 압축되거나 잘립니다.
실제로 어느 정도 빠른지 계산해보면: 평균 한 항목이 3~4줄을 차지한다고 가정하면 최대 50~66개 항목이 저장 가능합니다. 매일 Claude Code를 쓰면서 패턴 2~3개씩 기록되면 이론상 3~4주 안에 한계에 도달할 수 있습니다. 한 달 후에는 초기 기억이 살아있다고 보장 못 한다는 뜻입니다.
Reddit 사용자들이 실제로 겪은 사례도 있습니다. 한 개발자는 CLAUDE.md에 명시한 “절대 금지” 정책이 세션이 길어지면서 컨텍스트 윈도우 밖으로 밀려나 같은 실수를 3개월 후에 반복했다고 공유했습니다. MEMORY.md에 중요한 정책을 중복 기록해야 이 문제를 막을 수 있습니다. (출처: Medium @baramboys0615, 2026.02.28)
| 항목 | CLAUDE.md | MEMORY.md (Auto) |
|---|---|---|
| 작성 주체 | 사람이 직접 작성 | Claude가 자동 기록 |
| 팀 공유 | git에 포함, 공유 가능 | 개인 로컬, 공유 안 됨 |
| 용량 제한 | 실질적 제한 없음 | 200줄 초과 시 자동 요약 |
| 저장 위치 | 프로젝트 루트 | ~/.claude/projects/…/memory/ |
| 로드 범위 | 서브디렉토리 계층 전체 | git repo 단위 |
* 위 표 수치는 code.claude.com/docs/ko/memory 기준
“AI가 기억한다”는 말이 절반만 맞는 이유
솔직히 말하면, Auto Memory를 처음 들었을 때 “이제 Claude가 뭔가 배우는구나”라고 생각했습니다. 그런데 실제로는 그렇지 않습니다. Brent Peterson이 2026년 2월 24일 Medium에 공유한 실사용 분석이 이 지점을 정확히 짚습니다.
그는 13개 프로젝트, 40개 이상의 커스텀 스킬, 수개월의 일일 사용 후 Auto Memory 파일을 열었을 때 딱 12줄만 들어 있었다고 했습니다. 명명 충돌 버그 수정 기록과 세션 아이덴티티 등록 규칙, 그게 전부였습니다. 기대했던 것과 달랐습니다. (출처: Medium @brentwpeterson, 2026.02.24)
💡 Auto Memory가 저장하는 건 “왜”가 아니라 “무엇”뿐입니다.
패턴이 발생한 맥락과 이유는 기록하지 않습니다. 규칙의 배경이 필요하면 CLAUDE.md나 MCP Memory에 직접 넣어야 합니다. Auto Memory만 믿으면 이유 없는 규칙만 남게 됩니다.
공식 문서에도 Auto Memory의 적용 범위를 명확히 선을 긋습니다. “안정적인 패턴·선호도·아키텍처는 저장하되, 세션 상태와 추측은 저장하지 않는다”는 지침이 시스템 프롬프트에 명시돼 있습니다. (출처: Reddit r/ClaudeAI 2.1.59 CHANGELOG 분석, 2026.02.26) 이게 의미하는 건 하나입니다. Auto Memory는 AI가 스스로 성장하는 게 아니라, 사람이 만들어온 설정 환경을 자동으로 캡처하는 도구입니다.
세 메모리 레이어가 자동으로 연결되지 않는다는 사실
Claude Code의 메모리 시스템은 사실 세 층으로 나뉩니다. CLAUDE.md(직접 규칙 작성), MCP Memory(구조화 지식 데이터베이스), Auto Memory(자동 패턴 캡처). 세 레이어가 함께 작동하는 것처럼 보이지만, 실제로는 서로 연결되어 있지 않습니다.
Brent Peterson은 이 문제를 직접 겪었습니다. 수개월 동안 학습 사례를 로그 파일과 MCP Memory에 기록해왔는데, Auto Memory는 그 파일들을 전혀 읽지 못했습니다. 로그 파일은 세션 시작 시 자동 로드가 안 되고, MCP Memory도 마찬가지입니다. 오직 MEMORY.md만 시스템 프롬프트에 자동으로 올라갑니다. (출처: Medium @brentwpeterson, 2026.02.24)
💡 공식 발표문과 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다.
- CLAUDE.md는 팀 공유 가능, git 관리 → Auto Memory는 개인 로컬 전용
- MCP Memory는 프로젝트 간 공유 가능 → Auto Memory는 git repo 단위로만 격리
- 세 레이어 중 세션 시작 시 자동 로드되는 건 CLAUDE.md + MEMORY.md 뿐
실용적인 해결책은 간단합니다. CLAUDE.md에 중요한 정책을 적고, 같은 내용을 MEMORY.md의 첫 50줄 안에 핵심 요약으로 중복 기록해두는 것입니다. 200줄 제한 때문에 MEMORY.md 후반부는 자동 요약될 수 있으니 앞쪽에 두는 게 안전합니다. 두 파일 간 배선은 수동으로 직접 해야 합니다.
켜두면 생기는 보안 리스크 — CVE 3건 공식 확인
Auto Memory가 편리한 건 맞지만, 동시에 Claude Code에는 공식 보안 취약점 3건이 2025~2026년 사이에 공개됐습니다. Check Point Research가 2026년 2월 25일 발표한 내용으로, 세 가지 모두 설정 파일을 통한 공격 경로와 관련됩니다. (출처: The Hacker News, 2026.02.25)
⚠️ 공식 CVE 목록 (출처: GitHub Anthropic Security Advisories)
- CVE 없음 (CVSS 8.7) — .claude/settings.json의 untrusted hooks로 코드 실행. 버전 1.0.87에서 수정 (2025.09)
- CVE-2025-59536 (CVSS 8.7) — MCP .mcp.json 설정으로 사용자 승인 없이 외부 도구 초기화. 버전 1.0.111에서 수정 (2025.10)
- CVE-2026-21852 (CVSS 5.3) — 악성 저장소 열기만 해도 Anthropic API 키 유출 가능. 버전 2.0.65에서 수정 (2026.01)
Auto Memory가 직접적인 공격 경로는 아니지만, 문제의 핵심은 같습니다. Claude Code는 설정 파일(.claude/settings.json, .mcp.json, MEMORY.md)을 신뢰하고 자동으로 실행합니다. Check Point의 표현을 빌리면 “설정 파일이 이제 실행 레이어의 일부”입니다. 신뢰하지 않는 저장소를 열 때 이 파일들이 포함되어 있으면 자동으로 로드됩니다.
현재 최신 버전(2.1.59+)은 위 취약점 3건 모두 패치된 상태입니다. 오래된 버전을 쓰고 있다면 즉시 업데이트하는 게 맞습니다. Claude Code 버전 확인은 터미널에서 claude --version으로 가능합니다.
끄거나 조정하는 방법 — 공식 설정 그대로
Auto Memory를 완전히 끄고 싶다면 공식 문서에 두 가지 방법이 나옵니다. 환경 변수를 쓰거나, settings.json에 직접 추가하거나입니다. (출처: code.claude.com/docs/ko/memory)
방법 1 — 환경 변수 (bashrc 또는 zshrc에 추가)
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
방법 2 — settings.json에 직접 설정
{ "autoMemoryEnabled": false }
저장 위치를 바꾸고 싶다면 autoMemoryDirectory 옵션으로 커스텀 경로를 지정할 수 있습니다. 기본 경로인 ~/.claude/projects/<project>/memory/ 대신 팀이 원하는 디렉토리로 변경 가능합니다. 단, 이 옵션은 .claude/settings.json(프로젝트 설정)에 넣어야 합니다. 개인 설정 파일(.claude/settings.local.json)에 넣으면 팀과 공유가 안 됩니다.
이미 쌓인 메모리를 보거나 수정하려면 세션 중에 /memory 명령어를 실행하면 됩니다. 시스템 에디터로 파일이 열리고, 원하는 항목을 직접 지우거나 편집할 수 있습니다. 파일이 단순 마크다운이라 접근이 어렵지 않습니다.
Q&A 5가지
마치며 — 총평
Claude Code Auto Memory는 분명히 편리한 기능입니다. 매 세션마다 같은 컨텍스트를 다시 설명하는 수고를 줄여줍니다. 막상 쓰면 다릅니다. 200줄 제한, 개인 로컬 전용 저장, 세 레이어 간 자동 연결 없음 — 이 세 가지를 모르고 쓰면 “왜 기억을 못 하지?”라고 의아할 순간이 반드시 옵니다.
중요한 규칙일수록 CLAUDE.md에 먼저 적고, 같은 내용을 MEMORY.md 앞쪽에 요약 형태로 중복 기록해두는 방식이 현재로선 가장 안정적입니다. Auto Memory는 그 위에 알아서 쌓이는 보조 레이어로 쓰는 게 현실적입니다. 그리고 Claude Code 버전은 항상 최신으로 유지하는 것, 공식 보안 권고에서 직접 확인할 수 있는 조건입니다.
본 포스팅 참고 자료
- Anthropic 공식 Claude Code 메모리 문서 — code.claude.com/docs/ko/memory
- Anthropic GitHub Claude Code CHANGELOG v2.1.59 — github.com/anthropics/claude-code
- The Hacker News — Claude Code 보안 취약점 CVE 3건 (2026.02.25) — thehackernews.com
- Brent Peterson, Medium — “Automatic Memory Is Not Learning” (2026.02.24) — medium.com/@brentwpeterson
- Reddit r/ClaudeAI — Claude Code 2.1.59 공식 CHANGELOG 분석 (2026.02.26) — reddit.com/r/ClaudeAI
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 본 포스팅은 Claude Code 2.1.59 기준(2026.02.26 출시)으로 작성됐으며, Anthropic의 업데이트에 따라 내용이 달라질 수 있습니다. 최신 정보는 공식 문서를 직접 확인하세요.
댓글 남기기