claude-mem이 하는 일: 세션이 끝나도 남는 작업 기록
클로드 코드로 하루 종일 작업하다가 창을 닫고 다음 날 새 세션을 열면, 어제 어떤 파일을 고쳤고 어떤 버그를 왜 그렇게 잡았는지 처음부터 다시 설명해야 합니다. CLAUDE.md에 메모를 남기는 방법도 있지만 매번 손으로 정리하기는 번거롭습니다. claude-mem은 이 정리를 자동으로 해 주는 플러그인입니다.
작동 방식은 단순합니다. 클로드가 파일을 읽고, 고치고, 명령을 실행할 때마다 그 기록을 붙잡아 두고, 별도의 모델로 짧게 압축해 저장합니다. 그리고 다음 세션이 시작될 때 지금 프로젝트와 관련된 최근 기록을 골라 클로드의 첫 맥락에 넣어 줍니다. 공식 문서 표현으로는 지난 세션의 맥락이 새 세션에 자동으로 나타납니다. 사람이 손으로 쓰는 메모가 아니라 작업 중에 실제로 일어난 일을 바탕으로 쌓이는 기록이라는 점이 CLAUDE.md와 다릅니다.
저장소는 thedotmack 계정의 Alex Newman이 만들고 Apache 2.0 라이선스로 공개했습니다. 11월 2일 오전 기준 GitHub 별이 10만 9천 개를 넘었고, 그날 GitHub 트렌딩 1위에 올라 하루에만 1,500개 넘는 별이 붙었습니다. 10월 마지막 주 npm 내려받기는 3만 건을 조금 넘습니다.
이름은 클로드 코드용으로 시작했지만 지금은 Codex CLI, Gemini 계열, OpenCode, Cursor, T3 Code, OpenClaw 같은 다른 도구에도 붙일 수 있습니다. 업데이트도 잦아서 11월 1일 하루에만 15.8.0과 15.8.1 두 버전이 나왔습니다. 15.8.1은 저장소 정리만 한 버전이라 실행 방식은 그대로입니다.
#1 on @github trending AGAIN 1733 stars today https://t.co/tZjrS80Cpp
— Claude-Mem (@Claude_Memory) 2026년 11월 1일
claude-mem 설치 명령과 설치 화면의 세 단계
가장 짧은 길은 터미널에서 npx claude-mem install을 한 번 실행하는 것입니다. Node.js 20 이상이 필요하고, 실행에 쓰는 Bun과 검색용 Python 환경을 만드는 uv는 없으면 설치기가 알아서 설치합니다. 클로드 코드 안에서 직접 설치하고 싶다면 /plugin marketplace add thedotmack/claude-mem과 /plugin install claude-mem 두 줄을 입력한 뒤 클로드 코드를 다시 켜면 됩니다.
대화형 설치기는 세 단계로 진행됩니다. 먼저 컴퓨터에 깔린 에이전트를 찾아 미리 체크해 두고, 어떤 도구에 붙일지 고르게 합니다. 고른 뒤에는 플러그인 파일을 복사하고 의존성을 설치하고, 훅이 부를 claude-mem 실행 파일을 PATH에 올립니다. 두 번째는 cmem.ai 로그인 단계로, 이메일을 묻지 않고 기기 코드를 띄운 다음 브라우저로 인증 페이지를 엽니다. 세 번째가 메모리 제공자 선택입니다.
한 가지 함정이 있습니다. npm install -g claude-mem으로 전역 설치하면 라이브러리만 깔리고 클로드 코드 훅이나 백그라운드 워커는 등록되지 않습니다. 이렇게 깐 전역 claude-mem이 PATH에서 앞쪽에 있으면 오히려 훅이 엉뚱한 파일을 부르게 되니, 설치는 꼭 npx나 /plugin 명령으로 해야 합니다.
클로드 코드 버전도 확인해야 합니다. 훅을 짧은 실행 명령 형태로 등록하는 방식이 2.1.139부터 지원돼서, 그보다 오래된 버전에서는 훅이 사용법만 출력하고 아무것도 기록하지 않습니다. 이럴 때는 claude update로 올리면 되고, 설치가 제대로 됐는지는 npx claude-mem doctor의 Hook launcher 줄에서 볼 수 있습니다.
윈도우에서는 실행 파일이 %LOCALAPPDATA%\claude-mem\bin 아래에 놓이고 사용자 Path에 추가됩니다. 맥과 리눅스는 ~/.local/bin/claude-mem입니다. Path가 바뀐 직후에는 터미널이나 IDE를 다시 열어야 클로드 코드가 새 경로를 읽습니다. 마켓플레이스로만 설치한 경우 첫 세션은 실행 파일을 준비하느라 기억 없이 시작될 수 있고, 그다음 세션부터 정상으로 붙습니다.
# 터미널에서 한 번에 설치
npx claude-mem install
# 또는 클로드 코드 안에서
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
# 설치 상태 점검
npx claude-mem doctor설치 중 메모리 제공자 선택: 기본값은 CMEM Pro 체험
설치 화면에서 가장 신경 써서 봐야 할 곳이 세 번째 단계입니다. 기록을 짧게 압축하는 일에도 언어 모델이 필요한데, 그 모델을 누구 돈으로 돌릴지 고르는 단계입니다. 설치기는 CMEM Pro를 미리 선택해 둡니다. 엔터만 누르고 지나가면 결제 체험 페이지가 열리고, 계정이 준비되면 설정 파일이 써지고 워커가 다시 시작됩니다.
CMEM Pro는 claude-mem 개발자가 운영하는 호스팅 관찰 모델로, 기록 압축을 cmem.ai 서버에서 처리하고 여러 기기 사이에 기억을 동기화해 줍니다. 30일 체험 뒤에는 월 30달러이고, 사용량이 더 많은 Heavy는 월 70달러, CMEM Max는 월 100달러에 초과분이 따로 붙습니다. 체험 종료일이 아니라 게이트웨이가 계정 처리를 멈춘 시점에 내 Anthropic 플랜으로 넘어가는 구조라, 체험이 끝났다고 기억이 끊기지는 않습니다.
나머지 선택지는 세 가지입니다. 내 OpenRouter 키나 Gemini API 키를 넣으면 그 계정의 크레딧으로 압축이 돌아갑니다. --provider claude를 고르면 지금 쓰는 Claude 구독 플랜의 사용량을 나눠 쓰고, 이 경우 로그인 단계가 아예 생략됩니다. 압축에 쓸 모델은 Haiku, Sonnet, Opus 중에서 묻는데, 설정 파일 기본값은 Haiku입니다.
--provider claude로 설치해도 cmem.ai와 한 번은 통신합니다. 가입 링크를 만들 때 관찰 개수와 토큰 합계 같은 숫자만 담긴 사용량 요약을 보내고, 프롬프트나 파일 경로, 프로젝트 이름은 보내지 않는다고 문서에 적혀 있습니다. 그 뒤로는 cmem.ai로 가는 데이터가 없습니다.
Codex CLI를 쓰고 있다면 codex login을 해 둔 뒤 npx claude-mem install --provider codex로 설치하는 방법도 있습니다. 이때는 OpenAI API 키 없이 로컬 Codex CLI 로그인으로 압축을 돌립니다. 반대로 AI 에이전트에게 설치를 맡기는 것처럼 터미널 입력이 없는 환경에서 --provider 없이 실행하면, 새로 설치하는 경우 Anthropic 플랜이 기본으로 잡힙니다.
| 선택지 | 압축 비용을 내는 곳 |
|---|---|
| CMEM Pro (기본 선택) | 30일 체험 뒤 월 30달러부터 |
| --provider claude | 내 Claude 구독 플랜 사용량 |
| Gemini API 키 | 내 Gemini 키 크레딧 |
| OpenRouter 키 | 내 OpenRouter 크레딧 |
| --provider codex | 로컬 Codex CLI 로그인 계정 |
claude-mem 설치 문서와 설정 문서 기준. 엔진 자체는 무료이며 어떤 선택지든 모델 사용량은 따로 든다.
설치 뒤 달라지는 것: 자동 기록과 다음 세션의 요약
설치가 끝나면 따로 할 일이 없습니다. 클로드가 Read, Write, Edit, Bash, Grep 같은 도구를 쓸 때마다 기록이 잡히고, 워커가 그 기록마다 제목과 짧은 설명, 핵심 사실, 관련 파일, 버그 수정인지 결정인지 같은 유형을 붙여 저장합니다.
클로드가 답을 마치면 그 세션의 요약도 만들어집니다. 무엇을 요청했고, 무엇을 살펴봤고, 무엇을 알게 됐고, 무엇을 끝냈고, 다음에 할 일이 무엇인지로 나눠 정리됩니다. 다음 날 새 세션을 열면 현재 프로젝트의 최근 기록 50개가 시간순 목록으로 먼저 들어가고, 마지막 요약이 그 뒤 기록보다 최신일 때만 요약 전문이 함께 붙습니다.
처음부터 모든 내용을 쏟아 넣지 않는 점이 이 도구의 핵심입니다. 세션 시작 때는 기록 제목과 토큰 비용 정도만 보여 주고, 클로드가 더 필요하다고 판단하면 검색 도구로 해당 기록만 꺼내 봅니다. 문서는 목록을 먼저 보고 필요한 항목만 상세 조회하는 방식으로 토큰을 열 배가량 아낀다고 설명합니다. 사용자는 지난번에 고친 버그가 뭐였는지, 인증은 어떻게 구현했는지처럼 평소 말투로 물으면 됩니다.
/clear를 써도 세션은 끝나지 않습니다. 화면의 대화만 비워지고 최근 기록이 다시 주입되며, 기록과 요약은 같은 세션에 계속 쌓입니다. 기록 목록과 설정은 워커가 띄우는 로컬 웹 화면에서도 볼 수 있고, 주소는 워커가 시작할 때 터미널에 찍힙니다.
기억이 저장되는 위치와 남기기 싫은 내용 빼는 법
기록은 기본적으로 내 컴퓨터에 쌓입니다. 데이터 폴더는 ~/.claude-mem이고, 그 안의 claude-mem.db가 SQLite 데이터베이스, settings.json이 설정 파일, logs 폴더가 워커 로그입니다. 폴더를 옮기고 싶으면 CLAUDE_MEM_DATA_DIR 환경 변수를 쓰면 됩니다. CMEM Pro를 고르면 압축이 cmem.ai 서버에서 처리되고, 클라우드 동기화를 켜면 기록이 cmem.ai 계정으로 올라갑니다.
API 키나 사내 서버 주소처럼 남기면 안 되는 내용은 private 태그로 감싸면 됩니다. 프롬프트 안에서 <private>와 </private> 사이에 넣은 부분은 클로드가 지금 세션에서는 그대로 보고 쓰지만, 저장할 때 잘려 나가 데이터베이스와 검색 색인에 들어가지 않습니다. 따로 켜는 설정 없이 항상 동작하고 여러 줄도 감쌀 수 있습니다.
아예 기록하지 않을 프로젝트가 있다면 CLAUDE_MEM_EXCLUDED_PROJECTS에 폴더 패턴을 넣습니다. 특정 도구 호출을 빼고 싶을 때는 CLAUDE_MEM_SKIP_TOOLS를 쓰는데, 기본값으로 TodoWrite나 Skill 같은 도구는 이미 빠져 있습니다. 도구가 찍은 스크린샷을 함께 보관하는 기능은 기본으로 꺼져 있습니다.
기록 요약을 한국어로 받고 싶다면 settings.json의 CLAUDE_MEM_MODE를 code--ko로 바꾸고 클로드 코드를 다시 시작하면 됩니다. 저장소의 modes 폴더에 code--ko 파일이 들어 있습니다.
이 오류 원인 좀 봐줘
<private>
Host: internal-db.example.com
User: admin
</private>
연결이 왜 끊기는지 궁금해쓰기 전에 알아둘 점: 사용량, 삭제, CMEM 토큰
기록을 압축하는 데도 모델 호출이 들어간다는 점은 계산에 넣어야 합니다. --provider claude로 쓰면 그 호출이 내 Claude 플랜 한도에서 빠지므로, 한도가 빠듯한 요금제라면 압축 모델을 Haiku로 두는 편이 낫습니다. CMEM Pro 쪽은 이 부분을 플랜 밖에서 처리해 준다는 것이 유료 상품의 핵심 차이입니다.
지우고 싶을 때는 npx claude-mem uninstall을 실행합니다. 이 명령은 훅 실행 파일을 지우지만 셸 설정 파일이나 사용자 Path에 추가된 줄은 건드리지 않고, 지워야 할 줄을 출력만 해 줍니다. 안내에 데이터 폴더 삭제 이야기는 없으니 쌓인 기록까지 없애려면 ~/.claude-mem 폴더를 직접 확인하는 편이 안전합니다.
README 맨 아래에 나오는 CMEM 암호화폐 토큰 이야기는 플러그인 설치나 CMEM Pro 구독과 관계가 없습니다. 이름이 비슷해 헷갈리기 쉬우니 요금은 cmem.ai 요금 페이지 기준으로 보면 됩니다.
클로드 코드 플러그인을 고를 때 하나 더 볼 것은 출처입니다. 지난달 커서에 올라온 변조된 클로드 코드 확장 사고처럼, 이름이 비슷한 가짜 패키지가 끼어들 수 있습니다. claude-mem은 GitHub의 thedotmack/claude-mem 저장소와 npm의 claude-mem 패키지가 공식 경로입니다.