저는 Claude Code를 쓰다가 가끔 이렇게 말합니다.

너의 메모리를 최신화해줘.

프로젝트를 오래 다루다 보면 예전에 남긴 메모가 지금의 코드와 어긋날 때가 있습니다. 파일은 없어지고, 명령은 바뀌고, 작업 절차도 달라집니다. 하지만 그때마다 관련 메모리가 모두 함께 바뀌는 것은 아닙니다.

그렇다고 auto memory에 큰 문제가 있다는 뜻은 아닙니다. Claude는 필요한 내용을 알아서 남기고, 바뀐 사실을 알게 되면 메모리를 고치기도 합니다. 다만 모든 메모리가 늘 현재 상태를 반영하지는 않습니다.

그래서 가끔 지금의 프로젝트와 기억을 맞춰 보게 합니다.

이 글의 내용은 2026년 7월 27일 Windows 11에서 확인했습니다. Claude Code v2.1.220을 claude -p 자동 실행으로 구동했습니다. 공식 문서도 같은 날 열람한 내용을 기준으로 삼았습니다.

auto memory는 Claude가 남기는 작업 노트다

auto memory는 Claude가 일하면서 스스로 적어 두는 노트입니다. 무엇을 남길지도 Claude가 정합니다.

문서에 따르면 Claude는 매 세션마다 무언가를 저장하지 않습니다. 다음 대화에서도 쓸모가 있을지를 보고 남길 내용을 정합니다. auto memory는 기본으로 켜져 있으며 설정에서 끌 수 있습니다.

저장소마다 메모리 폴더가 하나씩 생깁니다. 그 안에는 목차인 MEMORY.md와 여러 주제별 파일이 들어 있습니다. 모두 평범한 마크다운 파일입니다. 사람이 직접 수정할 수도 있습니다. Claude에게 원하는 내용을 메모리에 저장하거나, 필요 없는 내용을 지워 달라고 할 수도 있습니다. 세션 안에서는 /memory로 이 폴더를 엽니다.

코딩할 때만 쓰이는 기능도 아닙니다. 자료를 정리하는 폴더에서는 “표는 이 형식으로 만든다” 같은 규칙도 알아서 남깁니다.

고쳐 쓰는 동작도 확인했습니다. 저장된 사실이 바뀌었다고 알려 주자 Claude는 메모리를 다시 썼습니다. 파일에는 작성 시각도 자동으로 들어갔습니다. 이 시각 기록은 v2.1.214 이상에서 동작합니다.

낡은 기억을 실제로 쓰게 해봤다

낡은 기억을 실제로 쓰게 하면 어떻게 되는지 확인했습니다.

작은 저장소를 만들고 CLAUDE.md에 두 가지 규칙을 적었습니다.

테스트는 node test.js로 실행한다.

CHANGELOG.md는 릴리스 스크립트가 만드니 직접 수정하지 않는다.

이 규칙은 세션이 시작될 때마다 Claude에게 전달됩니다.

그다음 규칙과 어긋나는 메모리 두 개를 넣었습니다.

하나는 테스트 명령에 관한 메모리였습니다. node tests/run.js로 실행한다고 적었습니다. 하지만 저장소에는 그런 경로가 없습니다.

다른 하나는 작업 절차에 관한 메모리였습니다. 코드를 고치면 CHANGELOG.md 맨 위에 한 줄을 추가한다고 적었습니다.

이 상태에서 테스트 케이스를 하나 추가하고 통과하는지 확인해 달라고 했습니다.

Claude는 두 메모리를 모두 걸러냈습니다.

없는 경로를 가리키던 메모리 파일은 지웠습니다. 목차에서도 해당 항목을 뺐습니다. CHANGELOG.md를 고치라는 메모리는 따르지 않았습니다. 파일도 건드리지 않았습니다.

대신 목차 항목 옆에 “프로젝트 CLAUDE.md와 충돌 — 사용자 확인 대기”라고 표시했습니다. 그리고 이 메모리를 지울지 물었습니다. 저장소에 저장된 규칙이 개인 메모리보다 앞서기 때문이라고 설명했습니다.

다만 정리하는 방식은 매번 같지 않았습니다.

다른 세션에서는 빌드 명령이 바뀌었다고 알려 주었습니다. Claude는 새 메모리를 만들고 목차에서 옛 항목을 뺐습니다. 하지만 옛 파일까지 지우지는 않았습니다. 그 안에 “이 메모는 폐기됐다”, “이 파일은 삭제 대상이다”라고 적어 두었습니다.

메모리를 지울지, 표시만 남길지는 그때의 판단에 달려 있었습니다.

쓰지 않은 기억은 갱신할 기회가 없다

앞의 실험에서는 쓰려는 기억을 현재 규칙과 대조했습니다. 아직 쓸 일이 없는 기억에는 그런 기회가 없습니다.

실험에 사용한 저장소에도 그런 메모리가 하나 있었습니다. 한 달 전에 만들어진 메모였습니다. 두 주 전에 없어진 파일에 무언가를 기록하라는 내용이었습니다.

그사이 프로젝트 규칙은 정반대로 바뀌었습니다. CLAUDE.md가 불러오는 규칙 문서에도 새 내용이 적혀 있었습니다. 그래도 옛 메모리는 그대로 남아 세션에 들어왔습니다.

반대 규칙이 없어서 남은 것은 아닙니다. 아직 그 메모리를 써야 할 작업이 없었기 때문입니다. 현재 상태와 대조할 순간도 오지 않았습니다.

메모리는 쓰인 날의 관측입니다. 이후 프로젝트에서 벌어진 변화가 대화에 들어오지 않으면 메모리까지 전달되지 않습니다. 이럴 때 한 번씩 최신화해 달라고 말하면 됩니다.

오래된 메모리에는 나이 경고가 붙는다

Claude Code에도 오래된 메모리를 알아차리는 장치는 있습니다. 오래된 메모리 파일을 읽으면 결과 뒤에 이런 경고가 붙습니다.

This memory is 44 days old. Memories are point-in-time observations, not live state — claims about code behavior or file:line citations may be outdated. Verify against current code before asserting as fact.

이 메모리는 44일 됐다는 내용입니다. 메모리는 한 시점의 관측이지 현재 상태가 아니라고 설명합니다. 코드 동작이나 파일·줄 인용은 낡았을 수 있으니, 현재 코드와 대조하라고 합니다.

관측에서는 0일 된 파일에 경고가 붙지 않았습니다. 2일 된 파일부터는 경고가 붙었습니다.

이 동작은 공식 문서의 메모리 페이지와 오류 페이지에 나오지 않습니다. CHANGELOG 전문에도 없습니다. 따라서 이 버전에서 관측한 동작으로만 봐야 합니다. 앞으로도 같을지는 알 수 없습니다.

경고는 파일 수정 시각을 기준으로 삼는다

문서는 메모리 파일에 작성 시각을 남긴다고 설명합니다. 파일이 frontmatter로 시작하면 Claude가 다시 쓸 때 시각이 들어갑니다. frontmatter가 없는 파일에는 새로 만들어 넣지 않습니다.

하지만 나이 경고는 파일 안의 작성 시각을 보지 않았습니다.

파일 수정 시각을 각각 0일, 2일, 7일, 21일 전으로 설정했습니다. 그런 다음 Claude에게 읽게 했습니다. 0일 된 파일에만 경고가 없었습니다.

이번에는 파일 안의 작성 시각을 68일 전으로 두었습니다. 파일 수정 시각만 당일로 맞추자 경고가 붙지 않았습니다.

관측한 기준은 파일 수정 시각이었습니다.

메모리 폴더를 복사하거나 파일을 손으로 고치면 수정 시각이 바뀝니다. 그러면 내용이 오래됐어도 경고가 사라질 수 있습니다. 경고만 보고 메모리의 나이를 판단하기는 어려운 이유입니다.

메모리는 낡기도 하고 쌓이기도 한다

메모리 폴더 전체가 세션마다 들어오는 것은 아닙니다.

세션이 시작될 때 불러오는 것은 목차 파일의 첫 200줄 또는 25KB까지입니다. 주제별 파일은 처음부터 들어오지 않습니다. Claude가 필요할 때 열어 읽습니다.

파일이 늘어난다고 세션 시작 비용이 그만큼 늘지는 않습니다. 대신 목차인 MEMORY.md는 한도 안에서 관리해야 합니다.

목차가 한도에 가까워지면 Claude에게 정리 지시가 전달됩니다. 193줄짜리 목차에 항목을 더하자 이런 지시가 따라왔습니다.

The memory index at MEMORY.md is 193 lines, approaching the 200-line read limit. Compact it to under 140 lines now: keep one line per entry, move detail into topic files, and merge or drop stale entries.

한 항목을 한 줄로 유지하고 자세한 내용은 주제별 파일로 옮기라는 지시입니다. 낡은 항목은 합치거나 버리라고도 합니다.

Claude는 이 지시에 따라 주제별 파일 190개를 한 파일로 합쳤습니다. 193줄이던 목차는 4줄로 줄였습니다. 참조가 끊긴 파일 190개를 지울지는 사용자에게 물었습니다.

목차 한도를 넘으면 뒤쪽 항목이 빠진다

정리하지 않은 채 한도를 넘기면 어떻게 되는지도 확인했습니다.

목차를 206줄로 만들었습니다. 세 번째 줄에는 낡은 배포 명령을 넣었습니다. 마지막 줄에는 그 명령을 폐기하는 최신 항목을 넣었습니다.

파일을 확인할 도구를 모두 막은 뒤 배포 명령을 물었습니다. Claude는 낡은 명령을 답했습니다. 마지막에 적은 최신 항목은 존재조차 알지 못했습니다.

목차를 앞에서부터 불러오기 때문입니다. 한도를 넘은 부분은 뒤에서 잘립니다. 새 항목이 아래에 붙는 구조라면 최근에 적은 기억부터 세션에서 빠집니다. 오래된 기억은 남고 새 결정은 보이지 않게 됩니다.

파일을 확인할 도구를 다시 열어 주고 같은 질문을 했습니다. 결과는 달라지지 않았습니다. Claude는 저장소를 조사했지만 메모리 폴더의 잘린 항목까지 찾지는 않았습니다. 목차에 남은 낡은 항목을 근거로 답했습니다.

Claude가 이 상태를 아예 모르는 것은 아닙니다. 잘린 목차 뒤에는 경고가 함께 들어옵니다.

WARNING: MEMORY.md is 206 lines (limit: 200). Only part of it was loaded. Keep index entries to one line under ~200 chars; move detail into topic files.

한도를 처음 넘는 순간에도 오류가 전달됩니다. 다만 문서가 밝히듯 사용자 화면에 배너로 뜨지는 않습니다. Claude에게만 전달됩니다. 세션 시작 경고도 마찬가지입니다.

사용자 화면에서는 아무 일도 일어나지 않은 것처럼 보입니다. v2.1.210 이전에는 그 신호조차 없었습니다. 다음 로드에서 한도를 넘은 부분이 조용히 잘렸습니다.

크기 한도는 실제 파일 용량이 아니라 글자 수를 기준으로 셉니다.

26,275자짜리 목차에는 25.7KB (limit: 24.4KB)라는 경고가 붙었습니다. 25.7에 1024를 곱하면 글자 수와 거의 맞아떨어집니다. 같은 파일의 UTF-8 용량은 59,763바이트였습니다.

한글이라고 용량 때문에 불리해지지는 않습니다. 실제 한도는 약 25,000자입니다.

그래서 가끔 메모리를 최신화한다

auto memory는 현재 상태를 실시간으로 보여주는 데이터가 아닙니다. Claude가 이전 작업에서 남긴 노트입니다. 프로젝트가 바뀌면 일부 내용이 낡을 수 있고, 항목이 많아지면 목차도 정리가 필요합니다.

Claude Code에는 이를 다루는 장치가 있습니다. 오래된 파일에는 경고를 붙입니다. 목차가 길어지면 압축을 지시합니다. 현재 규칙과 어긋나는 기억을 쓰려 할 때는 걸러내기도 합니다.

그럼에도 가끔은 먼저 정리를 맡깁니다.

너의 메모리를 최신화해줘.

이 한마디가 모든 주제별 파일을 빠짐없이 검사한다고 확인한 것은 아닙니다. 중요한 규칙을 바꾼 날에는 무엇이 달라졌는지도 함께 알려 주는 편이 분명합니다.

빌드 명령이 바뀌었어. 현재 저장소와 관련 메모리를 대조해서 최신화해줘.

직접 확인하고 싶을 때는 /memory를 열면 됩니다. 모두 마크다운이라 별도의 도구도 필요하지 않습니다.

auto memory가 특별히 위험해서 하는 일은 아닙니다. 오래 쓰는 작업 노트라면 가끔 펼쳐 보고, 지금 하는 일과 맞춰 볼 때가 있는 것뿐입니다.