Claude Code로 새 세션을 시작할 때마다 어제 수행했던 작업 맥락을 처음부터 다시 설명해야 했던 적 있으시죠? 예를 들어, CLAUDE.md에 일일이 정리하기 어려운 코딩 컨벤션이나 테스트 프레임워크를 어제 알려줬는데 오늘 또 같은 말을 해야 하는 상황이 있는데요. 이런 컨텍스트 반복은 번거롭고, 작업 흐름을 끊어 설정 누락과 같은 실수 가능성을 높일 수 있습니다.

Auto memory는 이 문제를 해결하기 위해 올해 2월 출시된 Claude Code의 새로운 기능입니다. Auto memory를 사용하면 Claude Code가 작업 중 유용한 컨텍스트를 탐지해 프로젝트별 메모리 디렉터리의 MEMORY.md에 저장합니다. 사용자가 직접 기록하지 않아도 이전 작업 맥락은 다음 세션에 자동으로 이어져 컨텍스트를 반복 설명하는 수고를 덜 수 있죠.

이 글에서는 Auto memory의 주요 기능과 동작 방식, 특징, 사용법, 유의 사항을 자세히 살펴보겠습니다.

Auto memory 개요​

Auto memory가 무엇이고, 어떻게 동작하는지 알아보겠습니다.

개념​

Auto memory는 Claude Code가 작업 중 파악한 유용한 컨텍스트를 자동으로 기록하고, 이후 세션에서 다시 불러오는 자동 메모리 기능입니다.

기존에도 CLAUDE.md에 직접 프로젝트 지침을 작성하거나, --resume으로 이전 세션의 대화를 이어가는 방법은 있었는데요. CLAUDE.md는 사용자가 직접 관리해야 하고, --resume은 이전 세션의 대화 기록을 복원할 뿐 패턴이나 선호도를 구조적으로 저장하지는 않았죠.

Auto memory는 이 과정을 자동화하는데요. Claude Code가 작업 흐름에서 발견한 프로젝트 패턴, 주요 명령어, 개인 선호도를 사용자 로컬 환경에서 프로젝트별로 MEMORY.md에 자동 저장하고요. 다음 세션 시작 시 이를 불러와 컨텍스트에 반영합니다.

동작 방식​

Auto memory는 별도 설정 없이 자동으로 동작합니다. Claude Code 세션을 시작하고 작업을 진행하면, Claude는 유용한 컨텍스트를 스스로 탐지해 기록하죠.

컨텍스트는 ~/.claude/projects/<project>/memory/ 디렉터리의 MEMORY.md에 저장됩니다. 다음 세션을 시작하면 Claude가 이 파일의 첫 200줄을 자동으로 불러와 컨텍스트에 반영하는데요. 만약 200줄을 초과하면 상세 내용을 별도 토픽 파일로 분리하고, MEMORY.md는 간결한 인덱스 역할을 하도록 구성하는 게 좋습니다.

Claude Code의 메모리는 크게 두 시스템으로 나뉩니다. 하나는 사용자가 직접 작성하는 CLAUDE.md이고, 다른 하나는 Claude가 자동으로 기록하는 Auto memory죠. 두 시스템은 세션 시작 시 로드되며, Auto memory는 CLAUDE.md에 작성한 지침을 대체하지 않고 추가 컨텍스트로 보완합니다.

Auto memory vs. CLAUDE.md 비교​

Auto memory가 있어도 CLAUDE.md는 여전히 필요합니다. 두 기능의 역할은 각각 다르므로 사용하기에 적합한 상황도 차이가 있습니다.

Auto memory (MEMORY.md)CLAUDE.md
작성 주체Claude가 자동으로 기록사람이 주도적으로 관리
내용 성격작업 중 발견한 패턴·선호도규칙·규약·아키텍처 지침
팀 공유기본적으로 로컬 전용git 커밋으로 공유 가능
로딩 방식첫 200줄만 로딩시작 시 전체 로딩

CLAUDE.md를 써야 할 때​

팀 전체가 따라야 하는 코딩 컨벤션, 아키텍처 패턴, 보안 관련 코딩 규칙은 CLAUDE.md에 작성합니다. CLAUDE.md는 git에 커밋되므로 팀원 누구나 동일한 지침을 적용받을 수 있고, 프로젝트 문서로도 활용할 수 있습니다.

Auto memory를 써야 할 때​

개인 작업 스타일, 세션 중 발견한 프로젝트 특이사항, Claude가 반복적으로 참조해야 할 선호도는 Auto memory에 맡깁니다. 다만 로컬에 저장되므로 팀 공유가 필요한 내용은 CLAUDE.md에 직접 옮겨야 합니다.

Auto memory 사용법​

Auto memory는 별도 설정 없이 바로 동작합니다. 세션을 시작하고 Claude와 작업하면 메모리가 자동으로 기록되고, 다음 세션에서 자동으로 로딩됩니다. 지금부터 상태 확인, 메모리 편집, 수동 추가 방법을 살펴보겠습니다.

Auto memory 상태 확인, 설정​

Auto memory는 Claude Code 설치 시 기본으로 활성화돼 있습니다. 현재 상태를 확인하거나 설정을 변경하려면 다음 단계를 따르세요.

  1. Claude Code 세션에서 /memory를 입력합니다.

    `/memory` 명령어 실행 화면 | 인포그랩 GitLab
    /memory 명령어 실행 화면

  2. 상단에 표시된 Auto memory 토글 항목의 현재 상태(on/off)를 확인합니다.

    Auto memory 토글과 메모리 파일 목록 | 인포그랩 GitLab
    Auto memory 토글과 메모리 파일 목록

  3. Auto memory를 활성화하거나 비활성화하려면 토글 항목을 선택한 뒤 Enter를 누릅니다. 누를 때마다 on/off가 전환됩니다.

    Auto memory 비활성 상태 | 인포그랩 GitLab
    Auto memory 비활성 상태

환경 변수로 제어해야 하면 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1로 강제 비활성화할 수 있습니다.

/memory 명령어로 메모리 직접 편집​

Auto memory에 저장된 내용을 직접 확인하고 수정하려면 다음 단계를 따르세요.

  1. 세션 중 /memory를 입력합니다.

    `/memory` 명령어 실행 화면 | 인포그랩 GitLab
    /memory 명령어 실행 화면

  2. 파일 선택기가 열리며, Auto memory 토글과 함께 MEMORY.md, CLAUDE.md 등이 함께 표시됩니다. MEMORY.md를 선택하고 Enter를 누릅니다.

    Auto memory 토글과 메모리 파일 목록 | 인포그랩 GitLab
    Auto memory 토글과 메모리 파일 목록

  3. 시스템 에디터에서 파일이 열립니다. 저장된 내용 전체를 확인하고, 불필요한 항목을 삭제하거나 직접 수정할 수 있습니다.

    Auto memory가 자동 생성한 `MEMORY.md` | 인포그랩 GitLab
    Auto memory가 자동 생성한 MEMORY.md

  4. 수정을 마치면 저장하고 에디터를 닫습니다. 변경 내용은 다음 세션 시작 시 로딩됩니다.

    `MEMORY.md` 편집 화면 | 인포그랩 GitLab
    MEMORY.md 편집 화면

MEMORY.md는 첫 200줄만 자동 로딩됩니다. Claude가 상세 내용을 토픽 파일로 분리하도록 설계돼 있지만, 200줄 범위에 근접하면 직접 내용을 확인하고 중요도가 낮은 항목을 정리하는 것도 좋습니다.

자연어로 기억 요청​

Claude에게 대화 중 기억을 저장하도록 직접 요청할 수 있습니다. 요구사항을 자연어로 입력하면 Claude가 해당 내용을 메모리에 기록합니다.

  1. Claude Code 세션에서 기억할 내용을 자연어로 입력합니다. 예를 들어, “이 프로젝트에서는 npm 대신 pnpm을 사용하는 걸 기억해”라고 입력합니다.

    대화로 프로젝트 규칙을 입력하는 화면 | 인포그랩 GitLab
    대화로 프로젝트 규칙을 입력하는 화면

  2. Claude가 “기억했습니다”라고 응답하면 MEMORY.md에 해당 내용이 저장된 것입니다.

    프로젝트 규칙 입력 후 메모리 저장 완료 화면 | 인포그랩 GitLab
    프로젝트 규칙 입력 후 메모리 저장 완료 화면

  3. 새로운 세션에서 관련 질문을 하면 Claude가 저장된 내용을 바탕으로 답변합니다. 예를 들어, “이 프로젝트의 패키지 매니저가 뭐야?”라고 물으면 이전 세션에서 저장한 “pnpm”을 기억하고 답합니다.

    새 세션에서 메모리에 저장된 pnpm 규칙을 응답하는 모습 | 인포그랩 GitLab
    새 세션에서 메모리에 저장된 pnpm 규칙을 응답하는 모습

코딩 컨벤션, 자주 쓰는 명령어, 프로젝트 특이사항 등 Claude가 반복적으로 참조해야 할 내용을 등록할 때 유용합니다.

유의 사항​

Auto memory를 효율적이고 안전하게 활용하려면 다음 사항을 유의해야 합니다.

1. MEMORY.md 주기적 정리​

Auto memory는 Claude가 유용하다고 판단한 내용을 자동으로 기록합니다. 그러나 시간이 지나면 Auto memory의 내용이 사용자에게 더 이상 유효하지 않을 수 있는데요. MEMORY.md는 첫 200줄만 로딩되므로 오래된 내용이 한도를 많이 차지하면, 중요한 최신 컨텍스트가 잘릴 수 있죠. 따라서 /memory로 파일을 열어 완료된 작업의 맥락, 중복된 선호도, 유효하지 않은 패턴을 주기적으로 정리하는 걸 권장합니다. 또 Claude가 사용자 의도와 다르게 기록할 가능성이 있어 새로 추가된 내용의 정확성도 함께 확인하는 게 좋고요.

2. CLAUDE.md와 Auto memory 병행 관리​

Auto memory는 사용자 홈 디렉터리(~/.claude/projects/<project>/memory/)에 저장되므로 기록된 내용이 다른 팀원에게 전파되지 않습니다. 팀 전체가 공유해야 하는 코딩 컨벤션이나 아키텍처 결정은 CLAUDE.md에 명시하고 git으로 관리해야 팀원 모두가 동일한 지침을 따를 수 있습니다.

3. 민감 정보 자동 저장 주의​

MEMORY.md는 로컬 파일 시스템에 평문으로 저장되므로, 해당 머신에 접근할 수 있으면 누구나 내용을 열람할 수 있습니다. API 키나 비밀번호와 같은 민감 정보가 작업 중에 자동으로 저장될 가능성을 완전히 배제할 수 없는데요. 민감 정보가 포함된 작업을 할 때는 Auto memory를 비활성화하거나, 작업 후 /memory로 파일을 열어 민감 정보 기록 여부를 확인하는 걸 권장합니다. 실수로 저장됐다면 해당 내용을 직접 삭제하면 되고요.

맺음말​

지금까지 Claude Code Auto memory의 주요 기능과 동작 방식, 특징, 사용법, 유의 사항을 살펴봤습니다. 이 글의 요점은 다음과 같은데요.

  1. Auto memory는 Claude Code가 작업 중 파악한 유용한 컨텍스트를 자동으로 기록하고, 이후 세션에서 다시 불러오는 자동 메모리 기능입니다.
  2. CLAUDE.md가 팀이 주도적으로 관리하는 규칙·지침 파일이라면, Auto memory는 Claude가 자동으로 기록하는 개인 작업 패턴·선호도 파일입니다. 두 기능의 역할은 다르므로 상황에 맞춰 병행해서 사용하는 게 좋습니다.
  3. Auto memory는 기본으로 활성화돼 있으며, /memory 명령어로 상태 확인·토글 전환·직접 편집이 가능합니다. 자연어로 기억을 요청할 수도 있죠.
  4. MEMORY.md는 첫 200줄만 로딩됩니다. 따라서 주기적으로 오래된 항목을 정리하고, 팀 공유가 필요한 내용은 CLAUDE.md에 옮겨 git으로 관리해야 합니다.
  5. MEMORY.md는 로컬에 평문으로 저장되므로 민감 정보가 자동 저장될 가능성에 유의해야 합니다. 민감 정보가 포함된 작업을 할 때는 Auto memory를 비활성화하거나, 필요 시 파일에서 해당 정보를 직접 삭제하는 걸 권장합니다.

참고 자료​

  1. “How Claude remembers your project”, Anthropic, https://code.claude.com/docs/en/memory
  2. “The CLAUDE.md Memory System”, SFEIR Institute, https://institute.sfeir.com/en/claude-code/claude-code-memory-system-claude-md/
  3. “The CLAUDE.md Memory System - Optimization Guide”, SFEIR Institute, https://institute.sfeir.com/en/claude-code/claude-code-memory-system-claude-md/optimization/
  4. claude-mem GitHub 리포지터리, https://github.com/thedotmack/claude-mem

우리 회사에 딱 맞는 DevSecOps 관행과 프레임워크를 찾고 계시나요? DevOps 전문가, 인포그랩과 상담하세요!