MCP 메모리 서비스
ChromaDB와 문장 변환기를 사용하여 Claude Desktop에 의미 메모리와 영구 저장 기능을 제공하는 MCP 서버입니다. 이 서비스는 의미 검색 기능을 갖춘 장기 메모리 저장 기능을 제공하여 대화와 인스턴스 전반의 맥락을 유지하는 데 이상적입니다.
돕다
TalkToGitHub 에서 저장소와 대화해보세요!
특징
- 문장 변환기를 사용한 의미 검색
- 자연어 시간 기반 리콜 (예: "지난주", "어제 아침")
- 태그 기반 메모리 검색 시스템
- ChromaDB를 사용한 영구 저장소
- 자동 데이터베이스 백업
- 메모리 최적화 도구
- 정확한 일치 검색
- 유사성 분석을 위한 디버그 모드
- 데이터베이스 상태 모니터링
- 중복 감지 및 정리
- 사용자 정의 가능한 임베딩 모델
- 크로스 플랫폼 호환성 (Apple Silicon, Intel, Windows, Linux)
- 다양한 환경에 대한 하드웨어 인식 최적화
- 제한된 하드웨어 리소스에 대한 우아한 대체
설치
빠른 시작(권장)
향상된 설치 스크립트는 자동으로 시스템을 감지하고 적절한 종속성을 설치합니다.
지엑스피1
install.py 스크립트는 다음을 수행합니다.
- 시스템 아키텍처와 사용 가능한 하드웨어 가속기를 감지합니다.
- 플랫폼에 적합한 종속성을 설치하세요
- 사용자 환경에 맞는 최적의 설정을 구성하세요
- 설치를 확인하고 필요한 경우 진단을 제공합니다.
도커 설치
Docker를 사용하여 메모리 서비스를 실행할 수 있습니다.
# Using Docker Compose (recommended)
docker-compose up
# Using Docker directly
docker build -t mcp-memory-service .
docker run -p 8000:8000 -v /path/to/data:/app/chroma_db -v /path/to/backups:/app/backups mcp-memory-service
다양한 시나리오에 맞춰 여러 가지 Docker Compose 구성을 제공합니다.
docker-compose.yml - pip install을 사용한 표준 구성docker-compose.uv.yml - UV 패키지 관리자를 사용한 대체 구성docker-compose.pythonpath.yml - 명시적 PYTHONPATH 설정을 사용한 구성
대체 구성을 사용하려면:
docker-compose -f docker-compose.uv.yml up
Windows 설치(특수한 경우)
Windows 사용자는 플랫폼별 휠 가용성으로 인해 PyTorch 설치 문제가 발생할 수 있습니다. Windows 전용 설치 스크립트를 사용하세요.
# After activating your virtual environment
python scripts/install_windows.py
이 스크립트는 다음을 처리합니다.
- CUDA 가용성 및 버전 감지
- 올바른 인덱스 URL에서 적절한 PyTorch 버전 설치
- PyTorch와 충돌하지 않고 다른 종속성 설치
- 설치 확인
Smithery를 통해 설치
Smithery를 통해 Claude Desktop용 메모리 서비스를 자동으로 설치하려면:
npx -y @smithery/cli install @doobidoo/mcp-memory-service --client claude
자세한 설치 가이드
포괄적인 설치 지침과 문제 해결에 대해서는 설치 가이드를 참조하세요.
클로드 MCP 구성
표준 구성
claude_desktop_config.json 파일에 다음을 추가하세요.
{
"memory": {
"command": "uv",
"args": [
"--directory",
"your_mcp_memory_service_directory", // e.g., "C:\\REPOSITORIES\\mcp-memory-service"
"run",
"memory"
],
"env": {
"MCP_MEMORY_CHROMA_PATH": "your_chroma_db_path", // e.g., "C:\\Users\\John.Doe\\AppData\\Local\\mcp-memory\\chroma_db"
"MCP_MEMORY_BACKUPS_PATH": "your_backups_path" // e.g., "C:\\Users\\John.Doe\\AppData\\Local\\mcp-memory\\backups"
}
}
}
Windows 특정 구성(권장)
Windows 사용자의 경우 PyTorch가 제대로 설치되었는지 확인하기 위해 래퍼 스크립트를 사용하는 것이 좋습니다.
{
"memory": {
"command": "python",
"args": [
"C:\\path\\to\\mcp-memory-service\\memory_wrapper.py"
],
"env": {
"MCP_MEMORY_CHROMA_PATH": "C:\\Users\\YourUsername\\AppData\\Local\\mcp-memory\\chroma_db",
"MCP_MEMORY_BACKUPS_PATH": "C:\\Users\\YourUsername\\AppData\\Local\\mcp-memory\\backups"
}
}
}
래퍼 스크립트는 다음을 수행합니다.
- PyTorch가 설치되고 올바르게 구성되었는지 확인하세요.
- 필요한 경우 올바른 인덱스 URL로 PyTorch를 설치하세요.
- 적절한 구성으로 메모리 서버를 실행하세요
사용 가이드
Claude Desktop에서 메모리 서비스와 상호 작용하는 방법에 대한 자세한 지침:
- 호출 가이드 - Claude에서 메모리 작업을 트리거하는 특정 키워드와 구문을 알아보세요
- 설치 가이드 - 자세한 설정 지침
메모리 서비스는 클로드와의 대화에서 자연어 명령을 통해 호출됩니다. 예:
- 저장 방법: "제 프로젝트 마감일은 5월 15일임을 기억해 주세요."
- 검색: "프로젝트 마감일과 관련해서 제가 말씀드린 걸 기억하시나요?"
- 삭제 방법: "제 주소에 대해 제가 말한 내용은 잊어주세요."
전체 명령어 목록과 자세한 사용 예는 호출 가이드를 참조하세요.
메모리 작업
메모리 서비스는 MCP 서버를 통해 다음과 같은 작업을 제공합니다.
코어 메모리 작업
store_memory - 선택적 태그를 사용하여 새 정보를 저장합니다.retrieve_memory - 관련 메모리에 대한 의미 검색을 수행합니다.recall_memory - 자연어 시간 표현을 사용하여 메모리 검색search_by_tag - 특정 태그를 사용하여 추억 찾기exact_match_retrieve - 정확한 콘텐츠 일치로 메모리 찾기debug_retrieve - 유사도 점수로 메모리 검색
데이터베이스 관리
create_backup - 데이터베이스 백업 생성get_stats - 메모리 통계 가져오기optimize_db - 데이터베이스 성능 최적화check_database_health - 데이터베이스 상태 지표 가져오기check_embedding_model - 모델 상태 확인
메모리 관리
delete_memory - 해시로 특정 메모리 삭제delete_by_tag - 특정 태그가 있는 모든 메모리 삭제cleanup_duplicates - 중복 항목 제거
구성 옵션
환경 변수를 통해 구성:
CHROMA_DB_PATH: Path to ChromaDB storage
BACKUP_PATH: Path for backups
AUTO_BACKUP_INTERVAL: Backup interval in hours (default: 24)
MAX_MEMORIES_BEFORE_OPTIMIZE: Threshold for auto-optimization (default: 10000)
SIMILARITY_THRESHOLD: Default similarity threshold (default: 0.7)
MAX_RESULTS_PER_QUERY: Maximum results per query (default: 10)
BACKUP_RETENTION_DAYS: Number of days to keep backups (default: 7)
LOG_LEVEL: Logging level (default: INFO)
# Hardware-specific environment variables
PYTORCH_ENABLE_MPS_FALLBACK: Enable MPS fallback for Apple Silicon (default: 1)
MCP_MEMORY_USE_ONNX: Use ONNX Runtime for CPU-only deployments (default: 0)
MCP_MEMORY_USE_DIRECTML: Use DirectML for Windows acceleration (default: 0)
MCP_MEMORY_MODEL_NAME: Override the default embedding model
MCP_MEMORY_BATCH_SIZE: Override the default batch size
하드웨어 호환성
| 플랫폼 | 건축학 | 촉진 신경 | 상태 |
|---|
| 맥OS | 애플 실리콘(M1/M2/M3) | MPS | ✅ 완벽히 지원됨 |
| 맥OS | Rosetta 2 아래의 Apple Silicon | CPU | ✅ 폴백 지원 |
| 맥OS | 인텔 | CPU | ✅ 완벽히 지원됨 |
| 윈도우 | x86_64 | 쿠다 | ✅ 완벽히 지원됨 |
| 윈도우 | x86_64 | 다이렉트ML | ✅ 지원됨 |
| 윈도우 | x86_64 | CPU | ✅ 폴백 지원 |
| 리눅스 | x86_64 | 쿠다 | ✅ 완벽히 지원됨 |
| 리눅스 | x86_64 | ROCm | ✅ 지원됨 |
| 리눅스 | x86_64 | CPU | ✅ 폴백 지원 |
| 리눅스 | ARM64 | CPU | ✅ 폴백 지원 |
테스트
# Install test dependencies
pip install pytest pytest-asyncio
# Run all tests
pytest tests/
# Run specific test categories
pytest tests/test_memory_ops.py
pytest tests/test_semantic_search.py
pytest tests/test_database.py
# Verify environment compatibility
python scripts/verify_environment_enhanced.py
# Verify PyTorch installation on Windows
python scripts/verify_pytorch_windows.py
# Perform comprehensive installation verification
python scripts/test_installation.py
문제 해결
자세한 문제 해결 단계는 설치 가이드를 참조하세요.
빠른 문제 해결 팁
- Windows PyTorch 오류 :
python scripts/install_windows.py 사용하세요 - macOS Intel 종속성 충돌 :
python install.py --force-compatible-deps 사용하세요 - 재귀 오류 :
python scripts/fix_sitecustomize.py 실행하세요 - 환경 검증 :
python scripts/verify_environment_enhanced.py 실행합니다. - 메모리 문제 :
MCP_MEMORY_BATCH_SIZE=4 설정하고 더 작은 모델을 시도해 보세요. - Apple Silicon : ARM64용으로 빌드된 Python 3.10+를 확인하고
PYTORCH_ENABLE_MPS_FALLBACK=1 설정합니다. - 설치 테스트 :
python scripts/test_installation.py 실행합니다.
프로젝트 구조
mcp-memory-service/
├── src/mcp_memory_service/ # Core package code
│ ├── __init__.py
│ ├── config.py # Configuration utilities
│ ├── models/ # Data models
│ ├── storage/ # Storage implementations
│ ├── utils/ # Utility functions
│ └── server.py # Main MCP server
├── scripts/ # Helper scripts
├── memory_wrapper.py # Windows wrapper script
├── install.py # Enhanced installation script
└��─ tests/ # Test suite
개발 지침
- 유형 힌트가 포함된 Python 3.10+
- 모델에 데이터 클래스를 사용하세요
- 모듈 및 함수에 대한 삼중 따옴표로 묶인 문서 문자열
- 모든 I/O 작업에 대한 비동기/대기 패턴
- PEP 8 스타일 가이드라인을 따르세요
- 새로운 기능에 대한 테스트를 포함합니다
특허
MIT 라이선스 - 자세한 내용은 라이선스 파일을 참조하세요.
감사의 말
- 벡터 데이터베이스를 위한 ChromaDB 팀
- 모델 임베딩을 위한 문장 변환기 프로젝트
- 프로토콜 사양을 위한 MCP 프로젝트
연락하다
전보
통합
MCP 메모리 서비스는 다양한 도구와 유틸리티를 통해 확장할 수 있습니다. 사용 가능한 옵션 목록은 통합을 참조하세요.