배경 및 맥락

Claude Code 같은 AI 코딩 어시스턴트의 가장 큰 약점 중 하나는 "세션 기한"입니다. 대화 윈도우가 종료되면 그 동안 AI가 학습한 프로젝트의 아키텍처, 버그 수정 이력, 설계 결정 등이 모두 사라집니다. 사용자가 다음 날 같은 프로젝트로 돌아올 때, AI는 마치 처음 보는 프로젝트처럼 다시 전체 컨텍스트를 요청하게 됩니다. 이는 토큰 낭비이자 개발 생산성 저하로 이어집니다.

특히 수개월 지속되는 장기 프로젝트에서는 이 문제가 치명적입니다. 매 세션마다 "이전에 우리는 왜 이렇게 설계했나?", "지난주 버그는 뭐였지?" 같은 컨텍스트를 다시 제공해야 합니다. 이런 배경에서 "Claude Code를 위한 영구 메모리 시스템"이라는 아이디어가 나왔고, claude-mem이 실질적인 해결책을 제시합니다.

---

핵심 내용

claude-mem은 Claude Code 세션 간 컨텍스트를 자동으로 보존하는 플러그인입니다. 핵심 메커니즘은 간단하지만 강력합니다: "Claude가 하는 모든 것을 기록하고, AI로 압축한 후, 다음 세션에서 관련 컨텍스트를 자동으로 주입"합니다.

작동 원리:

1. SessionStart: 새 세션이 시작되면, claude-mem이 과거 세션의 요약 인덱스 조회
2. UserPromptSubmit: 사용자 질문이 들어오면, Chroma 벡터 DB에서 관련 메모리 검색
3. PostToolUse: Claude가 도구를 사용할 때마다 결과를 메모리에 저장
4. SessionEnd: 세션 종료 시 대화 전체를 AI로 압축하여 SQLite에 저장

3계층 토큰 최적화 워크플로우:

1. search: 요약 인덱스 조회 (약 50~100 토큰) - "이 질문과 관련된 과거 세션이 있나?"
2. timeline: 특정 결과 주변의 시간순 컨텍스트 확인 (추가 100~200 토큰) - "그 결정 전후로 뭐가 있었나?"
3. get_observations: 필요한 ID의 전체 상세 정보만 수집 (500~1,000 토큰) - "상세 정보 필요할 때만"

이 3단계 구조로 "전체 컨텍스트 로드"와 비교해 약 10배의 토큰 절감을 달성합니다.

아키텍처 구성요소:

컴포넌트	역할
5개 생명주기 훅	SessionStart, UserPromptSubmit, PostToolUse, SessionEnd, Stop - Claude Code의 핵심 이벤트 포착
SQLite 데이터베이스	세션 메타데이터, 각 도구 호출(observations), AI 생성 요약 저장
Chroma 벡터 DB	하이브리드 검색 (의미론적 + 키워드) - "벡터 임베딩"으로 의미 기반 유사성 매칭
Worker Service	Express API (port 37777), Bun 런타임으로 관리 - claude-mem의 백엔드 서버
mem-search 스킬	단계적 공개 기반 쿼리 - 필요할 때만 상세 정보 검색
Viewer UI	React 기반 웹 대시보드 (localhost:37777) - 메모리 상태 시각화 및 수동 편집

주요 기능:

• 자동 컨텍스트 캡처: Claude가 파일 생성, 수정, 실행한 모든 것을 기록
• Smart Compression: 대화를 의미를 유지하면서 토큰 기준으로 압축
• 시맨틱 검색: 벡터 임베딩으로 키워드가 아닌 "의미" 기반 검색
• 자동 주입: 새 세션 시작 시 관련 메모리가 자동으로 로드되어 있음 (사용자가 재입력 불필요)
• Smart Trash: 삭제된 데이터도 복구 가능
• 세션 재개: SDK 세션 ID로 예전 대화 재개

설치 및 사용:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
# Claude Code 재시작

설치 후 즉시 이전 세션의 관련 메모리가 표시되기 시작합니다.

설정 커스터마이징 (~/.claude-mem/settings.json):

• AI 압축에 사용할 모델 선택 (Claude, Gemini 등)
• Worker 포트 변경
• 데이터 디렉토리 위치
• 로그 레벨
• 컨텍스트 주입 자동화 수준

---

경쟁 구도 / 비교

현재 Claude Code 사용자들의 대안:

방식	장점	단점
아무것도 안 함 (기본)	설치 불필요	매 세션 컨텍스트 재입력, 토큰 낭비, 생산성 저하
수동으로 README 유지	간단	시간 소비, 대화 기록 손실, 불완전
claude-mem	자동화, 토큰 절감, 의미 기반 검색	37777 포트 점유, SQLite/Chroma 의존
대안 1: 로컬 RAG (LLamaIndex)	매우 유연	직접 구현 필요, 유지보수 복잡
대안 2: 외부 서비스 (Langsmith, Helicone)	웹 기반 통합	데이터 외부 노출, 구독료 발생

claude-mem의 가장 큰 강점은 로컬 전용 저장과 Claude Code 네이티브 통합입니다. 데이터가 절대 외부로 나가지 않으면서도 플러그인 형식으로 seamless 통합됩니다.

---

의미

Claude Code 사용 패턴의 변화:

claude-mem은 "일회성 세션"에서 "장기 프로젝트 개발 환경"으로 AI 어시스턴트의 역할을 확대합니다. 사용자는 "이번 세션에서 얼마나 할 수 있나?"가 아니라 "이 프로젝트를 완성하려면 몇 세션이 필요한가?"로 사고방식을 전환할 수 있습니다.

토큰 경제학의 재정의:

claude-mem 없는 상태에서 장기 프로젝트는 토큰 폭증의 악순환을 겪습니다. 각 세션마다 전체 아키텍처를 다시 설명하기 때문입니다. claude-mem은 이를 구조화된 메모리 + 3계층 검색으로 해결하여, 결과적으로 전체 프로젝트 토큰 소비를 50~70% 절감할 수 있게 합니다.

협업 개발의 새로운 가능성:

여러 개발자가 같은 프로젝트에서 Claude Code를 사용할 때, claude-mem은 "팀의 공유 지식 기반" 역할을 합니다. 한 개발자가 발견한 버그, 작성한 아키텍처 결정이 다른 개발자가 실수하지 않도록 자동으로 공유됩니다.

앞으로의 전망:

• 표준화 가능성: claude-mem의 아키텍처(생명주기 훅, 메모리 저장소)가 향후 Claude Code 공식 기능으로 통합될 수 있는 기초를 제시합니다.
• 멀티에이전트 통합: claude-mem 같은 메모리 시스템이 oh-my-ag 같은 멀티에이전트 프레임워크와 결합되면, AI 팀 전체가 프로젝트 히스토리를 공유하는 "집단 지능" 형태의 개발이 가능해집니다.
• 엔터프라이즈 버전: 조직 수준의 메모리 관리, 감사 로그(audit trail), 다중 프로젝트 관리 기능을 갖춘 상용 버전이 출현할 가능성.