💡 요약
thedotmack/claude-mem은 터미널 기반 AI 코딩 에이전트 Claude Code에 영구 기억 장치를 제공하는 오픈소스 플러그인 및 MCP 서버입니다. 세션 종료 시 작업 내용이 사라지는 한계를 해결하며, 배경에서 AI 압축엔진이 도구 호출 결과와 설계 결정을 분석해 로컬 DB에 자동 저장하고 다음 세션 시작 시 필요한 맥락을 자동으로 주입합니다.
| 항목 | 내용 |
|---|---|
| 프로젝트명 | thedotmack/claude-mem |
| 개발자 | thedotmack |
| 주요 역할 | Claude Code 세션 간 영구 맥락 수집, 자동 요약, 시맨틱 검색 및 주입 |
| 저장소 방식 | 로컬 SQLite (claude-mem.db) + Chroma Vector DB |
| 웹 대시보드 | http://localhost:37777 (워커 서비스 연동) |
| 저장소 주소 | https://github.com/thedotmack/claude-mem |
1. 세션 단절 문제와 영구 메모리의 필요성
Claude Code 같은 터미널 기반 AI 개발 도구를 사용하다 보면 세션을 새로 열 때마다 이전 대화에서 진행한 작업 내용이나 아키텍처 결정 사항을 다시 설명해야 합니다.
- 맥락 파실 및 세션 단절: 기존 세션을 종료하거나 터미널을 다시 시작하면 이전 세션의 실행 이력과 디버깅 과정이 모두 사라집니다.
- 중복 설명으로 인한 토큰 소모: 새로 시작한 터미널에서 기존 시스템 구조와 모듈 간 관계를 다시 프롬프트로 입력하느라 불필요한 토큰과 시간이 소모됩니다.
- 과거 디버깅 이력 재조회 불가: 며칠 전 해결했던 오류 원인이나 특정 함수를 수정한 이유를 AI가 스스로 기억하지 못합니다.
claude-mem은 Claude Code의 라이프사이클 이벤트 후크(Lifecycle Hooks)에 연동하여 이 문제를 해결합니다. 에이전트가 수행한 도구 호출, 파일 수정, 사용자의 지시 사항을 실시간으로 감지하고 AI 기반 압축 엔진을 통해 정제된 메모리로 변환하여 저장합니다.
2. 5단계 메모리 파이프라인 동작 원리
claude-mem이 세션 내 이력을 수집하고 저장하여 다음 대화로 전달하는 5단계 흐름입니다.
3. 백그라운드 아키텍처 및 저장 구조
claude-mem은 시스템 내부에서 두 가지 핵심 구성 요소와 로컬 데이터베이스를 활용하여 메모리를 관리합니다.
워커 서비스 (Worker Service)
백그라운드에서 동작하는 워커 프로세스는 Claude Code가 전달하는 이벤트 핸들러를 수신합니다. 수신한 툴 실행 로그와 터미널 대화 내역을 원문 그대로 저장하지 않고, AI 모델을 이용해 핵심 설계 결정과 작업 요약문으로 압축합니다. 기본적으로 37777 포트를 사용하여 로컬 웹 UI를 함께 제공합니다.
이중 데이터베이스 구성
데이터 저장은 100% 사용자의 로컬 컴퓨터에서 처리됩니다.
- SQLite 데이터베이스:
~/.claude-mem/claude-mem.db파일에 저장되며, FTS5(Full Text Search)를 지원해 텍스트 키워드 기반의 정확한 검색을 지원합니다. - Chroma 벡터 데이터베이스:
~/.claude-mem/vector-db/chroma.sqlite3위치에 세션 기록의 임베딩을 저장하여 관련성이 높은 과거 맥락을 시맨틱 의미 단위로 탐색합니다.
4. 플러그인 설치 및 설정 절차
Claude Code 터미널 환경에서 공식 명령어 플러그인 마켓플레이스를 통해 바로 설치할 수 있습니다.
설치 명령어
Claude Code 세션 실행 상태에서 아래 명령어를 순서대로 입력합니다.
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem설치가 완료되면 백그라운드 워커 데몬이 활성화되며, Claude Code 세션이 시작하고 끝날 때마다 이벤트 수집이 자동 시작됩니다.
💡 꿀팁 기본 포트 37777이 다른 프로그램과 충돌할 경우 터미널 환경 변수로 포트를 변경할 수 있습니다: export CLAUDE_MEM_WORKER_PORT=8080
⚠️ 경고 로컬 워커 서비스의 웹 UI API는 별도의 인증 절차 없이 로컬호스트(localhost)에 개방되므로 보안상 외부 네트워크로 포트 포워딩을 설정하지 않아야 합니다.
5. 메모리 조회 및 실전에 활용하기
설치 후 별도의 커스텀 명령어를 외울 필요 없이 자연어로 과거 작업 내용을 질의할 수 있습니다.
📍 터미널 프롬프트 대화 예시
> 지난주에 작업했던 인증 모듈의 리팩터링 방향과 변경한 데이터베이스 스키마 구조를 요약해줘.Claude Code는 내부 MCP 도구를 호출하여 Chroma 및 SQLite DB에서 관찰 기록(Observations)을 조회하고, 질문에 부합하는 이전 세션 맥락을 추출하여 대답을 구성합니다.
웹 대시보드 활용
브라우저 주소창에 http://localhost:37777을 입력하면 타임라인 형태로 축적된 프로젝트별 메모리 스트림을 시각적으로 확인하고 개별 관찰 노드를 관리할 수 있습니다.
6. 한눈에 보는 요약 체크리스트
✅ 한눈에 보는 실행 체크리스트
- ✅ Claude Code 세션에서
/plugin marketplace add thedotmack/claude-mem실행하기 - ✅
/plugin install claude-mem입력하여 플러그인 설치 완료하기 - ✅ 웹 브라우저에서
http://localhost:37777접속 후 워커 동작 여부 확인하기 - ✅ 필요 시
export CLAUDE_MEM_WORKER_PORT환경 변수로 포트 변경 설정하기 - ✅ 새로운 세션에서 과거 작업 내역을 자연어로 질문해 맥락 복원 테스트 진행하기
7. 자주 묻는 질문 (FAQ)
Q1. claude-mem을 사용하면 API 토큰 비용이 많이 증가하나요?
원문 전체를 저장하지 않고 백그라운드에서 요약 및 압축을 진행하므로 신규 세션 개시 시 전달되는 토큰 양을 효과적으로 조절합니다. 이전 전체 대화록을 다시 붙여넣는 방식에 비해 토큰 사용량이 현저히 줄어듭니다.
Q2. 수집된 데이터는 외부 서버로 전송되나요?
아닙니다. 모든 대화 기록, 요약본, 시맨틱 임베딩 노드는 사용자의 홈 디렉터리(~/.claude-mem) 내부 SQLite 파일 및 Chroma DB에 로컬 저장됩니다.
Q3. 여러 개의 Claude Code 세션을 동시에 열었을 때 포트 충돌이나 프로세스 오류가 발생하면 어떻게 하나요?
동시 세션이 많아지거나 워커 프로세스가 중복 실행될 경우 포트 37777 응답이 지연될 수 있습니다. lsof -i :37777 명령어로 프로세스를 확인하거나 환경변수로 포트를 분리 지정하면 안정적으로 구동됩니다.