MemPalace/mempalace

로컬 우선(Local-first) AI 메모리. 원문 그대로 저장하고, 플러그인 백엔드를 사용하며, LongMemEval에서 96.6% R@5 raw를 달성했습니다 — API 호출이 전혀 필요 없습니다.

주의사항

사칭 사이트를 조심하세요. MemPalace의 다른 공식 웹사이트는 없습니다. 유일한 공식 출처는 이 GitHub 저장소, PyPI 패키지, 그리고 mempalaceofficial.com의 문서를 통해서입니다. 다른 모든 도메인(예: .tech, .net 또는 기타 .com 변형)은 사칭이며 악성 코드를 배포할 수 있습니다. 자세한 내용과 타임라인은 docs/HISTORY.md를 참고하세요.

중요

Claude Code 세션은 자동 저장 후크가 연결되지 않으면 30일 후에 만료됩니다. 여기를 읽어보세요 →

가장 짧은 복구/설정 경로가 필요하신가요? Claude Code 보존 설정 체크리스트를 사용하세요.

MemPalace는 대화 기록을 원문 그대로의 텍스트로 저장하고 의미 검색(semantic search)으로 이를 검색합니다. 요약하거나, 추출하거나, 의역하지 않습니다. 인덱스는 구조화되어 있어 — 사람과 프로젝트가 날개가 되고, 주제가 방이 되며, 원본 콘텐츠는 서랍에 보관됩니다 — 따라서 평평한 코퍼스(flat corpus) 전체를 대상으로 실행하는 대신 검색 범위를 제한할 수 있습니다.

검색(retrieval) 계층은 플러그인 방식으로 구현되어 있습니다. 현재 기본값은 ChromaDB이며, 인터페이스는 mempalace/backends/base.py에 정의되어 있어 다른 백엔드를 시스템의 나머지 부분을 건드리지 않고도 추가할 수 있습니다.

사용자의 기기를 벗어나는 것은 사용자가 옵트인(opt in)하는 경우를 제외하고는 없습니다.

아키텍처, 개념 및 마이닝 흐름: mempalaceofficial.com/concepts/the-palace.

MemPalace는 CLI를 제공하므로, Debian/Ubuntu/Homebrew Python에서 PEP 668 오류를 방지하고 mempalace의 의존성(chromadb, numpy, grpcio, …)이 전역 site-packages에 있는 다른 것들과 충돌하는 것을 막기 위해 격리된 환경에 설치하는 것이 좋습니다.

다음과 같이 uv를 사용하는 것을 권장합니다.

uv tool install mempalace
mempalace init ~/projects/myapp

선호한다면 pipx도 동일하게 작동합니다:
pipx install mempalace

단순히 pip를 사용하는 것을 선호하는 경우, 명시적으로 import mempalace가 사용 가능한 활성화된 가상 환경(virtualenv) 내부에서만 사용하세요:

python -m venv .venv && source .venv/bin/activate
pip install mempalace

로컬 Python 툴체인 없이 MCP 서버 또는 CLI를 실행하기 위한 컨테이너 이미지도 제공됩니다. 모든 것은 /data 아래에 유지되므로, 해당 위치에 볼륨을 마운트하세요.

# 이미지 빌드 (CPU; `extract` + `spellcheck` 추가 기능 번들)
docker build -t mempalace .
# stdio를 통한 MCP 서버 — `-i` 플래그에 유의하십시오 (JSON-RPC는 stdin 필요)
...

이를 stdio 서버로 MCP 클라이언트(예: Claude Code)에 연결하세요:

{
"mcpServers": {
"mempalace": {
...

docker compose run --rm mcp도 작동하며 (docker-compose.yml 참조), CUDA 가속 임베딩의 경우 docker build -f Dockerfile.gpu -t mempalace:gpu .로 GPU 버전을 빌드하고 --gpus all과 함께 실행하세요. 빌드 시간에 번들된 추가 기능을 사용자 정의할 수 있습니다 (예: docker build --build-arg EXTRAS="extract,spellcheck" -t mempalace .).

ChromaDB가 기본입니다. 플러그어블 백엔드 미리보기의 경우, MemPalace는 로컬 정확 벡터 무결성 검사를 위해 sqlite_exact도 제공하며, 두 가지 선택적 외부 서비스 백엔드인 qdrant (REST)와 pgvector (Postgres)를 함께 제공합니다. 이 두 외부 백엔드는 서로 다른 기질(REST/딕셔너리 스토어 및 SQL/JSONB 스토어)에서 저장소 계약을 수행하므로, 특정 벤더에 우연히 맞춰지지 않습니다.

# 로컬 비서비스 백엔드
mempalace mine ~/projects/myapp --backend sqlite_exact
# Qdrant 백엔드 (기본값: http://localhost:6333)
...

Qdrant는 또한 MEMPALACE_QDRANT_API_KEY, MEMPALACE_QDRANT_NAMESPACE, 및 MEMPALACE_QDRANT_TIMEOUT으로 구성할 수 있습니다. pgvector는 MEMPALACE_PGVECTOR_NAMESPACE로 구성합니다. 두 외부 백엔드 모두 네임스페이스(지원되는 supports_namespace_isolation 기능에 의해 광고됨)별로 테넌트를 격리하고, 잘못된 서버에 대해 실수로 palace를 열어두는 것을 방지하기 위해 로컬 마커(qdrant_backend.json / pgvector_backend.json)를 작성합니다.

MEMPALACE_QDRANT_URL 또는 MEMPALACE_PGVECTOR_DSN

자신의 로컬 또는 신뢰할 수 있는 셀프 호스팅 (self-hosted) 서비스가 아닌 다른 곳을 지정할 경우, MemPalace는 작성된 텍스트와 메타데이터를 있는 그대로 해당 위치로 전송하고 저장합니다. 이는 명시적인 백엔드 선택 (opt-in) 사항이며, 결코 기본값 (default)이 아닙니다.

# 콘텐츠를 palace로 마이닝 (mine)
mempalace mine ~/projects/myapp # 프로젝트 파일
mempalace mine ~/.claude/projects/ --mode convos # Claude Code 세션 (프로젝트별로 --wing을 사용하여 범위 지정)
...

Claude Code, Gemini CLI, MCP 호환 도구 및 로컬 모델에 대한 내용은 mempalaceofficial.com/guide/getting-started를 참조하세요.

아래의 모든 수치는 benchmarks/BENCHMARKS.md에 있는 명령어를 통해 이 저장소에서 재현 가능합니다.

질문당 전체 결과 파일은 benchmarks/results_* 아래에 커밋되어 있습니다.

LongMemEval — 검색 재현율 (retrieval recall) (R@5, 500개 질문):

모드	R@5	필요한 LLM
Raw (시맨틱 검색 (semantic search), 휴리스틱 없음, LLM 없음)	96.6%	없음
Hybrid v4, 홀드아웃 (held-out) 450q (50개 개발용 데이터로 튜닝, 학습 중 미노출)	98.4%	없음
Hybrid v4 + LLM 재순위화 (rerank) (전체 500개)	≥99%	역량 있는 모든 모델

Raw 방식의 96.6%는 어떤 단계에서도 API 키, 클라우드, LLM을 필요로 하지 않습니다. 하이브리드 (hybrid) 파이프라인은 키워드 부스팅 (keyword boosting), 시간적 근접성 부스팅 (temporal-proximity boosting), 선호도 패턴 추출 (preference-pattern extraction)을 추가합니다. 홀드아웃(held-out) 방식의 98.4%가 정직하고 일반화 가능한 수치입니다.

재순위화 (rerank) 파이프라인은 LLM 리더 (reader)를 사용하여 검색된 상위 20개 세션 중 최적의 후보를 승격시킵니다. 이는 합리적인 역량을 갖춘 어떤 모델과도 작동합니다. 당사는 Claude Haiku, Claude Sonnet, 그리고 Ollama Cloud를 통한 minimax-m2.7(Anthropic 의존성 없음)로 이를 재현했습니다. Raw 방식과 재순위화 방식 사이의 격차는 모델에 구애받지 않습니다. 당사는 "100%"라는 수치를 헤드라인으로 내세우지 않는데, 그 이유는 마지막 0.6%가 특정 오답을 검토함으로써 도달한 수치이며, benchmarks/BENCHMARKS.md에서는 이를 시험 문제에 맞춘 학습 (teaching to the test)으로 분류하기 때문입니다.

기타 벤치마크 (전체 결과는 benchmarks/BENCHMARKS.md에서 확인 가능):

벤치마크 (Benchmark)	지표 (Metric)	점수 (Score)	비고 (Notes)
LoCoMo (session, top-10, no rerank)	R@10	60.3%	1,986개 질문
...

우리는 Mem0, Mastra, Hindsight, Supermemory 또는 Zep과의 병렬 비교 (side-by-side comparison)를 의도적으로 포함하지 않았습니다. 해당 프로젝트들은 서로 다른 데이터 분할 (splits)에 대해 서로 다른 지표를 발표하고 있으며, 검색 재현율 (retrieval recall)을 엔드투엔드 질의응답 (end-to-end QA) 정확도와 나란히 배치하는 것은 정직한 비교가 아닙니다. 각 프로젝트가 발표한 수치는 해당 프로젝트의 연구 페이지를 참조하십시오.

모든 결과 재현하기 (Reproducing every result):

git clone https://github.com/MemPalace/mempalace.git
cd mempalace
uv sync --extra dev # 또는: pip install -e "[dev]"
...

MemPalace는 유효 기간 (validity windows)을 가진 시계열 개체-관계 그래프 (temporal entity-relationship graph)를 포함하며 — 추가 (add), 쿼리 (query), 무효화 (invalidate), 타임라인 (timeline) — 로컬 SQLite를 기반으로 작동합니다. 사용법 및 도구 참조: mempalaceofficial.com/concepts/knowledge-graph.

29개의 MCP 도구는 palace 읽기/쓰기, 지식 그래프 (knowledge-graph) 작업, 크로스 윙 (cross-wing) 탐색, 서랍 (drawer) 관리 및 에이전트 일기 (agent diaries)를 지원합니다. 설치 및 전체 도구 목록: mempalaceofficial.com/reference/mcp-tools.

각 전문 에이전트 (specialist agent)는 palace 내에 자신만의 윙 (wing)과 일기를 가집니다.
런타임 시 mempalace_list_agents를 통해 탐색 가능합니다.

시스템 프롬프트 (system prompt)의 비대화를 방지합니다:
mempalaceofficial.com/concepts/agents.

두 개의 Claude Code 훅 (hooks)은 주기적으로, 그리고 컨텍스트 압축 (context compression) 전에 저장 작업을 수행합니다: mempalaceofficial.com/guide/hooks.

시간 압박 속에서 설치해야 하는 경우, Claude Code 유지 관리 설정 체크리스트부터 시작하십시오:
훅을 연결하고, 기존 JSONL 트랜스크립트 (transcripts)를 백업한 다음,
mempalace mine ~/.claude/projects/ --mode convos
명령어로 데이터를 채워 넣으십시오.

훅이 생성하는 파일 수준의 청크 (chunks) 외에 메시지별 재현 (per-message recall)을 원한다면,
mempalace sweep <transcript-dir>
을 주기적으로 실행하십시오. 이는 사용자/어시스턴트 메시지당 하나의 축자적 (verbatim) 서랍을 저장하며, 멱등성 (idempotent)이 보장되고 재개 (resume) 시 안전합니다.

• Python 3.9+
• 벡터 저장소 백엔드 (vector-store backend) (기본값: ChromaDB)
• 임베딩 모델 (embedding model)을 위한 약 300 MB의 디스크 공간. 온보딩 (
  python -m mempalace.onboarding
  ) 시 embeddinggemma-300m을 제공합니다.

(다국어 지원, 100개 이상의 언어, 권장됨) 또는 all-MiniLM-L6-v2 (영어 전용, 약 30 MB). 자세한 내용과 마이그레이션(migration) 참고 사항은 mempalace/embedding.py의 docstring을 확인하세요.

핵심 벤치마크(benchmark) 경로에는 API 키가 필요하지 않습니다.

• 시작하기 → mempalaceofficial.com/guide/getting-started
• CLI 레퍼런스 → mempalaceofficial.com/reference/cli
• Python API → mempalaceofficial.com/reference/python-api
• 전체 벤치마크 방법론 → benchmarks/BENCHMARKS.md
• 릴리스 노트 → CHANGELOG.md
• 수정 사항 및 공지 사항 → docs/HISTORY.md

PR(Pull Request)을 환영합니다. CONTRIBUTING.md를 참조하세요.

MIT — LICENSE를 참조하세요.