mempalace

MemPalace
로컬 우선 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는 대화 기록을 원문 텍스트로 저장하고 시맨틱 검색으로 검색합니다. 요약, 추출, 의역을 하지 않습니다. 인덱스는 구조화되어 있습니다 — 사람과 프로젝트는 wings가 되고, 주제는 rooms가 되며, 원본 콘텐츠는 drawers에 저장됩니다 — 따라서 검색은 평면적인 코퍼스에 대해 실행되는 대신 범위를 지정할 수 있습니다.

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

옵트인하지 않는 한 아무것도 여러분의 머신을 떠나지 않습니다.

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

설치
에이전트 안내 설정
먼저 MemPalace 스킬을 설치한 다음, 코딩 에이전트에게 MemPalace를 설정하도록 요청하세요. 설정 스킬은 시스템을 감지하고, Python 패키지를 설치하고, MCP를 구성하며, 비공개 로컬 팰리스, 공유 브레인 허브, 또는 기존 허브에 연결된 클라이언트 중 무엇을 원하는지 묻습니다:

npx skills add MemPalace/mempalace
저장소는 세 가지 스킬을 제공합니다: 안내 설치 및 운영을 위한 mempalace, 답변 전 검색 리콜을 위한 mempalace-recall, logstream 위임을 위한 mempalace-task. 스킬을 설치한다고 해서 MemPalace CLI나 MCP 서버가 설치되는 것은 아닙니다; 설정 스킬이 에이전트를 안내하여 그러한 시스템 변경을 수행하고 라이브 연결을 검증합니다.

안내 설정 중에 에이전트는 주간 안정 릴리스 확인을 제안할 수 있습니다. 기본적으로 비활성화되어 있으며, 활성화되면 PyPI에만 접속하고, 업데이트를 자동으로 설치하지 않습니다. 캐시된 가용성 정보는 서빙 런타임에 대한 범위 지정된 mempalace_status 필드에 나타나며, 로컬 프록시가 있는 경우 그 클라이언트 런타임에도 나타나므로, 에이전트가 릴리스를 설명하고 정확한 업그레이드 계획을 보여주기 전에 승인을 요청할 수 있습니다. 설정은 런타임이 uv tool, pipx, 또는 pip에서 왔는지 기록하므로 계획이 잘못된 설치에 대해 업그레이드 명령을 제안하는 일이 없습니다.

직접 CLI 설정
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
Android / Termux
ChromaDB와 ONNX Runtime 같은 컴파일된 의존성이 Android 휠이 아닌 Linux 휠을 배포하기 때문에 네이티브 Termux 설치는 현재 지원되지 않습니다. Android ARM64 사용자는 대신 격리된 Debian PRoot 컨테이너에서 일반 Linux 패키지를 실행할 수 있습니다. 테스트된 설정과 argv 보존 런처는 Termux 설치 가이드를 참조하세요.

Docker
로컬 Python 툴체인 없이 MCP 서버나 CLI를 실행하기 위한 컨테이너 이미지도 제공됩니다. 멀티 아키텍처(amd64 + arm64)이므로 Apple Silicon에서 네이티브로 실행됩니다:

docker pull ghcr.io/mempalace/mempalace:latest
모든 것이 /data 아래에 유지됩니다 — 팰리스, 구성, 캐시된 임베딩 모델 — 따라서 거기에 볼륨을 마운트하고 실행 간에 재사용하세요:

# MCP server over stdio — note the `-i` flag (JSON-RPC needs stdin)
docker run -i --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace

# Run any CLI command instead. The container only sees what you mount, so
# mount the directory you want to mine — read-only is enough, mining never
# writes to the source.
docker run --rm -v mempalace-data:/data -v /path/to/project:/work:ro \
ghcr.io/mempalace/mempalace mine /work
docker run --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace search " why GraphQL "
임베딩이 필요한 첫 번째 명령은 모델을 /data로 다운로드합니다(기본 minilm의 경우 ~80 MB, embeddinggemma의 경우 ~300 MB). 볼륨이 유지되는 한 일회성 작업이지만, 첫 호출이 느리고 네트워크가 필요하다는 의미이므로 컨테이너가 멈췄다고 가정하기 전에 알아두는 것이 좋습니다.

MCP 클라이언트(예: Claude Code)에 stdio 서버로 연결하세요. 서버가 마이닝할 수 있도록 원하는 것은 무엇이든 마운트하세요 — 그렇지 않으면 서버가 여러분의 트랜스크립트에 접근할 수 없습니다:

{
"mcpServers" : {
"mempalace" : {
"command" : " docker " ,
"args" : [
" run " , " -i " , " --rm " ,
" -v " , " mempalace-data:/data " ,
" -v " , " /absolute/path/to/.claude/projects:/transcripts:ro " ,
" ghcr.io/mempalace/mempalace "
]
}
}
}
거기에 실제 절대 경로를 사용하세요 — ~와 $HOME은 모든 MCP 클라이언트에서 확장되지 않습니다. 경로는 그때부터 컨테이너 경로입니다: ~/.claude/projects가 아니라 mine /transcripts.

Linux의 마운트 권한. 이미지는 uid 1000으로 실행되며 바인드 마운트는 호스트 소유권을 유지하므로, 마운트된 디렉터리는 해당 uid가 읽을 수 있어야 합니다 — 일반적인 0755 체크아웃은 괜찮지만 0700 디렉터리는 안 되며, 실패는 Docker에 관한 것이 아니라 PermissionError: [Errno 13]으로 나타납니다. Docker Desktop은 macOS와 Windows에서 uid를 매핑하므로 이는 Linux에서만 문제가 됩니다. --user로 우회하지 마세요: /data는 이미지 내부에서 uid 1000이 소유하므로 다른 uid는 팰리스를 전혀 쓸 수 없습니다.

docker compose run --rm mcp도 작동하며(docker-compose.yml 참조), deploy/docker-compose.server.yml은 팀 서버를 세웁니다. 풀하는 대신 이미지를 직접 빌드하려면 — 게시되지 않은 GPU 변형에 필요합니다:

docker build -t mempalace . # CPU
docker build --build-arg EXTRAS= " extract,spellcheck " -t mempalace .
docker build -f Dockerfile.gpu -t mempalace:gpu . # CUDA; run with --gpus all
GPU 이미지는 x86_64 전용입니다: onnxruntime-gpu는 aarch64 Linux 휠을 게시하지 않으므로, 그 마지막 빌드는 ARM 호스트(Apple Silicon 포함)에서 명확하지 않은 의존성 해결 오류로 실패합니다.

클론에서 빌드하면 체크아웃한 브랜치를 사용한다는 점에 유의하세요; develop이 기본 브랜치이므로 릴리스된 버전을 원하면 게시된 이미지를 풀하세요.

스토리지 백엔드
ChromaDB가 기본이며 구성이 필요 없습니다. MemPalace는 또한 플러그 가능한 백엔드 계약을 제공하며, 의도적으로 서로 다른 기반에 걸쳐 실행되어 계약이 실수로 한 벤더를 중심으로 형성되지 않도록 합니다. 모든 비기본 백엔드는 옵트인입니다.

백엔드
모드
설치
네임스페이스
어휘
구성 방법

chroma (기본)
로컬 (임베디드)
번들
–
✓
–

sqlite_exact
로컬 (정확한 NumPy)
번들
–
✓
–

rust_exact
로컬 (네이티브 벡터)
휠 / 컴파일됨
–
✓
–

milvus
로컬 (Lite) · 서버 옵트인
mempalace[milvus]
✓
✓
MEMPALACE_MILVUS_URI

qdrant
서버 (REST)
번들
✓
✓
MEMPALACE_QDRANT_URL

pgvector
서버 (Postgres)
mempalace[pgvector]
✓
✓
MEMPALACE_PGVECTOR_DSN

--backend <name>, MEMPALACE_BACKEND=<name>, 또는 config.json의 "backend": "<name>"으로 선택하세요. rust_exact는 sqlite_exact와 디스크상에서 정확히 동일한 sqlite_exact.sqlite3 파일을 데이터 마이그레이션 없이 사용합니다. 별도로 배포되는 휠과 실행 파일은 네이티브 설치 및 벡터 CLI 사용법을 참조하세요.

네이티브 벡터 검색
rust_exact와 독립 실행형 mempalace-native CLI는 네이티브 Rust 엔진으로 동일한 sqlite_exact 데이터베이스를 스캔합니다. rust_exact 어댑터는 복잡한 필터, 반환된 임베딩 요청, 네이티브 확장이 없는 설치의 경우 Python 백엔드로 폴백합니다; mempalace-native 실행 파일은 Rust 전용이며 Python 폴백이 없습니다. 이 릴리스에 대해 게시된 벤치마크 수치는 없습니다; mempalace-native bench --db <sqlite_exact.sqlite3>가 여러분의 데이터에서 측정합니다. 코어 워크스페이스, PyO3 바인딩, 네이티브 CLI는 crates/를 참조하세요.

빠른 시작
# Mine content into the palace
mempalace mine ~ /projects/myapp # project files
mempalace mine ~ /.claude/projects/ --mode convos # Claude Code sessions (scope with --wing per project)

# Search
mempalace search " why did we switch to GraphQL "

# Load context for a new session
mempalace wake-up

# Score how well organized the palace is (read-only, safe while the MCP server runs)
mempalace audit
Claude Code, Gemini CLI, Antigravity, MCP 호환 도구, 로컬 모델의 경우 mempalaceofficial.com/guide/getting-started를 참조하세요.

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

LongMemEval — 검색 리콜 (R@5, 500 질문):

모드
R@5
LLM 필요

Raw (시맨틱 검색, 휴리스틱 없음, LLM 없음)
96.6%
없음

Hybrid v4, 홀드아웃 450q (50 dev에서 튜닝, 학습 중 보지 않음)
98.4%
없음

Hybrid v4 + LLM 리랭크 (전체 500)
≥99%
유능한 모델 아무거나

raw 96.6%는 API 키, 클라우드, 그리고 어느 단계에서든 LLM이 필요 없습니다. 하이브리드 파이프라인은 키워드 부스팅, 시간적 근접성 부스팅, 선호 패턴 추출을 추가합니다; 홀드아웃 98.4%가 정직하게 일반화 가능한 수치입니다.

리랭크 파이프라인은 LLM 리더를 사용하여 상위 20개 검색된 세션 중 최고 후보를 승격합니다. 합리적으로 유능한 모델이면 작동합니다 — Claude Haiku, Claude Sonnet, 그리고 Ollama Cloud를 통한 minimax-m2.7(Anthropic 의존성 없음)로 재현했습니다. raw와 리랭크 간의 격차는 모델에 무관합니다; 마지막 0.6%는 특정 오답을 검사하여 도달했기 때문에 "100%" 수치를 헤드라인으로 내세우지 않으며, benchmarks/BENCHMARKS.md는 이를 시험에 맞춘 교수법으로 표시합니다.

다른 벤치마크(전체 결과는 benchmarks/BENCHMARKS.md):

벤치마크
지표
점수
비고

LoCoMo (세션, top-10, 리랭크 없음)
R@10
60.3%
1,986 질문

LoCoMo (hybrid v5, top-10, 리랭크 없음)
R@10
88.9%
동일 세트

ConvoMem (모든 카테고리, 250 항목)
평균 리콜
92.9%
카테고리당 50

MemBench (ACL 2025, 8,500 항목)
R@5
80.3%
모든 카테고리

우리는 의도적으로 Mem0, Mastra, Hindsight, Supermemory, Zep과의 나란히 비교를 포함하지 않습니다. 그 프로젝트들은 서로 다른 분할에서 서로 다른 지표를 게시하며, 검색 리콜을 엔드투엔드 QA 정확도 옆에 놓는 것은 정직한 비교가 아닙니다. 게시된 수치는 각 프로젝트의 자체 연구 페이지를 참조하세요.

모든 결과 재현:

git clone https://github.com/MemPalace/mempalace.git
cd mempalace
uv sync --extra dev # or: pip install -e ".[dev]"
# see benchmarks/README.md for dataset download commands
uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json

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

MCP 서버
47개의 MCP 도구가 팰리스 읽기/쓰기, 지식 그래프 작업, 크로스 윙 내비게이션, 드로어 관리, 에이전트 다이어리, 에이전트 조정(logstream 이벤트 + 아티팩트 핸드오프)을 다룹니다. 설치 및 전체 도구 목록: mempalaceofficial.com/reference/mcp-tools.

에이전트
각 전문 에이전트는 팰리스에서 자체 윙과 다이어리를 갖습니다. 런타임에 mempalace_list_agents로 검색 가능 — 시스템 프롬프트에 부풀리지 않음: mempalaceofficial.com/concepts/agents.

자동 저장 훅
Claude Code, Codex CLI, Cursor IDE용 자동 저장 훅은 주기적으로 그리고 컨텍스트 압축 전에 저장합니다:

Claude Code + Codex → mempalaceofficial.com/guide/hooks
Cursor IDE (세션 시작 리콜과 압축 전 트랜스크립트 스냅샷 추가) → mempalaceofficial.com/guide/cursor-hooks

만약 y…