claudekit / guides / memory-tool
[ Guide · Practical · 8분 ]

Claude Code auto memory 시작하기

published · updated

세션 간 컨텍스트를 유지해주는 Claude Code auto memory의 동작 방식과 활용법을 안내합니다. 어떤 정보가 저장되고, 어디에 저장되며, 직접 편집하는 방법을 다룹니다.

Claude Code 공식 문서는 이 기능을 auto memory라고 부릅니다. 개발자가 자기 애플리케이션에서 파일 저장 동작을 구현해 쓰는 Claude API의 Memory tool과는 다른 기능입니다.

auto memory가 해결하는 문제

매 세션 시작 시 같은 컨텍스트를 다시 설명해야 하는 비효율이 있습니다. auto memory는 사용자, 프로젝트의 잘 변하지 않는 사실과 반복 피드백을 영구 저장하여, 다음 세션에서 자동 복원합니다.

저장 위치

~/.claude/projects/<project>/memory/
├── MEMORY.md           # 인덱스 (메모리마다 1줄, 매 세션 로드)
├── user_role.md        # 메모리 1개
├── feedback_testing.md # 메모리 1개
└── ...                 # Claude가 만드는 기타 토픽 파일
  • <project>는 git 저장소 기준으로 정해집니다. 같은 저장소의 하위 디렉토리와 worktree는 하나의 메모리 디렉토리를 공유하고, git 저장소가 아니면 프로젝트 루트를 기준으로 합니다.
  • 다른 위치에 저장하려면 settings.json에 autoMemoryDirectory를 지정합니다.
  • auto memory는 해당 머신에만 저장되며 다른 머신이나 클라우드 환경과 공유되지 않습니다.
  • 메모리 종류는 각 파일 frontmatter의 type 필드(user, feedback, project, reference)로 기록됩니다.

MEMORY.md 로드 범위

세션 시작 시 MEMORY.md의 앞 200줄 또는 앞 25KB 중 먼저 닿는 지점까지만 로드됩니다. 그 뒤 내용은 시작 시 로드되지 않으므로, Claude는 인덱스를 항목당 1줄로 유지하고 자세한 내용은 토픽 파일로 옮깁니다. 인덱스가 한도를 넘으면 Claude Code가 인덱스를 다시 쓰라는 오류를 Claude에게 돌려줍니다. user_role.md 같은 토픽 파일은 시작 시 로드되지 않고, Claude가 필요할 때 읽습니다.

메인 대화의 auto memory는 subagent에 로드되지 않습니다(부모 대화를 이어받는 fork는 예외). subagent 자체의 메모리는 subagent 정의의 memory 필드로 따로 켭니다.

자동 저장되는 정보

사용자 (user)

역할, 전문 분야, 작업 선호

  • 예: “데이터 사이언티스트, 현재 관측성과 로깅에 집중”

피드백 (feedback)

교정 내역과 사용자가 확인한 접근 방식

  • 예: “통합 테스트는 mock DB 대신 실제 DB 사용 — 작년 마이그레이션 실패 사례”

프로젝트 (project)

코드나 git 이력으로 알 수 없는 진행 중인 작업, 마감, 결정

  • 예: “2026-03-05부터 모바일 릴리스 컷을 위한 머지 프리즈”

참조 (reference)

이슈 트래커, 대시보드처럼 프로젝트 밖에서 정보를 찾을 곳

  • 예: “파이프라인 버그는 Linear의 INGEST 프로젝트에서 추적”

Claude가 매 세션 무언가를 저장하지는 않습니다. 이후 대화에 쓸모가 있는지를 기준으로 저장 여부를 정합니다.

저장하지 않는 정보

  • 아키텍처, 파일 경로처럼 코드에서 알 수 있는 정보
  • git 이력으로 알 수 있는 변경 내역
  • 디버깅 해결책 (코드와 커밋 메시지에 남음)
  • CLAUDE.md에 이미 적혀 있는 내용

직접 추가, 삭제

이 결정 기억해줘: 결제 프로세서로 Stripe 사용. PayPal은 예전에 검토했지만 한국 법인 처리 한계로 제외.

Claude가 auto memory에 저장합니다. CLAUDE.md에 넣고 싶으면 “CLAUDE.md에 추가해줘”처럼 명시합니다.

Stripe 결정 메모리 삭제해줘

해당 메모리를 찾아 제거합니다.

또는 메모리 디렉토리에서 .md 파일을 직접 편집하거나 삭제할 수 있습니다.

메모리 확인과 끄기

/memory

CLAUDE.md, CLAUDE.local.md와 메모리 파일 위치를 목록으로 보여주고, auto memory 켜기와 끄기 토글, auto memory 폴더 열기를 제공합니다. 파일을 선택하면 편집기에서 열립니다.

끄는 방법은 세 가지입니다.

방법범위
/memory의 auto memory 토글~/.claude/settings.json의 autoMemoryEnabled에 저장 (사용자 전체)
프로젝트 설정에 "autoMemoryEnabled": false해당 프로젝트
환경 변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1그 환경에서 실행한 세션

좋은 메모리의 특징

  • 비명시적 사실 — 코드만으로 알 수 없는 결정, 배경
  • 이유 포함 — “왜 그렇게 정했는지”가 같이 적혀 있음
  • 절대 날짜 — “내일”, “다음 주” 대신 2026-05-15
  • 간결 — 인덱스 1줄 + 본문 짧은 단락

활용 패턴

팀 규칙은 CLAUDE.md에

“우리 팀은 PR 머지 전에 항상 Plan mode로 검토” 같은 팀 규칙은 메모리가 아니라 프로젝트 CLAUDE.md에 둡니다. auto memory는 해당 머신에만 저장되어 팀원과 공유되지 않고, 공식 문서는 코딩 표준과 워크플로를 CLAUDE.md의 용도로 안내합니다. 메모리와 CLAUDE.md 모두 강제 설정이 아니라 컨텍스트로 다뤄지므로, 반드시 막아야 하는 동작은 PreToolUse 훅으로 차단합니다(CLAUDE.md 잘 쓰는 법, Hook으로 자동화 워크플로 만들기).

사고 사후 기록

인시던트 후 “X 마이그레이션은 항상 Y 도구로 검증” 같은 교훈을 메모리에 저장하면 재발 방지에 도움.

외부 시스템 매핑

“디자인 리뷰는 Figma의 ‘Design QA’ 채널에서” 같은 매핑을 저장해두면 Claude가 관련 작업 시 바로 안내.

다음 단계

§ 10

자주 묻는 질문

자주 묻는 질문
§ 10.1
auto memory는 무엇인가요?
Claude Code에서 Claude가 사용자의 교정과 선호를 바탕으로 직접 기록하는 메모입니다. 다음 세션 시작 시 다시 불러오므로 같은 컨텍스트를 매번 설명하지 않아도 됩니다. Claude API의 Memory tool과는 별개의 기능입니다.
§ 10.2
어디에 저장되나요?
`~/.claude/projects/<project>/memory/` 디렉토리에 마크다운 파일로 저장됩니다. `<project>`는 git 저장소 기준으로 정해지므로 같은 저장소의 하위 디렉토리와 worktree는 하나의 메모리 디렉토리를 공유합니다. 위치는 `autoMemoryDirectory` 설정으로 바꿀 수 있습니다.
§ 10.3
어떤 정보가 자동으로 저장되나요?
사용자 역할과 선호(user), 피드백과 교정 내역(feedback), 진행 중인 작업과 결정(project), 외부 시스템 참조(reference) 네 가지입니다. 아키텍처, 파일 경로, 디버깅 해결책처럼 코드에서 알 수 있는 정보와 CLAUDE.md에 이미 있는 내용은 저장하지 않습니다.
§ 10.4
메모리를 직접 추가하거나 삭제할 수 있나요?
네. 메모리 파일은 일반 마크다운이라 직접 편집하거나 삭제할 수 있고, `/memory`에서 메모리 폴더를 열 수 있습니다. "이 사실 기억해줘"라고 지시하면 Claude가 auto memory에 저장합니다.
§ 10.5
auto memory를 끌 수 있나요?
`/memory`의 auto memory 토글로 끄고 켤 수 있으며, 이 값은 `~/.claude/settings.json`의 `autoMemoryEnabled`에 저장됩니다. 특정 프로젝트만 끄려면 그 프로젝트 설정에 `"autoMemoryEnabled": false`를 넣고, 환경 변수로는 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`을 사용합니다.
§ 10.6
claude-mem 플러그인과 무엇이 다른가요?
auto memory는 Claude Code에 내장된 자동 메모리 시스템입니다. claude-mem 플러그인은 세션 작업 내역을 더 적극적으로 압축, 관리하는 별도 도구로, auto memory와 함께 사용해 장기 컨텍스트 유지를 강화할 수 있습니다.