Agent Memory — 드디어 경력사원이네

이전 이야기에서: Worktree Isolation으로 팀 에이전트의 파일 충돌이 해결됐다. 각 에이전트가 자기 방에서 일하고, 완료 후 머지한다. 제품이 론칭됐다. 소연이 투자자 데모에서 성공. 현우가 "인정한다." 그런데 유지보수 첫 주, 기묘한 데자뷔가 시작됐다...

Harness = Tools + Knowledge + Context + Permissions

Agent Memory는 에이전트가 스스로 Knowledge를 작성하고 축적한다. "The agent should get smarter, not restart from zero each session"

"또 신입사원이야"

제품이 론칭됐다. 소연의 데모는 성공적이었다.

지민은 유지보수 모드에 들어갔다. 새 세션을 열고 버그를 수정하려 했다.

지민: 사용자 로그인 후 세션 유지가 안 되는 버그 수정해줘
Claude: 네, 먼저 프로젝트를 파악할게요...
        어떤 패키지 매니저를 사용하나요?

지민은 멈췄다. 지난주 론칭 스프린트 동안 매일 함께 일한 Claude가 물었다.

"어떤 패키지 매니저를 사용하나요?"

지난주 화요일: "pnpm 써" → 학습 ✅
지난주 수요일: pnpm 정상 사용 ✅
지난주 목요일: pnpm 정상 사용 ✅
이번주 월요일: "어떤 패키지 매니저를 사용하나요?" ← ?!

세션이 바뀌면서 모든 것을 잊었다. 지민이 중얼거렸다.

"또 신입사원이야."

Ch01에서 처음 Agent Loop를 이해했을 때 한 말이었다. 그 뒤로 CLAUDE.md(Ch02)를 만들고, Skills(Ch04)를 만들고, Rules(Ch08)를 만들었다. 하지만 이것들은 사람이 사전에 알고 있는 지식을 명시적으로 작성한 것이다.

지금 지민이 원하는 건 다르다. Claude가 스스로 일하면서 발견한 것을 기억하게 하고 싶다.

"pnpm을 쓴다"는 것은 지민이 미리 CLAUDE.md에 쓸 수 있다. 하지만 "N+1 쿼리 문제가 이 프로젝트에서 3번 발생했다"는 건 Claude가 코드 리뷰를 하면서 발견한 패턴이다. 이런 운영 지식은 사람이 사전에 작성할 수 없다.

해결책: 에이전트 전용 MEMORY.md

지민의 질문은 단순했다: "Claude가 세션 사이에 기억을 유지할 수 없을까?"

모든 레이어가 갖춰졌다. Task System, Background Tasks, Agent Teams, Worktree Isolation.

그런데 하나의 근본적인 문제가 남아 있었다:

세션 1 (월요일):
나: 패키지 설치해줘
Claude: npm install [실패]
나: 이 프로젝트는 pnpm 써야 해
Claude: 아, pnpm install [성공] → 이제 알겠다

세션 2 (화요일):
나: 새 패키지 추가해줘
Claude: npm install [실패]
나: ...

세션 1 (지난 주):
나: DB 마이그레이션 실행해줘
Claude: prisma migrate deploy 실행... [성공]
나: 잠깐, 그건 프로덕션 명령이야! 개발 환경에서는 prisma migrate dev 써
Claude: 죄송합니다, 알겠습니다.

세션 2 (이번 주):
Claude: prisma migrate deploy 실행... [성공]
나: 또!?

에이전트의 Context는 세션이 끝나면 소멸한다. 아무리 많이 가르쳐도 다음 세션에서 다시 가르쳐야 한다.

이건 CLAUDE.md나 Rules로 해결할 수 없다. CLAUDE.md는 사람이 미리 알아야 쓸 수 있다. 하지만 "이 프로젝트는 pnpm을 쓴다"는 걸 사전에 CLAUDE.md에 써놓기 어렵다. 에이전트가 일하면서 발견하는 것들이기 때문이다.

해결책: 에이전트 전용 MEMORY.md

2026년 초, Claude Code에 Agent Memory 시스템이 추가됐다.

핵심 아이디어: 에이전트가 학습한 것을 파일에 기록하고, 다음 세션에서 자동으로 읽는다.

각 에이전트는 자신의 MEMORY.md 파일을 갖는다. 세션이 시작되면 이 파일의 첫 200줄이 자동으로 시스템 프롬프트에 주입된다.

세션 시작 시 (자동):

~/.claude/MEMORY.md → 시스템 프롬프트에 주입
.claude/MEMORY.md   → 시스템 프롬프트에 주입
.claude-local/MEMORY.md → 시스템 프롬프트에 주입

에이전트가 활동 중:
발견 → 기록 → .claude/MEMORY.md 업데이트

다음 세션:
이 내용이 다시 자동 주입 → 에이전트가 기억한다