17 de septiembre de 2026

hermes-memory-pgvector v0.5.3: Usa tu propio modelo de embeddings

hermes-memory-pgvector v0.5.3: Usa tu propio modelo de embeddings

hermes-memory-pgvector es el complemento de código abierto que proporciona a una flota de agentes hermes-agent memoria compartida y persistente en PostgreSQL y pgvector. La versión 0.5.3 ya está disponible en PyPI, y elimina la última suposición codificada de forma fija en el complemento: qué modelo de embeddings convierte tus memorias en vectores buscables.

Por qué existe esta versión

Hasta ahora, el modelo de embeddings estaba prácticamente fijado. El complemento comprobaba cada vector frente a unas 768 dimensiones literales, el tamaño del modelo predeterminado nomic-embed-text, y no tenía forma de enviar una clave de API, así que los servicios de embeddings alojados quedaban fuera de alcance.

Eso se convirtió en una limitación real para nuestro propio despliegue. Trasladamos la base de datos de memoria a text-embedding-3-small de OpenAI, servido a través de OpenRouter, porque un endpoint alojado está siempre listo, mientras que un modelo autoalojado puede tardar varios segundos en activarse. Las columnas de la base de datos cambiaron a 1536 dimensiones, y el complemento no tenía ningún ajuste que pudiera seguirlas. La v0.5.3 añade esos ajustes.

Tres nuevos ajustes

  • embed_dim es la longitud del vector que devuelve tu modelo. El valor predeterminado es 768, así que las configuraciones existentes no se ven afectadas. Cada embedding sigue comprobándose, ahora frente a este valor, así que una discrepancia falla rápidamente en lugar de llegar a la base de datos.
  • embed_api_key_env es el nombre de una variable de entorno que contiene un token bearer, como OPENROUTER_API_KEY. La clave nunca va en el archivo de configuración; se lee en el momento de la llamada y nunca se registra.
  • embed_protocol es openai, ollama o auto. El valor predeterminado, auto, prueba la ruta compatible con OpenAI y, si falla, recurre a la API nativa de Ollama. Elegir openai para un servicio alojado significa que un error de autenticación o de modelo se informa tal cual, en lugar de quedar oculto detrás de un 404 del fallback.

Apuntar ahora el complemento a text-embedding-3-small a través de OpenRouter se ve así:

plugins:
  pgvector:
    embed_url: "https://openrouter.ai/api"
    embed_model: "openai/text-embedding-3-small"
    embed_dim: 1536
    embed_api_key_env: "OPENROUTER_API_KEY"
    embed_protocol: "openai"

Dos correcciones que importan incluso si no cambias nada

  • Embeddings bajo el cargador de complementos de hermes-agent. Después de cargar el complemento, el cargador del host vuelve a adjuntar cada submódulo al paquete, incluido uno llamado embed. Eso sustituyó la función que llamaba el complemento, así que la generación de embeddings fallaba con TypeError: 'module' object is not callable y las escrituras de memoria se descartaban en lugar de almacenarse como texto. Ahora el complemento llama a un alias privado que el cargador nunca toca.
  • Endpoints lentos. Un servidor que aceptaba la conexión pero respondía después del tiempo de espera lanzaba un TimeoutError sin formato, que se colaba por el manejo de errores del complemento: sin fallback, sin reintentos y con una escritura perdida. Ahora se maneja como cualquier otro fallo de endpoint.

Actualización

Los valores predeterminados no han cambiado: 768 dimensiones, ningún encabezado de autenticación, el protocolo auto y sin nuevas migraciones de base de datos. Actualiza con:

pip install -U hermes-memory-pgvector

Cambiar a un modelo con un tamaño de vector distinto es una migración de base de datos, no solo una edición de la configuración, porque los vectores de dos modelos diferentes no son comparables. El README lo explica paso a paso: cambia el tipo de columna, vuelve a generar los embeddings de las filas existentes con hermes-pgvector backfill, y luego reconstruye los índices HNSW.

El código fuente y la referencia completa de configuración están en GitHub:

👉 github.com/andreab67/hermes-memory-pgvector

← Volver al blog