Claude Code에게 메모리를 부여하는 방법에 대한 게시물은 수백 개가 넘으며, 거의 모든 게시물이 똑같은 말을 합니다. 컨텍스트(Context)를 CLAUDE.md에 넣으면 매 세션마다 불러온다는 것입니다. 맞는 말이지만, 동시에 문제의 시작이기도 합니다.

그 파일이 한두 화면을 넘어가는 순간, 당신은 모델에게 메모리를 주는 것이 아니라 매 대화마다 스스로에게 컨텍스트 세금(Context tax)을 부과하는 셈이 됩니다. CLAUDE.md에 있는 모든 토큰(Token)은 관련 여부와 상관없이 매 턴마다 다시 읽힙니다. 4,000토큰짜리 "메모리" 파일은 모델이 "이 변수 이름 좀 바꿔줘"라는 질문에 답하기 위해 당신의 인생 전체를 헤치며 나아가야 함을 의미합니다.

진정한 메모리는 모든 것을 저장하는(storing) 것이 아닙니다. 적절한 순간에 적절한 것을 회상하는(recalling) 것입니다. 거대한 메모리 파일이 무관한 컨텍스트로 인해 매 세션을 서서히 오염시키는 것을 지켜본 끝에 제가 정착한 포맷은 다음과 같습니다.

하나의 사실, 하나의 파일

메모리의 단위는 단 하나의 사실을 담은 단일 파일입니다. 섹션이 아닙니다. 제목 아래의 불렛 포인트도 아닙니다. 파일 하나입니다.

memory/
├── MEMORY.md                          # 인덱스 (항상 로드됨)
├── user_identity.md                   # 내가 누구인지, 어떻게 일하는지
...

큰 문서 안에 제목을 나누는 대신 왜 파일 하나당 하나의 사실을 담아야 할까요? 몇 주간 사용해 본 후에야 나타나는 세 가지 이유가 있습니다.

1. 파일을 깔끔하게 삭제할 수 있습니다. 사실이 오래되어 쓸모없어지면 rm으로 삭제하면 됩니다. 600줄짜리 파일에서 특정 섹션을 삭제하는 것은 아무도 하고 싶어 하지 않는 번거로운 작업이기에, 오래된 컨텍스트가 쌓이게 되고 결국 모든 답변의 질을 조용히 떨어뜨립니다.
2. 파일을 선택적으로 회상할 수 있습니다. 인덱스는 매 세션 로드되지만, _본문(bodies)_은 관련이 있을 때만 로드됩니다. 거대한 단일 파일(Monolith)은 입도(Granularity)가 없습니다. 전부 아니면 전무(All-or-nothing) 방식입니다.
3. 파일에는 출처(Provenance)가 있습니다. 각 파일에는 언제, 왜 작성되었는지가 포함되어 있으므로, 3월에 사실이었던 정보가 오늘날에도 사실인 것처럼 위장하지 않습니다.

프론트매터(Frontmatter)는 모두가 건너뛰는 부분입니다

모든 메모리 파일에는 작은 YAML 헤더가 붙습니다. 이것이 "노트 폴더"와 "회상하는 시스템"을 가르는 차이점입니다.

---
name: feedback-no-guessing-numbers
description: "Never state a dollar/metric figure without verifying it from a source first."
...

두 필드가 핵심적인 역할을 수행합니다:

• **description**은 회상 키 (recall key)입니다. 특정 메모리가 현재 작업과 관련이 있는지 결정할 때, 전체 본문이 아닌 바로 이 한 줄이 스캔됩니다. 제목이 아니라 이 메모리가 어떤 도움을 줄 수 있는지를 작성하세요. "numbers rule"보다는 "Never state a figure without verifying"가 더 낫습니다.
• **type**은 사실을 user, feedback, project, reference 카테고리로 분류합니다. 이 네 가지 유형은 수명이 다르기 때문에 중요합니다. user 사실은 지속적이지만, project 사실은 만료됩니다. 유형을 아는 것은 (사용자와 모델 모두에게) 오래된 정보를 얼마나 신뢰할지 알려줍니다.

인덱스는 로드되지만, 본문은 로드되지 않습니다

MEMORY.md는 매 세션마다 컨텍스트 (context)에 포함됨이 보장되는 유일한 파일입니다. 따라서 이 파일에는 메모리당 한 줄씩만 포함하며 그 외의 것은 넣지 않습니다:

# Memory Index

## How I work
...

그게 전부입니다. 인덱스는 목차이지 컨테이너 (container)가 아닙니다. 인덱스에 사실의 *내용 (content)*을 붙여넣기 시작하는 순간, 당신은 다시 모놀리스 (monolith) 구조를 재발명하게 되며 컨텍스트 비용 (context tax)이 즉시 다시 발생합니다.

작동 방식은 다음과 같습니다: 모델이 인덱스를 읽고, 자신이 수행하려는 작업과 일치하는 한 줄짜리 훅 (hook)을 발견하면, 그다음에 해당 특정 파일을 엽니다. 본문에 대한 비용은 그것이 관련이 있을 때만 지불합니다. 40개의 메모리를 가진 시스템은 40줄의 인덱스를 가질 수 있으며, 특정 턴에서 본문의 거의 대부분을 로드하지 않은 상태를 유지할 수 있습니다.

연결 (Linking), 회상이 이웃을 찾을 수 있도록

본문 내부에서는 [[name]] (다른 파일의 name: 슬러그)을 사용하여 관련 사실들을 연결하세요. 모델이 하나의 메모리를 가져올 때, 링크는 어떤 이웃 정보가 중요할 수 있는지를 알려줍니다. 예를 들어, 마이그레이션 제약 조건은 마감 기한과 연결되고, 이는 다시 온콜 (on-call) 규칙과 연결됩니다. 아낌없이 연결하세요. 아직 존재하지 않는 [[name]]이라도 괜찮습니다. 그것은 오류가 아니라 나중에 작성할 가치가 있는 메모리를 위한 표시기입니다.

아무도 경고하지 않는 실패 모드: 오래된 메모리는 메모리가 없는 것보다 나쁘다

이것이 저를 괴롭혔던 부분입니다. _"배포 스크립트가 scripts/deploy.sh에 있습니다"_라고 말하는 메모리는 누군가 그 파일을 옮기는 순간 적극적으로 해가 됩니다. 모델은 더 이상 존재하지 않는 경로를 자신 있게 추천할 것이며, 그 말투는 마치 정답을 말하는 것처럼 매우 확신에 차 있을 것입니다.

메모리가 부패하는 것을 방지하기 위한 두 가지 규칙이 있습니다:

1. 작성할 때 상대적인 날짜를 절대적인 날짜로 변환하세요. "다음 달에 마이그레이션합니다"는 "2026-08-01까지 마이그레이션"으로 바뀌어야 합니다. 10월에 읽은 메모리가 "다음 달"을 11월이라고 생각해서는 안 됩니다.
2. 추천하기 전에 검증하세요. 회상된 메모리에 파일, 함수 또는 플래그(flag)가 명시되어 있다면, 모델은 이를 실행하기 전에 여전히 존재하는지 확인해야 합니다. 메모리를 _현재 사실인 것_이 아니라, _작성되었을 당시 사실이었던 것_으로 취급하세요.

메모리는 단순히 계속 추가만 되는 진실이 아닙니다. 그것은 타임스탬프(timestamp)가 찍힌 주장입니다. 시스템의 성능은 잘못된 메모리를 삭제하려는 여러분의 의지에 달려 있습니다.

왜 벡터 DB / RAG 설정이 아닌가요?

이 작업에 있어서 그것은 얻는 것 없이 과할 뿐이기 때문입니다. 전체 코퍼스(corpus)는 수십 개의 짧은 마크다운 (markdown) 파일에 불과하며, 이는 목차 하나에 들어갈 정도의 양입니다. 임베딩 (embedding) 서버도 필요 없고, 조정해야 할 유사도 임계값 (similarity threshold)도 없으며, 디버깅해야 할 검색 블랙박스 (retrieval black box)도 없습니다. 일반 파일 형식을 사용하면 에디터에서 AI의 전체 메모리를 읽을 수 있고, git diff로 변경 사항을 확인하며, rm으로 잘못된 사실을 삭제할 수 있습니다. 올바른 컨텍스트 (context)를 회상하는 가장 단순한 것이 승리하며, 이 정도 규모에서는 마크다운 폴더가 바로 그 가장 단순한 것입니다.

시도해 보세요

저는 템플릿(frontmatter schema, 인덱스 형식, 네 가지 유형, 유지 관리 규칙)을 의존성이 없는 무료 리포지토리 (repo)에 보관하고 있습니다. 구조를 복사하고, 에이전트 (agent)가 memory/ 폴더를 가리키도록 설정한 뒤, 여러분이 수정해 주는 대로 에이전트가 스스로 사실을 기록하게 하세요.

→ github.com/LuciferForge/claude-code-memory

만약 여러분만의 버전을 만드셨다면, 여러분이 결정한 형식을 진심으로 보고 싶습니다 — Discussions board가 열려 있습니다. 현재 저에게 가장 흥미로운 질문은 언제 삭제할 것인가 입니다 — 아직 누구도 메모리 만료 (memory expiry)에 대한 깔끔한 규칙을 가지고 있지 않습니다.