Solución de Problemas

Problemas comunes y soluciones para Remembrances MCP

Problemas de Instalación

La Compilación Falla con Errores de llama.cpp

Problema: El proceso de compilación falla al compilar las dependencias de llama.cpp.

Soluciones:

Asegúrate de tener las herramientas de compilación necesarias:

# Ubuntu/Debian
sudo apt-get install build-essential cmake

# macOS
xcode-select --install

# Fedora
sudo dnf install gcc-c++ cmake

Verifica la versión de Go (requiere Go 1.20+):
```
go version
```
Limpia y recompila:
```
make clean
make build
```

Falta Soporte de GPU

Problema: La aceleración GPU no funciona aunque tengas una GPU compatible.

Soluciones:

NVIDIA (CUDA):

# Verificar instalación de CUDA
nvidia-smi
nvcc --version

# Asegúrate de que el toolkit CUDA está instalado
# Ubuntu/Debian
sudo apt-get install nvidia-cuda-toolkit

AMD (ROCm):

# Verificar instalación de ROCm
rocm-smi

# Instalar ROCm si falta
# Sigue las instrucciones en https://rocm.docs.amd.com/

Apple Silicon (Metal): Metal debería funcionar automáticamente en macOS con Apple Silicon. Asegúrate de estar ejecutando la compilación nativa ARM64.

Problemas en Tiempo de Ejecución

Errores de Falta de Memoria (OOM)

Problema: El servidor se cuelga con errores de memoria al procesar embeddings.

Soluciones:

Reduce las capas GPU:

# Usa menos capas GPU
--gguf-gpu-layers 16  # en lugar de 32

# O desactiva GPU completamente
--gguf-gpu-layers 0

Usa un modelo más pequeño:
- Cambia de nomic-embed-text-v1.5 a all-MiniLM-L6-v2
- Usa una versión más cuantizada (Q4_K_M en lugar de Q8_0)

Reduce el tamaño de lote (si aplica):

--gguf-batch-size 256  # el valor por defecto suele ser mayor

El Modelo No Carga

Problema: El servidor no arranca con errores de “modelo no encontrado” o similares.

Soluciones:

Verifica la ruta del archivo y permisos:

ls -lh ./model.gguf
chmod +r ./model.gguf

Verifica que el archivo del modelo no esté corrupto:

# Comprueba que el tamaño del archivo coincide con lo esperado
ls -lh ./model.gguf

# Vuelve a descargar si es necesario
wget https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.Q4_K_M.gguf

Usa ruta absoluta:

--gguf-model-path /ruta/completa/al/model.gguf

Rendimiento Lento

Problema: La generación de embeddings o la búsqueda es más lenta de lo esperado.

Soluciones:

Activa la aceleración GPU:
```
--gguf-gpu-layers 32
```

Aumenta el número de hilos:

--gguf-threads 8  # ajusta según el número de núcleos de tu CPU

Usa un modelo más rápido:
- all-MiniLM-L6-v2 es significativamente más rápido que nomic-embed-text-v1.5

Verifica el throttling térmico:

# Monitoriza temperaturas de CPU/GPU
# NVIDIA
nvidia-smi -l 1

# CPU
sensors  # Linux

Problemas de Base de Datos

La Conexión a la Base de Datos Falla

Problema: No se puede conectar a SurrealDB (embebida o externa).

Soluciones:

Para base de datos embebida:

# Verifica permisos del archivo
ls -la ./remembrances.db

# Asegúrate de que el directorio existe y tiene permisos de escritura
mkdir -p ./data
chmod 755 ./data
--db-path ./data/remembrances.db

Para SurrealDB externa:

# Verifica que SurrealDB está ejecutándose
curl http://localhost:8000/health

# Comprueba los parámetros de conexión
--surrealdb-url ws://localhost:8000
--surrealdb-user root
--surrealdb-pass root

Corrupción de Base de Datos

Problema: Errores de base de datos o datos inconsistentes después de un crash.

Soluciones:

Respalda y recrea:

# Respalda datos existentes
cp ./remembrances.db ./remembrances.db.backup

# Elimina base de datos corrupta
rm ./remembrances.db

# Reinicia - creará una base de datos nueva
./remembrances-mcp --gguf-model-path ./model.gguf

Ejecuta con logging de debug para identificar problemas:
```
--log-level debug
```

Problemas de Conexión MCP

Claude Desktop No Conecta

Problema: Claude Desktop no reconoce o no conecta con Remembrances MCP.

Soluciones:

Verifica la ubicación del archivo de configuración:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/claude/claude_desktop_config.json

Verifica la sintaxis JSON:

# Valida JSON
cat ~/.config/claude/claude_desktop_config.json | python -m json.tool

Usa rutas absolutas en la configuración:

{
  "mcpServers": {
    "remembrances": {
      "command": "/usr/local/bin/remembrances-mcp",
      "args": [
        "--gguf-model-path",
        "/home/usuario/models/nomic-embed-text-v1.5.Q4_K_M.gguf"
      ]
    }
  }
}

Reinicia Claude Desktop después de cambios en la configuración.

Problemas de MCP Streamable HTTP / API HTTP

Problema: No se puede conectar vía MCP Streamable HTTP (tools MCP) o la API JSON HTTP.

Soluciones:

Verifica si el puerto está en uso:

# Verificar disponibilidad del puerto
lsof -i :3000  # MCP Streamable HTTP por defecto
lsof -i :8080  # HTTP por defecto

Usa un puerto diferente:

--mcp-http --mcp-http-addr ":3001"
--http --http-addr ":8081"

Verifica la configuración del firewall:

# Permitir puerto (Linux con ufw)
sudo ufw allow 8080/tcp

Problemas de Embeddings

Resultados de Búsqueda Inconsistentes

Problema: Los resultados de búsqueda varían o no coinciden con el contenido esperado.

Soluciones:

Asegura un modelo de embeddings consistente - no mezcles embeddings de diferentes modelos
Verifica que las dimensiones de embeddings coincidan:
- nomic-embed-text-v1.5: 768 dimensiones
- all-MiniLM-L6-v2: 384 dimensiones

Re-indexa después de cambiar de modelo:

# Puede que necesites re-generar embeddings de todo el contenido si cambias de modelo

Los Embeddings No Se Generan

Problema: El contenido se almacena pero los embeddings están vacíos o faltan.

Soluciones:

Verifica la configuración del embedder:

# Verifica que el modelo está especificado
--gguf-model-path ./model.gguf
# O
--ollama-model nomic-embed-text
# O
--openai-key sk-xxx

Activa logging de debug:
```
--log-level debug
```

Obtener Ayuda

Si sigues experimentando problemas:

Revisa los logs con modo debug:
```
--log-level debug
```
Busca issues existentes en GitHub Issues
Abre un nuevo issue con:
- Sistema operativo y versión
- Versión de Go (go version)
- Tipo de GPU (si aplica)
- Mensaje de error completo
- Pasos para reproducir

Ver También

Primeros Pasos - Guía de instalación
Configuración - Opciones de configuración
Modelos GGUF - Selección y optimización de modelos