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


# 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`에서 실시간 메모리 스트림을 확인할 수 있습니다.

## 실제 효과

| 지표 | 개선 효과 |
|------|----------|
| 세션당 토큰 절약 | ~2,250 토큰 |
| 컨텍스트 재설명 시간 | ~60% 감소 |
| 코드 컨벤션 준수율 | 30% → 85% |
| 기능 구현 시간 | ~50% 단축 |

## 설치

```bash
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](https://github.com/thedotmack/claude-mem)
- [공식 문서](https://docs.claude-mem.ai)