claude-mem: Claude Code에 영구 메모리를 추가하는 방법

claude-mem은 Claude Code용 영구 메모리 압축 시스템으로, 세션 간 컨텍스트를 자동 보존하여 개발 생산성을 획기적으로 높이는 오픈소스 플러그인입니다.

Claude Code를 사용하는 개발자라면 한 번쯤 겪어봤을 겁니다. 어제 열심히 디버깅한 내용, 프로젝트 아키텍처 결정, 코딩 컨벤션 합의 — 세션을 닫는 순간 claude-mem 없이는 모두 사라집니다. 매 세션마다 프로젝트를 처음부터 다시 설명해야 하는 비효율이 반복되죠.

claude-mem은 GitHub 스타 44,900개를 돌파하며 이 문제의 표준 해법으로 자리잡았습니다. 이 글에서는 claude-mem의 작동 원리, 설치 방법, 실제 효과를 상세히 다룹니다.

AI 코딩 어시스턴트의 기억 상실 문제

모든 Claude Code 세션은 빈 컨텍스트 창으로 시작합니다. 이전 세션에서 아무리 깊이 있는 작업을 했더라도, 새 세션을 열면 Claude는 다음을 전혀 기억하지 못합니다:

• 프로젝트 아키텍처 결정: "왜 이 패턴을 선택했는지" 매번 재설명
• 디버깅 과정과 해결 방법: 같은 버그를 다시 조사하는 시간 낭비
• 코딩 컨벤션과 선호사항: 일관성 없는 코드 스타일
• 지난 리팩토링 맥락: 이전 작업의 연속성 단절

기존 대안인 CLAUDE.md 파일은 정적이며 수동 관리가 필요합니다. 시맨틱 검색도 지원하지 않아, 프로젝트 규모가 커질수록 관리 부담이 기하급수적으로 증가합니다.

claude-mem의 해결 방식: Capture → Compress → Inject

claude-mem은 세 단계의 파이프라인으로 작동합니다.

1단계: Capture (자동 캡처)

5개의 Lifecycle Hook이 세션 중 Claude의 모든 도구 실행을 자동으로 기록합니다:

매 도구 실행마다 PostToolUse 훅이 발동하므로, 세션당 100회 이상의 관찰이 자동으로 축적됩니다.

2단계: Compress (AI 압축)

Claude Agent SDK를 활용하여 수집된 raw 데이터를 지능적으로 압축합니다:

• Raw 도구 출력: 1,000~10,000 토큰
• 압축된 관찰: ~500 토큰 (최대 20배 압축)
• 관찰 타입 자동 분류: decision, bugfix, feature, refactor, discovery, change
• 개념 태그와 파일 참조 자동 추출

3단계: Inject (자동 주입)

다음 세션 시작 시 관련 컨텍스트가 자동으로 주입됩니다. Progressive Disclosure 방식으로 토큰 효율을 극대화합니다.

기술 아키텍처 분석

claude-mem의 기술 스택은 다음과 같습니다:

핵심은 SQLite와 ChromaDB의 하이브리드 검색 구조입니다. 키워드 기반 정확 매칭(FTS5)과 의미 기반 유사도 검색(ChromaDB)을 결합하여, "지난주 인증 관련 리팩토링"같은 자연어 쿼리로 정확한 컨텍스트를 찾을 수 있습니다.

Progressive Disclosure: 토큰 효율의 핵심

claude-mem의 MCP 검색 도구는 3계층 Progressive Disclosure 패턴을 사용합니다:

1. search — 컴팩트 인덱스 반환 (~50-100 토큰/결과)
2. timeline — 시간순 컨텍스트 제공
3. get_observations — 전체 상세 정보 (~500-1,000 토큰/결과)

상세 정보를 먼저 필터링한 후 가져오므로, 기존 방식 대비 약 10배의 토큰 절약 효과가 있습니다. 대규모 프로젝트에서 수백 개의 관찰이 축적되어도 효율적으로 필요한 맥락만 검색할 수 있습니다.

설치 방법

설치는 놀라울 정도로 간단합니다:

# 방법 1: npx (권장)
npx claude-mem install

# 방법 2: Claude Code 플러그인 마켓플레이스
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

# 방법 3: Gemini CLI 사용자
npx claude-mem install --ide gemini-cli

요구사항: Node.js 18+, Bun (자동 설치), SQLite 3 (번들 포함)

설치 후 별도 설정 없이 바로 작동합니다. Worker Service가 port 37777에서 HTTP API와 Web Viewer를 제공하며, http://localhost:37777에서 실시간 메모리 스트림을 확인할 수 있습니다.

실제 효과: 개발자 피드백 기반

claude-mem 사용자들의 실측 데이터를 종합하면:

특히 코드 컨벤션 준수율의 변화가 주목할 만합니다. 메모리 없이는 30%에 불과했던 컨벤션 준수율이 85%까지 올라간다는 것은, claude-mem이 단순한 편의 도구가 아닌 코드 품질 향상 도구라는 의미입니다.

주요 기능 상세

Privacy Control

<private>API_KEY=sk-abc123...</private>

<private> 태그로 감싼 내용은 메모리 저장에서 자동 제외됩니다. API 키, 비밀번호, 민감한 비즈니스 로직을 안전하게 보호할 수 있습니다.

Mode System

Code, Email Investigation, Chill 등 다양한 모드를 지원하여 작업 맥락에 맞는 메모리 관리가 가능합니다.

Knowledge Agents

축적된 관찰 이력에서 질의 가능한 "브레인"을 구축합니다. 프로젝트의 의사결정 히스토리를 장기적으로 보존하고 검색할 수 있습니다.

Web Viewer

http://localhost:37777에서 실시간 메모리 스트림을 시각적으로 확인할 수 있습니다. React + TypeScript 기반의 직관적인 UI로 관찰 타입, 시간순 흐름, 개념 태그를 한눈에 파악 가능합니다.

대안 도구 비교

claude-mem의 가장 큰 장점은 Claude Code에 네이티브로 통합된다는 점과, 44,900개 이상의 GitHub 스타가 증명하는 활발한 커뮤니티입니다.

한계와 주의사항

claude-mem을 도입하기 전에 알아야 할 점들이 있습니다:

• 관찰 생성 시 추가 시간: 도구 호출당 60-90초 추가 (대부분 비동기 처리)
• macOS 안정성: 간헐적 프로세스 충돌이 보고됨
• Windows 호환성: 일부 이슈 존재
• 검색 품질 벤치마크 미공개: Mem0의 LOCOMO 같은 공식 벤치마크 부재
• AGPL-3.0 라이선스: 서버에 배포하는 경우 소스 공개 의무 발생

자주 묻는 질문 (FAQ)

Q: claude-mem은 무료인가요? A: 네, AGPL-3.0 라이선스의 오픈소스 프로젝트입니다. 개인 개발 환경에서 무료로 사용 가능합니다.

Q: 기존 CLAUDE.md와 함께 사용할 수 있나요? A: 네, claude-mem은 기존 CLAUDE.md를 대체하지 않고 보완합니다. CLAUDE.md는 정적 설정 파일로, claude-mem은 동적 세션 메모리로 역할이 다릅니다.

Q: 얼마나 많은 메모리를 저장할 수 있나요? A: SQLite 기반이므로 사실상 무제한입니다. 다만 Progressive Disclosure 패턴으로 검색 시 최적의 결과만 반환합니다.

Q: Gemini CLI에서도 작동하나요? A: 네, npx claude-mem install --ide gemini-cli 명령으로 Gemini CLI에서도 사용 가능합니다.

마무리: 세션의 끝이 기억의 끝이 아닌 시대

claude-mem은 AI 코딩 어시스턴트의 근본적 한계였던 "세션 간 기억 상실"을 해결합니다. Capture → Compress → Inject의 단순한 파이프라인이, 개발자 경험을 근본적으로 변화시키고 있습니다.

Claude Code를 매일 사용하는 개발자라면, npx claude-mem install 한 줄로 시작해보세요. 세션이 바뀌어도 컨텍스트가 이어지는 경험은, 한번 맛보면 돌아가기 어렵습니다.

참고 자료

• claude-mem 공식 GitHub
• claude-mem 공식 문서
• Augment Code: claude-mem 46K Stars 분석
• Better Stack: claude-mem 가이드
• Bridgers Agency: 아키텍처 심층 리뷰