이 레포가 무엇을 하는 물건인가.
대부분의 AI 메모리 도구는 대화를 LLM으로 요약·추출해 저장합니다 — 그 과정에서 정보가 변형되고 비용이 듭니다. MemPalace의 선택은 반대입니다: 저장은 원문 그대로(무손실), 대신 검색을 구조화(궁전 구조)와 임베딩으로 강하게. 그 결과 저장·검색 어디에도 LLM이 필요 없습니다.
사용법은 세 동사로 요약됩니다. mine — 프로젝트 파일이나 Claude Code 세션 기록(~/.claude/projects/)을 궁전으로 채굴해 들이기. search — "우리가 왜 GraphQL로 갈아탔지?" 같은 자연어로 과거를 검색. wake-up — 새 세션 시작 때 맥락을 불러오기. Claude Code에는 훅(자동 저장)·슬래시 커맨드·MCP 서버 3종 세트로 붙습니다.
트렌딩 이유 · 경쟁 대비 장점.
직접적 트리거는 "Claude Code 세션이 30일 뒤 만료된다"는 사실이 널리 알려진 것입니다 — 자동 저장 훅을 안 걸어두면 대화 자산이 통째로 증발하죠. MemPalace는 이 보존 문제의 해결책으로 떠올랐습니다. 더 근본적으로는 벤치마크를 직접 재현 가능한 형태로 커밋해 둔 정직성이 신뢰를 샀습니다 — 96.6%(무보정)과 98.4%(held-out)를 구분 표기하고, "100%는 테스트에 맞춘 튜닝이라 내세우지 않는다"고 명시합니다.
| 비교 항목 | 요약형 메모리 (Mem0 등) | MemPalace |
|---|---|---|
| 저장 방식 | LLM이 요약·추출 (변형 발생) | 원문 그대로 (무손실) |
| LLM 의존 | 저장 시점부터 필요 | 저장·검색 모두 0 (rerank만 선택) |
| 검색 구조 | 평면 코퍼스 벡터 검색 | 윙/룸/서랍으로 범위 한정 가능 |
| 데이터 위치 | 클라우드 서비스 多 | 로컬 기본 — 옵트인 없인 아무것도 안 나감 |
요약본에서 코드 조각·정확한 수치·말의 뉘앙스는 사라집니다. 게다가 저장할 때마다 LLM 비용이 들고, 요약 품질에 검색 품질이 종속됩니다.
원문 보존 + 구조화 색인 + 로컬 임베딩. 하이브리드 모드는 키워드 부스팅·시간 근접 부스팅·선호 패턴 추출을 얹고, 최후의 0.6%만 LLM rerank(아무 모델이나 가능)에 맡깁니다 — 의존성의 우선순위가 명확합니다.
주의 맥락 하나: README 최상단에 사칭 사이트 경고가 있습니다. 공식 출처는 GitHub 저장소·PyPI·mempalaceofficial.com 셋뿐이고, 다른 도메인은 멀웨어 배포 가능성이 있는 사칭입니다 — 인기 레포가 겪는 공급망 위협의 생생한 사례입니다.
Python 코어 + 교체 가능한 벡터 백엔드.
| 레이어 | 기술 | 역할 |
|---|---|---|
| 코어 | Python (mempalace CLI) | mine·search·wake-up 명령. uv tool / pipx 격리 설치 권장. |
| 벡터 저장 | ChromaDB (기본) + sqlite_exact·Qdrant·pgvector | backends/base.py 계약 하나로 4종 교체 — 플러그형 백엔드. |
| 임베딩 | 로컬 임베딩 모델 (캐시됨) | API 호출 없이 시맨틱 검색. GPU Docker 변형도 제공. |
| 에이전트 연동 | .claude-plugin/ + .codex-plugin/ + MCP 서버 | 훅(자동 저장)·슬래시 커맨드(/mine /search)·stdio MCP. |
| 채굴기 | convo_miner·format_miner·diary_ingest | Claude Code 세션·프로젝트 파일·일지 등 소스별 파서. |
| 배포 | PyPI · Docker(CPU/GPU) · devcontainer | /data 볼륨에 궁전·설정·모델 캐시 영속화. |
| 품질 | 벤치마크 4종 스크립트 + 결과 JSON 커밋 | LongMemEval·LoCoMo·ConvoMem·MemBench 재현 가능. |
대화 하나가 궁전 서랍이 되고, 다시 검색되기까지.
채굴 흐름을 따라가면: ① convo_scanner.py가 Claude Code 세션 JSONL 등을 읽고, ② entity_detector.py·entity_registry.py가 등장 인물·프로젝트를 식별해 윙을 만들고 주제를 룸에 배정하며, ③ 원문이 서랍에 그대로 들어가고(dedup.py가 중복만 거름), ④ 임베딩이 백엔드에 기록됩니다. 검색은 역방향 — 쿼리를 임베딩해 (범위를 좁힌 뒤) 벡터 검색하고, 필요하면 하이브리드 부스팅과 LLM rerank를 얹습니다.
아키텍처의 백미는 백엔드 계약(backends/base.py)입니다. 같은 인터페이스를 ChromaDB(로컬 벡터DB)·sqlite_exact(정확도 검증용)·Qdrant(REST)·pgvector(SQL)가 구현하는데, README는 "REST/dict 저장소와 SQL/JSONB 저장소 양쪽에서 계약을 검증해 특정 벤더 모양에 우연히 묶이지 않게 했다"고 설명합니다. 외부 백엔드를 쓸 때는 로컬 마커 파일로 "엉뚱한 서버에 궁전을 여는" 사고까지 방지합니다.
도서관에 비유하면, 요약형 메모리는 사서가 책마다 독후감을 써서 독후감만 보관하는 방식입니다. MemPalace는 책을 원본 그대로 서가(윙=층, 룸=서가, 서랍=책)에 꽂고, 색인 카드(임베딩)를 잘 만들어 두는 방식이죠. 몇 년 뒤 "그 책 274쪽에 뭐라고 적혀 있었지?"에 답할 수 있는 건 후자뿐입니다.
어떤 폴더가 무슨 일을 하나.
| 위치 | 주목할 점 |
|---|---|
backends/base.py | 전체 시스템에서 가장 먼저 읽을 파일 — 저장 계약이 곧 아키텍처. |
benchmarks/ | 벤치마크 스크립트와 결과를 코드와 함께 커밋 — 주장 검증이 git clone 한 번. |
.claude-plugin/hooks/ | precompact·stop 훅 — 세션이 압축·종료되기 직전에 자동 저장하는 타이밍 설계. |
fact_checker.py·collision_scan.py | 기억 충돌·오류 검사 — 메모리 시스템의 데이터 위생 계층. |
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
모두가 요약으로 달려갈 때 원문 보존을 택하고 벤치마크로 입증한 사례. 저장과 검색의 책임 분리를 어떻게 가르는지가 핵심 교훈입니다.
base.py 계약 → 4종 구현 → "서로 다른 substrate에서 계약 검증" 전략. 벤더 락인 없는 저장 계층 설계의 교과서적 흐름입니다. 네임스페이스 격리 capability와 마커 파일 가드도 눈여겨볼 것.
dev 50문항으로 튜닝하고 held-out 450문항 수치를 대표값으로 쓰는 것, 마지막 0.6%는 "테스트에 가르친 것"이라며 헤드라인에서 빼는 것 — benchmarks/BENCHMARKS.md는 평가 방법론 문서로도 읽을 가치가 있습니다.
자동(훅) / 수동(슬래시 커맨드) / 프로그래매틱(MCP 서버) — 같은 기능을 세 통로로 노출하는 .claude-plugin/ 구성은 Claude Code 플러그인 만들 때 그대로 참고할 만합니다.
돌리려면 무엇이 필요한가.
| 항목 | 요구사항 |
|---|---|
| 설치 | uv tool install mempalace 권장 (pipx도 가능) — PEP 668 회피를 위한 격리 환경. |
| 런타임 | Python 3.9+ 필수 (chromadb·numpy·huggingface-hub 의존). Docker로 무설치 실행도 가능. |
| 디스크 | 임베딩 모델 캐시 ~300 MB 필요 (최초 실행 시 자동 다운로드). |
| GPU | 선택 — Dockerfile.gpu + --gpus all로 CUDA 임베딩 가속. |
| 네트워크 | 기본 0 — 로컬 임베딩·로컬 저장. Qdrant/pgvector 외부 백엔드는 명시적 옵트인. |
| 보안 주의 | 공식 출처는 GitHub·PyPI·mempalaceofficial.com 셋뿐 — 다른 도메인은 사칭. |
난이도별로 손에 익히는 단계.
uv tool install mempalace → 프로젝트 하나를 mine → 과거 결정에 대해 search로 물어보기. 윙·룸이 어떻게 자동 배정됐는지 확인하세요.
플러그인 설치 후 ~/.claude/projects/를 --mode convos로 채굴하고, precompact/stop 훅이 자동 저장하는 걸 확인합니다 — 30일 만료 문제의 실전 해법.
같은 데이터를 --backend sqlite_exact와 기본 ChromaDB로 각각 채굴해 검색 결과를 비교합니다. 로컬 Qdrant를 띄워 세 번째 백엔드도 — 계약 기반 설계의 이점을 체감하는 과제.
benchmarks/BENCHMARKS.md대로 LongMemEval R@5를 재현하고, 하이브리드 부스팅을 끄고 켜며 수치 변화를 관찰합니다. 부스팅 가중치를 바꿔 held-out 점수가 어떻게 움직이는지도.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 설치·첫 궁전·검색 감 잡기 | README · 실습 1 |
| 2주차 | 임베딩·벡터 검색 기초 | embedding.py · ChromaDB 문서 |
| 3주차 | 백엔드 계약 정독 + 교체 실험 | backends/ · 실습 3 |
| 4주차 | 채굴 파이프라인 — 엔티티·중복·위생 | convo_miner.py · entity_detector.py |
| 5주차 | 메모리 벤치마크 방법론 | benchmarks/ · LongMemEval 논문 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| verbatim 저장 | 요약·추출 없이 원문 그대로 보관하는 방식. |
| 윙 / 룸 / 서랍 | 사람·프로젝트 / 주제 / 원문 콘텐츠 — 궁전의 3계층 색인 구조. |
| mine / wake-up | 기록을 궁전에 들이기 / 새 세션에 맥락 불러오기. |
| R@5 | 검색 상위 5개 안에 정답이 든 비율 — 회수율 지표. |
| LongMemEval | 장기 대화 기억력을 재는 500문항 벤치마크. |
| 하이브리드 검색 | 벡터 검색에 키워드·시간 근접 부스팅을 결합한 방식. |
| rerank | 검색 상위 후보를 LLM이 다시 읽고 순서를 고치는 후처리 — 여기선 선택사항. |
| ChromaDB / Qdrant / pgvector | 벡터 저장 백엔드 3종 — 로컬 임베디드 / REST 서비스 / Postgres 확장. |
| held-out | 튜닝에 쓰지 않고 떼어둔 평가 데이터 — 일반화 성능의 정직한 척도. |
| precompact 훅 | Claude Code가 컨텍스트를 압축하기 직전에 실행되는 훅 — 자동 백업 타이밍. |