컨텍스트 엔지니어링 실패모드 위키

Claude Code — Auto Memory 세션 간 학습

7 min read

상위: 08_00_MOC

Claude Code — Auto Memory 세션 간 학습

Auto Memory란

Auto Memory는 사용자가 직접 쓰지 않아도 Claude가 세션 중 관찰한 패턴·교정·선호사항을 스스로 기록하는 메커니즘이다. CLAUDE.md가 “사용자가 쓰는 파일”이라면 Auto Memory는 “Claude가 쓰는 파일”이다.

“Auto memory lets Claude accumulate knowledge across sessions without you writing anything. Claude saves notes for itself as it works: build commands, debugging insights, architecture notes, code style preferences, and workflow habits.” — How Claude remembers your project, Anthropic

요구사항: Claude Code v2.1.59 이상. claude --version으로 확인.

저장 위치와 구조

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 요약 인덱스 — 매 세션 시작 시 자동 로드
├── debugging.md       # 디버깅 패턴 상세 노트 (온디맨드)
├── api-conventions.md # API 설계 결정사항 (온디맨드)
└── ...                # Claude가 생성하는 토픽 파일들

<project> 경로는 git 저장소를 기준으로 정해진다. 같은 레포의 모든 worktree와 서브디렉토리는 하나의 auto memory 디렉토리를 공유한다. git 저장소 밖에서 실행하면 프로젝트 루트가 기준이 된다.

커스텀 위치 설정:

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

절대 경로 또는 ~/로 시작해야 함. 프로젝트 settings에서 설정 시 워크스페이스 신뢰 대화상자 승인 필요.

로드 규칙: “200줄 또는 25KB”

“The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation. Content beyond that threshold is not loaded at session start.” — How Claude remembers your project, Anthropic

  • MEMORY.md: 첫 200줄 또는 25KB 중 먼저 도달하는 기준까지만 세션 시작 시 로드
  • 토픽 파일(debugging.md 등): 세션 시작 시에는 로드되지 않고, 필요할 때 Claude가 표준 파일 도구로 온디맨드 읽는다
  • CLAUDE.md와의 차이: CLAUDE.md는 길이 제한 없이 전체가 로드된다(단, 200줄을 넘기면 준수율이 떨어질 위험이 있다)

여기서 Auto Memory 로드 한도(200줄/25KB)와 CLAUDE.md 준수율이 떨어지기 시작하는 임계(200줄)는 같은 수치다. 실무에서는 둘을 묶어 하나의 “200줄 원칙”으로 기억하면 편하다.

Auto Memory가 기록하는 시점

Claude는 매 세션마다 무언가를 저장하지는 않는다. 앞으로의 대화에 쓸모가 있을지를 따져 기록 여부를 판단한다.

“Claude doesn’t save something every session. It decides what’s worth remembering based on whether the information would be useful in a future conversation.”

기록이 일어나는 계기는 대체로 이렇다.

  • 사용자가 같은 교정을 두 번 이상 한 경우
  • 빌드/테스트 명령을 발견한 경우
  • 프로젝트 특화 패턴을 파악한 경우
  • 사용자가 명시적으로 “기억해줘”를 요청한 경우

UI에 “Writing memory”나 “Recalled memory” 메시지가 뜨면 Claude가 ~/.claude/projects/<project>/memory/를 읽거나 쓰고 있다는 뜻이다.

/memory 명령

/memory 명령은 다음을 한다.

  • 현재 세션에 로드된 모든 CLAUDE.md, CLAUDE.local.md, rules 파일 목록을 보여준다
  • Auto memory를 켜고 끈다
  • Auto memory 폴더를 여는 링크를 제공한다
  • 파일을 골라 편집기에서 연다

활용 패턴은 이렇다.

  • 세션을 시작하기 전, 어떤 지시가 로드됐는지 확인하려면 /memory
  • 잘못된 패턴이 굳었는지 점검하려면 /memory로 파일을 열어 직접 편집
  • 불필요한 메모리 항목은 ~/.claude/projects/<project>/memory/를 직접 편집해 삭제

서브에이전트와 Auto Memory

서브에이전트는 부모의 auto memory를 공유하지 않는다. 대신 memory 프론트매터를 설정하면 자기만의 MEMORY.md를 따로 둘 수 있다.

“The subagent gets its own system prompt, shorter than the main session’s. The main session’s auto memory is not included. If a custom agent has memory: in its frontmatter, it loads its own separate MEMORY.md here instead.” — Explore the context window, Anthropic

비활성화 방법

// settings.json
{
  "autoMemoryEnabled": false
}

또는 환경변수: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Auto Memory의 부패(Decay) 위험

05 부패 실패모드의 Auto Memory 버전: 오래된 MEMORY.md 항목이 현재 아키텍처·의존성과 어긋나면 모델이 잘못된 전제로 출발한다.

예시 시나리오를 보자.

  1. 3개월 전에 “빌드 명령은 npm run build”라고 기록한다
  2. 그 후 팀이 pnpm으로 전환한다
  3. MEMORY.md는 여전히 낡은 npm run build를 기억한다
  4. Claude가 세션마다 틀린 빌드 명령을 쓴다

완화 방법은 다음과 같다.

  • /memory로 주기적으로 감사한다(자동화 수단이 없어 수동으로 해야 한다)
  • 아키텍처가 바뀌면 “MEMORY.md 업데이트해줘”라고 분명히 요청한다
  • MEMORY.md는 plain markdown이므로 직접 편집하거나 삭제할 수 있다

남는 문제는 “기억할 가치”의 판단 기준이 불투명하다는 점이다. 잘못된 패턴이 한번 굳으면 세션을 거듭할수록 오류가 증폭되는데, 정기 감사가 사실상 유일한 방어책이지만 이를 자동화할 공식 수단은 아직 없다.

참고문헌

관련 노트

그래프 뷰

백링크