memory에 뭘 기록해야 할까—내 5개를 하나씩 점검했다

지난 글에서 CLAUDE.md에는 Claude가 코드를 읽어도 알 수 없는 것만 담자고 주장했다. 한 독자가 즉시 물었다—그럼 memory는? memory도 맥락인데, CLAUDE.md와 뭐가 다른가?

많은 사람이 쓰다 보면 memory를 CLAUDE.md의 "백업 확장"처럼 다루게 된다—떠오르는 것마다 한 줄씩 넣는다. 시간이 지나면 memory는 비대해지고, Claude는 매 세션마다 다 읽고, 결국 낡은 정보로 판단을 내린다.

이 글은 추상적 정의를 다루지 않는다. 이 프로젝트에 실제로 살아 있는 5개의 memory 파일을 모두 열어 하나씩 audit한다—무엇을 남기고, 무엇을 지우고, 애초에 쓰지 말았어야 하는 게 무엇인지. 그 과정에서 CLAUDE.md vs memory 문제는 저절로 답이 나온다.

한 줄 차이

CLAUDE.md는 매 세션의 system prompt로 들어간다. 정적. 불변량에 맞다.
memory는 Claude가 직접 읽고 쓴다. 동적. 변하는 사실, 혹은 한 번의 사건을 남길 가치가 있는 것에 맞다.

유용한 질문은 "어디에 넣을까"가 아니라 "이 정보의 수명이 얼마나 길고, 누가 갱신하는가"다.

내 memory 5개

feedback_commits               — 내가 "commit"이라고 말할 때까지 commit하지 않기
feedback_article_authenticity  — 실전 글은 지어내면 안 됨
project_i18n_strategy          — 모든 언어 동시 출시라는 전략적 판단
project_howdev_plan            — how2claude.dev의 미완성 구현 계획
project_article_workflow       — 글 발행 파이프라인

타입별로 점검해본다.

A 유형: 한 번의 교정이 영구 규칙이 되는 경우 (feedback_commits)

본문이 짧다: "don't auto-commit, wait for user to confirm."

memory 중 ROI가 가장 높은 유형이다. 한 번 교정 → 이후 모든 세션에 걸쳐 영구적으로 유효.

왜 CLAUDE.md에 넣지 않을까? 프로젝트 규칙이 아니라 내 개인 작업 습관이기 때문이다. 다른 기여자가 프로젝트에 합류해도 같은 규칙을 따를 필요는 없다. CLAUDE.md는 팀 단위, memory는 "나와 Claude 사이의" 것이다.

왜 매 대화 시작마다 다시 말하지 않을까? 세션을 가로질러 보존되기 때문이다. Claude가 다음 주에 코드를 도와줄 때도 여전히 기억한다.

트리거가 명확하다: 한 번 교정했고, 그 교정이 영원히 유지되기를 원한다.

B 유형: 날짜가 달린 사고 기록 (feedback_article_authenticity)

이 memory의 본문은 비정상적으로 구체적이다:

2026-04-16, multi-agent 시리즈 마지막 글을 쓸 때, "3개의 Agent가 webhook 기능을 만든다"는 이야기를 상상으로 지어냈다... 전부 날조였다. 사용자가 "진짜인가 지어낸 건가" 물었다—이는 앞선 두 편의 (방법론) 글과는 다른 기준이다...

핵심: Why 필드가 추상적 원칙이 아니라 구체적 사건 + 날짜 + 그때 무엇이 일어났는가다.

왜 이렇게 쓰는가? 6개월 후 "실전 글에는 진짜 소재가 필요하다"는 추상적 규칙만 보면 헷갈린다—언제 정했지, 왜 정했지? 그런데 "4-16, 내가 agent 이야기를 지어냈다 걸렸다"를 보면 즉시 떠오른다. 그리고 이 규칙이 여전히 적용되는지도 현장에서 판단할 수 있다.

이것이 내 5개 중 가장 "무거운" 항목이다. 단순한 규칙이 아니라 Claude와 내가 모두 조회할 수 있는 사고 기록이다.

C 유형: 전략적 판단의 배경 (project_i18n_strategy)

내용: 이 프로젝트가 왜 모든 언어를 공격적으로 동시 출시했는지—Claude를 통한 번역 비용이 거의 0, 공식 문서가 영어만 있다는 게 핵심 기회 창구라는 판단.

코드에서는 볼 수 없다. 코드에는 19개의 로케일 파일이 있을 뿐이다. 왜 19개인지, 왜 동시인지, 왜 일본어와 한국어의 우선순위가 높은지—모두 내 머릿속에 있다.

memory는 그 "머릿속 판단"을 지속 가능한 형태로 침전시켜, Claude가 나중에 기능을 제안할 때 "이 제안이 i18n 전략과 충돌하는가"를 물을 수 있게 한다.

운영 규칙이 아니다(CLAUDE.md에 넣지 않는다), 전략적 배경이다(memory에 넣는다).

D 유형: 세션 간 인수인계 (project_howdev_plan)

가장 임시적인 것: how2claude.dev 개발자 사이트의 9개 파일 구현 계획, 말미에 "다음 세션에서 계속"이라고 적혀 있다.

가장 위험한 유형—쉽게 좀비 memory가 된다. 구현을 끝내고도 삭제를 잊어버리면, 다음번에 Claude는 여전히 유효하다고 여기고 낡은 계획을 바탕으로 "step 3을 아직 안 했네요"라고 조언한다.

이런 memory에는 명확한 퇴장 메커니즘이 필요하다: how2claude.dev가 출시되는 순간 수동으로 삭제해야 한다.

E 유형: 삭제해야 할 한 건 (project_article_workflow)

정보 밀도가 가장 높은 항목이고, 한때 가장 유용하다고 생각했다—찬찬히 들여다보기 전까지는:

/write-article과 /publish-article의 존재 → .claude/commands/를 보면 알 수 있다
draft 디렉토리 구조 (meta.json + lang.md) → docs/drafts/를 보면 한눈에 파악 가능
API URL → .claude/publish-config.json에 있다
Category/series slug 목록 → seed 파일에 있다

Claude는 코드를 읽으면 전부 도출할 수 있다.

memory가 실제로 제공하는 유일한 것은 마지막 블록이다: "Accounts (production): zh → @how2claude, en → @howtoclaude"—그리고 이 부분은 이미 낡았다. 지난 세션에서 프로덕션은 실제로 zh=@howtoclaude임이 드러났다. memory는 며칠 전 스냅샷을 기록했고 이미 어긋나 있다.

결론: 이 memory는 90%를 덜어내야 한다. 남길 만한 부분("kamal로 실시간 계정 조회")은 CLAUDE.md에 넣는 게 낫다—아니면 아예 쓰지 않는 편이 낫다. memory에 고정된 계정은 언젠가 또 낡을 테니까.

네 가지 깨달음

1. memory의 진짜 역할은 Claude가 들어갈 수 없는 방을 열어주는 것.

내 머릿속에 들어갈 수 없음 → 전략, 취향, 이유
지난주 세션에 들어갈 수 없음 → 내가 지난번에 교정한 것
3개월 전 실패에 들어갈 수 없음 → 구체적 사건 + 날짜

2. Claude가 코드에서 읽을 수 있는 것은 memory에 넣지 말 것.

앞선 CLAUDE.md 글과 같은 원칙. 파일 경로, API URL, 디렉토리 구조—모두 코드가 답할 수 있는 질문이다. 한 번 grep하기 귀찮아서 memory에 넣는 건, 그 정보가 영원히 변하지 않을 거라는 데 거는 것과 같다.

3. memory는 낡는다.

project_article_workflow가 그 증거다—며칠 전에 썼는데 계정 정보는 이미 틀리다. 오래된 memory일수록 덜 믿을 만하다. 정기적으로 audit > 무한정 추가.

4. Why 필드가 당신을 구한다.

내 두 feedback을 비교해보면 보인다:

feedback_article_authenticity의 Why: "4-16, multi-agent 글에서 이야기를 지어냈다" → 6개월 후 즉시 여전히 적용되는지 판단 가능.
feedback_commits의 Why: "user wants to review"뿐 → 6개월 후 어떤 교정에서 태어난 건지 나도 모른다.

후자가 훨씬 약하다. 추상적 원칙은 살아남지 못한다—왜 부과됐는지 아무도 기억하지 못한다.

결정 트리: CLAUDE.md vs memory vs 아무 것도 쓰지 않기

새로운 정보가 나타나면 세 가지 질문을 던진다:

Claude가 코드에서 도출할 수 있는가? Yes → 아무 것도 쓰지 않는다.
모든 기여자가 따라야 하는가? Yes → CLAUDE.md.
시간이 지나면서 변하는가? Yes → memory(구체적 Why + How to apply와 함께).

세 번째 질문이 함정이다. 적어두고 싶은 "변하지 않는" 것들 대부분은 실제로는 코드에서 도출 가능하다—그저 Claude가 다시 grep하게 하는 게 귀찮을 뿐.

audit 후 보이는 것들

한번 훑고 몇 가지가 눈에 들어왔다:

project_article_workflow의 90%는 코드에서 도출 가능하다. 이 항목을 가장 손봐야 한다
project_howdev_plan은 임시 인수인계—이론상 퇴장 메커니즘이 있어야 한다
project_i18n_strategy는 전략적 판단—몇 달 후 다시 검토할 가치가 있다
feedback_commits의 Why가 약하다. 구체적 사건을 붙이면 더 견고해진다

곁가지 관찰: 내 type 분포는 feedback×2 + project×3, user나 reference 타입은 하나도 없다. Claude에게 "내가 누구인지", "어떤 외부 시스템에서 상태를 읽는지" 아직 말하지 않았다는 뜻이다. 다음 배치에서 보완할 후보들.

마무리

memory의 가장 큰 함정은 "써야 하는데 안 쓴 것"이 아니다. "써놓았는데 낡아버린 것"이다. 5개 중 1개만 어긋나도 충분하다—Claude는 조용히 낡은 정보로 판단을 내리고, 그 어긋남을 알려주지 않는다.

내 5개 중에는 이미 손보고 싶은 데가 몇 군데 보인다. 당신 것은 어떤가?