claude-mem - Claude Code 세션 간 컨텍스트를 자동 보존하는 메모리 시스템
목차
개요
Claude Code를 사용하다 보면 세션이 종료되거나 컨텍스트가 리셋될 때 이전 작업 내용이 모두 사라지는 문제를 경험하게 됩니다.
claude-mem은 이러한 문제를 해결하기 위해 개발된 플러그인으로, 세션 간 컨텍스트를 자동으로 보존하여 Claude가 프로젝트 지식을 지속적으로 유지할 수 있게 합니다.
이 글에서는 claude-mem의 핵심 기능, 기술 아키텍처, 설치 방법, 그리고 효율적인 사용 방법에 대해 자세히 살펴보겠습니다.
claude-mem이란
claude-mem은 Claude Code 개발 환경을 위한 지속적 메모리 압축 시스템입니다.
탄생 배경
AI 코딩 어시스턴트의 가장 큰 한계 중 하나는 컨텍스트 윈도우의 제한입니다.
세션이 길어지거나 종료되면 이전에 논의한 내용, 발생했던 버그, 내린 결정들이 모두 사라집니다.
claude-mem은 이러한 문제를 해결하기 위해 세션 라이프사이클 훅을 통해 중요한 정보를 자동으로 수집하고 보존합니다.
작동 원리
claude-mem은 세션 중 프롬프트, 툴 사용 내역, 종료 시점의 컨텍스트를 자동으로 수집합니다.
이 정보들은 로컬 데이터베이스에 저장되어 새 세션에서 필요할 때 자동으로 활용됩니다.
핵심 기능
메모리 지속성
세션이 종료되어도 이전 작업 내용이 보존됩니다.
새 세션을 시작하면 이전에 저장된 컨텍스트가 자동으로 활용되어 마치 작업을 중단한 적이 없는 것처럼 연속성을 유지할 수 있습니다.
지능형 검색
의미 기반 요약과 단계적 컨텍스트 주입을 제공합니다.
mem-search 스킬을 통해 자연어로 과거 작업, 버그, 의사결정 이력을 검색할 수 있습니다.
검색 예시
1
2
3
"지난주에 발생한 인증 관련 버그가 뭐였지?"
"API 엔드포인트 설계할 때 어떤 결정을 내렸었나?"
"이전에 PostgreSQL 연결 문제 어떻게 해결했더라?"
웹 UI
localhost:37777에서 메모리 스트림을 실시간으로 확인할 수 있습니다.
저장된 컨텍스트를 시각적으로 탐색하고 관리할 수 있어 편리합니다.
MCP 도구
자연어로 프로젝트 이력을 질의할 수 있는 4개의 MCP 도구를 제공합니다.
이를 통해 Claude가 필요한 정보를 효율적으로 검색하고 활용할 수 있습니다.
기술 아키텍처
하이브리드 검색 시스템
claude-mem은 두 가지 검색 기술을 결합하여 효율적인 검색을 제공합니다.
SQLite + FTS5
전문 검색(Full-Text Search)을 위해 SQLite의 FTS5 확장을 사용합니다.
키워드 기반 검색에 최적화되어 있습니다.
Chroma 벡터 데이터베이스
의미 기반 검색을 위해 Chroma 벡터 데이터베이스를 사용합니다.
자연어 질의를 벡터로 변환하여 유사한 컨텍스트를 찾아냅니다.
토큰 절감 효과
하이브리드 검색 시스템을 통해 약 10배의 토큰 절감을 달성합니다.
필요한 정보만 선별적으로 가져오기 때문에 컨텍스트 윈도우를 효율적으로 사용할 수 있습니다.
로컬 아키텍처
모든 데이터는 로컬에 저장됩니다.
HTTP 워커와 웹 뷰어 UI가 로컬에서 실행되어 외부 서버에 데이터를 전송하지 않습니다.
설치 및 사용 방법
설치
Claude Code 터미널에서 다음 명령어를 실행합니다.
1
2
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
설치 후 Claude Code를 재시작하면 자동으로 작동합니다.
기본 사용법
설치 후 특별한 설정 없이 자동으로 작동합니다.
세션 중 작업 내용이 자동으로 저장되고, 새 세션에서 필요할 때 활용됩니다.
메모리 검색
mem-search 스킬을 사용하여 과거 작업을 검색할 수 있습니다.
1
2
/mem-search "인증 버그"
/mem-search "데이터베이스 마이그레이션"
웹 UI 접속
브라우저에서 http://localhost:37777에 접속하면 메모리 스트림을 실시간으로 확인할 수 있습니다.
3단계 워크플로우 패턴
claude-mem은 토큰 비용을 효율적으로 관리하기 위해 “3단계 워크플로우 패턴”을 사용합니다.
1단계: 검색 색인 조회
먼저 검색 색인을 조회하여 관련 항목의 목록을 가져옵니다.
이 단계에서는 전체 내용이 아닌 요약 정보만 가져오므로 토큰 사용량이 적습니다.
2단계: 관련 항목 선별
검색 결과 중 실제로 필요한 항목을 선별합니다.
모든 결과를 가져오지 않고 필요한 것만 선택합니다.
3단계: 상세 정보 조회
선별된 항목에 대해서만 상세 정보를 가져옵니다.
이를 통해 불필요한 토큰 사용을 줄이고 컨텍스트 윈도우를 효율적으로 활용합니다.
점진적 정보 공개의 장점
| 기존 방식 | 3단계 패턴 |
|---|---|
| 모든 정보를 한 번에 로드 | 필요한 정보만 선별적 로드 |
| 토큰 낭비 발생 | 토큰 절감 |
| 컨텍스트 윈도우 빠르게 소진 | 컨텍스트 효율적 활용 |
프라이버시 제어
private 태그
민감한 정보는 <private> 태그를 사용하여 저장에서 제외할 수 있습니다.
1
2
3
4
<private>
API_KEY=sk-xxxxxxxxxxxxx
DATABASE_PASSWORD=mypassword123
</private>
<private> 태그로 감싼 내용은 메모리에 저장되지 않아 보안에 민감한 정보를 안전하게 처리할 수 있습니다.
로컬 저장
모든 데이터는 로컬에 저장되므로 외부 서버로 데이터가 전송되지 않습니다.
프라이버시를 중요시하는 사용자에게 적합합니다.
시스템 요구사항
claude-mem을 사용하기 위한 시스템 요구사항입니다.
| 요구사항 | 버전 |
|---|---|
| Node.js | 18.0.0 이상 |
| Claude Code | 최신 버전 |
| Bun | 자동 설치 가능 |
| SQLite | 3 (번들 포함) |
라이선스
claude-mem은 AGPL-3.0 라이선스로 배포됩니다.
일부 ragtime 디렉토리는 PolyForm Noncommercial License 1.0.0이 적용됩니다.
결론
claude-mem은 Claude Code 사용자들이 겪는 컨텍스트 손실 문제를 효과적으로 해결하는 플러그인입니다.
세션 간 컨텍스트를 자동으로 보존하고, 지능형 검색을 통해 과거 작업 이력을 쉽게 찾을 수 있습니다.
하이브리드 검색 시스템과 3단계 워크플로우 패턴을 통해 약 10배의 토큰 절감을 달성하며, 프라이버시 제어 기능으로 민감한 정보를 안전하게 처리할 수 있습니다.
Claude Code를 자주 사용하면서 세션 종료 시 컨텍스트 손실로 불편을 겪고 있다면, claude-mem을 설치해보는 것을 권장합니다. 간단한 설치만으로 작업 연속성을 크게 향상시킬 수 있습니다.