이 레포가 무엇을 하는 물건인가.
영화 〈메멘토〉의 주인공은 몇 분이 지나면 기억이 리셋된다. 그래서 중요한 단서를 몸에 문신하고 폴라로이드에 메모를 남긴다. LLM 에이전트도 똑같다 — 세션이 끝나면 그동안의 맥락이 백지가 된다. claude-mem은 그 주인공을 대신해 일하는 동안 자동으로 메모를 남기고, 다음 판이 시작되면 관련 메모만 골라 다시 읽어준다.
조금 더 정확히 말하면, claude-mem은 Claude Code(앤트로픽의 터미널형 코딩 에이전트)를 비롯한 여러 AI 에이전트에 붙는 영속 메모리 압축 시스템(persistent memory compression system)이다. 에이전트가 파일을 읽고, 명령을 실행하고, 코드를 고치는 모든 도구 사용을 가로채 기록한 다음, 그 원본 로그를 그대로 쌓아두는 게 아니라 AI가 "무슨 일이 있었는지"를 짧은 요약으로 압축해 저장한다. 다음에 같은 프로젝트로 돌아오면, 이 요약들이 "지난 줄거리"처럼 컨텍스트에 깔린다.
중요한 점 하나 — claude-mem은 단순히 "대화 전체를 파일에 저장"하는 도구가 아니다. 핵심은 압축과 골라서 주입이다. 모든 걸 다시 집어넣으면 컨텍스트가 금세 꽉 차버리기 때문에, "검색 → 훑어보기 → 필요한 것만 펼치기"라는 단계적 전략(progressive disclosure)으로 토큰을 아낀다. 이 설계 철학이 이 레포의 정체성이다.
트렌딩 이유 · 경쟁 대비 장점.
2025~2026년 AI 코딩 에이전트가 폭발적으로 늘면서, 모두가 같은 벽에 부딪혔다 — "에이전트가 어제 한 일을 오늘 기억하지 못한다." 사람들은 임시방편으로 CLAUDE.md 같은 메모 파일을 손으로 관리했지만, 매번 갱신하기도 번거롭고 길어지면 그것대로 컨텍스트를 잡아먹었다. claude-mem은 이 문제를 자동 캡처 + AI 압축 + 의미 검색으로 풀어, "설치 한 줄"로 끝낸다는 점에서 주목받았다.
| 비교 항목 | 기존 방식(수동 메모) | claude-mem의 접근 |
|---|---|---|
| 기록 | 사람이 직접 메모 파일 갱신 | 도구 사용을 훅으로 자동 캡처 |
| 저장 형태 | 원문 그대로 쌓임 → 비대해짐 | AI가 의미 요약으로 압축 |
| 다시 불러오기 | 전체를 통째로 붙여넣기(토큰 폭증) | 검색 후 필요한 것만(약 10배 절약) |
| 적용 범위 | 한 도구에 종속 | Claude Code·Gemini CLI·Codex 등 다중 에이전트 |
새 세션을 열 때마다 "이 프로젝트는 이런 구조고, 어제 이 버그를 고쳤고…"를 사람이 다시 떠먹여야 했다. 떠먹이지 않으면 에이전트는 같은 실수를 반복하고, 다 떠먹이면 컨텍스트가 본 작업 전에 가득 찬다.
세션이 시작되면 이전 세션의 요약이 자동으로 주입되고, 본문 중엔 자연어로 "지난번에 인증 버그 어떻게 고쳤지?"라고 물으면 메모리에서 검색해 답한다. 사람은 손으로 메모를 관리할 필요가 없다.
또 하나의 매력은 로컬 우선(local-first)이라는 점이다. 메모리는 내 PC의 SQLite 파일에 쌓이고, 워커 서비스도 내 컴퓨터에서 돈다. 민감한 내용은 <private> 태그로 저장에서 제외할 수 있고, localhost:37777의 웹 뷰어로 무엇이 기억됐는지 실시간으로 들여다볼 수 있다.
$CMEM이 있고 제작자가 이를 "공식적으로 포용"한다고 적혀 있다. 코드/소프트웨어 자체와는 별개이며, 학습용으로 레포를 볼 때는 신경 쓸 필요가 없는 부분이다. 다만 오픈소스 도구에 코인이 붙는 건 흔치 않은 일이라 사실로만 짚어둔다.한 도구가 의외로 많은 부품을 쓴다 — 레이어별로 펼쳐본다.
claude-mem은 "플러그인 하나"처럼 보이지만, 실제로는 백그라운드 HTTP 서버 + 데이터베이스 + AI 처리기 + 웹 UI가 한 몸으로 도는 작은 시스템이다. 언어는 전부 TypeScript이고, 실행 환경으로 Node.js와 Bun을 함께 쓴다.
| 레이어 | 기술 / 버전 | 역할 |
|---|---|---|
| 언어 | TypeScript (ES2022 / ESNext) | 훅·서버·UI 모두 한 언어로. |
| 런타임 | Node.js 20+ & Bun ≥ 1.0 | Node로 설치, Bun이 워커 프로세스를 띄우고 관리. |
| HTTP 서버 | Express.js 5 + SSE | 검색 API·뷰어를 제공, 실시간 스트림 푸시. |
| 데이터베이스 | SQLite 3 (bun:sqlite) + FTS5 | 세션·관측·요약 저장 + 전문(full-text) 검색. |
| 벡터 검색 | Chroma (선택) | 의미 기반 유사도 검색(하이브리드). |
| AI 처리 | @anthropic-ai/claude-agent-sdk | 관측 로그를 요약으로 압축(또는 Gemini·OpenRouter). |
| 프론트엔드 | React 19 + esbuild | 메모리 스트림 웹 뷰어(단일 HTML로 번들). |
| 작업 큐 | BullMQ + ioredis | 관측 처리를 비동기 큐로 차곡차곡. |
| 코드 파싱 | tree-sitter (20+ 문법) | 읽은 소스코드를 구조적으로 이해. |
| 기타 | zod · MCP SDK · handlebars · better-auth · DOMPurify | 검증 · 도구 프로토콜 · 템플릿 · 인증 · 보안. |
먼저 전체 그림 한 장, 그다음 데이터 한 줄기를 끝까지 따라가 본다.
claude-mem의 핵심 구조는 "훅(hook)이 기록하고, 워커(worker)가 가공한다"로 요약된다. 에이전트의 생명주기(세션 시작·프롬프트 입력·도구 사용·종료) 곳곳에 훅 스크립트가 걸려 있고, 이들이 데이터를 SQLite에 떨군다. 그러면 백그라운드 워커가 그걸 읽어 AI로 요약하고 다시 DB에 넣는다. 다음 세션의 시작 훅이 그 요약을 꺼내 컨텍스트에 깔면 한 바퀴가 완성된다.
전체 그림만으론 감이 안 오니, 가장 흔한 동작 하나를 입력부터 출력까지 손으로 따라가 보자. 곁가지(에러 처리·엣지 케이스)는 생략하고 해피 패스만 본다.
여기서 이 프로젝트 특유의 "정상적인 모양새" 두 가지를 짚어두면 코드가 덜 낯설다. 첫째, 모든 훅은 같은 워커로 모인다 — 훅마다 따로 로직을 두지 않고, worker-service.cjs에 hook claude-code <이벤트> 인자를 넘겨 한 곳에서 분기한다(단일 디스패처). 둘째, 무거운 일은 전부 비동기다 — 도구를 쓸 때마다 AI 요약을 기다리면 에이전트가 느려지니, 기록만 즉시 하고 압축은 큐에서 천천히 돌린다.
search로 제목·ID만 담긴 가벼운 목록(결과당 50~100토큰) → ② timeline으로 관심 항목 주변 맥락 → ③ get_observations로 고른 ID만 전체 내용(결과당 500~1,000토큰). 필터링 후 펼치므로 토큰을 약 10배 아낀다. 마트에서 "목록 보고 → 관심 코너 가서 → 살 것만 장바구니" 하는 것과 같다.소스(src/)에서 만들어 플러그인(plugin/)으로 배포되는 구조.
핵심은 두 폴더의 관계다. src/는 사람이 쓰는 TypeScript 원본이고, esbuild가 이를 번들해 plugin/ 안의 실행 스크립트로 떨어뜨린다. 마켓플레이스에 배포되는 건 plugin/ 쪽이다.
| 경로 | 역할 |
|---|---|
src/services/sqlite/ | 저장의 심장 — 세션·관측·요약 CRUD와 FTS5 검색. |
src/services/worker-service.ts | 워커의 진입점. HTTP API·SSE·비동기 처리를 모두 띄운다. |
src/sdk/ | 관측을 요약으로 압축하는 AI 처리 로직(Agent SDK 연동). |
plugin/hooks/hooks.json | "어떤 사건에 어떤 스크립트를 실행할지" 등록표. |
plugin/scripts/worker-service.cjs | 실제로 도는 워커 데몬 겸 모든 훅의 단일 디스패처. |
plugin/skills/mem-search | 자연어로 기억을 검색하는 에이전트 스킬. |
이 레포에서 진짜 배울 만한 것 + 어느 파일을 보면 되는지.
Claude Code 같은 호스트가 정해진 순간에 외부 스크립트를 호출하고, 그 스크립트가 stdin으로 데이터를 받아 처리하는 구조는 플러그인 개발의 정석이다. plugin/hooks/hooks.json(등록표)과 worker-service.cjs(디스패처)를 같이 읽으면 "이벤트 → 단일 처리기" 패턴이 한눈에 들어온다.
요즘은 검색 하면 곧장 벡터DB를 떠올리지만, claude-mem은 SQLite 내장 FTS5를 1차 검색으로 쓰고 Chroma는 선택이다. 가벼운 로컬 파일 하나로 전문검색을 구현하는 법(src/services/sqlite/)은 실전에서 두고두고 쓸모 있다.
3단계 점진적 공개(search→timeline→get_observations)는 단순한 검색이 아니라 "토큰을 아끼려고 일부러 정보를 미루는" 설계다. MCP 도구 대신 스킬+HTTP로 바꿔 세션당 ~2,250토큰을 더 아낀 사례까지, 컨텍스트 엔지니어링의 좋은 교과서다.
도구를 쓸 때마다 AI 요약을 동기로 기다리면 에이전트가 느려진다. 기록은 즉시, 압축은 BullMQ 큐에서 천천히 — 이 분리가 체감 속도를 살린다. 백그라운드 워커 + 큐 패턴을 실제 제품 코드로 보는 좋은 예.
훅이 워커를 부르는 핵심 연결을 코드로 보면 이렇게 단순하다(개념 예시 — 복사용 아님):
// 모든 생명주기 훅은 같은 워커에 이벤트 이름만 바꿔 넘긴다
// 예: PostToolUse 훅 → "observation" 이벤트
bun worker-service.cjs hook claude-code observation // 도구 사용 기록
bun worker-service.cjs hook claude-code context // 세션 시작 시 주입
bun worker-service.cjs hook claude-code summarize // 정지 시 요약 생성순수 소프트웨어 — 특별한 하드웨어는 필요 없다.
| 항목 | 요구사항 |
|---|---|
| Node.js | 20.0.0+ (README 및 package.json engines 동일) |
| Bun | ≥ 1.0 — 워커 런타임/매니저 (없으면 자동 설치) |
| uv | Python 패키지 매니저 — 벡터 검색용 (없으면 자동 설치) |
| SQLite 3 | 저장소 (번들 제공) |
| 호스트 | Claude Code(플러그인 지원 최신판) · 또는 Gemini CLI · OpenCode · OpenClaw 등 |
| OS | macOS · Linux · Windows (PowerShell 지원) |
| API 키 | 요약 처리에 Anthropic/Gemini/OpenRouter 중 하나의 키 |
설치는 사실상 npx claude-mem install 한 줄, 또는 Claude Code 안에서 /plugin install이면 끝이다. Bun·uv 같은 부속은 알아서 깔리므로, "런타임을 직접 챙겨야 하나" 걱정할 필요는 거의 없다. 주의: npm install -g claude-mem은 라이브러리(SDK)만 깔고 훅·워커는 등록하지 않으니, 반드시 npx claude-mem install 또는 /plugin으로 설치한다.
손으로 만져봐야 구조가 몸에 붙는다.
npx claude-mem install로 깔고 Claude Code를 재시작한다. 몇 번 작업한 뒤 브라우저로 http://localhost:37777에 접속해, 내 행동이 어떤 관측·요약으로 쌓이는지 실시간 스트림을 관찰한다. "무엇이 기억되는가"를 눈으로 확인하는 게 첫걸음.
한 세션에서 작은 작업을 끝낸 뒤 세션을 닫고, 새 세션을 연다. 시작 시 자동 주입되는 이전 요약을 확인하고, "지난번에 뭐 했었지?"라고 자연어로 물어 mem-search가 검색해 답하는 걸 본다.
~/.claude-mem/settings.json에서 주입할 관측 개수·AI 모델·언어 모드(code--ko 같은)를 바꿔 본다. 민감 내용은 <private> 태그로 감싸 저장에서 빠지는지 확인한다. "무엇을 기억하고 무엇을 잊을지"를 직접 조율하는 연습.
~/.claude-mem/claude-mem.db를 SQLite 뷰어로 열어 sessions·observations·summaries 테이블과 FTS5 가상 테이블이 어떻게 생겼는지 본다. 검색 쿼리를 직접 날려보며 "AI 메모리가 결국 평범한 테이블"임을 체감한다.
plugin/hooks/hooks.json에서 PostToolUse 훅이 어떤 스크립트를 부르는지 찾고, worker-service.cjs가 observation 이벤트를 어떻게 분기하는지 코드로 따라간다. 가능하면 워커 로그(npm run worker:logs)를 켜고 실제 호출을 눈으로 확인.
claude-mem을 발판으로 "에이전트 메모리" 전반을 익히는 4주 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 설치·뷰어 관찰로 전체 그림 잡기 | 공식 문서 + 실습 1·2 |
| 2주차 | 훅 시스템과 단일 디스패처 패턴 | plugin/hooks/ · worker-service.cjs · 실습 5 |
| 3주차 | SQLite FTS5 + 점진적 공개 검색 | src/services/sqlite/ · 검색 아키텍처 문서 |
| 4주차 | 벡터 검색·임베딩으로 확장(Chroma) | ChromaSync.ts · 벡터DB 기초 자료 |
| +α | 내 도구에 메모리 이식해보기 | Claude Agent SDK · MCP 명세 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| 관측 (observation) | 에이전트의 도구 사용 한 건을 캡처한 기록 단위. 검색·인용의 기본 알갱이. |
| 요약 (summary) | 관측들을 AI가 "무슨 일이었나"로 압축한 결과. 다음 세션에 주입되는 줄거리. |
| 훅 (hook) | 특정 생명주기 사건에 자동 실행되는 스크립트. |
| 워커 서비스 | 백그라운드에서 도는 Express HTTP 서버. 기록을 받아 요약·검색을 처리. |
| 점진적 공개 | search→timeline→get_observations로 단계적으로 펼쳐 토큰을 아끼는 검색 전략. |
| FTS5 | SQLite 내장 전문검색 엔진. 1차(키워드) 검색을 담당. |
| Chroma | 선택적 벡터 데이터베이스. 의미 유사도 기반 검색을 더한다(하이브리드). |
| MCP | Model Context Protocol. 에이전트와 외부 도구를 잇는 표준 프로토콜. |
| Claude Agent SDK | 앤트로픽의 에이전트 개발 키트. 관측을 요약으로 압축하는 AI 처리에 사용. |
| mem-search 스킬 | 자연어로 기억을 검색하는 에이전트 스킬(HTTP API 기반). |
| Endless Mode | 긴 세션용 "생체모방 메모리" 베타 기능. |
| local-first | 데이터·처리를 클라우드 대신 내 컴퓨터에 두는 설계 원칙. |