Servicio de memoria MCP
Un servidor MCP que proporciona memoria semántica y capacidades de almacenamiento persistente para Claude Desktop mediante ChromaDB y transformadores de oraciones. Este servicio permite el almacenamiento en memoria a largo plazo con funciones de búsqueda semántica, lo que lo hace ideal para mantener el contexto entre conversaciones e instancias.
Ayuda
¡Hable con el repositorio con TalkToGitHub !
Características
- Búsqueda semántica mediante transformadores de oraciones
- Recuerdo basado en el tiempo del lenguaje natural (por ejemplo, "la semana pasada", "ayer por la mañana")
- Sistema de recuperación de memoria basado en etiquetas
- Almacenamiento persistente mediante ChromaDB
- Copias de seguridad automáticas de bases de datos
- Herramientas de optimización de memoria
- Recuperación de coincidencias exactas
- Modo de depuración para análisis de similitud
- Monitoreo del estado de la base de datos
- Detección y limpieza de duplicados
- Modelo de incrustación personalizable
- Compatibilidad entre plataformas (Apple Silicon, Intel, Windows, Linux)
- Optimizaciones basadas en hardware para diferentes entornos
- Respaldos elegantes para recursos de hardware limitados
Instalación
Inicio rápido (recomendado)
El script de instalación mejorado detecta automáticamente su sistema e instala las dependencias adecuadas:
# Clone the repository
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Run the installation script
python install.py
El script install.py hará lo siguiente:
- Detecte la arquitectura de su sistema y los aceleradores de hardware disponibles
- Instale las dependencias adecuadas para su plataforma
- Configure los ajustes óptimos para su entorno
- Verificar la instalación y proporcionar diagnósticos si es necesario
Instalación de Docker
Puede ejecutar el servicio de memoria usando 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
Proporcionamos múltiples configuraciones de Docker Compose para diferentes escenarios:
docker-compose.yml - Configuración estándar mediante pip installdocker-compose.uv.yml : configuración alternativa mediante el administrador de paquetes UVdocker-compose.pythonpath.yml : configuración con ajustes PYTHONPATH explícitos
Para utilizar una configuración alternativa:
docker-compose -f docker-compose.uv.yml up
Instalación de Windows (caso especial)
Los usuarios de Windows podrían experimentar problemas de instalación de PyTorch debido a la disponibilidad de ruedas específicas de cada plataforma. Utilice nuestro script de instalación específico para Windows:
# After activating your virtual environment
python scripts/install_windows.py
Este script maneja:
- Detección de la disponibilidad y versión de CUDA
- Instalar la versión adecuada de PyTorch desde la URL de índice correcta
- Instalar otras dependencias sin entrar en conflicto con PyTorch
- Verificando la instalación
Para instalar el Servicio de memoria para Claude Desktop automáticamente a través de Smithery :
npx -y @smithery/cli install @doobidoo/mcp-memory-service --client claude
Guía de instalación detallada
Para obtener instrucciones completas de instalación y solución de problemas, consulte la Guía de instalación .
Configuración de Claude MCP
Configuración estándar
Agregue lo siguiente a su archivo 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"
}
}
}
Configuración específica de Windows (recomendada)
Para los usuarios de Windows, recomendamos utilizar el script contenedor para garantizar que PyTorch esté instalado correctamente:
{
"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"
}
}
}
El script contenedor hará lo siguiente:
- Compruebe si PyTorch está instalado y configurado correctamente
- Instale PyTorch con la URL de índice correcta si es necesario
- Ejecute el servidor de memoria con la configuración adecuada
Guía de uso
Para obtener instrucciones detalladas sobre cómo interactuar con el servicio de memoria en Claude Desktop:
El servicio de memoria se invoca mediante comandos de lenguaje natural en tus conversaciones con Claude. Por ejemplo:
- Para guardar: "Por favor, recuerde que la fecha límite de mi proyecto es el 15 de mayo".
- Para recuperar: "¿Recuerdas lo que te dije sobre la fecha límite de mi proyecto?"
- Para borrar: "Por favor olvida lo que te dije sobre mi dirección".
Consulte la Guía de invocación para obtener una lista completa de comandos y ejemplos de uso detallados.
Operaciones de memoria
El servicio de memoria proporciona las siguientes operaciones a través del servidor MCP:
Operaciones de memoria central
store_memory - Almacena nueva información con etiquetas opcionalesretrieve_memory - Realizar una búsqueda semántica de recuerdos relevantesrecall_memory - Recupera recuerdos usando expresiones de tiempo en lenguaje naturalsearch_by_tag - Encuentra recuerdos usando etiquetas específicasexact_match_retrieve - Encuentra recuerdos con coincidencia exacta de contenidodebug_retrieve - Recupera memorias con puntuaciones de similitud
Gestión de bases de datos
create_backup - Crear copia de seguridad de la base de datosget_stats - Obtener estadísticas de memoriaoptimize_db - Optimizar el rendimiento de la base de datoscheck_database_health - Obtener métricas de salud de la base de datoscheck_embedding_model - Verificar el estado del modelo
Gestión de la memoria
delete_memory - Eliminar memoria específica por hashdelete_by_tag - Elimina todos los recuerdos con una etiqueta específicacleanup_duplicates - Eliminar entradas duplicadas
Opciones de configuración
Configurar a través de variables de entorno:
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
Compatibilidad de hardware
| Plataforma | Arquitectura | Acelerador | Estado |
|---|
| macOS | Silicona de Apple (M1/M2/M3) | MPS | ✅ Totalmente compatible |
| macOS | Apple Silicon bajo Rosetta 2 | UPC | ✅ Compatible con alternativas |
| macOS | Intel | UPC | ✅ Totalmente compatible |
| Ventanas | x86_64 | CUDA | ✅ Totalmente compatible |
| Ventanas | x86_64 | DirectML | ✅ Compatible |
| Ventanas | x86_64 | UPC | ✅ Compatible con alternativas |
| Linux | x86_64 | CUDA | ✅ Totalmente compatible |
| Linux | x86_64 | ROCm | ✅ Compatible |
| Linux | x86_64 | UPC | ✅ Compatible con alternativas |
| Linux | ARM64 | UPC | ✅ Compatible con alternativas |
Pruebas
# 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
Solución de problemas
Consulte la Guía de instalación para obtener pasos detallados para la solución de problemas.
Consejos rápidos para la solución de problemas
- Errores de PyTorch de Windows : utilice
python scripts/install_windows.py - Conflictos de dependencia de Intel en macOS : use
python install.py --force-compatible-deps - Errores de recursión : Ejecute
python scripts/fix_sitecustomize.py - Verificación del entorno : ejecutar
python scripts/verify_environment_enhanced.py - Problemas de memoria : establezca
MCP_MEMORY_BATCH_SIZE=4 y pruebe un modelo más pequeño - Apple Silicon : asegúrese de que Python 3.10+ esté creado para ARM64, configure
PYTORCH_ENABLE_MPS_FALLBACK=1 - Prueba de instalación : ejecute
python scripts/test_installation.py
Estructura del proyecto
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
Directrices de desarrollo
- Python 3.10+ con sugerencias de tipos
- Utilice clases de datos para modelos
- Documentstrings entre comillas triples para módulos y funciones
- Patrón asíncrono/en espera para todas las operaciones de E/S
- Siga las pautas de estilo de PEP 8
- Incluir pruebas para nuevas funciones
Licencia
Licencia MIT: consulte el archivo de LICENCIA para obtener más detalles
Expresiones de gratitud
- Equipo de ChromaDB para la base de datos vectorial
- Proyecto Transformadores de Sentencias para incrustar modelos
- Proyecto MCP para la especificación del protocolo
Telegrama
Integraciones
El servicio de memoria MCP se puede ampliar con diversas herramientas y utilidades. Consulte Integraciones para ver una lista de las opciones disponibles, entre ellas: