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

Claude Code를 사용하는 개발자의 가장 큰 불편함은 세션 간 기억 상실입니다. 세션을 닫는 순간, 프로젝트 아키텍처 결정, 디버깅 이력, 코딩 컨벤션이 모두 사라집니다.

claude-mem은 GitHub 44,900+ Stars를 기록하며 이 문제의 표준 해법으로 자리잡은 영구 메모리 플러그인입니다.

작동 원리: Capture → Compress → Inject

Capture (자동 캡처)

5개 Lifecycle Hook이 세션 중 모든 도구 실행을 자동 기록합니다. SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd — 세션당 100회 이상의 관찰이 축적됩니다.

Compress (AI 압축)

Claude Agent SDK로 raw 데이터를 지능적으로 압축합니다. 1만 토큰짜리 로그가 500 토큰의 구조화된 관찰로 변환됩니다. decision, bugfix, feature, refactor, discovery, change 6가지 타입으로 자동 분류됩니다.

Inject (자동 주입)

다음 세션 시작 시 이전 10개 세션의 요약이 자동 로드됩니다. Progressive Disclosure 패턴으로 토큰 효율 ~10배를 달성합니다.

기술 아키텍처

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

Worker Service가 port 37777에서 HTTP API와 Web Viewer를 제공하며, http://localhost:37777에서 실시간 메모리 스트림을 확인할 수 있습니다.

실제 효과

설치

npx claude-mem install

Node.js 18+ 필요. Bun과 SQLite는 자동 설치됩니다. Gemini CLI에서도 --ide gemini-cli 옵션으로 사용 가능합니다.

주의사항

• 도구 호출당 60-90초 추가 (대부분 비동기)
• macOS 간헐적 프로세스 충돌
• AGPL-3.0 라이선스 (서버 배포 시 소스 공개 의무)

마무리

npx claude-mem install 한 줄로 시작할 수 있습니다. 세션이 바뀌어도 컨텍스트가 이어지는 경험은, 한번 써보면 돌아가기 어렵습니다.

• GitHub
• 공식 문서