Claude-MEM 사용 가이드 - AI에게 장기 기억을 달아주는 플러그인
Claude Code는 대화가 끝나면 모든 걸 잊어버립니다. Claude-MEM은 이 문제를 해결하는 플러그인으로, 설치만 하면 자동으로 버그 수정, 새 기능, 의사결정을 백그라운드에서 기록하고 다음 세션에서 검색해서 정확히 알려줍니다.
TL;DR (3줄 요약)
- Claude Code는 대화가 끝나면 모든 걸 잊어버림 -> Claude-MEM이 장기 기억을 달아줌
- 설치만 하면 자동으로 동작 - 버그 수정, 새 기능, 의사결정을 백그라운드에서 기록
- 다음 세션에서 “지난번에 어떻게 했었지?” 물어보면 검색해서 정확히 알려줌
이 가이드가 필요한 이유
Claude Code(터미널에서 쓰는 AI 코딩 도구)는 대화가 끝나면 모든 걸 잊어버립니다.
어제 같이 3시간 동안 버그 잡았던 거? 기억 못 합니다. 지난주에 “이 설정은 이렇게 바꾸면 안 돼"라고 알려줬던 거? 역시 기억 못 합니다.
Claude-MEM은 이 문제를 해결합니다. AI에게 장기 기억을 달아주는 플러그인입니다.
같은 말 두 번 안 해도 됩니다. 그게 Claude-MEM의 핵심 가치입니다.
Claude-MEM 없이 vs 있으면
| 상황 | Claude-MEM 없이 | Claude-MEM 있으면 |
|---|---|---|
| 어제 고친 버그가 또 나옴 | “이 버그 처음 보는데요?” | “어제 이 버그 고쳤었는데, 원인은 A였고, B로 해결했습니다” |
| 프로젝트 설정 물어봄 | 매번 처음부터 파일 읽고 분석 | “지난 세션에서 확인한 설정입니다” |
| “지난번에 어떻게 했더라?” | 대답 불가 | 검색해서 정확히 알려줌 |
| 같은 실수 반복 | 매번 같은 삽질 | “이전에 이 방법은 안 됐습니다. 대신 B를 쓰세요” |
어떻게 동작하나요? (원리)
Claude-MEM은 백그라운드에서 자동으로 돌아갑니다. 여러분이 특별히 뭘 할 필요 없습니다.
여러분이 Claude Code로 작업
↓
Claude-MEM이 자동으로 중요한 내용을 기록 (관찰 기록)
↓
SQLite 데이터베이스에 저장
↓
다음 세션에서 필요할 때 검색해서 꺼내 씀
자동으로 기록되는 것들
| 종류 | 아이콘 | 예시 |
|---|---|---|
| 버그 수정 | – | “JWT 토큰 만료 시간 버그 수정” |
| 새 기능 | – | “로그인 API 추가” |
| 리팩토링 | – | “인증 모듈 구조 변경” |
| 코드 변경 | – | “설정 파일 경로 수정” |
| 발견 사항 | – | “이 라이브러리는 v3부터 API가 바뀜” |
| 의사결정 | – | “Redis 대신 SQLite를 선택한 이유” |
여러분이 코딩하는 동안 Claude-MEM이 알아서 “아, 이건 기억해둘 만한 거네” 하고 저장합니다.
실제로 쓰는 방법
1. 자동 기억 (아무것도 안 해도 됨)
그냥 평소대로 Claude Code를 쓰세요. Claude-MEM이 백그라운드에서 알아서 기록합니다.
- 세션 시작할 때: 이전 작업 내용을 자동으로 불러옴
- 작업 중: 도구를 쓸 때마다 중요한 내용을 자동 기록
- 세션 끝날 때: 이번 세션에서 한 일을 자동 요약
팁: 특별히 뭔가 설정하거나 명령어를 외울 필요 없습니다. 그냥 쓰면 됩니다.
2. 과거 기억 검색하기
Claude Code에서 그냥 자연어로 물어보면 됩니다:
"지난번에 인증 관련해서 뭘 했었지?"
"저번 주에 고친 버그들 보여줘"
"도커 설정 어떻게 바꿨었는지 기억나?"
또는 스킬 명령어를 직접 쓸 수도 있습니다:
/claude-mem:mem-search 인증 버그
3. 중요한 걸 직접 기억시키기
자동 기록만으로 부족할 때, 직접 기억시킬 수도 있습니다:
"이거 기억해둬: GitLab 러너는 반드시 docker executor로 설정해야 해.
shell executor는 권한 문제가 생김"
Claude가 save_memory 도구를 사용해서 저장합니다.
검색이 똑똑하게 동작하는 이유 (3단계 검색)
Claude-MEM은 기억을 찾을 때 3단계로 검색합니다. 이건 비용(토큰)을 아끼면서도 정확한 결과를 주기 위한 설계입니다.
[1단계] 검색 (search)
"인증" 관련 기록 20개의 제목만 가져옴 ← 가볍다 (제목만)
↓
[2단계] 맥락 파악 (timeline)
관심 있는 기록 주변에 뭐가 있었는지 확인 ← 전후 사정 파악
↓
[3단계] 상세 조회 (get_observations)
정말 필요한 2~3개만 전체 내용을 가져옴 ← 필요한 것만 꺼냄
왜 이렇게 하냐면:
- 1단계 결과 1개 = 약 50~100 토큰 (제목 수준)
- 3단계 결과 1개 = 약 500~1,000 토큰 (전체 내용)
- 20개를 다 가져오면 20,000 토큰, 필요한 3개만 가져오면 3,000 토큰
- 약 10배 절약
토큰이란? AI에게 보내는 글자 단위입니다. 토큰을 많이 쓰면 느려지고 비용이 올라갑니다. 한글 한 글자가 보통 2~3 토큰 정도입니다.
제공되는 명령어 (스킬)
/claude-mem:mem-search - 기억 검색
과거 세션에서 했던 작업을 검색합니다.
/claude-mem:mem-search 도커 설정 변경
검색 조건을 세밀하게 줄 수도 있습니다:
| 조건 | 설명 | 예시 |
|---|---|---|
query |
검색어 | “인증”, “도커” |
type |
검색 대상 | “observations” (기록), “sessions” (세션), “prompts” (질문) |
obs_type |
기록 종류 | “bugfix”, “feature”, “decision”, “discovery”, “change” |
dateStart |
시작일 | “2026-01-01” |
dateEnd |
종료일 | “2026-02-07” |
project |
프로젝트 | “homelab” |
/claude-mem:make-plan - 실행 계획 만들기
복잡한 작업을 단계별 계획으로 정리합니다. 여러 세션에 걸쳐 작업할 때 유용합니다.
/claude-mem:make-plan GitLab CI/CD 파이프라인에 자동 배포 추가
이렇게 하면:
- 관련 문서를 먼저 찾아봄 (문서 탐색 단계)
- 단계별로 뭘 해야 하는지 정리
- 각 단계마다 검증 방법까지 포함
- 세션이 바뀌어도 이어서 할 수 있게 구성
/claude-mem:do - 계획 실행하기
make-plan으로 만든 계획을 실제로 실행합니다.
/claude-mem:do 위에서 만든 배포 계획 실행
이렇게 하면:
- 각 단계를 하위 에이전트에게 위임
- 단계별로 검증 후 다음으로 진행
- 문제가 생기면 멈추고 보고
프로젝트 모드
Claude-MEM은 작업 성격에 따라 기록 방식을 조절합니다.
기본 모드 (code)
모든 작업을 꼼꼼하게 기록합니다. 새 프로젝트나 학습 중일 때 좋습니다.
느긋한 모드 (code–chill)
“다시 찾기 힘든 것만” 골라서 기록합니다. 반복적인 작업이 많을 때 좋습니다.
- 배포한 기능, 고친 버그, 아키텍처 결정 -> 기록함
- 이미 있는 패턴 따라한 것, 단순 반복 작업 -> 건너뜀
실전 활용 시나리오
시나리오 1: “저번에 이 에러 어떻게 고쳤더라?”
나: "traefik 502 에러 어떻게 고쳤었는지 기억나?"
Claude: (claude-mem에서 검색)
"2주 전에 같은 이슈가 있었습니다.
원인: health check 경로가 잘못 설정됨
해결: traefik.yml에서 healthcheck path를 /health → /ping으로 변경
관련 파일: infrastructure/proxy/traefik/traefik.yml"
핵심: 에러 원인과 해결 방법을 즉시 알려줍니다. 같은 삽질을 반복하지 않아도 됩니다.
시나리오 2: 프로젝트 인수인계
새로운 세션에서 프로젝트를 이어받을 때:
나: "이 프로젝트에서 지금까지 뭘 했었어?"
Claude: (claude-mem에서 전체 기록 조회)
"최근 작업 요약:
1. Caddy + Traefik 프록시 구조 설정 (1/15)
2. GitLab CE 도커 설치 및 SSL 설정 (1/20)
3. n8n 워크플로우 자동화 연동 (1/25)
4. Telegram 봇에 /ask 명령어 추가 (2/01)
..."
시나리오 3: 의사결정 근거 추적
나: "왜 n8n을 호스트 네트워크 모드로 설정했었지?"
Claude: (claude-mem에서 decision 타입 검색)
"1월 25일 세션에서 결정한 내용입니다:
이유: n8n에서 호스트의 Claude Code SSH에 접근해야 하는데,
브릿지 네트워크에서는 localhost 접근이 안 됨.
대안 검토: extra_hosts 설정도 시도했지만 SSH 포트 매핑 이슈로 포기"
왜 중요하냐면: 시간이 지나면 “왜 이렇게 했지?” 기억이 안 납니다. Claude-MEM이 그 이유까지 기록해두니까, 나중에 설정을 변경할 때 실수를 방지할 수 있습니다.
데이터는 어디에 저장되나요?
모든 데이터는 로컬(내 컴퓨터)에만 저장됩니다. 외부 서버로 전송되지 않습니다.
~/.claude/ # Claude Code 설정 폴더
├── plugins/
│ └── cache/thedotmack/claude-mem/ # 플러그인 코드
└── ...
데이터: SQLite 데이터베이스 (로컬 저장)
자주 묻는 질문
Q: 설치하면 바로 쓸 수 있나요?
네. 이미 설치되어 있으므로, 그냥 Claude Code를 쓰면 됩니다. 자동으로 기록하고, 자동으로 불러옵니다.
Q: 기억을 삭제할 수 있나요?
현재는 개별 기억 삭제 기능은 제공하지 않습니다. SQLite DB를 직접 조작하면 가능합니다.
Q: 기록이 너무 많으면 느려지나요?
3단계 검색 구조 덕분에 기록이 많아져도 성능 영향이 적습니다. 제목만 먼저 가져오고, 필요한 것만 상세 조회하니까요.
Q: 프로젝트별로 기억이 분리되나요?
네. project 파라미터로 프로젝트별 기억을 분리할 수 있습니다. 검색할 때도 프로젝트를 지정하면 해당 프로젝트 기록만 나옵니다.
Q: 이 플러그인이 내 코드를 외부로 보내나요?
아닙니다. 모든 데이터는 로컬 SQLite에 저장됩니다. MCP 서버도 로컬에서 실행됩니다.
한 줄 정리
| 항목 | 내용 |
|---|---|
| 뭔가요 | Claude Code에 장기 기억을 달아주는 플러그인 |
| 왜 쓰나요 | 세션이 바뀌어도 이전 작업 내용을 기억하게 하려고 |
| 어떻게 쓰나요 | 설치만 하면 자동으로 동작. 검색은 자연어로 물어보면 됨 |
| 뭘 기억하나요 | 버그 수정, 새 기능, 설정 변경, 의사결정 등 |
| 데이터는 어디에 | 내 컴퓨터 로컬에만 저장 (외부 전송 없음) |
| 핵심 명령어 | /claude-mem:mem-search, /claude-mem:make-plan, /claude-mem:do |
다음 단계: 지금 바로 Claude Code를 열고 아무 작업이나 해보세요. 다음 세션에서 “지난번에 뭘 했었지?” 하고 물어보면, Claude-MEM이 기억하고 있을 겁니다.
