MCP 메모리 서비스

ChromaDB와 문장 변환기를 사용하여 Claude Desktop에 의미 메모리와 영구 저장 기능을 제공하는 MCP 서버입니다. 이 서비스는 의미 검색 기능을 갖춘 장기 메모리 저장 기능을 제공하여 대화와 인스턴스 전반의 맥락을 유지하는 데 이상적입니다.

특징

문장 변환기를 사용한 의미 검색
자연어 시간 기반 리콜 (예: "지난주", "어제 아침")
태그 기반 메모리 검색 시스템
ChromaDB를 사용한 영구 저장소
자동 데이터베이스 백업
메모리 최적화 도구
정확한 일치 검색
유사성 분석을 위한 디버그 모드
데이터베이스 상태 모니터링
중복 감지 및 정리
사용자 정의 가능한 임베딩 모델
크로스 플랫폼 호환성 (Apple Silicon, Intel, Windows, Linux)
다양한 환경에 대한 하드웨어 인식 최적화
제한된 하드웨어 리소스에 대한 우아한 대체

빠른 시작

가장 빠르게 시작하는 방법:

지엑스피1

Docker 및 Smithery 통합

Docker 사용법

더 나은 격리 및 배포를 위해 Docker 컨테이너에서 서비스를 실행할 수 있습니다.

# Build the Docker image
docker build -t mcp-memory-service .

# Run the container
# Note: On macOS, paths must be within Docker's allowed file sharing locations
# Default allowed locations include:
# - /Users
# - /Volumes
# - /private
# - /tmp
# - /var/folders

# Example with proper macOS paths:
docker run -it \
  -v $HOME/mcp-memory/chroma_db:/app/chroma_db \
  -v $HOME/mcp-memory/backups:/app/backups \
  mcp-memory-service

# For production use, you might want to run it in detached mode:
docker run -d \
  -v $HOME/mcp-memory/chroma_db:/app/chroma_db \
  -v $HOME/mcp-memory/backups:/app/backups \
  --name mcp-memory \
  mcp-memory-service

macOS에서 Docker의 파일 공유를 구성하려면:

Docker 데스크톱 열기
설정(환경 설정)으로 이동하세요
리소스 -> 파일 공유로 이동하세요
공유해야 할 추가 경로를 추가하세요.
"적용 및 다시 시작"을 클릭하세요

스미서리 통합

이 서비스는 smithery.yaml 통해 Smithery와 통합되도록 구성되었습니다. 이 구성을 통해 Claude Desktop과 같은 MCP 클라이언트와 stdio 기반 통신이 가능해집니다.

Smithery와 함께 사용하려면:

claude_desktop_config.json 이 올바른 경로를 가리키는지 확인하세요.

{
  "memory": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-v", "$HOME/mcp-memory/chroma_db:/app/chroma_db",
      "-v", "$HOME/mcp-memory/backups:/app/backups",
      "mcp-memory-service"
    ],
    "env": {
      "MCP_MEMORY_CHROMA_PATH": "/app/chroma_db",
      "MCP_MEMORY_BACKUPS_PATH": "/app/backups"
    }
  }
}

smithery.yaml 구성은 stdio 통신과 환경 설정을 자동으로 처리합니다.

Claude Desktop으로 테스트

Claude Desktop에서 Docker 기반 메모리 서비스가 올바르게 작동하는지 확인하려면 다음을 수행합니다.

docker build -t mcp-memory-service .
영구 저장소에 필요한 디렉토리를 만듭니다.
mkdir -p $HOME/mcp-memory/chroma_db $HOME/mcp-memory/backups
Claude Desktop 구성 파일을 업데이트하세요.
- macOS의 경우: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows의 경우: %APPDATA%\Claude\claude_desktop_config.json
- Linux의 경우: ~/.config/Claude/claude_desktop_config.json
Claude Desktop을 다시 시작하세요
Claude가 시작되면 메모리 서비스가 다음 메시지와 함께 초기화되는 것을 볼 수 있습니다.
MCP Memory Service initialization completed
메모리 기능을 테스트하세요:
- 클로드에게 뭔가를 기억해 달라고 부탁하세요: "제가 가장 좋아하는 색깔은 파란색이라는 걸 기억해 주세요."
- 대화 후반부나 새로운 대화에서 "내가 가장 좋아하는 색깔은 뭐예요?"라고 물어보세요.
- Claude는 메모리 서비스에서 정보를 검색해야 합니다.

문제가 발생하는 경우:

Claude Desktop 콘솔에서 오류 메시지를 확인하세요.
Docker가 마운트된 디렉토리에 액세스하는 데 필요한 권한이 있는지 확인하세요.
Docker 컨테이너가 올바른 매개변수로 실행되고 있는지 확인하세요.
오류 출력을 확인하려면 컨테이너를 수동으로 실행해보세요.

자세한 설치 지침, 플랫폼별 가이드 및 문제 해결 방법은 다음 설명서를 참조하세요.

설치 가이드 - 모든 플랫폼에 대한 포괄적인 설치 지침
문제 해결 가이드 - 일반적인 문제에 대한 솔루션
기술 문서 - 자세한 기술 절차 및 사양
스크립트 문서 - 사용 가능한 스크립트 및 사용법 개요

구성

표준 구성(권장)

UV를 사용하려면 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가 제대로 설치되었는지 확인하기 위해 래퍼 스크립트를 사용하는 것이 좋습니다. 자세한 내용은 Windows 설치 가이드를 참조하세요.

{
  "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를 설치하세요.
적절한 구성으로 메모리 서버를 실행하세요

하드웨어 호환성

플랫폼	건축학	촉진 신경	상태
맥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	✅ 폴백 지원

메모리 작업

메모리 서비스는 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

도움 받기

문제가 발생할 경우:

문제 해결 가이드를 확인하세요
설치 가이드를 검토하세요
Windows 관련 문제에 대해서는 Windows 설치 가이드를 참조하세요.
Telegram: t.me/doobeedoo를 통해 개발자에게 문의하세요.

프로젝트 구조

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
│   ├── convert_to_uv.py         # Script to migrate to UV
│   └── install_uv.py            # UV installation helper
├── .uv/                         # UV configuration
├── memory_wrapper.py            # Windows wrapper script
├── memory_wrapper_uv.py         # UV-based wrapper script
├── uv_wrapper.py                # UV wrapper script
├── install.py                   # Enhanced installation script
└── tests/                       # Test suite

개발 지침

유형 힌트가 포함된 Python 3.10+
모델에 데이터 클래스를 사용하세요
모듈 및 함수에 대한 삼중 따옴표로 묶인 문서 문자열
모든 I/O 작업에 대한 비동기/대기 패턴
PEP 8 스타일 가이드라인을 따르세요
새로운 기능에 대한 테스트를 포함합니다

특허

MIT 라이선스 - 자세한 내용은 라이선스 파일을 참조하세요.

감사의 말

벡터 데이터베이스를 위한 ChromaDB 팀
모델 임베딩을 위한 문장 변환기 프로젝트
프로토콜 사양을 위한 MCP 프로젝트

연락하다

t.me/두비두

Cloudflare Worker 구현

이제 Cloudflare Workers를 사용하여 MCP 메모리 서비스의 서버리스 구현을 사용할 수 있습니다. 이 구현은 다음과 같습니다.

저장을 위해 Cloudflare D1을 사용합니다(서버리스 SQLite)
임베딩 생성을 위해 Workers AI 사용
MCP 프로토콜을 위한 SSE(Server-Sent Events) 를 통해 통신합니다.
로컬 설치나 종속성이 필요하지 않습니다.
사용량에 따라 자동으로 확장됩니다

Cloudflare 구현의 이점

로컬 설치 없음 : Python, 종속성 또는 로컬 저장소가 필요하지 않습니다.
크로스 플랫폼 호환성 : 인터넷에 연결할 수 있는 모든 기기에서 작동합니다.
자동 스케일링 : 구성 없이 여러 사용자를 처리합니다.
글로벌 배포 : 어디서나 저지연 접속 가능
유지 관리 없음 : 업데이트 및 유지 관리가 자동으로 처리됩니다.

Cloudflare 구현에서 사용 가능한 도구

Cloudflare Worker 구현은 Python 구현과 동일한 모든 도구를 지원합니다.

도구	설명
`store_memory`	선택적 태그를 사용하여 새 정보를 저장합니다.
`retrieve_memory`	쿼리를 기반으로 관련 메모리 찾기
`recall_memory`	자연어 시간 표현을 사용하여 메모리 검색
`search_by_tag`	태그로 추억을 검색하세요
`delete_memory`	해시로 특정 메모리 삭제
`delete_by_tag`	특정 태그가 있는 모든 메모리 삭제
`cleanup_duplicates`	중복 항목 찾기 및 제거
`get_embedding`	콘텐츠에 대한 원시 임베딩 벡터 가져오기
`check_embedding_model`	임베딩 모델이 로드되어 작동하는지 확인하세요
`debug_retrieve`	디버그 정보를 사용하여 메모리 검색
`exact_match_retrieve`	정확한 콘텐츠 일치를 사용하여 메모리 검색
`check_database_health`	데이터베이스 상태를 확인하고 통계를 얻으세요
`recall_by_timeframe`	특정 기간 내의 기억을 검색합니다
`delete_by_timeframe`	특정 기간 내의 메모리 삭제
`delete_before_date`	특정 날짜 이전의 기억을 삭제하세요

Cloudflare 메모리 서비스를 사용하도록 Claude 구성

Cloudflare 기반 메모리 서비스를 사용하려면 Claude 구성에 다음을 추가하세요.

{
  "mcpServers": [
    {
      "name": "cloudflare-memory",
      "url": "https://your-worker-subdomain.workers.dev/mcp",
      "type": "sse"
    }
  ]
}

your-worker-subdomain 실제 Cloudflare Worker 하위 도메인으로 바꾸세요.

자체 Cloudflare 메모리 서비스 배포

저장소를 복제하고 Cloudflare Worker 디렉토리로 이동합니다.
git clone https://github.com/doobidoo/mcp-memory-service.git cd mcp-memory-service/cloudflare_worker
Wrangler(Cloudflare의 CLI 도구) 설치:
npm install -g wrangler
Cloudflare 계정에 로그인하세요:
wrangler login
D1 데이터베이스를 만듭니다.
wrangler d1 create mcp_memory_service
이전 단계의 데이터베이스 ID로 wrangler.toml 파일을 업데이트합니다.
데이터베이스 스키마를 초기화합니다.
wrangler d1 execute mcp_memory_service --local --file=./schema.sql
schema.sql 에 다음이 포함되어 있습니다.
CREATE TABLE IF NOT EXISTS memories ( id TEXT PRIMARY KEY, content TEXT NOT NULL, embedding TEXT NOT NULL, tags TEXT, memory_type TEXT, metadata TEXT, created_at INTEGER ); CREATE INDEX IF NOT EXISTS idx_created_at ON memories(created_at);
작업자 배포:
wrangler deploy
새로운 작업자 URL을 사용하도록 Claude 구성을 업데이트하세요.

Cloudflare 메모리 서비스 테스트

배포 후 curl을 사용하여 메모리 서비스를 테스트할 수 있습니다.

사용 가능한 도구 나열:
curl https://your-worker-subdomain.workers.dev/list_tools
메모리를 저장하세요:
curl -X POST https://your-worker-subdomain.workers.dev/mcp \ -H "Content-Type: application/json" \ -d '{"method":"store_memory","arguments":{"content":"This is a test memory","metadata":{"tags":["test"]}}}'
기억을 되찾다:
curl -X POST https://your-worker-subdomain.workers.dev/mcp \ -H "Content-Type: application/json" \ -d '{"method":"retrieve_memory","arguments":{"query":"test memory","n_results":5}}'

제한 사항

Cloudflare Workers 및 D1에는 무료 계층 제한이 적용될 수 있습니다.
Workers AI 임베딩 모델은 로컬 문장 변환기 모델과 약간 다를 수 있습니다.
수동 작업을 위한 기본 데이터베이스에 직접 액세스할 수 없습니다.
Cloudflare Workers는 무료 플랜에서 최대 30초의 실행 시간을 갖습니다.

MCP Memory Service

Integrations