Deepseek ArtifactsDeepseek Artifacts
Claude Code 메모리 플러그인 가이드

Claude-Mem: Claude Code를 위한 영구 메모리 플러그인

Claude-Mem은 에이전트가 하는 일을 지켜보고, 두 번째 에이전트가 이를 관찰 기록으로 압축한 뒤, 그 짧은 인덱스를 다음 세션에 주입하는 서드파티 플러그인입니다. 실제로 무엇을 하는지, 어떻게 설치하고 설정하는지, 그리고 어디까지가 Claude-Mem의 몫이고 어디부터 CLAUDE.md의 몫인지 살펴봅니다.

설치 방법으로 이동FAQ로 이동

Claude-Mem 한눈에 보기

  • 규칙 파일이 아니라 메모리 계층입니다. 훅이 모든 도구 호출을 로컬 워커에 넘기고, 두 번째 에이전트가 그 활동을 짧은 관찰 기록으로 바꾸며, 다음 세션은 그 기록의 압축 인덱스로 시작합니다.
  • 지원되는 설치 경로는 두 가지입니다. npx claude-mem install(런타임을 준비하고 브라우저 설정 페이지를 엽니다) 또는 /plugin marketplace add thedotmack/claude-mem 다음에 /plugin install claude-mem을 실행하는 방법입니다.
  • Apache-2.0, TypeScript로 작성되었고 Alex Newman(thedotmack)이 유지 관리합니다. 메모리는 ~/.claude-mem/claude-mem.db의 SQLite에 로컬로 저장되며, 클라우드 동기화는 선택 사항입니다.
  • CLAUDE.md나 Claude Code의 자동 메모리를 대체하지 않습니다. 세 가지 모두 세션 시작 시 로드되지만 서로 다른 질문에 답합니다. 간단히 알고 싶다면 아래 비교 표를 보세요.

thedotmack/claude-mem — README

출처github.comchecked 2026-11-13

열기

.claude-plugin/marketplace.json — claude-mem 15.18.3

출처raw.githubusercontent.comchecked 2026-11-13

열기

Installation Guide

출처docs.claude-mem.aichecked 2026-11-13

열기

Configuration

출처docs.claude-mem.aichecked 2026-11-13

열기

Telemetry — what is collected and how to opt out

출처docs.claude-mem.aichecked 2026-11-13

열기

How Claude remembers your project — CLAUDE.md vs auto memory

출처code.claude.comchecked 2026-11-13

열기

dsh-claude-mem — DeepSeek Harness port (unofficial)

출처deepseekharnessplugins.comchecked 2026-11-13

열기

이 페이지의 명령, 설정, 기본값, 경로는 2026-11-13에 업스트림 저장소와 공식 문서에서 확인한 것입니다. 명령과 설정 이름은 의도적으로 번역하지 않았습니다. 번역된 명령은 동작하지 않는 명령이기 때문입니다.

저장소 정보는 2026-11-13 GitHub API 기준입니다. 스타 116,640개, 포크 10,120개, 생성일 2025-08-31, 최신 릴리스 v15.18.3 공개일 2026-11-12. 스타 수는 매일 바뀌므로 점수가 아니라 스냅샷으로 봐야 합니다.

Claude-Mem은 실제로 무엇인가

Claude-Mem은 Claude Code(그리고 십여 개의 다른 코딩 에이전트)에 자기 작업에 대한 기억을 부여하는 오픈소스 플러그인입니다. 프로젝트는 문제를 담백하게 설명합니다. 새 세션은 매번 0에서 시작하고, 같은 파일을 다시 읽고, 같은 질문을 다시 던지고, 이미 함께 고친 실수에 다시 발을 들인다고요.

해법은 당신 옆에서 돌아가는 두 번째 에이전트입니다. 호스트 에이전트에 설치된 훅이 각 도구 호출(무엇을 읽고, 편집하고, 실행했는지)을 작은 로컬 워커에 넘깁니다. 워커는 그 활동에 관찰자 모델을 돌려 짧은 구조화된 관찰 기록과 세션 종료 요약을 작성해 로컬 SQLite 데이터베이스에 저장합니다. 새 세션이 시작되면 호스트 에이전트는 이 프로젝트에 중요한 관찰 기록의 압축 인덱스를 받고, 필요할 때만 전체 내용을 가져옵니다.

즉 여기서 기억의 단위는 당신이 쓴 지시가 아니라, 실제로 일어난 작업에 대한 관찰입니다. 이것이 CLAUDE.md와의 결정적 차이이며, 둘이 경쟁하지 않고 공존하는 이유입니다.

라이선스
Apache-2.0
최신 릴리스
v15.18.3 · 2026-11-12
메모리 저장 위치
~/.claude-mem/claude-mem.db
스타 수(2026-11-13)
116,640

세 단계로 보는 동작 원리

README는 이 루프를 세 문장으로 설명하며, 나머지 모든 기능은 여기에서 파생됩니다.

  1. 1

    에이전트가 작업한다

    호스트 에이전트의 수명 주기 훅이 각 도구 호출을 작은 로컬 워커에 넘깁니다. Claude Code의 경우 훅은 SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, SubagentStop, SessionEnd를 다루며, claude --init과 --maintenance를 위한 Setup 항목도 있습니다. 각 훅은 셸을 거치지 않는 명령 하나, claude-mem hook claude-code <event>입니다.

  2. 2

    관찰자가 기록한다

    두 번째 에이전트가 그 활동을 짧은 관찰 기록으로 바꾸고 세션이 끝날 때 요약을 작성합니다. 기본 압축 모델은 Haiku(CLAUDE_MEM_MODEL=haiku)이며 당신의 Anthropic 플랜에서 실행됩니다. 대신 OpenRouter나 Gemini 키를 지정하거나 벤더가 호스팅하는 관찰자를 사용할 수도 있습니다.

  3. 3

    다음 세션이 그 기록으로 시작한다

    SessionStart 시점에 에이전트는 이 프로젝트의 관찰 기록 압축 인덱스를 받습니다. 기본 50개이며 CLAUDE_MEM_CONTEXT_OBSERVATIONS로 설정합니다. 전체 내용은 필요할 때만 가져옵니다. 주입은 프로젝트에서 두 번째 세션부터 시작됩니다. 첫 세션에는 아직 주입할 것이 없기 때문입니다.

검색도 같은 계층화 발상입니다. 세 가지 MCP 도구인 search, timeline, get_observations가 먼저 인덱스를, 다음으로 시간순 컨텍스트를, 마지막으로 전체 레코드를 반환하므로 에이전트는 자기가 고른 행에만 상세 비용을 지불합니다. mem-search 스킬이 이 도구들을 대신 호출해 주며, README에 적힌 수치로는 인덱스 한 행이 약 50~100 토큰, 전체 레코드가 500~1,000 토큰입니다. 이는 행당 비율일 뿐 엔드투엔드로 측정한 절감량이 아니라고 README가 직접 밝히고 있습니다.

워커가 제공하는 다른 것들

로컬 워커는 시작 시 출력되는 URL에서 뷰어를 제공합니다. /viewer에 메모리, 세션, 설정이 있고 루트에는 My Work가 있습니다. 검색 외의 도구도 노출합니다. 코드 탐색용 smart_search, smart_outline, smart_unfold, 의도적으로 메모를 남기는 save_memory, 그리고 작업 상태 추적입니다. 모든 관찰 기록에는 워커 API로 인용할 수 있는 ID가 있습니다.

설치와 확인

아래 두 경로는 모두 업스트림 문서에서 그대로 가져온 것입니다. 프로젝트가 권장하는 것은 설치 프로그램 경로로, 런타임을 준비하고 훅 런처를 컴파일하기 때문입니다. 플러그인 경로는 Claude Code 안에서 프롬프트 두 번이면 끝납니다.

경로 1 — 설치 프로그램

터미널에서 이것을 실행하세요. 설치 프로그램은 Bun과 uv를 확인하고, 플러그인 파일을 복사하고, 의존성을 설치하고, claude-mem 런처를 PATH에 올린 뒤 에이전트, 통합, 스킬, 메모리 제공자를 고르는 브라우저 설정 페이지를 엽니다. 그 페이지를 쓰는 동안 터미널은 계속 실행해 두세요.

npx claude-mem install

npm install -g claude-mem으로 설치하지 마세요. README는 분명히 밝힙니다. 전역 npm 설치는 SDK/라이브러리를 머신에 두기만 할 뿐, 플러그인 훅을 등록하지 않고 워커도 시작하지 않으며, PATH에 있는 진짜 런처를 가릴 수도 있습니다.

경로 2 — 플러그인 마켓플레이스

Claude Code 안에서 이것을 각각 별도의 프롬프트로 보낸 뒤 재시작하세요. 두 경로 모두 훅을 구성하고 워커를 시작하므로, 이후 새 세션에는 이전 세션의 컨텍스트가 자동으로 나타납니다.

/plugin marketplace add thedotmack/claude-mem/plugin install claude-mem

마켓플레이스로만 설치하면 설치 프로그램 단계가 없어서, 플러그인이 첫 세션 시작 시 컴파일하면서 런처를 배치합니다. 그 첫 세션은 메모리 컨텍스트 없이 돌아갈 수 있고, 다음 세션부터는 사용할 수 있습니다. npx claude-mem install을 한 번 실행하면 이 공백이 메워집니다.

실제로 돌아가는지 확인하기

npx claude-mem doctor를 실행하세요. Bun, uv, 훅 런처, 워커를 점검하고 무엇을 고쳐야 하는지 알려줍니다. claude-mem --version은 런처 프로토콜 번호를 출력하고, 시작 시 출력되는 워커 URL이 뷰어를 제공합니다. 훅이 "Executable not found in $PATH"를 보고하면 doctor가 PATH에서 어떤 claude-mem이 잡히는지, 그것이 런처인지 보여줍니다.

npx claude-mem doctorclaude-mem --version

시작하기 전 요구 사항

  • 1Node.js 20.19 이상(20.x 계열) 또는 22.12 이상.
  • 2Bun 1.2.16 이상 — 훅 런처가 이것으로 컴파일됩니다. 없으면 설치 프로그램이 Bun을 설치합니다.
  • 3uv, 없으면 자동 설치됩니다. Chroma의 시맨틱 검색용 임베딩 서비스에서 Python 쪽을 담당합니다.
  • 4Claude Code 2.1.139 이상 — exec 형식 훅 인자를 실행하는 첫 릴리스입니다. 그보다 오래된 빌드는 인자를 무시하고 맨 claude-mem을 실행하므로 아무것도 수집되지 않습니다. SQLite는 bun:sqlite를 통해 함께 제공됩니다.

실제로 동작을 바꾸는 설정

모든 설정은 ~/.claude-mem/settings.json에 있으며, 첫 실행 시 기본값으로 자동 생성됩니다. 같은 이름의 환경 변수가 파일 값을 덮어씁니다. 아래는 알아둘 만한 항목이고, 나머지는 설정 문서에 정리되어 있습니다.

설정기본값하는 일
CLAUDE_MEM_MODELhaiku제공자가 Claude일 때 관찰 기록을 압축하는 모델. haiku는 최신 Haiku를 따르고, 전체 ID를 지정하면 버전이 고정됩니다.
CLAUDE_MEM_PROVIDERclaude관찰자를 실행하는 제공자. claude, codex, gemini, openrouter, openai-compatible 중 하나.
CLAUDE_MEM_CONTEXT_OBSERVATIONS50세션 시작 시 주입되는 관찰 기록 수. 시작 블록이 무겁게 느껴지면 낮추세요.
CLAUDE_MEM_MODEcode워크플로 프로필과 생성되는 관찰 기록의 언어. 예: code, 관찰 기록을 줄이는 code--chill, 중국어용 code--zh.
CLAUDE_MEM_DATA_DIR~/.claude-mem데이터 루트. 데이터베이스, Chroma 인덱스, 로그, 설정, 워커 pid와 포트 파일 등 나머지 모든 경로가 여기서 파생됩니다.
CLAUDE_MEM_WORKER_PORT37700 + (uid % 100)워커 포트. 기본값이 사용자별로 달라서 한 머신의 두 사용자가 충돌하지 않습니다. HTTP API에 맞춰 스크립트를 쓴다면 고정 포트를 지정하세요.
CLAUDE_MEM_CONTEXT_PROJECTScurrentSessionStart이 어느 프로젝트의 메모리를 읽을지 정합니다. current는 이 체크아웃, all은 glob 패턴으로 제외한 프로젝트를 뺀 모든 프로젝트입니다.
CLAUDE_MEM_SKIP_TOOLSListMcpResourcesTool, SlashCommand, Skill, TodoWrite, AskUserQuestion관찰 기록에서 제외할 도구. 출력이 지식이 아니라 소음인 도구에 유용합니다.
CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCESfalseSessionStart 컨텍스트에 현재 사용 중인 하네스뿐 아니라 모든 하네스의 관찰 기록을 포함할지 여부. 기본값 false.
CLAUDE_MEM_SKILLS_DISABLED(none)번들 스킬을 폴더 이름 그대로 지정해 Claude Code의 목록과 슬래시 명령에서 숨깁니다.

두 가지는 더 알아 둘 만합니다. CLAUDE_MEM_SKIP_BASH_PATTERNS는 각 셸 명령에 대조할 정규식을 받아 시끄러운 명령이 관찰 기록이 되지 않게 하고, CLAUDE_MEM_REDACT_ENABLED(기본값 꺼짐)는 저장 전에 인식된 시크릿 패턴을 자동으로 마스킹합니다.

Claude-Mem과 Claude Code 내장 메모리 비교

Claude Code는 이미 두 가지 방식으로 세션 간에 지식을 전달하며, Anthropic 문서는 이 둘을 상호 보완 관계로 봅니다. 당신이 쓰는 CLAUDE.md와 Claude가 스스로 쓰는 자동 메모리입니다. Claude-Mem은 그 위에 얹히는 세 번째 독립 계층입니다.

항목Claude Code 내장Claude-Mem 플러그인
작성 주체CLAUDE.md는 당신이 쓰고, 자동 메모리는 Claude가 당신의 교정에서 씁니다.세션이 만들어낸 도구 활동을 바탕으로 두 번째 관찰자 에이전트가 씁니다.
저장 위치CLAUDE.md는 프로젝트 루트 또는 ~/.claude/CLAUDE.md. 자동 메모리는 ~/.claude/projects/<project>/memory/에 MEMORY.md 인덱스와 함께 있습니다.SQLite는 ~/.claude-mem/claude-mem.db, 설정과 로그도 같은 폴더에 있습니다. 시맨틱 검색용 Chroma 인덱스는 선택 사항입니다.
담기는 내용지시와 규칙. 자동 메모리는 학습 내용과 패턴을 담으며, 처음 200줄 또는 25KB만 로드됩니다.일어난 작업에 대한 관찰 기록 — 결정, 버그 수정, 무엇을 읽고 바꿨는지 — 를 모델로 압축한 것.
로드 시점매 세션마다 자동으로, 시스템 프롬프트 뒤의 컨텍스트로.SessionStart 시점에 훅을 통해, 프로젝트의 두 번째 세션부터.
읽는 방식파일 전체 또는 자동 메모리 인덱스가 그대로 컨텍스트에 존재합니다. /memory로 파일을 나열하고 열 수 있습니다.압축 인덱스가 주입되고, 상세 내용은 세 가지 MCP 도구(search, timeline, get_observations)로 가져옵니다.
의존성과 비용추가로 필요한 것이 없습니다 — Claude Code에 포함되어 있습니다.Node, Bun, uv, 로컬 워커 프로세스, 그리고 압축을 수행하는 모델. 기본은 당신의 Anthropic 플랜이고, 자기 키나 유료 호스팅 관찰자를 쓸 수도 있습니다.

실무적 분담은 이렇습니다. 규칙과 관례는 CLAUDE.md에, 선호는 자동 메모리에 모으게 하고, Claude-Mem에는 실제로 무엇을 했는지의 이력을 맡기세요. 한 번만 중요한 세션 세부 정보는 셋 다 필요 없고, 매번 지켜야 하는 규칙이 있을 자리는 CLAUDE.md뿐입니다. 저장 위치도 배타적이지 않습니다 — claude-mem의 memory ingest는 Claude Code 자동 메모리의 토픽 파일을 모델 토큰을 쓰지 않고 관찰 기록으로 자기 데이터베이스에 가져옵니다.

Claude Code memory 튜토리얼

프라이버시, 한계, 그리고 솔직한 주의사항

이 플러그인은 작업 세션을 기록하므로, 업무 저장소에 들이기 전에 기본값을 한 번 읽어볼 만합니다.

  • 1기본은 로컬. 세션, 관찰 기록, 요약은 ~/.claude-mem/claude-mem.db의 SQLite에 기록되고 설정과 로그도 같은 폴더에 있습니다. 클라우드 동기화는 선택 사항이며 자동으로 이뤄지지 않습니다.
  • 2내용을 <private> 태그로 감싸면 저장되지 않습니다 — README의 표현 그대로입니다. 인식된 시크릿 패턴 자동 마스킹은 별도의 옵트인 스위치 CLAUDE_MEM_REDACT_ENABLED이며 기본값은 꺼짐입니다.
  • 3익명 텔레메트리는 기본으로 켜져 있습니다(PostHog, 무작위 설치 UUID에만 연결). npx claude-mem telemetry disable로 끌 수 있으며, DO_NOT_TRACK도 존중되어 모든 설정을 덮어씁니다.
  • 4압축은 모델 호출이므로 도구 활동이 선택한 제공자에게로 머신 밖으로 나갑니다. 당신의 Anthropic 플랜, OpenRouter나 Gemini 키, 또는 벤더의 호스팅 관찰자입니다. 신중하게 고르세요.
  • 5이것은 Anthropic 제품이 아닌 서드파티 소프트웨어이며 실행 가능한 훅을 설치합니다. 팀에 배포하기 전에 plugin/hooks/hooks.json과 설정을 읽어보세요. 플러그인을 당신이 실행하는 코드로 취급하세요. 실제로 그렇기 때문입니다.
  • 6토큰만이 아니라 컨텍스트도 소모합니다. 주입되는 인덱스, 워커 프로세스, 머신 위의 Bun과 uv입니다. 세션이 이미 짧고 자기완결적이라면 이득은 작습니다. 헤드라인 숫자를 믿지 말고 자기 저장소에서 측정하세요.

그렇다고 설치하지 말라는 뜻은 아닙니다. 먼저 실제 프로젝트 하나에서 써 보라는 뜻입니다 — 절대 기록하고 싶지 않은 저장소는 glob으로 제외하고, 원하면 텔레메트리도 끈 뒤에, 여는 모든 저장소의 기본값으로 삼을지 결정하세요.

텔레메트리 해제는 명령 하나면 됩니다:

npx claude-mem telemetry disable

Claude-Mem 자주 묻는 질문

더 살펴보기

Claude Code memory 튜토리얼Claude Code 자동 컴팩트Claude Code 플러그인 마켓플레이스 튜토리얼Claude Code hooks 튜토리얼Claude Code 토큰 절약 가이드GitHub Copilot Memory 튜토리얼: 확인·삭제와 사용자 지정 지침 템플릿