코딩 에이전트와 한 시간 동안 버그를 잡고 세션을 닫으면, 다음 날 새 세션은 어제의 결정과 시행착오를 모른 채 시작한다. claude-mem은 에이전트가 세션 중에 한 일을 로컬에 기록해 두었다가 다음 세션 시작에 관련 내용을 넣어 주는 오픈소스 플러그인이다. Claude Code를 비롯해 Codex, Cursor, OpenCode 등을 지원하고, 11월 10일 15.15.0 버전이 나왔다. 이 글은 Claude Code 기준 설치 방법과 첫 사용 흐름을 다룬다.
claude-mem 설치 방법: 플러그인 두 줄
Node.js가 20.19 이상(20 계열) 또는 22.12 이상이어야 한다. Bun과 uv는 없으면 설치 과정에서 함께 설치된다. Claude Code 입력창에서 다음 두 줄을 차례로 실행하고, 끝나면 Claude Code를 다시 시작한다.
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem터미널에서 안내를 따라가며 설치하고 싶다면 대화형 설치기를 쓴다. 지원하는 에이전트를 고르는 질문이 나오고, Claude Code에서는 기본 자동 기억 기능을 끌지도 묻는다.
npx claude-mem installnpm install -g claude-mem은 쓰면 안 된다. 이 명령은 라이브러리만 설치하고 훅과 백그라운드 서비스는 등록하지 않는다. 설치 후에는 점검 명령으로 Bun, uv, 훅 실행 파일, worker가 모두 정상인지 본다.
npx claude-mem doctor설치할 때 로그인 질문이 나오면 한 가지를 알아 두면 된다. 호스팅되는 관찰 서비스는 30일 무료 체험이 있지만 결제 수단이 필요하고, 체험이 끝나면 기억 요약은 Anthropic 요금제를 쓰는 쪽으로 돌아간다. 로그인 없이 쓰려면 OpenRouter나 Gemini 키를 직접 넣을 수 있다. 사용 통계는 기본으로 켜져 있어서, 끄려면 npx claude-mem telemetry disable을 실행한다.
기억이 만들어지는 순서
설치하면 Claude Code의 세션 시작, 프롬프트 입력, 도구 사용 전후, 종료 같은 이벤트마다 훅이 claude-mem 명령을 부른다. 이 기록은 내 컴퓨터에서 돌아가는 worker 서비스로 가고, 별도 에이전트(observer)가 짧은 관찰로 줄여 쓴다. 관찰은 ~/.claude-mem/claude-mem.db의 SQLite에 저장되고, 의미 검색을 위한 Chroma 벡터 색인이 함께 만들어진다. 클라우드 동기화는 켜지 않는 한 쓰이지 않는다.
다음 세션이 시작될 때는 관련 관찰의 색인만 먼저 들어간다. 본문 전체를 넣지 않으니 시작 부담이 작고, 필요하면 에이전트가 번호로 자세한 내용을 불러온다.
어제 한 일을 찾아 쓰는 법
기억 검색은 MCP 도구 세 단계로 이뤄진다. 먼저 search로 번호가 붙은 짧은 목록을 받고, timeline으로 그 주변의 시간순 맥락을 보고, get_observations로 고른 번호의 전체 내용만 가져온다. README는 걸러서 가져오는 이 방식이 토큰을 약 10배 아낀다고 설명한다.
search(query="authentication bug", type="bugfix", limit=10)
get_observations(ids=[123, 456])따라서 새 세션에서는 「어제 인증 버그를 어떻게 고쳤는지 claude-mem에서 찾아 줘」처럼 말하면 된다. 저장된 기록은 웹 화면에서도 본다. worker가 시작하면서 출력하는 주소의 첫 화면은 진행 중인 요청과 검토 대기열을 보여 주고, 같은 주소의 /viewer에서는 기억, 세션, 설정을 볼 수 있다. 관찰마다 번호가 있어서 회의록처럼 번호를 인용할 수 있다.
민감한 내용과 설정
저장하고 싶지 않은 내용은 <private> 태그로 감싸면 기억에 남지 않는다. 설정은 ~/.claude-mem/settings.json에 있고, AI 모델, worker 포트, 저장 위치, 로그 수준, 시작 때 넣을 맥락의 양을 정한다. 한국어로 기록을 받고 싶으면 모드를 CLAUDE_MEM_MODE=code--ko로 지정한다. 관찰 수를 줄이려면 code--chill이다. 모드를 바꾼 뒤에는 Claude Code를 다시 시작한다.
적용해 볼 점
며칠씩 이어지는 작업, 예를 들어 오래된 코드의 이전이나 반복되는 장애 대응처럼 지난 결정이 다음 작업의 전제가 되는 일에서 효과가 크다. 처음에는 하나의 저장소에서 한 주 정도 켜 두고, 시작 때 들어오는 맥락이 실제로 쓸모 있는지와 /viewer에 쌓이는 관찰이 읽을 만한지를 본다. 관찰이 너무 많으면 code--chill 모드로 낮춘다. 비밀 값이 오가는 작업은 <private> 태그로 감싸는 습관부터 들이는 편이 좋다.