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.

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

Inicio rápido

Para comenzar de la forma más rápida:

# Install UV if not already installed
pip install uv

# Clone and install
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt
uv pip install -e .

# Run the service
uv run memory

Integración de Docker y Smithery

Uso de Docker

El servicio se puede ejecutar en un contenedor Docker para un mejor aislamiento e implementación:

# 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

Para configurar el uso compartido de archivos de Docker en macOS:

Abrir Docker Desktop
Vaya a Configuración (Preferencias)
Vaya a Recursos -> Compartir archivos
Añade cualquier ruta adicional que necesites compartir
Haga clic en "Aplicar y reiniciar"

Integración de herrería

El servicio está configurado para la integración con Smithery mediante smithery.yaml . Esta configuración permite la comunicación basada en stdio con clientes MCP como Claude Desktop.

Para utilizar con Smithery:

Asegúrese de que su claude_desktop_config.json apunte a las rutas correctas:

{
  "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"
    }
  }
}

La configuración de smithery.yaml maneja la comunicación de stdio y la configuración del entorno automáticamente.

Pruebas con Claude Desktop

Para verificar que su servicio de memoria basado en Docker funcione correctamente con Claude Desktop:

Construya la imagen de Docker con docker build -t mcp-memory-service .
Cree los directorios necesarios para el almacenamiento persistente:
mkdir -p $HOME/mcp-memory/chroma_db $HOME/mcp-memory/backups
Actualice su archivo de configuración de Claude Desktop:
- En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- En Windows: %APPDATA%\Claude\claude_desktop_config.json
- En Linux: ~/.config/Claude/claude_desktop_config.json
Reiniciar Claude Desktop
Cuando Claude se inicia, debería ver que el servicio de memoria se inicializa con un mensaje:
MCP Memory Service initialization completed
Pruebe la función de memoria:
- Pídele a Claude que recuerde algo: "Por favor, recuerda que mi color favorito es el azul".
- Más adelante en la conversación o en una nueva conversación, pregunte: "¿Cuál es mi color favorito?"
- Claude debería recuperar la información del servicio de memoria.

Si experimenta algún problema:

Compruebe la consola de Claude Desktop para ver si hay mensajes de error
Verifique que Docker tenga los permisos necesarios para acceder a los directorios montados
Asegúrese de que el contenedor Docker se esté ejecutando con los parámetros correctos
Intente ejecutar el contenedor manualmente para ver cualquier salida de error

Para obtener instrucciones de instalación detalladas, guías específicas de la plataforma y solución de problemas, consulte nuestra documentación :

Guía de instalación : instrucciones de instalación completas para todas las plataformas
Guía de resolución de problemas : soluciones para problemas comunes
Documentación técnica : procedimientos y especificaciones técnicas detalladas
Documentación de scripts : descripción general de los scripts disponibles y su uso

Configuración

Configuración estándar (recomendada)

Agregue lo siguiente a su archivo claude_desktop_config.json para usar UV (recomendado para un mejor rendimiento):

{
  "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 usuarios de Windows, recomendamos usar el script wrapper para garantizar la correcta instalación de PyTorch. Consulte nuestra Guía de instalación de Windows para obtener instrucciones detalladas.

{
  "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

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

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 opcionales
retrieve_memory - Realizar una búsqueda semántica de recuerdos relevantes
recall_memory - Recupera recuerdos usando expresiones de tiempo en lenguaje natural
search_by_tag - Encuentra recuerdos usando etiquetas específicas
exact_match_retrieve - Encuentra recuerdos con coincidencia exacta de contenido
debug_retrieve - Recupera memorias con puntuaciones de similitud

Para obtener información detallada sobre el almacenamiento y la gestión de etiquetas, consulte nuestra Documentación de almacenamiento de etiquetas .

Gestión de bases de datos

create_backup - Crear copia de seguridad de la base de datos
get_stats - Obtener estadísticas de memoria
optimize_db - Optimizar el rendimiento de la base de datos
check_database_health - Obtener métricas de salud de la base de datos
check_embedding_model - Verificar el estado del modelo

Gestión de la memoria

delete_memory - Eliminar memoria específica por hash
delete_by_tag - Elimina todos los recuerdos con una etiqueta específica
cleanup_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

Obtener ayuda

Si encuentra algún problema:

Consulte nuestra Guía de solución de problemas
Revise la Guía de instalación
Para problemas específicos de Windows, consulte nuestra Guía de instalación de Windows
Contacta con el desarrollador vía Telegram: t.me/doobeedoo

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
│   ├── 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

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

Contacto

t.me/doobidoo

Implementación de Cloudflare Worker

Ya está disponible una implementación sin servidor del Servicio de Memoria MCP mediante Cloudflare Workers. Esta implementación:

Utiliza Cloudflare D1 para almacenamiento (SQLite sin servidor)
Utiliza Workers AI para la generación de incrustaciones
Se comunica a través de eventos enviados por el servidor (SSE) para el protocolo MCP
No requiere instalación local ni dependencias
Se escala automáticamente con el uso

Beneficios de la implementación de Cloudflare

Instalación local cero : no se necesita Python, dependencias ni almacenamiento local
Compatibilidad multiplataforma : funciona en cualquier dispositivo que pueda conectarse a Internet.
Escalado automático : maneja múltiples usuarios sin configuración
Distribución global : acceso de baja latencia desde cualquier lugar
Sin mantenimiento : las actualizaciones y el mantenimiento se gestionan automáticamente

Herramientas disponibles en la implementación de Cloudflare

La implementación de Cloudflare Worker admite las mismas herramientas que la implementación de Python:

Herramienta	Descripción
`store_memory`	Almacenar nueva información con etiquetas opcionales
`retrieve_memory`	Encuentre recuerdos relevantes según la consulta
`recall_memory`	Recuperar recuerdos utilizando expresiones de tiempo en lenguaje natural
`search_by_tag`	Buscar recuerdos por etiquetas
`delete_memory`	Eliminar una memoria específica por su hash
`delete_by_tag`	Eliminar todos los recuerdos con una etiqueta específica
`cleanup_duplicates`	Buscar y eliminar entradas duplicadas
`get_embedding`	Obtener vector de incrustación sin procesar para contenido
`check_embedding_model`	Compruebe si el modelo de incrustación está cargado y funcionando
`debug_retrieve`	Recuperar recuerdos con información de depuración
`exact_match_retrieve`	Recuperar recuerdos utilizando la coincidencia exacta de contenido
`check_database_health`	Comprobar el estado de la base de datos y obtener estadísticas
`recall_by_timeframe`	Recuperar recuerdos dentro de un período de tiempo específico
`delete_by_timeframe`	Eliminar recuerdos dentro de un período de tiempo específico
`delete_before_date`	Eliminar recuerdos antes de una fecha específica

Configuración de Claude para usar el servicio de memoria de Cloudflare

Agregue lo siguiente a su configuración de Claude para utilizar el servicio de memoria basado en Cloudflare:

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

Reemplace your-worker-subdomain con su subdominio de Cloudflare Worker real.

Implementación de su propio servicio de memoria de Cloudflare

Clone el repositorio y navegue al directorio de Cloudflare Worker:
git clone https://github.com/doobidoo/mcp-memory-service.git cd mcp-memory-service/cloudflare_worker
Instalar Wrangler (la herramienta CLI de Cloudflare):
npm install -g wrangler
Inicie sesión en su cuenta de Cloudflare:
wrangler login
Crear una base de datos D1:
wrangler d1 create mcp_memory_service
Actualice el archivo wrangler.toml con su ID de base de datos del paso anterior.
Inicializar el esquema de la base de datos:
wrangler d1 execute mcp_memory_service --local --file=./schema.sql
Donde schema.sql contiene:
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);
Implementar el trabajador:
wrangler deploy
Actualice su configuración de Claude para utilizar su nueva URL de trabajador.

Prueba de su servicio de memoria de Cloudflare

Después de la implementación, puedes probar tu servicio de memoria usando curl:

Lista de herramientas disponibles:
curl https://your-worker-subdomain.workers.dev/list_tools
Almacenar un recuerdo:
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"]}}}'
Recuperar recuerdos:
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}}'

Limitaciones

Pueden aplicarse límites de nivel gratuito en Cloudflare Workers y D1
Los modelos de incorporación de IA de los trabajadores pueden diferir ligeramente de los modelos de transformadores de oraciones locales
No hay acceso directo a la base de datos subyacente para operaciones manuales
Los trabajadores de Cloudflare tienen un tiempo máximo de ejecución de 30 segundos en los planes gratuitos

MCP Memory Service

Integrations