claude-mem은 Claude Code 등 세션 중의 조작을 기록하고 요약하여 다음 세션으로 전달하는 플러그인입니다. GitHub 스타는 약 112k이며, 하루에 +1,139가 증가했습니다 (2026-11-04 기준 자동 다이제스트 값, ※3).
이 글은 작동 원리를 설명하기보다는, 도입 전에 직접 확인해 보고 싶은 항목들을 정리한 절차서입니다. 작동 원리에 대한 자세한 내용은 Zenn의 다른 글에서 다루었습니다.
먼저 밝힙니다. 저는 본고를 위해 claude-mem을 설치하거나 실행하지 않았습니다. 아래의 절차는 README에 기재된 내용(※1)을 바탕으로 한 확인 항목이며, 작동 여부는 미검증입니다. 명령어 출력 예시도 포함하고 있지 않습니다. 시도해 보실 경우, 버려도 문제없는 환경에서 진행해 주시기 바랍니다.
| 항목 | 내용 | 출처 |
|---|
| 라이선스 | Apache License 2.0 | ※1 |
| ... | ※1 | |
README에는 두 가지 설치 방법이 있습니다(※1).
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
첫 번째는 Claude Code의 플러그인 마켓플레이스에서 설치하는 방법입니다. 두 번째는 인스톨러를 통해 OpenCode, T3 Code, Antigravity, OMP, Pi, DeepSeek Harness 등 --ide 옵션에도 대응할 수 있습니다.
README에는 npm install -g claude-mem으로 설치할 경우 SDK(라이브러리)만 된다는 점에 주의하라고 되어 있습니다. 훅 등록과 worker 서비스는 설정되지 않습니다(※1). '설치했는데 아무것도 기록되지 않는다'면, 설치 방법을 확인해 보고 싶습니다.
Windows에서는 claude-mem의 실행 명령어가 PATH에 포함되지 않는 문제가 있어, README에는 다음 진단을 안내하고 있습니다(※1).
npx나 /plugin install로 가져오는 것은 외부 코드입니다. 다음 사항들을 실행 전에 확인해야 합니다.
- 리포지토리의 소유자와 URL이 README에 제시된 것과 일치하는가?
- 버전이 고정되어 있는가? 자동 업데이트는 업데이트 후 동작이 달라질 수 있습니다.
- 자신의 조직에서 외부 플러그인 도입에 승인이 필요한가?
저의 환경에서는 외부 코드 설치가 자동 판별로 멈춰서 실행할 수 없었습니다. 조직이나 환경에 따라 같은 제한이 걸릴 수 있습니다. 우회하기보다는, 승인 경로를 확인하는 것이 순서입니다.
README에서 읽을 수 있는 관측 데이터 전송 후보지는 다음 세 가지입니다(※1).
| 경로 | 내용 |
|---|
| 호스트형 observer | 사인인 시 30일 무료 체험. 이후는 구독, 또는 Anthropic의 플랜으로 복귀 |
| ... | |
| 그림 2: 관측 데이터가 외부로 나갈 수 있는 경로. README 설명에 근거함 | |
확인 절차는 다음과 같습니다.
~/.claude-mem/settings.json 파일을 열어봅니다. - 프로바이더나 동기화 관련 항목을 찾아 기본값을 메모합니다.- 사용하지 않는 전송지는 비활성화합니다.
- 변경한 내용과 이유를 기록으로 남깁니다.
설정 항목명은 제가 확인하지 않았기 때문에 여기서는 적지 않습니다. 실제 파일에서 찾아보시기 바랍니다.
훅(Hook)은 PreToolUse와 PostToolUse를 포함하며, 도구의 입력과 출력에 접근합니다(※1). 다음과 같은 것들이 기록에 섞일 수 있습니다.
.env나 설정 파일 내부 내용 - 명령어 출력에 포함된 토큰- 고객 데이터가 포함된 파일 내용
확인하려면 기밀이 없는 더미 데이터를 사용해야 합니다.
# 테스트용 디렉토리에서 실행합니다 (실제 비밀은 사용하지 않습니다)
mkdir cm-test && cd cm-test
echo "API_KEY=dummy-1234" > .env
그 후, Claude Code에게 .env를 읽게 하는 작업을 시키고 세션 종료 후에 SQLite 내용을 확인합니다. 더미 값이 기록에 남아 있다면, 실제 값도 남을 수 있다고 생각해야 합니다.
README 범위 내에서는 SQLite 파일의 위치를 확인할 수 없습니다. 설정 파일이나 worker에 포함된 Web 뷰어에서 확인해 주십시오. 찾았다면, 읽기 전용으로 여세요.
sqlite3 -readonly <DB파일 경로> ".tables"
테이블 이름은 버전에 따라 다를 수 있습니다. 위의 명령어는 확인의 시작점입니다.
기록이 불필요해졌을 때, 어떻게 삭제할지 미리 결정해야 합니다. README 범위 내에서는 삭제 절차를 확인할 수 없습니다. 다음 사항들을 확인합니다.
- Web 뷰어에 삭제 기능이 있는지.
- SQLite 파일을 직접 삭제해도 되는지 (Chroma 데이터와의 불일치가 발생하지 않는지).
- Cloud Sync를 사용했을 경우, 클라우드 측의 삭제는 어떻게 처리되는지.
claude-mem은 검색을 3단계로 나눕니다 (※1).
| 단계 | 도구 | 역할 |
|---|
| 1 | search | 가벼운 인덱스를 반환 |
| 2 | timeline | 시간 순서의 컨텍스트를 반환 |
| 3 | get_observations | 선택된 ID에 대한 상세 정보만 반환 |
README는 필터링하여 가져옴으로써 약 10배의 토큰을 절약할 수 있다고 설명하고 있습니다. 이는 해당 사의 주장이며, 필자는 검증하지 않았습니다.
스스로 확인하려면 다음 두 가지를 측정해야 합니다.
- 로드하는 양: 같은 질문에 대해, 기억(memory)을 사용하지 않을 때, 전체 내용을 넣었을 때, 3단계로 가져왔을 때의 입력 토큰 수를 비교합니다.
- 누락률: 과거에 확실히 수행했던 작업 5건을 선택하여, 1단계에서 그 5건이 후보로 나오는 비율을 계산합니다. 너무 많이 필터링하면 필요한 기억이 후보에서 빠질 수 있습니다.
# 누락률 집계 예시 (결과는 직접 입력)
expected = {"fix-login-bug", "migrate-db", "add-cache", "rename-api", "update-ci"}
found = {"fix-login-bug", "add-cache", "update-ci"} # 1단계 후보에 나온 것
...
위의 코드는 집계 작성 예시이며, 값은 가상의 것입니다. 실제 측정값이 아닙니다.
그림 3: 공식 페이지 설명 기반 비교 (2026-11-05 확인)
| 목적 | 적합한 메커니즘 |
|---|
| 매번 지키게 하고 싶은 규칙 | CLAUDE.md (※2) |
| ... | |
| Claude Code 공식은 CLAUDE.md와 자동 메모리가 "강제되는 설정이 아닌 컨텍스트"라고 설명합니다. 작동을 확실히 막으려면 PreToolUse 훅(hook)을 사용해야 합니다 (※2). 기억 관련 플러그인을 넣어도 이 성질은 변하지 않습니다. | |
자동 메모리는 ~/.claude/projects/<project>/memory/ 에 저장되며, 시작 시 상위 200줄 또는 25KB가 로드됩니다. 비활성화하려면 /memory 토글을 사용하거나 환경 변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 을 사용할 수 있습니다 (※2). 기억 관련 플러그인과 함께 사용할 경우, 둘 다 컨텍스트를 추가하므로 중복되는 부분이 없는지 확인하고 싶습니다.
README에는 타사 토큰(CMEM)과 계약 주소(contract address)를 기재한 섹션이 있습니다 (※1). 이는 소프트웨어 기능과는 관련이 없고, 그 위험성에 대한 설명도 없습니다.
본고에서는 기술 평가 자료로 삼지 않았습니다. 투자나 구매를 권장할 의도도 없습니다. 도입 판단 시에는 기능과 운영 확인에 집중하고, 금전적인 문제는 분리하여 생각하는 것이 좋습니다.
- 배포처의 URL과 버전을 확인했다.
- 외부 코드 도입에 대해 조직의 승인을 확인했다.
settings.json 의 기본값과 전송지를 확인했다 - 사용하지 않는 전송지는 비활성화했다.- 더미 비밀로 기록 혼입을 확인했다.
- 저장소 파일과 삭제 수단을 파악했다.
- 기밀성이 있는 리포지토리에서는 사용하지 않도록 운영했다.
- 약 10배의 절감을, 자신의 환경에서 측정할 때까지 효과를 단정하지 않는다.
- 업데이트가 있을 때마다 동작을 재확인한다.
claude-mem은 작업 이력을 검색할 수 있다는 점이 매력이지만, 관측 데이터가 외부 공급자에게 전송될 수 있으므로 도입 전 확인이 필수적입니다. 본고의 절차는 공식 페이지의 설명에 근거한 것이며, 필자는 실제 기기에서 테스트하지 않았습니다. 먼저 기밀성이 없는 리포지토리에서 전송지와 저장 내용을 확인한 후, 사용 범위를 결정해야 합니다.
※본 기사에 기재된 내용은 필자 개인의 견해이며, 소속 회사나 조직의 입장이나 방침과는 전혀 관련이 없습니다.
【Tomcat-zhou】 | AI/AX/AI 보안 전문가
AI 전략 통찰력, AI 기반 개발의 방법론 설계 및 현장에서 작동하는 시스템 구축을 하고 있습니다.
note에서는 전략적 통찰력을, Zenn과 Qiita에서는 기술 및 방법론을 작성하고 있습니다.
AI 보안(AI Security), AI 컨설팅, AI 에이전트 개발, AI 활용, AI 기반 개발 교육, AI 인재 육성 서비스를 통합적으로 제공합니다.
X: @ZY20240528
LinkedIn: Tomcat-zhou
Facebook: zhou yi
note: Tomcat-zhou
zenn: Tomcat-zhou
- thedotmack/claude-mem (GitHub)
- How Claude remembers your project (Claude Code 공식 문서)
- AI Open Source Trends 2026-11-04 (agents-radar, 자동 요약)
- mem0ai/mem0 (GitHub)
ClaudeCode
AI
MCP
보안(Security)
SQLite
AI 에이전트(Agent)
