Memory: 세션을 넘어 축적되는 프로젝트 학습 기록 #
Memory는 Claude가 세션을 넘어 프로젝트별 학습 내용을 기억하는 공간입니다.
CLAUDE.md가 사람이 작성한 규칙이라면, Memory는 작업 중 반복해서 배운 사실과 디버깅 패턴을 축적하는 용도입니다.
즉, CLAUDE.md는 “앞으로 항상 이렇게 일하라”는 명시적 운영 규칙이고, Memory는 “이 프로젝트를 다루다 보니 이런 문제가 반복되더라”는 경험 기반 노트에 가깝습니다.
~/.claude/projects/<project>/memory/
├── MEMORY.md
├── debugging.md
├── opensearch.md
├── db-migrations.md
└── mcp-server.md
Memory에 남기기 좋은 내용:
- 같은 실수를 두 번 이상 수정한 경우
- Claude가 자주 잊는 실행 순서, 테스트 명령, 환경 조건
- 프로젝트별 인덱스명, 포트, 마이그레이션 주의사항
- 다음 세션에도 유용한 디버깅 원인과 해결법
저장하면 안 되는 내용:
- 실제 비밀번호, 토큰, 인증키
- 운영 DB 접속 정보
- 개인 식별 정보나 민감한 사용자 정보
- 일회성으로만 필요한 임시 정보
Claude Memory 작성 방식 #
Memory는 일반 Markdown 파일로 관리할 수 있습니다.
Claude Code에서는 /memory 명령으로 현재 세션에 로드된 CLAUDE.md, CLAUDE.local.md, rules 파일을 확인하고, auto memory 폴더를 열어 직접 편집할 수 있습니다.
또한 “이 내용을 기억해줘”, “API 테스트에는 Redis가 필요하다는 점을 기억해”처럼 요청하면 Claude가 auto memory에 저장할 수 있습니다.
반대로 명시적으로 규칙 파일에 넣고 싶다면 “이 내용을 CLAUDE.md에 추가해줘”라고 구분해서 지시하는 것이 좋습니다.
Memory는 다음처럼 요약 인덱스 + 주제별 상세 파일 구조로 쓰는 것이 좋습니다.
# debugging.md
## API 테스트 실패: Redis 연결 오류
### 증상
- `pnpm test:api` 실행 시 Redis connection refused 발생
### 원인
- 테스트 환경에서 Redis mock을 사용하지 않고 실제 로컬 Redis에 연결함
### 해결
- 테스트 전 `docker compose up -d redis` 실행
- CI에서는 `services.redis` 설정 확인
CLAUDE.md와의 연계 방식 #
CLAUDE.md에는 Memory의 세부 내용을 길게 복사하기보다, 어떤 Memory 파일을 언제 참고해야 하는지만 짧게 적는 것이 좋습니다.
예를 들어 다음처럼 연결합니다.
## Memory Usage
- 반복 디버깅 패턴은 `~/.claude/projects/<project>/memory/debugging.md`를 참고한다.
- OpenSearch 관련 작업 전에는 memory의 `opensearch.md`를 먼저 확인한다.
- DB migration 수정 전에는 memory의 `db-migrations.md`에 기록된 주의사항을 확인한다.
이렇게 하면 CLAUDE.md는 짧은 운영 규칙으로 유지되고, 세부 경험치는 Memory에 누적됩니다.
MEMORY.md는 세션 시작 시 일부가 로드되며, 긴 상세 노트는 별도 주제 파일로 분리해 필요할 때 읽는 방식이 권장됩니다.
MEMORY.md는 첫 200줄 또는 25KB 중 먼저 도달하는 범위까지만 시작 시 로드되고, debugging.md, patterns.md 같은 주제 파일은 필요할 때 Claude가 파일 도구로 읽는 구조입니다.
