MemPalace/mempalace

개요

MemPalace는 AI 어시스턴트(Claude Code, Codex CLI, Cursor, Gemini CLI, MCP 호환 클라이언트)를 위한 로컬 우선 메모리 계층입니다. 대화 기록을 그대로 저장하고(요약이나 의역 없음), 새 세션에서 컨텍스트가 필요할 때 의미론적 검색으로 검색합니다. 개인정보 보호를 강조하며, 명시적으로 옵트인하지 않는 한(예: 서버 측 임베딩 엔드포인트 연결) 데이터가 기기를 벗어나지 않습니다.

해결하는 문제

AI 에이전트에는 메모리 문제가 있습니다. 각 새 세션은 콜드 상태로 시작하고, 장기 실행 세션은 컨텍스트가 압축되어 소멸됩니다. 예를 들어 Claude Code 세션은 주의 깊게 훅을 연결하지 않으면 약 30일 후에 만료됩니다. MemPalace는 에이전트에게 과거 작업의 영구적이고 검색 가능한 아카이브를 제공하여, 새 세션이 "왜 GraphQL로 전환했지?"라는 질문에 요약이 아닌 결정이 이루어진 실제 대화를 검색하여 답할 수 있게 합니다.

작동 방식

마이닝 — CLI 명령(mempalace mine)이 파일, git 기록 또는 Claude Code 대화 기록을 가져와 그대로 텍스트 청크로 저장합니다.
인덱싱 — 청크는 로컬 모델(MiniLM 약 30MB, 또는 다국어 지원 EmbeddingGemma 약 300MB)로 임베딩되어 벡터 데이터베이스에 저장됩니다. 기본 백엔드는 ChromaDB이며 SQLite-exact, Rust-native, Milvus, Qdrant, pgvector는 선택적 드롭인입니다.
구조화 — 인덱스는 궁전 은유를 사용합니다. 사람/프로젝트는 날개, 주제는 방, 콘텐츠는 서랍에 배치됩니다. 검색은 플랫 코퍼스가 아닌 특정 날개로 범위를 좁힐 수 있습니다.
검색 — 검색 또는 wake-up 명령이 관련 과거 세션을 에이전트의 컨텍스트로 가져옵니다.
제공 — MCP 서버(47개 도구)를 통해 MCP 호환 에이전트가 런타임에 궁전을 쿼리할 수 있습니다. 읽기/쓰기, 지식 그래프 작업, 날개 간 탐색, 로그스트림 이벤트를 통한 에이전트 조정이 가능합니다.

주요 구성 요소

CLI(mempalace): mine, search, wake-up, audit, sweep — uv tool, pipx, virtualenv 또는 Docker(멀티 아키텍처 amd64/arm64, Dockerfile.gpu를 통한 GPU 변형)로 설치 가능.
MCP 서버: 47개 도구를 노출하는 stdio JSON-RPC 서버. Claude Code에 하위 프로세스로 통합됩니다.
플러그형 백엔드: 공통 계약(backends/base.py) 뒤에 있는 6개의 스토리지 백엔드. 기본이 아닌 것은 모두 옵트인입니다.
지식 그래프: 유효 기간이 있는 시간적 엔터티-관계 그래프 — 추가, 쿼리, 무효화, 타임라인 — 로컬 SQLite로 지원됩니다.
에이전트 날개 및 일기: 각 전문 에이전트는 자체 네임스페이스를 가지며 시스템 프롬프트를 비대화하지 않고 런타임에 검색할 수 있습니다.
자동 저장 훅: Claude Code, Codex CLI, Cursor용. 주기적 저장 및 압축 전 스냅샷. sweep는 메시지별 그대로 서랍을 추가합니다.
네이티브 Rust 엔진: rust_exact 백엔드와 독립형 mempalace-native CLI가 Rust 벡터 엔진으로 동일한 SQLite 데이터베이스를 스캔합니다. 복잡한 경우 Python으로 대체됩니다.
설정 스킬: npx skills add MemPalace/mempalace는 시스템을 감지하고, 패키지를 설치하고, MCP를 구성하고, 라이브 연결을 확인하는 에이전트 스킬을 설치합니다.

주목할 만한 세부 사항/주장

벤치마크(모두 리포지토리에서 재현 가능): LongMemEval 검색 리콜 R@5 원시 96.6%(의미론적 검색만, LLM 없음, API 키 없음), 하이브리드 v4로 98.4%(50개 샘플의 홀드아웃 개발 세트에서 튜닝, 450개의 보이지 않는 데이터로 보고), 선택적 LLM 재랭크로 ≥99%(Haiku, Sonnet, Ollama Cloud를 통한 minimax 등 모든 우수한 모델에서 작동). 또한 LoCoMo R@10 88.9%(하이브리드 v5), ConvoMem 평균 리콜 92.9%, MemBench(ACL 2025) R@5 80.3%가 나열됩니다.
정직한 벤치마킹: README는 Mem0, Mastra, Hindsight, Supermemory, Zep과의 나란히 비교를 명시적으로 거부하며 혼합 메트릭 비교는 부정직하다고 말합니다. 또한 재랭크 이득의 마지막 0.6%를 "시험 가르치기"로 표시하고 의도적으로 100% 수치를 헤드라인으로 삼지 않습니다.
보안 태세: 전체 CAUTION 섹션은 맬웨어를 배포하는 사칭 도메인(mempalace.tech/.net 및 기타 .com 변형)에 대해 경고합니다. 공식은 GitHub, PyPI, mempalaceofficial.com뿐입니다.
Docker 문제점 문서화: Linux 바인드 마운트의 uid 1000 권한, 첫 실행 모델 다운로드(약 80MB/300MB, 네트워크 필요), GPU 이미지는 x86 전용(aarch64 onnxruntime-gpu 휠 없음), develop가 기본 분기(릴리스의 경우 게시된 이미지 풀).

제한 사항/주의 사항

설정 마찰: README 자체에서 자동 저장 훅을 연결하지 않으면 Claude Code 세션이 30일 후에 만료된다고 경고합니다. 따라서 가치 제안은 설정 체크리스트를 주의 깊게 따르는 데 달려 있습니다.
Android/Termux 네이티브 지원 없음: ChromaDB 및 ONNX Runtime에는 Android 휠이 없습니다. Termux 사용자는 Debian PRoot을 실행해야 합니다.
첫 사용 지연: 임베딩이 필요한 첫 명령은 파워 모델(약 80~300MB)을 다운로드하고 멈춘 것처럼 보일 수 있습니다.
임베딩 모델 변경 시 인덱스 재구축 필요(mempalace repair rebuild-index): 모델을 전환하거나 서버 측 OpenAI 호환 임베딩 엔드포인트로 이동하는 경우.
네이티브 Rust 확장은 선택 사항: rust_exact는 복잡한 필터 및 네이티브 확장이 설치되지 않은 경우 Python으로 대체됩니다. 네이티브 경로에 대한 게시된 벤치마크는 없습니다.

평가

AI 메모리 분야의 진정하고 중요한 프로젝트: 실제 코드(Python + Rust 크레이트), 재현 가능한 벤치마크, 플러그형 아키텍처, Docker 패키징, MCP 통합, 보안에 민감한 README. "궁전" 은유는 일관되게 적용되며 벤치마크 규율(홀드아웃 분할, 정직한 주의 사항)은 이 범주에서 비정상적으로 우수합니다. 핵심 아이디어 — 그대로 저장, 구조화된 범위, 로컬 전용 개인 정보 보호 — 는 단순하지만 잘 실행되었으며 에이전트 훅 생태계(Claude Code, Codex, Cursor)로 즉시 실행 가능합니다. 에이전트 메모리를 구축하거나 Mem0/Zep 생태계를 평가하는 경우 살펴볼 가치가 있습니다.