메모를 열심히 쌓을수록 AI 가 더 많이 기억할 거라고 생각했습니다.
그런데 어느 날 보니 쌓은 메모의 뒷부분은 세션을 열어도 아예 읽히지 않고 있었습니다. 오류도 경고도 없이요.
이번 포스팅에서는 Claude Code 메모리 색인 파일이 한도를 넘었을 때 무슨 일이 생겼는지, 그리고 그 문제를 세션 시작 훅으로 어떻게 돌렸는지 풀어 보도록 하겠습니다.
Claude Code 메모리는 색인 파일 하나로 시작합니다
Claude Code 의 파일 메모리는 프로젝트마다 폴더 하나에 쌓입니다.
사실 하나를 파일 하나에 적고, 그 목록을 MEMORY.md 라는 색인 파일에 한 줄씩 답니다.
세션을 열 때마다 따라오는 건 이 색인 파일입니다. 개별 메모 파일은 필요할 때 따로 열어 봅니다.
그러니 색인이 곧 에이전트가 세션 첫머리에 아는 전부입니다.
2026년 9월, 색인이 한도를 넘어 있었습니다
기억 서버를 설계하던 2026-09-11 에 현재 상태를 점검하다가 발견했습니다.
메모리가 60여 건 쌓여 있었고, 색인 파일이 한도(24.4KB)를 넘어 일부만 로드되는 상태였습니다.
넘친 부분은 조용히 빠집니다. 세션은 정상으로 열리고, 에이전트도 평소처럼 대답합니다.
빠진 쪽이 하필 최근에 추가한 메모라면, 가장 최신 사정을 모르는 에이전트와 일하게 됩니다.
제가 가장 쓰게 느낀 대목은 이것입니다. 메모를 적는 일에만 신경 썼고, 그 메모가 실제로 읽히는지는 확인한 적이 없었습니다.
⚠️ 메모리 색인은 쌓는다고 다 읽히지 않습니다. 길이에 한도가 있고, 넘친 부분은 아무 표시 없이 빠집니다.
해결 하나, 색인은 한 줄 요약으로만 씁니다
색인 한 줄에는 제목과 "언제 이 파일을 열어야 하는지" 만 적습니다.
- [화면 멈춤 함정 3종](ui-render-traps.md) — 15만 행 innerHTML·페이저 CSS 위치
- [로컬 서버 기동](local-server-run.md) — 비밀번호 기본값 없음, 환경변수 필수경위나 해결 과정은 개별 파일에만 둡니다. 색인에 길게 쓰면 그만큼 다른 메모가 밀려나기 때문입니다.
오늘(2026-10-07) 재 보니 메모 파일은 115개로 늘었고, 색인 파일은 14,686바이트입니다.
요약 한 줄이 짧을수록 더 많은 메모가 세션에 실립니다.
해결 둘, 세션 시작 때 서버가 필요한 것만 넣어 줍니다
그래도 색인 한 장에 모든 걸 담는 방식은 언젠가 다시 넘칩니다.
그래서 기억의 정본을 서버(PostgreSQL)로 옮기고, 세션을 열 때 SessionStart 훅이 지금 폴더에 맞는 것만 골라 넣게 했습니다.
cwd = payload.get("cwd") or os.getcwd()
ws = config.resolve_workspace(cwd) # 폴더 → 프로필·프로젝트
if not ws:
return # 매핑 밖이면 아무것도 안 넣는다
out = compiler.build(profile, project, None, 3000)
sys.stdout.write(out) # 훅의 표준출력이 곧 세션 컨텍스트훅이 넣는 묶음은 약 3,000토큰 예산 안에서 만듭니다. 프로젝트 요약, 활성 결정, 열린 할 일, 검증된 지식, 오늘 일정, 미해결 문제, 최근 변경 순서입니다.
예산은 칸마다 몫을 나눠 두고, 몫을 넘는 줄은 그 칸 안에서 덜어 냅니다. 지식이 아무리 많아져도 결정이나 할 일 칸을 밀어내지 못하게 하려는 것입니다.
서버가 꺼져 있거나 터널이 끊겨도 세션은 정상으로 열립니다. 실패는 한 줄만 남기고 넘어갑니다.
처음 옮길 때 메모리 105건을 서버로 올렸습니다.
옮기고 나서 걸린 함정 두 가지
첫째, 분류기가 한글 제목을 못 읽었습니다.
메모를 어느 프로젝트로 보낼지 영문 파일명으로 가르다 보니, 한글 세션 제목만 있는 기록은 엉뚱한 쪽으로 샜습니다. 한글 낱말 점수로 가르는 분류기를 따로 만들었습니다.
둘째, "공통" 꼬리표가 너무 넓었습니다.
프로젝트가 정해지지 않은 메모를 전부 공통으로 두었더니, 사무용 도구나 출석 앱 메모가 모든 프로젝트 세션에 주입되고 있었습니다.
공통은 인코딩 함정처럼 어디서나 통하는 교훈에만 붙이도록 좁혔습니다.
주입이 생기니 이번에는 "무엇을 넣지 않을지"가 문제가 된 것입니다.
메모리가 많아졌다면 확인할 것
1. 색인 파일 크기를 직접 재 봅니다. 한도를 넘어도 알려 주지 않습니다.
2. 색인 한 줄에는 제목과 여는 조건만 씁니다. 경위는 개별 파일로 보냅니다.
3. 프로젝트가 여럿이면 세션 시작 훅으로 지금 폴더에 맞는 것만 넣습니다.
4. 주입 예산은 칸마다 나눠 둡니다. 한 칸이 길어져도 다른 칸이 밀려나지 않게 하는 일입니다.
5. "공통"으로 묶은 메모가 엉뚱한 세션에 들어가지 않는지 한 번씩 봅니다.
기억을 늘리는 것보다, 기억이 실제로 읽히는지 확인하는 쪽이 먼저였습니다.
지금 쓰고 계신 메모리 색인 파일, 크기가 몇 KB 인지 한번 확인해 보시는 건 어떨까요?
그러면 오늘도 모두 스테이블 하세요.
만든 것들
'Coding, Testing, Challenge' 카테고리의 다른 글
| Claude Code 기억 서버를 VPS 월 12달러로 만든 구조, 서버에 둔 것과 PC에 남긴 것 (0) | 2026.10.08 |
|---|---|
| AI 대화 기록에 비밀번호·키 144개가 남아 있었다, 바이브코딩 전에 할 보안 점검 (0) | 2026.10.08 |
| 고치지도 않았는데 버그가 사라졌습니다 (0) | 2026.10.06 |
| 롤백 가드를 만들었는데 DDL 에서는 무의미했습니다 (0) | 2026.10.06 |
| 미니앱 번들 3,072KB 상한 맞추기, 한 줄로 앱당 1MB를 덜어냈습니다 (0) | 2026.10.05 |
