에이전트가 잊지 않게 하는 메모리 파일: 75개 중 다시 말할 일이 없어진 유형 5개

10월 한 달, 이 블로그 저장소에서 연 AI 대화가 만든 커밋커밋 commit 고친 파일들을 한 단위로 묶어 변경 기록에 남기는 일.눌러서 용어 설명서 보기 → 327개에는 AI 공동저자 줄이 하나도 없었습니다. 다른 프로젝트에서 연 대화가 같은 저장소에 남긴 커밋은 96개 중 93개에 AI 공동저자 줄이 붙어 있었습니다.

AI 코딩 도구에 같은 말을 두 번 하면, 저는 그 말을 메모리 파일 한 장으로 남깁니다. 그렇게 넉 달 반 동안 이 블로그 저장소에 75장이 쌓였습니다.

이 글은 그 75장을 한 달치 대화 기록과 맞춰 본 결과입니다. 어떤 메모리 뒤에는 같은 지적이 끊겼고, 어떤 메모리 뒤에는 똑같은 요청이 계속 나왔습니다.

처음이라면 지적 하나를 파일 하나로 남깁니다

첫 단계는 같은 말을 두 번째 한 순간, 그 말을 파일 한 장에 적게 하는 것입니다. 제 메모리는 모두 이 모양입니다.

위 그림은 제 실제 파일을 설명용으로 줄여 다시 짠 것입니다. 머리말 구조를 단순하게 바꾸고 본문 일부를 뺐습니다.

Claude CodeClaude Code 클로드 코드 Anthropic의 코딩용 AI 도구. 내 컴퓨터의 파일을 직접 읽고 고칩니다.눌러서 용어 설명서 보기 →의 자동 메모리는 기본 설정에서 저장소마다 memory/ 폴더 하나와 색인 MEMORY.md를 둡니다. 공식 문서 기준으로 색인은 대화가 시작될 때마다 앞 200줄(또는 25KB)까지 실리고, 본문 파일은 필요할 때 열립니다.

AI에게 같은 지적을 두 번째 했다면 아래를 붙여 넣습니다.

방금 내가 한 지적을 다음 대화에서도 지키게 메모리 파일 하나로 남겨 줘.
- 파일 하나에 규칙 하나. 본문 첫 줄은 "무엇을 하지 않는다/한다" 한 문장
- 내가 한 말 원문과 오늘 날짜를 Why에 적기
- How to apply에는 실제로 손이 가는 동작 하나
- 색인 MEMORY.md에 한 줄 추가. 그 줄만 읽어도 규칙이 보이게(파일 이름만 쓰지 않기)
- 같은 내용 파일이 이미 있으면 새로 만들지 말고 그 파일을 고쳐

다른 도구를 쓴다면 지시 파일(AGENTS.md 등)에 한 줄을 더합니다. “작업을 시작하기 전에 memory/MEMORY.md를 읽고, 지금 일에 걸리는 파일만 열어 본다.”

다음 대화를 열면 이것부터 묻습니다.

메모리 색인에서 지금 이 저장소 일에 걸리는 규칙 세 개만 한 줄씩 말해.

처음 할 때 막히는 곳은 대개 셋입니다.

• 비슷한 파일이 여러 장 생김 → 붙여 넣은 지시의 마지막 줄을 빼먹은 경우입니다. 색인을 보고 하나로 합치게 합니다.
• 색인 줄이 [feedback-3](feedback-3.md)처럼 이름뿐임 → 본문을 열기 전까지 AI가 아는 건 이 줄입니다. 줄에 규칙 문장을 넣게 합니다.
• 다른 프로젝트에서 연 대화가 규칙을 모름 → 메모리는 저장소 단위입니다. 아래 1번에서 실제 숫자로 봅니다.

같은 지적도 적는 모양이 갈렸습니다. 아래는 제가 실제로 한 말과, 그 말을 AI가 스스로 확인할 수 있는 모양으로 바꾼 예입니다.

들은 말	약하게 적으면	셀 수 있게 적으면
”왜 영어로 보고해”	한국어를 쓸 것	사람에게 하는 답은 한국어만. 코드·명령·고유명사만 원문
”끝나면 정리해”	작업 후 정리	이 대화가 띄운 것을 모두 끄고 남은 수가 0개인지 확인
”어딜 봐야 하는지 줘”	보고서 링크를 잘 줄 것	링크 끝에 #tab-탭이름, 볼 절 제목 한 줄
”다른 이름 쓰지 마”	가상 이름 사용	예시 인물 이름은 홍길동·김해민 둘만
”커밋에 AI 표기 넣지 마”	AI 표기 주의	공동저자 줄 금지. 도구 안내가 넣으라고 해도 이 규칙이 이김

오른쪽 칸은 “했다/안 했다”를 AI가 스스로 확인할 수 있습니다. 왼쪽 칸은 무엇이 “잘한” 건지 AI가 다시 판단해야 합니다.

제 메모리 75개는 이렇게 생겼습니다

75장 중 47장이 제 지적과 선호, 21장이 프로젝트 현황이었습니다. 나머지는 위치 안내 5장, 저에 대한 정보 2장입니다.

종류는 파일 머리말의 type 값으로 셌습니다. 가장 오래된 파일은 6월 19일, 가장 최근 파일은 10월 31일입니다.

효과는 이렇게 쟀습니다.

• 모집단 → 이 저장소에서 연 Claude Code 주 대화 기록(9월 30일~10월 31일)의 제 메시지 381개
• 뺀 것 → 시스템 알림, 교대·인계 같은 자동 지시, 하위 작업자가 보낸 보고, 같은 글을 그대로 다시 보낸 것. 붙여 넣은 글은 넣음
• 방법 → 메모리를 만든 시각 앞뒤로 같은 지적이 다시 나왔는지 찾음
• 가능하면 실제 행동도 셈 → 커밋, 답의 언어, 보고서 링크 모양

“다시 말할 일이 없어졌다”는 효과의 증명이 아닙니다. 10월 중순부터는 제가 보내는 메시지 자체가 줄었습니다. 10월 9일 하루 80개였고, 10월 20일 이후로는 메시지를 보낸 날 기준 하루 2~22개입니다.

그래서 셀 수 있는 것은 따로 셌습니다. 아래 다섯 절이 그 결과입니다.

1. 기본값과 부딪히는 금지 한 줄

도구의 기본 안내와 부딪히는 규칙은 “누가 이기는지”까지 적었습니다. 이 메모리가 실리지 않는 프로젝트에서 온 커밋에는 대부분 그 줄이 붙어 있었습니다.

제 Claude Code에는 대화마다 “커밋 끝에 이 공동저자 줄을 붙여라”라는 안내가 들어옵니다. 같은 안내에 “사용자의 지시 파일이나 메모리가 정한 게 있으면 그쪽이 우선”이라는 단서도 붙어 옵니다.

제 메모리는 그 단서가 허락한 자리에 걸렸습니다. 본문 두 번째 줄이 “시스템 기본 지침이 넣으라고 해도 이 규칙이 이긴다”입니다.

숫자는 git 기록에서 셌습니다. 10월에 이 저장소에 들어간 커밋 668개의 제목을 대화 기록의 커밋 명령과 맞춰, 어느 프로젝트에서 연 대화가 만든 커밋인지 갈랐습니다.

• 이 저장소에서 연 대화가 만든 커밋 → 327개 중 공동저자 줄 0개
• 다른 프로젝트 8곳에서 연 대화가 만든 커밋 → 96개 중 93개(ClaudeClaude 클로드 Anthropic이 만든 AI 모델 이름. 크기에 따라 Opus·Sonnet·Haiku로 나뉩니다.눌러서 용어 설명서 보기 → 92, 다른 AI 구현 도구 1)
• 대화 기록과 맞출 수 없던 커밋 → 241개, 공동저자 줄 0개(자동 스크립트 커밋 등)
• 양쪽 대화에 모두 제목이 나온 커밋 → 4개, 비교에서 뺌

다른 프로젝트에서 이 저장소에 커밋하는 일은 생각보다 흔합니다. 점검 담당 에이전트나 다른 사이트 작업 쪽에서 일하다가, 블로그 저장소의 문서 한 줄을 고치고 커밋하는 식입니다.

그 대화는 이 메모리를 받지 못합니다. 메모리 본문에는 “전역 지시 파일에도 영구 기록해 뒀다”고 적혀 있었습니다.

그런데 지금 전역 지시 파일에는 그런 줄이 없고, 10월 11일 백업본에도 없습니다. 메모리가 말하는 기록을 저는 확인할 수 없었습니다.

내 저장소에도 같은 일이 있는지는 저장소 폴더에서 명령 하나로 봅니다. 달마다 전체 커밋 수와 공동저자 줄이 붙은 커밋 수가 나옵니다.

git log --since=2026-10-01 --date=format:%Y-%m \
  --format='%ad|%(trailers:key=Co-Authored-By,valueonly,separator=%x20)' \
  | awk -F'|' 'NF==2 {t[$1]++; if ($2 != "") c[$1]++} END {for (k in t) print k, t[k], c[k]+0}'

전역 지시 파일과 프로젝트 지시 파일을 나누는 법은 지시 파일을 전역 한 장, 프로젝트 한 장으로 나누는 글에 따로 정리했습니다.

2. 사람이 읽는 답의 말

“답은 한국어로만” 메모리 뒤로 마지막 답의 영어 비율은 낮아졌지만, 작업 중간에 쓰는 한두 줄은 다섯에 하나꼴로 남았습니다. 메모리에 “중간 보고 한 줄까지”라고 적었는데도 그랬습니다.

10월 9일, 저는 아홉 시간 사이에 “왜 영어로 보고하냐”는 말을 두 번 했습니다(두 번째는 오타를 고쳐 한 번 더 보냄). 두 번째 말이 나온 그 분에 메모리가 생겼습니다.

그 뒤 같은 대화에서 37분 안에 두 번 더 말했습니다. 그중 한 번은 “터미널에서 왜 영어 쓰냐”였습니다. 그다음 22일 동안은 한 번도 하지 않았습니다.

실제 답의 언어도 셌습니다.

• 대상 → 이 저장소 Claude Code 주 대화 29개, 코드·경로를 뺀 글자 30자 이상의 글
• 영어 위주 → 한글이 영문자의 10%가 안 되는 글
• 마지막 답 → 제가 다음 말을 보내기 직전의 답. 6.0%(84개 중 5) → 1.8%(272개 중 5)
• 중간 글 → 도구를 부르는 사이사이 한두 줄. 27.0% → 21.8%

메모리를 만든 뒤에 나온 실제 중간 글은 이런 모양이었습니다.

• “Now update the report tab and commit the dashboard.”
• “Relative path issue only; rerun from repo dir.”
• “Now the preview step for the blog draft.”

영어 마지막 답은 전후 모두 5개라, 비율이 낮아진 건 답 자체가 늘어난 영향도 큽니다. 메모리가 원인인지는 확인하지 못했습니다.

제 지적에는 터미널의 중간 글도 들어 있었으니, 이 메모리는 절반만 지켜지고 있는 셈입니다. 지적이 끊긴 것도 답이 바뀌어서인지, 제가 덜 말하게 돼서인지 가를 수 없습니다.

중간 글까지 바꾸려면 메모리보다 강한 자리가 필요할 것 같습니다. 저는 아직 그 자리를 확인하지 못했습니다.

3. 끝 상태를 숫자로

“정리해”가 아니라 “0개”라고 적은 메모리 뒤로는 같은 지적이 나오지 않았습니다. 제 짐작으로는 끝났는지를 AI가 스스로 셀 수 있는 모양이라서입니다.

10월 10일 밤, 이 저장소의 하위 작업자가 16개까지 쌓여 있었습니다. 저는 “작업 끝나면 전체 0개 되도록 해”라고 했고, 1분 뒤 메모리가 생겼습니다.

메모리 본문은 세 가지만 적습니다.

• 끄는 것 → 하위 작업자, 백그라운드 감시, 임시 서버서버 server 인터넷으로 들어온 요청을 받아 일을 처리해 주는 컴퓨터.눌러서 용어 설명서 보기 →
• 확인 → 마지막에 남은 수를 보고 0개인지
• 보고 → 끝에 남은 수를 한 줄로

그 뒤 21일 동안 같은 지적은 없었습니다. 남은 작업자 수를 매번 세어 기록한 자료는 없어서, 행동까지 확인한 건 아닙니다.

“깔끔하게 마무리해”는 AI마다 뜻이 다릅니다. “0개”는 하나뿐입니다.

이 저장소의 작업 기준에도 같은 모양의 끝 상태가 두 개 더 있습니다. 글 형식 검사 오류 0건, 사이트를 고쳤다면 화면 검사 오류 0건입니다.

둘 다 숫자라서 AI가 “끝났습니다”라고 말하기 전에 스스로 돌려 보고 결과 숫자를 보고에 적습니다. 저는 그 숫자만 보면 됩니다.

4·5. 값은 목록으로, 위치는 주소까지 적습니다

고를 값을 목록으로 박아 두거나 주소 모양까지 적은 메모리 뒤로는 같은 지적이 없었습니다. 둘 다 AI가 새로 판단할 몫이 거의 없는 모양입니다.

4번은 글에 넣는 예시 인물 이름입니다. 10월 11일에 “예시 이름은 홍길동, 김해민 둘만”이라는 메모리를 만들었고, 그 뒤 20일 동안 이름 지적은 없었습니다. 글마다 이름을 전부 세어 본 것은 아닙니다.

당시 메모리에는 “여러 명이면 유명 영화 인물 이름” 예외도 있었습니다. 지금 작업 기준은 두 이름만 남겨서, 이 글과 키트의 예시도 그 기준에 맞췄습니다.

“가상 이름을 쓰라”고만 하면 AI는 매번 새 이름을 지어야 합니다. 쓸 수 있는 값을 다 적어 두면 고를 일이 없어집니다.

5번은 보고서 링크입니다. 탭이 열 개 넘는 보고서인데, AI는 늘 첫 화면 주소만 줬습니다.

10월 24일에 “어딜 봐야 하는지 바로 줘야 알지”라고 했고, 메모리에는 주소 모양을 그대로 적었습니다.

링크는 …/channel-growth/#tab-<탭 이름> 으로 주고,
탭 안에서 볼 절 제목을 한 줄로 같이 적는다.

• 메모리 전 → 대화 속 보고서 링크 13개 중 탭 주소 0개
• 메모리 뒤 → 관찰된 6개 중 6개

위치 안내는 오래돼도 맞을 수 있습니다. 6월에 만든 “이 저장소에서는 npm이 PATH에 없다, 이 경로를 앞에 붙여라” 메모리는 넉 달 넘게 그대로 맞고, 10월 대화에서도 그 파일을 부른 호출이 네 번 있었습니다.

메모리로는 안 된 셋

품질 기준과 취향은 메모리를 만든 뒤에도 같은 말이 또 나왔습니다. “잘해”는 AI가 스스로 잴 수 있는 모양이 아니었습니다.

품질 기준: 모바일, 그림

품질 기준은 “모바일에서도 읽히게”, “그림을 넣어” 같은 것입니다.

• 모바일 → 10월 11일 메모리 뒤로 나흘(10월 15·25·27·31일)에 걸쳐 같은 요청 5번(글·도표, 보고서, 미리보기 화면)
• 그림 → 10월 10일 메모리 뒤, 10월 23일 다른 사이트용 원고 6편이 그림 없이 승인 요청으로 올라옴

그림 쪽은 메모리가 실리는 바로 이 저장소의 대화에서 생겼습니다. 그 사이트의 기존 글 20편이 글자뿐이었고, 새 원고도 그 모양을 따랐습니다.

메모리에는 “블로그 글”이라고만 적혀 있었습니다. 지금은 “블로그·다른 사이트 글 모두”로 고쳤고, 그 사이트에도 그림 수를 세는 검사를 붙였습니다.

취향 판정: 재미

취향 판정은 “재미없다”입니다. 저는 재미와 방향에 관한 메모리를 세 번(10월 15일, 21일, 27일) 만들었습니다.

첫 메모리 뒤로도 노잼 판정은 세 번(10월 15일 밤, 21일, 27일) 더 나왔고, 21일과 27일 메모리는 그 판정 직후에 생겼습니다.

재미는 규칙 한 줄로 옮겨지지 않았습니다. 지금은 원고를 먼저 쓰지 않고 시안 2~3개를 보여 고르는 쪽으로 바꿨습니다.

현황 사본: 프로젝트 사실

현황 사본은 프로젝트 사실을 베껴 둔 메모리입니다. 75장 중 21장이 이 종류였습니다.

이런 메모리는 적는 날에는 맞습니다. 8월에 적은 “다음에 쓸 글은 3번, 4번”은 두 달 뒤에도 같은 말을 하고 있었습니다.

10월 31일 아침, 정리 스크립트가 이 저장소의 현황 메모리 3장을 “정본으로 이동”으로 바꿨습니다. 본문은 내리고, 지금 사실은 어디서 확인하는지 한 줄만 남겼습니다(원래 본문은 백업 파일로 보관).

바뀐 본문은 이 한 줄뿐입니다.

정본으로 이동: 이 프로젝트의 현재 사실은 프로젝트 관리 도구와
해당 저장소의 요청·문서에서 확인한다. (원래 본문: 백업 파일 경로)

그런데 그 3장의 색인 줄은 여전히 옛 요약을 담고 있습니다. 대화마다 실리는 건 색인 줄이라, 본문만 바꾸면 반만 고친 셈입니다.

이미 쓰는 사람에게: 구조 셋

메모리를 이미 쓰고 있다면 파일 개수보다 색인 한 줄, 저장소 범위, 올리는 순서를 먼저 봅니다.

도구 호출에 경로가 나온 메모리는 75개 중 34개입니다

10월 한 달, 이 저장소 Claude Code 주 대화 29개 중 16개에서 메모리 파일 경로가 도구 호출에 나왔습니다. 경로가 나온 파일은 모두 34장이었습니다(읽기와 쓰기 포함).

나머지 41장은 한 달 동안 경로가 한 번도 나오지 않았습니다. 다른 방식으로 읽혔을 수도 있어, 본문을 안 썼다고 단정할 수는 없습니다.

확실한 건 색인 줄은 대화마다 실린다는 것뿐입니다. 본문이 열리지 않아도 규칙이 전달되게, 색인 줄은 이름이 아니라 규칙이어야 합니다.

• 약한 줄 → [AI 표기](no-ai-attribution.md) — 커밋 관련 규칙
• 일하는 줄 → [AI 표기 금지](no-ai-attribution.md) — 커밋·PR에 Co-Authored-By Claude 절대 넣지 않음 (전역)

제 색인 줄은 중앙값 92자입니다. 75줄을 다 합쳐도 7,500자(약 11.7KB)라 공식 문서의 25KB 한도 안에 들어갑니다.

메모리는 그 저장소에서 연 대화만 읽습니다

공식 문서에 따르면 기본 설정에서 자동 메모리는 저장소 단위이고, 같은 저장소의 하위 폴더와 작업 사본(worktree)이 함께 씁니다. 저장 위치는 설정으로 바꿀 수 있지만 저는 기본값 그대로 씁니다. 1번의 327개 중 0개와 96개 중 93개가 그 차이입니다.

• 이 저장소에서만 맞는 선호 → 이 저장소 메모리
• 모든 프로젝트에서 지킬 금지 → 전역 지시 파일
• 특정 작업의 절차 → 그 작업을 맡길 때 읽히는 지시 문서

같은 지적이 또 나오면 한 칸 위로 올립니다

그림 규칙이 그렇게 올라갔습니다.

• 10월 10일 21시 48분 → “공개한 글에 도식, 이미지가 하나도 없다”는 지적, 1분 뒤 메모리
• 같은 날 23시 30분 → “글 쓸 때마다 왜 누락되냐”는 두 번째 지적
• 같은 날 23시 43분 → 형식 검사기에 “본문 그림 3장 미만이면 오류”를 넣음

검사기는 배포배포 deploy 만든 프로그램을 다른 사람이 쓸 수 있게 인터넷에 올리는 일.눌러서 용어 설명서 보기 → 명령에 붙어 있어서 그림이 3장보다 적으면 배포가 멈춥니다. 10월 27일부터는 8~14장을 벗어나면 경고도 냅니다.

공식 문서도 메모리와 지시 파일은 “강제 설정이 아니라 맥락”이라고 적고, 무조건 막아야 하는 동작은 훅(도구 실행 전에 도는 검사)을 쓰라고 안내합니다.

AI 표기는 아직 메모리와 작업 지시 문서까지만 올라가 있습니다. 다른 프로젝트의 96개 중 93개를 보면, 다음 칸은 커밋 전에 그 줄을 찾아 막는 검사입니다.

내 메모리 효과를 직접 재는 법

이 글의 숫자는 특별한 도구 없이 셌습니다. 같은 방법으로 자기 저장소를 재 볼 수 있습니다.

1. 메모리 위치 → Claude Code에서 /memory로 메모리 폴더 경로를 확인해 MEMORY_DIR에 넣음
2. 만든 시각 → 리눅스는 stat -c '%w %n' "$MEMORY_DIR"/*.md, 맥은 stat -f '%SB %N' "$MEMORY_DIR"/*.md
3. 대화 기록 → 같은 상위 폴더에 대화마다 .jsonl 파일이 있음. 그 안에서 내가 보낸 메시지만 골라, 메모리를 만든 시각 앞뒤로 같은 말을 찾음
4. 행동으로 셀 수 있으면 행동도 셈 → 커밋, 링크 모양, 답의 언어

막히는 곳은 둘입니다. 파일을 지웠다 다시 만들면 생성 시각이 바뀌니, 메모리 안의 날짜와 같이 봅니다.

또 대화 기록의 시각은 세계 표준시(UTC)라 한국 시각보다 9시간 늦게 찍힙니다. 그대로 비교하면 메모리가 지적보다 9시간 뒤에 생긴 것처럼 보입니다.

파일 틀과 점검기를 그대로 가져가세요

틀, 다섯 유형 예시, 안 된 셋의 대안, 점검기를 한 번에 받을 수 있게 묶었습니다.

• memory-file-kit.md → 처음 붙여 넣을 지시문, 파일 틀, 다섯 유형 예시, 안 된 셋의 대안, 올리는 순서
• memory-audit.py → 메모리 폴더를 읽기만 하는 점검기(파이썬 표준 라이브러리만 씀)

점검기는 내려받은 폴더에서 이렇게 돌립니다. 경로는 위 1단계에서 확인한 메모리 폴더 경로로 바꿉니다.

python3 memory-audit.py "$HOME/.claude/projects/내-저장소-폴더-이름/memory"

제 저장소에 돌리면 이렇게 나옵니다.

파일 75개 · 색인 줄 75개
종류: feedback 47, project 21, reference 5, user 2
[색인에 없는 파일] 0
[파일이 없는 색인 줄] 0
[200자 넘는 색인 줄] 1
[14일 넘은 현황 메모리(정본 위치 단어 없음)] 9

걸린 9장이 다 틀린 건 아닙니다. 그중 하나가 넉 달째 맞는 npm 경로 메모리입니다.

점검기는 볼 후보만 고르고, 정본 위치가 실제로 맞는지는 확인하지 않습니다. 지울지는 사람이 정합니다.

오늘 할 일은 하나입니다. 오늘 AI에게 두 번째로 한 말 하나를 골라, 위 지시문으로 파일 한 장을 만드세요. 그리고 “0개”, “목록 안”, “#tab” 같은 셀 수 있는 모양으로 적혔는지만 확인하세요.

이 글의 숫자

• 메모리 75장: 이 저장소 memory/ 파일 머리말(10월 31일 기준), 만든 시각은 파일 생성 시각
• 지적 재발: 이 저장소 Claude Code 주 대화 기록(9월 30일~10월 31일)의 제 메시지 381개, 시각은 한국 시각
• 커밋 327개·96개: 10월 이 저장소 git 기록 668개를 대화 기록의 커밋 명령과 제목으로 맞춤(양쪽에 나온 4개, 못 맞춘 241개 제외), 공동저자 줄은 git 기록에서 읽음
• 답의 언어: 이 저장소 Claude Code 주 대화 29개(하위 작업자와 다른 실행 도구가 띄운 대화 제외)
• 보고서 링크: 같은 기록의 어시스턴트 글 속 보고서 주소
• 경로가 나온 대화 16/29, 메모리 34/75: 10월 1~31일 주 대화에서 메모리 파일 경로가 들어간 읽기·셸 호출(쓰기 포함)
• 공식 문서: Claude Code 문서 「How Claude remembers your project」(자동 메모리 저장 위치·로딩 한도·강제 아님)