MemPalace/mempalace

<div align="center">

<img src="assets/mempalace_logo.png" alt="MemPalace" width="240">

MemPalace

로컬 우선 AI 메모리. 원문 저장, 플러그형 백엔드, LongMemEval에서 96.6% R@5 raw — API 호출 없음.

</div>

[!CAUTION]

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

[!IMPORTANT]

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

>

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

무엇인가요

MemPalace는 대화 기록을 원문 텍스트로 저장하고 의미 검색으로 검색합니다. 요약, 추출, 또는 의역하지 않습니다. 인덱스는 구조화되어 있습니다 — 사람과 프로젝트는 날개(wings)가 되고, 주제는 방(rooms)이 되며, 원본 콘텐츠는 서랍(drawers)에 있습니다 — 따라서 검색이 평평한 코퍼스에 대해 실행되는 것이 아니라 범위를 지정할 수 있습니다.

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

사용자가 동의하지 않는 한 어떤 데이터도 기계 밖으로 나가지 않습니다.

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

설치

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

uv를 권장합니다 — uv tool install은 mempalace CLI를 PATH의 격리된 환경에 넣습니다:

uv tool install mempalace
mempalace init ~/projects/myapp

pipx도 선호한다면 같은 방식으로 작동합니다: pipx install mempalace.

import mempalace를 명시적으로 사용 가능하게 하려는 활성화된 virtualenv 내에서만 일반 pip를 선호합니다:

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

Docker

로컬 Python 도구 체인 없이 MCP 서버 또는 CLI를 실행하기 위한 컨테이너 이미지도 제공됩니다. 모든 것은 /data 아래에 유지됩니다(palace, config 및 캐시된 임베딩 모델). 따라서 볼륨을 마운트하세요.

# 이미지 빌드 (CPU; `extract` + `spellcheck` extras 번들)
docker build -t mempalace.

# stdio를 통한 MCP 서버 — `-i` 플래그 참고 (JSON-RPC는 stdin 필요)
docker run -i --rm -v mempalace-data:/data mempalace

# 대신 CLI 명령 실행 (마이닝하려는 호스트 디렉토리 마운트)
docker run --rm -v mempalace-data:/data -v /path/to/project:/work mempalace mine /work
docker run --rm -v mempalace-data:/data mempalace search "why GraphQL"

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

{
  "mcpServers": {
    "mempalace": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "mempalace-data:/data", "mempalace"]
    }
  }
}

docker compose run --rm mcp도 작동합니다(docker-compose.yml 참조). CUDA 가속 임베딩의 경우 docker build -f Dockerfile.gpu -t mempalace:gpu.로 GPU 변형을 빌드하고 --gpus all로 실행하세요. 빌드 시 번들 extras를 사용자 정의하세요(예: docker build --build-arg EXTRAS="extract,spellcheck" -t mempalace.).

스토리지 백엔드

ChromaDB가 기본값입니다. 플러그형 백엔드 미리보기의 경우, MemPalace는 로컬 정확 벡터 정확성 검사를 위한 sqlite_exact와 두 가지 옵트인 외부 서비스 백엔드 — qdrant (REST) 및 pgvector (Postgres)도 제공합니다. 두 외부 백엔드는 서로 다른 기반(REST/dict 저장소 및 SQL/JSONB 저장소)에서 스토리지 계약을 테스트하므로, 특정 벤더에 맞춰 우연히 형성되지 않습니다.

# 로컬 무서비스 백엔드
mempalace mine ~/projects/myapp --backend sqlite_exact

# Qdrant 백엔드, 기본값 http://localhost:6333
MEMPALACE_QDRANT_URL=http://localhost:6333 \
  mempalace mine ~/projects/myapp --backend qdrant

# Postgres + pgvector 백엔드, 기본값 postgresql://localhost:5432/mempalace
#   선택적 드라이버 필요: pip install mempalace[pgvector]
#   서버에서 `vector` 확장 사용 가능해야 함
MEMPALACE_PGVECTOR_DSN=postgresql://localhost:5432/mempalace \
  mempalace mine ~/projects/myapp --backend pgvector

Qdrant는 MEMPALACEQDRANTAPIKEY, MEMPALACEQDRANTNAMESPACE, MEMPALACEQDRANTTIMEOUT으로도 구성할 수 있습니다. pgvector는 MEMPALACEPGVECTORNAMESPACE로 구성할 수 있습니다. 두 외부 백엔드는 네임스페이스로 테넌트를 격리하고(supportsnamespaceisolation 기능을 통해 알림), 로컬 마커(qdrantbackend.json / pgvector_backend.json)를 작성하여 잘못된 서버에 대해 palace를 여는 것을 방지합니다.

MEMPALACEQDRANTURL 또는 MEMPALACEPGVECTORDSN이 사용자 자신의 로컬 또는 신뢰할 수 있는 자체 호스팅 서비스 이외의 다른 곳을 가리키는 경우, MemPalace는 원문 서랍 텍스트와 메타데이터를 해당 위치로 보내고 저장합니다. 이는 명시적인 옵트인 백엔드 선택이며, 기본값이 아닙니다.

빠른 시작

# palace에 콘텐츠 마이닝
mempalace mine ~/projects/myapp                    # 프로젝트 파일
mempalace mine ~/.claude/projects/ --mode convos   # Claude Code 세션 (프로젝트당 --wing으로 범위 지정)

# 검색
mempalace search "why did we switch to GraphQL"

# 새 세션을 위한 컨텍스트 로드
mempalace wake-up

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

벤치마크

아래 모든 수치는 이 저장소에서 benchmarks/BENCHMARKS.md의 명령어로 재현 가능합니다. 전체 질문별 결과 파일은 benchmarks/results_* 아래에 커밋되어 있습니다.

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

Raw 96.6%는 API 키, 클라우드, 또는 어떤 단계에서도 LLM이 필요하지 않습니다. 하이브리드 파이프라인은 키워드 부스팅, 시간적 근접성 부스팅 및 선호도 패턴 추출을 추가합니다. held-out 98.4%는 정직하게 일반화 가능한 수치입니다.

rerank 파이프라인은 LLM 리더를 사용하여 검색된 상위 20개 세션 중 최상의 후보를 승격시킵니다. 합리적으로 유능한 모든 모델에서 작동합니다 — Claude Haiku, Claude Sonnet, Ollama Cloud를 통한 minimax-m2.7로 재현했습니다(Anthropic 종속성 없음). raw와 rerank 간의 차이는 모델에 무관합니다. "100%" 수치를 강조하지 않는 이유는 마지막 0.6%가 특정 오답을 검사하여 도달했기 때문이며, benchmarks/BENCHMARKS.md는 이를 테스트에 맞춰 가르치는 것으로 플래그 지정합니다.

기타 벤치마크 (전체 결과는 benchmarks/BENCHMARKS.md에 있음):

우리는 의도적으로 Mem0, Mastra, Hindsight, Supermemory 또는 Zep과의 나란히 비교를 포함하지 않습니다. 해당 프로젝트들은 다른 분할에 대해 다른 메트릭을 게시하며, 검색 재현율을 종단간 QA 정확도 옆에 배치하는 것은 정직한 비교가 아닙니다. 게시된 수치는 각 프로젝트의 자체 연구 페이지를 참조하세요.

모든 결과 재현:

git clone https://github.com/MemPalace/mempalace.git
cd mempalace
uv sync --extra dev   # 또는: pip install -e ".[dev]"
# 데이터셋 다운로드 명령어는 benchmarks/README.md 참조
uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json

지식 그래프

MemPalace는 유효성 기간이 있는 시간적 엔터티-관계 그래프를 포함합니다 — 추가, 쿼리, 무효화, 타임라인 — 로컬 SQLite로 백업됩니다. 사용법 및 도구 참조: mempalaceofficial.com/concepts/knowledge-graph.

MCP 서버

35개의 MCP 도구가 palace 읽기/쓰기, 지식 그래프 작업, 날개 간 탐색, 서랍 관리 및 에이전트 일기를 다룹니다. 설치 및 전체 도구 목록: mempalaceofficial.com/reference/mcp-tools.

에이전트

각 전문 에이전트는 palace에서 자체 날개와 일기를 얻습니다. mempalacelistagents를 통해 런타임에 검색 가능 — 시스템 프롬프트에 bloating 없음: mempalaceofficial.com/concepts/agents.

자동 저장 후크

Claude Code, Codex CLI 및 Cursor IDE를 위한 자동 저장 후크는 주기적으로 그리고 컨텍스트 압축 전에 저장합니다:

• Claude Code + Codex →

• Cursor IDE (세션 시작 recall 및 압축 전 트랜스크립트 스냅샷 추가) →

mempalaceofficial.com/guide/hooks mempalaceofficial.com/guide/cursor-hooks

시간 압박 속에서 설치하는 경우, Claude Code 보존 설정 체크리스트로 시작하세요: 후크 연결, 기존 JSONL 트랜스크립트 백업, mempalace mine ~/.claude/projects/ --mode convos로 백필.

후크가 생성하는 파일 수준 청크 위에 메시지별 recall을 위해, 주기적으로 mempalace sweep <transcript-dir>을 실행하세요 — 사용자/어시스턴트 메시지당 하나의 원문 서랍을 저장하며, 멱등성 있고 재개 안전합니다.

요구 사항

• Python 3.9+
• 벡터 저장소 백엔드 (기본값 ChromaDB)
• 임베딩 모델을 위한 ~300 MB 디스크. 온보딩(python -m mempalace.onboarding)은 embeddinggemma-300m(다국어, 100개 이상 언어, 권장) 또는 all-MiniLM-L6-v2(영어 전용, ~30 MB)를 제공합니다. 자세한 내용 및 마이그레이션 노트는 mempalace/embedding.py의 독스트링을 참조하세요.

핵심 벤치마크 경로에는 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 환영합니다. CONTRIBUTING.md를 참조하세요.

라이선스

MIT — LICENSE 참조.