Memoria autodirigida con modelos de lenguaje locales para el agente Hermes: la visión retrospectiva

Un agente de IA autoalojado necesita más que una ventana de contexto amplia. Necesita una forma de retener hechos útiles, recuperar decisiones anteriores y revisar lo que cree saber a medida que los proyectos evolucionan.

Hermes Agent se entrega con archivos de memoria integrados, pero un proveedor externo puede ofrecer una recuperación mucho más rica entre sesiones. Hindsight es una de las opciones más interesantes en ese ámbito. Esta guía lo instala para Hermes sin inferencia en la nube, primero como un contenedor Docker todo-en-uno y luego contra un servidor PostgreSQL existente con puntos de conexión locales separados para los modelos.

La guía cubre el despliegue, la elección y conexión de modelos locales de incrustación (embeddings), reordenación (reranking) y generativos, el control de lo que auto-retain escribe en el banco, la conexión de Hermes y la capa operativa: copia de seguridad, migración e higiene diaria del banco. Los ejemplos utilizan un esquema de puertos deliberado: 8080 para el servidor principal de llama.cpp, 8081 para incrustaciones, 8082 para reordenación y 11434 para Ollama, así que cámbialos a los puertos que ya utilices y mantén los servidores pequeños fuera del puerto del modelo principal.

Qué hace Hindsight

Hindsight es un motor de memoria persistente para agentes con tres operaciones principales: retain (retener), recall (recordar) y reflect (reflexionar). Retain extrae y almacena información; recall combina recuperación semántica, por palabras clave, de grafo y temporal; reflect sintetiza una respuesta a partir de memorias acumuladas. La consolidación en segundo plano puede convertir observaciones superpuestas en una capa de conocimiento más útil.

No es solo una base de datos de incrustaciones. Un almacén vectorial puede localizar pasajes similares, pero un sistema de memoria también debe preservar la cronología, los límites del proyecto, las pruebas contradictorias y los cambios en las decisiones. Esos modos de fallo se exploran en bucles de memoria autorreforzantes.

Para el mercado más amplio, consulta proveedores de memoria para agentes comparados. La memoria integrada de MEMORY.md, USER.md y los modos de memoria de Hermes se cubren en la guía de sistema de memoria de Hermes Agent, por lo que este artículo asume que conoces cómo funciona la capa integrada.

¿Por qué ir más allá de Mnemosyne?

Mnemosyne para Hermes ofrece ideas atractivas centradas en lo local, incluyendo almacenamiento SQLite y recuperación híbrida. En la práctica, las restricciones de instalación, la compatibilidad de versiones, el comportamiento de aprobación de escritura y los cambios rápidos en torno a sus prelanzamientos 4.0 pueden dificultar su operación de manera predecible. Esas son preocupaciones operativas, no evidencia de que el modelo de memoria de Mnemosyne esté fundamentalmente defectuoso.

Hindsight tampoco está libre de dependencias: su imagen Docker y los modelos locales pueden consumir un espacio en disco considerable. Ejecutar su API como un servicio independiente, con la inferencia en otra parte, aísla las actualizaciones y la solución de problemas del propio agente.

Elegir un despliegue

Aquí, “todo-en-uno” significa que la API, la UI y la base de datos de Hindsight están en un solo contenedor; el LLM de inferencia sigue alojado en otra parte. Esto es intencional: la imagen oficial de Docker de Hindsight no incluye un servidor llama.cpp generativo local listo para usar.

Utiliza direcciones accesibles en la LAN, no localhost, para servicios que se ejecutan en un host diferente. Restringe estos puertos a clientes de confianza; las llaves dummy de ejemplo son marcadores de posición de compatibilidad, no autenticación.

Opción A: Contenedor Hindsight Todo-en-Uno

Esta es la forma más sencilla de evaluar Hindsight sin llenar la VM de Hermes con Python, Torch y dependencias de modelos locales. El contenedor ejecuta Hindsight y PostgreSQL integrado, mientras tu LLM principal de llama.cpp se encarga de la extracción y reflexión de la memoria.

Aquí importan dos etiquetas de imagen. ghcr.io/vectorize-io/hindsight:latest es la imagen grande —aproximadamente 9 GB en AMD64— porque incluye un incrustador BGE, un reordenador MiniLM y PostgreSQL integrado. latest-slim es de aproximadamente 500 MB y espera que esos dos modelos estén en otra parte, que es lo que quieres una vez que apuntes Hindsight a la configuración de incrustación y reordenación en “Servir y conectar modelos locales”. Una vez que la prueba de salud pase, fija una etiqueta específica: una etiqueta cambiante es una mala opción para una base de datos que pretendes conservar.

Crea un directorio y un archivo Compose en el host de Hindsight:

mkdir -p ~/services/hindsight
cd ~/services/hindsight
cat > compose.yaml <<'YAML'
services:
  hindsight:
    image: ghcr.io/vectorize-io/hindsight:latest
    container_name: hindsight
    restart: unless-stopped
    shm_size: 1gb
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - "8888:8888"  # Memory API
      - "9999:9999"  # Control-plane UI
    environment:
      HINDSIGHT_API_WORKER_ID: hindsight-standalone
      HINDSIGHT_API_LLM_PROVIDER: openai
      HINDSIGHT_API_LLM_BASE_URL: http://WORKSTATION_IP:8080/v1
      HINDSIGHT_API_LLM_MODEL: LocalMegaLLM
      HINDSIGHT_API_LLM_API_KEY: dummy
      HINDSIGHT_API_LLM_MAX_CONCURRENT: "2"
    volumes:
      - hindsight-pg0:/home/hindsight/.pg0
volumes:
  hindsight-pg0:
YAML

Reemplaza WORKSTATION_IP con el host que ejecuta llama.cpp. En Linux, host.docker.internal se resuelve solo si el contenedor declara el mapeo host-gateway mostrado arriba; sin él, una URL base de http://host.docker.internal:8080/v1 apunta a ningún lado. La reserva de 1 GB de memoria compartida es particularmente útil para el indexado de PostgreSQL integrado; el /dev/shm pequeño predeterminado de Docker puede causar fallos. Un volumen con nombre preserva la base de datos cuando el contenedor se recrea, y una alternativa de montaje vinculado (bind mount) debe ser poseída por el uid 1000, el usuario dentro de la imagen.

HINDSIGHT_API_WORKER_ID debe permanecer estable entre recreaciones: el valor predeterminado de Docker es el nombre del host del contenedor, y una tarea que estaba en curso cuando un contenedor murió queda atascada bajo el id de trabajador antiguo.

docker compose up -d
docker compose logs -f --tail=100
curl -f http://localhost:8888/health

Si la versión de Hindsight instalada expone la salud en una ruta diferente, inspecciona http://localhost:8888/docs y los registros del contenedor. El plano de control normalmente está disponible en http://HINDSIGHT_HOST:9999. Una vez que el despliegue básico funcione, también puedes apuntar sus proveedores de incrustación y reordenación a la configuración de “Servir y conectar modelos locales” en lugar de cargar los modelos predeterminados dentro del contenedor.

No expongas los puertos 8888 o 9999 directamente a internet. Usa una red privada o un proxy inverso autenticado. PostgreSQL integrado es conveniente para pruebas, pero una base de datos administrada externamente es más fácil de hacer copia de seguridad y mantener.

Opción B: Hindsight contra un servidor PostgreSQL existente

Para una instalación de larga duración, prefiero mantener la API de Hindsight, la base de datos y los puntos de conexión de inferencia separados. La VM de Hindsight puede permanecer pequeña porque ejecuta orquestación y servicios HTTP en lugar de modelos pesados.

Preparar PostgreSQL y pgvector

Hindsight necesita PostgreSQL 14 o más nuevo y una extensión vectorial en la base de datos hindsight. La extensión es por base de datos: instalar el paquete en el servidor no hace nada hasta que se ejecute CREATE EXTENSION allí. En un servidor PostgreSQL de Debian o Ubuntu, instala el paquete pgvector que coincida con la versión principal actual de PostgreSQL; por ejemplo, en PostgreSQL 16:

sudo apt update
sudo apt install postgresql-16-pgvector

El nombre y la disponibilidad del paquete dependen de tus repositorios apt configurados. Si no está disponible, sigue las instrucciones de instalación de pgvector, o instala un paquete compatible del repositorio PGDG de PostgreSQL. No cambies la versión principal de PostgreSQL a ciegas en un servidor compartido.

Crea un rol y una base de datos dedicados como administrador de PostgreSQL:

CREATE ROLE hindsight LOGIN PASSWORD 'REPLACE_WITH_LONG_PASSWORD';
CREATE DATABASE hindsight OWNER hindsight;

Conéctate a la nueva base de datos y habilita la extensión:

sudo -u postgres psql -d hindsight -c \
  'CREATE EXTENSION IF NOT EXISTS vector;'
sudo -u postgres psql -d hindsight -c \
  "SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';"

La extensión normalmente necesita privilegios elevados para instalar; el rol de la aplicación no necesita ser superusuario. Hindsight usa pgvector por defecto y desea 0.8.0 o más nuevo para escaneos ANN iterativos; los servidores más antiguos rechazan esa configuración. HINDSIGHT_API_VECTOR_EXTENSION puede seleccionar alternativamente pgvectorscale (una opción DiskANN que Hindsight documenta para bancos muy grandes) o vchord, ambos de los cuales necesitan empaquetado adicional en esta compilación exacta de PostgreSQL. Cambiar algoritmos después de que existan memorias detiene el inicio y pide una migración, así que elige antes del primer retain. Para un banco personal de Hermes, pgvector es el que debes instalar y luego dejar.

Permite solo el host de Hindsight a través de pg_hba.conf, por ejemplo:

host  hindsight  hindsight  192.168.1.50/32  scram-sha-256

Configura listen_addresses de PostgreSQL apropiadamente y usa TLS o una red privada de confianza para conexiones entre hosts. Haz copia de seguridad de esta base de datos independientemente del contenedor Docker de Hindsight. Si el servidor se comparte con otras aplicaciones, mantén Hindsight en su propia base de datos, o establece HINDSIGHT_API_DATABASE_SCHEMA en un esquema que poseas; el esquema predeterminado es public.

Ejecutar Hindsight contra PostgreSQL

Crea compose.yaml en la VM de Hindsight. Esta versión deliberadamente no inicia PostgreSQL localmente:

services:
  hindsight:
    image: ghcr.io/vectorize-io/hindsight:latest-slim
    restart: unless-stopped
    ports:
      - "8888:8888"
      - "9999:9999"
    env_file: .env
    environment:
      HINDSIGHT_API_LLM_PROVIDER: openai
      HINDSIGHT_API_LLM_BASE_URL: http://WORKSTATION_IP:8080/v1
      HINDSIGHT_API_LLM_MODEL: LocalMegaLLM
      HINDSIGHT_API_LLM_API_KEY: dummy
      HINDSIGHT_API_LLM_MAX_CONCURRENT: "2"
      HINDSIGHT_API_DB_POOL_MIN_SIZE: "2"
      HINDSIGHT_API_DB_POOL_MAX_SIZE: "10"
      HINDSIGHT_API_WORKER_ID: hindsight-standalone

Guarda la URL de la base de datos externa en un archivo llamado .env:

HINDSIGHT_API_DATABASE_URL=postgresql://hindsight:YOUR_PASSWORD@POSTGRES_IP:5432/hindsight

chmod 600 .env
docker compose up -d
docker compose logs -f --tail=100

Si tu contraseña contiene @, :, / u otros caracteres reservados de URL, codifícalos en URL antes de ponerlos en la cadena de conexión. Prueba que la VM de Hindsight pueda llegar al puerto 5432 de PostgreSQL y que pg_hba.conf permita el host de Hindsight: un servidor unido solo a 127.0.0.1 rechaza la conexión incluso cuando la URL parece correcta. Permite que el primer inicio ejecute las migraciones de la base de datos; las migraciones se ejecutan en el inicio a menos que establezcas HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUP=false. Con la API y la base de datos en pie, continúa con Elegir modelos para Hindsight y Servir y conectar modelos locales antes de conectar Hermes.

Elegir modelos para Hindsight

El despliegue pone la API y la base de datos en la red. La siguiente decisión es qué modelos llenan los tres roles de inferencia: incrustaciones para candidatos de recuperación, un reordenador para reordenarlos y un LLM generativo para retener, reflexionar y consolidar. Un predeterminado práctico para un host Hindsight CPU cuya GPU ya esté ocupada con la conversación es Qwen/Qwen3-Embedding-0.6B en proceso, BAAI/bge-reranker-v2-m3 en proceso, y un modelo de chat llama.cpp compartido para trabajo generativo.

Modelos de incrustación

Hindsight lee la dimensión de la incrustación en el inicio y dimensiona el banco para coincidir, por lo que el modelo que elijas en el primer retain es el modelo que el banco conserva hasta que lo reconstruyas. La dimensionalidad y el comportamiento de las instrucciones importan más que la clasificación del marcador de posición: un incrustador 8B más fuerte no vale una migración si el banco ya es de 384 o 1024 dimensiones. Las filas de abajo están ordenadas de más ligero a más pesado; las cifras de RAM son aproximaciones de la huella cargada en CPU (FP16 / carga local típica), no el tamaño del archivo GGUF.

Cómo se ejecuta el modelo es la otra mitad de la elección. Los proveedores de incrustación de Hindsight, del más simple al de más piezas móviles:

Qwen3-Embedding-0.6B no necesita un servicio externo de incrustaciones. En un host Hindsight CPU se carga dentro del proceso de API con el proveedor local: Hugging Face descarga los pesos en el primer inicio, y el proveedor aplica la instrucción de búsqueda del modelo por sí mismo:

# Entorno de Compose (o claves .env equivalentes)
HINDSIGHT_API_EMBEDDINGS_PROVIDER: local
HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL: Qwen/Qwen3-Embedding-0.6B

Usa un endpoint externo compatible con OpenAI solo si quieres el incrustador en otra máquina o fuera del proceso de API. Ollama es un tal host:

# Incrustaciones: Qwen3-Embedding-0.6B en Ollama
HINDSIGHT_API_EMBEDDINGS_PROVIDER: openai
HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL: http://192.168.1.123:11434/v1
HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL: qwen3-embedding:0.6b-q8_0
HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY: dummy

Reemplaza el host, el puerto y la etiqueta con lo que muestre ollama list en tu máquina de inferencia.

HINDSIGHT_API_EMBEDDINGS_QUERY_PREFIX depende del proveedor:

Para la ruta externa, establece:

# Nueva línea real antes de Query:. Bash $'...' es la forma confiable de pasarlo.
HINDSIGHT_API_EMBEDDINGS_QUERY_PREFIX=$'Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery:'
HINDSIGHT_API_EMBEDDINGS_PASSAGE_PREFIX=

En Compose YAML, la misma cadena necesita un \n explícito (o un valor multilínea literal). Establece los prefijos antes del primer retain: cambiarlos después significa que los vectores antiguos y las nuevas consultas ya no se encuentran en el mismo espacio.

Dos propiedades deciden más que la posición en el marcador de posición. Sensibilidad a instrucciones: las incrustaciones de Qwen3 aplican una instrucción de búsqueda en el lado de la consulta; sin el prefijo coincidente en un servidor compatible con OpenAI, el lado almacenado y el lado de la consulta dejan de estar en el mismo espacio. Bloqueo de dimensión: porque el ancho se lee una vez en el inicio, pasar de 0.6B a 4B después es una migración de banco, no un cambio de configuración — y aun un cambio de misma dimensión (BGE-M3 ↔ Qwen3-0.6B, o EmbeddingGemma 2 ↔ nomic en 768) cambia el espacio vectorial, por lo que los vectores del banco no se recalculan automáticamente. Planea un banco nuevo o una re-incrustación/reindexado manual; consulta Exportar, importar y migrar el banco de memoria. Después de dejar BGE-small, sondea recall_min_scores contra la nueva distribución de puntajes — los umbrales calibrados en BGE-small pueden ser demasiado estrechos para Qwen3-0.6B y privar al reordenador de candidatos. Para benchmarks y antecedentes de GGUF/Ollama sobre la familia Qwen3, consulta Modelos de incrustación y reordenación Qwen3 en Ollama.

Modelos de reordenación

Las incrustaciones recuperan un conjunto de candidatos; el reordenador puntúa cada par consulta/pasaje y lo reordena antes de que Hindsight lo inyecte. Con el proveedor local, Hindsight carga un cross-encoder de SentenceTransformers (o un reordenador generativo donde esté soportado). Con un endpoint externo compatible con Cohere, envía el cuerpo completo estilo Cohere a HINDSIGHT_API_RERANKER_COHERE_BASE_URL. El reordenador es opcional, pero una vez que el incrustador está fijo, suele ser el mayor palanca de calidad de recuperación — y, en CPU, a menudo la mayor parte del tiempo real de la recuperación. Las filas están ordenadas de más ligero a más pesado.

Los reordenadores de API en la nube (Cohere, ZeroEntropy, Alibaba qwen3-rerank, TypeSafe y similares) funcionan en Hindsight pero envían el texto de la memoria fuera de la caja. Para un diseño local exclusivo de dominio cruzado, están fuera de alcance.

Dos restricciones operativas dominan la elección. VRAM: si el modelo conversacional ya satura la GPU (por ejemplo, un Qwen3.8-27B Q5 en una tarjeta de 16 GB sin margen), cada fila “GPU preferido” queda fuera de la mesa y la elección activa colapsa a MiniLM o BGE-v2-m3 en CPU. Conteo de candidatos: HINDSIGHT_API_RERANKER_MAX_CANDIDATES (30 en el ejemplo de endpoint externo a continuación) limita cuántos pasajes el modelo repuntúa; cada candidato es una pasada completa hacia adelante, por lo que corta el piso antes de saltar a una capa de modelo más alta. Para Qwen3 a través de llama.cpp, el GGUF debe mantener la cabeza de clasificación — un convert_hf_to_gguf.py antiguo que la descarta puntúa cada pasaje cerca de cero — y aun una conversión correcta necesita una prueba de pasaje conocido-bueno/conocido-malo hasta que la ruta de puntaje generativo esté confirmada.

Capas de LLM generativo

Los modelos de incrustación y reordenación no son sustitutos del LLM generativo usado para extraer y razonar sobre memorias. Hindsight soporta un LLM predeterminado y reemplazos específicos de operación, que pueden apuntar al mismo servidor llama.cpp o endpoints independientes.

Estas son recomendaciones operativas, no conteos de parámetros mínimos oficiales de Hindsight. Un modelo pequeño puede extraer correctamente un número de puerto pero perder que una decisión arquitectónica anterior ha sido superada. La confiabilidad de la salida estructurada y el manejo fiel de la negación importan más que el conteo nominal de parámetros solo. Los predeterminados de temperatura de Hindsight mismo valen la pena dejar intactos — 0.1 para retain, 0.0 para consolidación, 0.9 para reflect — y para retain y consolidación, el alias no-pensante vale la pena servir si tu compilación de llama.cpp tiene uno, porque los checkpoints pequeños de Qwen3.5 gastan muchos tokens en modo de pensamiento.

Para un despliegue con un endpoint llama.cpp Qwen3.8-27B existente, comienza compartiéndolo en tareas generativas de Hindsight con baja concurrencia:

HINDSIGHT_API_LLM_PROVIDER=openai
HINDSIGHT_API_LLM_BASE_URL=http://WORKSTATION_IP:8080/v1
HINDSIGHT_API_LLM_MODEL=LocalMegaLLM
HINDSIGHT_API_LLM_API_KEY=dummy
HINDSIGHT_API_LLM_MAX_CONCURRENT=2
HINDSIGHT_API_RETAIN_LLM_MAX_CONCURRENT=1
HINDSIGHT_API_CONSOLIDATION_LLM_MAX_CONCURRENT=1

Más tarde, enrutina la extracción rutinaria a un modelo 9B independiente y reserva el 27B para reflexiones difíciles:

HINDSIGHT_API_RETAIN_LLM_PROVIDER=openai
HINDSIGHT_API_RETAIN_LLM_BASE_URL=http://MEMORY_LLM_HOST:8083/v1
HINDSIGHT_API_RETAIN_LLM_MODEL=MemoryLLM
HINDSIGHT_API_RETAIN_LLM_API_KEY=dummy

HINDSIGHT_API_REFLECT_LLM_PROVIDER=openai
HINDSIGHT_API_REFLECT_LLM_BASE_URL=http://WORKSTATION_IP:8080/v1
HINDSIGHT_API_REFLECT_LLM_MODEL=LocalMegaLLM
HINDSIGHT_API_REFLECT_LLM_API_KEY=dummy

El modelo 4B más pequeño es económico pero necesita pruebas; 9B es un compromiso sensato de calidad/rendimiento. Si retain y consolidación comparten un modelo pequeño, reduce HINDSIGHT_API_CONSOLIDATION_LLM_BATCH_SIZE a 2 — el lote predeterminado de 8 es un prompt largo para una ventana de contexto pequeña. Qwen3.6-35B-A3B es atractivo para un servidor de inferencia separado bien provisionado (es un modelo de mezcla de expertos con aproximadamente 3 mil millones de parámetros activos, así que presupuéstalo como un modelo activo pequeño), mientras que un modelo denso de 27B suele ser innecesario para cada evento de retain rutinario. Limitar la concurrencia en segundo plano protege al modelo conversacional de Hermes de ráfagas de mantenimiento de memoria.

Servir y conectar modelos locales

Si los ajustes de incrustación y reordenador local en proceso de “Elegir modelos” son suficientes, puedes omitir las subsecciones de Ollama y llama.cpp externas y saltar a la conexión — o dejar Compose en los predeterminados local mostrados allí. Los endpoints externos importan cuando el incrustador o reordenador debe vivir en otro host.

Incrustaciones externas: Ollama o llama.cpp

Las incrustaciones externas son para cuando quieres Qwen3-Embedding-0.6B (u otro modelo) en un host separado. Dos opciones prácticas son Ollama, que maneja la adquisición y el servicio de modelos con poca configuración, y llama.cpp, que da control preciso sobre la cuantización GGUF, hilos de CPU, colocación de dispositivo y lotes. El antecedentes y benchmarks de ambos modelos Qwen3 están en Modelos de incrustación y reordenación Qwen3 en Ollama.

Qwen3-Embedding-0.6B devuelve vectores de 1024 dimensiones, y Hindsight lee ese ancho en el inicio y dimensiona la base de datos para coincidir. Un banco creado con el modelo BGE de 384 dimensiones integrado no puede aceptar este modelo — comienza desde una base de datos o volumen vacío, y decide el modelo de incrustación antes del primer retain. Un cambio de proveedor de incrustaciones después requiere re-incrustar los registros almacenados incluso si ambos modelos usan la misma dimensionalidad.

Opción 1: Ollama para Qwen3-Embedding-0.6B

Instala Ollama en el host de inferencia usando su documentación oficial de instalación para Linux, luego inicia el modelo de incrustación:

ollama pull qwen3-embedding:0.6b
ollama serve

Para acceso remoto, configura OLLAMA_HOST=0.0.0.0:11434 de Ollama en su entorno de servicio, reinicia el servicio y protégelo con un firewall hacia la VM de Hindsight — el procedimiento se cubre en Acceso remoto a Ollama. Un demonio unido solo a 127.0.0.1 es invisible para el contenedor de Hindsight. Primero verifica el nombre del modelo con ollama list, y prueba el endpoint estándar de incrustación:

curl http://EMBED_HOST:11434/api/embed \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen3-embedding:0.6b","input":"A test memory"}'

El proveedor de incrustaciones OpenAI de Hindsight en cambio llama al endpoint /v1/embeddings compatible con OpenAI de Ollama. Verifica que ese endpoint funcione con tu versión de Ollama antes de configurar Hindsight. Ollama es directo para incrustaciones; no asumas que su API ofrece un endpoint de reordenación compatible. Para reordenación, prefiere la ruta local de BGE en proceso a continuación, o un endpoint llama.cpp / TEI separado después de que hayas validado los puntajes.

Opción 2: llama.cpp para Qwen3-Embedding-0.6B

Descarga una conversión GGUF de Qwen3-Embedding-0.6B verificada. Usa el nombre del archivo GGUF que descargaste realmente:

#!/bin/sh
# start-embedding.sh - servidor de incrustación solo CPU
set -eu
cd "$HOME/prj"
exec ./llama.cpp/llama-server \
  --host 0.0.0.0 --port 8081 \
  --model "$HOME/ggufs/Qwen3-Embedding-0.6B-Q8_0.gguf" \
  --alias qwen3-embedding-0.6b \
  --embedding --pooling last \
  --ctx-size 4096 --parallel 1 \
  --threads 4 --threads-batch 4 \
  --batch-size 512 --ubatch-size 256 \
  --n-gpu-layers 0

Las incrustaciones de Qwen3 usan agrupamiento de último token (last-token pooling), a diferencia del agrupamiento CLS usado por algunos modelos BGE. Una compilación de llama.cpp solo CPU es preferible si quieres absolutamente ninguna inicialización de CUDA en una estación de trabajo cuya GPU esté ocupada por un gran modelo conversacional. No habilites --reranking en este servidor de incrustación: esa combinación es una forma conocida de obtener un vector de ceros.

curl -s http://EMBED_HOST:8081/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen3-embedding-0.6b","input":"A test memory"}' \
  | jq '.data[0].embedding | length'

Una salida completa de dimensiones de Qwen3-Embedding-0.6B debe contener 1024 flotantes. Verifica que la conversión GGUF y tu manejo de instrucciones de consulta/documento de Hindsight sean compatibles; los modelos de incrustación sensibles a instrucciones pueden perder precisión cuando se les da el prompt incorrectamente.

Reordenador: BGE local o Qwen3 a través de llama.cpp

La reordenación es diferente de las incrustaciones: el modelo puntúa cada par consulta/documento y devuelve un puntaje de relevancia. En un host Hindsight solo CPU — o cuando la GPU conversacional no tenga margen de VRAM — la ruta práctica es el proveedor local de Hindsight con BAAI/bge-reranker-v2-m3 (o el predeterminado más ligero MiniLM). No se requiere sidecar:

HINDSIGHT_API_RERANKER_PROVIDER=local
HINDSIGHT_API_RERANKER_LOCAL_MODEL=BAAI/bge-reranker-v2-m3
HINDSIGHT_API_RERANKER_MAX_CANDIDATES=20

Qwen3-Reranker-0.6B es un puntajeador generativo de token sí, no un cross-encoder clásico. Puede ser servido a través de llama.cpp con una conversión GGUF diseñada para clasificación, pero trata esa ruta como experimental hasta que confirmes puntajes en un par conocido-bueno/conocido-malo: un convert_hf_to_gguf.py antiguo que descarta la cabeza de clasificación puntúa cada pasaje cerca de cero, y la ruta nativa /rerank de llama.cpp tiene informes conocidos de puntajes incorrectos para esta familia.

#!/bin/sh
# start-reranker.sh - GPU o CPU según lo seleccione --n-gpu-layers
set -eu
cd "$HOME/prj"
exec ./llama.cpp/llama-server \
  --host 0.0.0.0 --port 8082 \
  --model "$HOME/ggufs/Qwen3-Reranker-0.6B-Q8_0.gguf" \
  --alias qwen3-reranker-0.6b \
  --embedding --reranking --pooling rank \
  --ctx-size 4096 --parallel 1 \
  --batch-size 512 --ubatch-size 256 \
  --n-gpu-layers 99

Establece --n-gpu-layers 0 para ejecutarlo en CPU. La versión GPU necesita VRAM adicional para buffers de cómputo y contexto, no solo pesos del modelo; evita asumir que el tamaño del archivo es la asignación total de GPU.

curl -s http://RERANK_HOST:8082/v1/rerank \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen3-reranker-0.6b", "query":"PostgreSQL storage", "documents":["Hindsight stores memories in PostgreSQL.","A recipe for bread."], "top_n":2}' \
  | jq

El documento de PostgreSQL debería clasificarse por encima del documento no relacionado; los puntajes de relevancia todos en cero significan que el GGUF es la conversión incorrecta, y la recuperación parecerá aleatoria incluso cuando los hechos estén almacenados. Verifica la forma exacta de results[].index y results[].relevance_score: Hindsight espera una respuesta de reordenación compatible con Cohere, y la compatibilidad de llama.cpp puede variar entre compilaciones.

Conectar endpoints a Hindsight

Agrega las siguientes configuraciones de entorno al servicio Compose de Hindsight, o guárdalas en su archivo .env. Elige una ruta de incrustaciones — local en proceso, Ollama, o llama.cpp — nunca dos a la vez.

# Opción A: Qwen3 en proceso en el host de Hindsight (CPU; sin sidecar)
HINDSIGHT_API_EMBEDDINGS_PROVIDER=local
HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=Qwen/Qwen3-Embedding-0.6B

# Opción B: servicio de incrustación llama.cpp
# HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
# HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL=http://EMBED_HOST:8081/v1
# HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL=qwen3-embedding-0.6b
# HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=dummy
# HINDSIGHT_API_EMBEDDINGS_OPENAI_BATCH_SIZE=8
# HINDSIGHT_API_EMBEDDINGS_QUERY_PREFIX=$'Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery:'
# HINDSIGHT_API_EMBEDDINGS_PASSAGE_PREFIX=

# Opción C: Ollama en otro host
# HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
# HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL=http://192.168.1.40:11434/v1
# HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL=qwen3-embedding:0.6b-q8_0
# HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=dummy
# HINDSIGHT_API_EMBEDDINGS_QUERY_PREFIX=$'Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery:'
# HINDSIGHT_API_EMBEDDINGS_PASSAGE_PREFIX=

# Opción: reordenador BGE local (sin sidecar; preferido en CPU)
HINDSIGHT_API_RERANKER_PROVIDER=local
HINDSIGHT_API_RERANKER_LOCAL_MODEL=BAAI/bge-reranker-v2-m3
HINDSIGHT_API_RERANKER_MAX_CANDIDATES=20

# Opción: endpoint de reordenación compatible con Cohere de llama.cpp (valida puntajes Qwen3 primero)
# HINDSIGHT_API_RERANKER_PROVIDER=cohere
# HINDSIGHT_API_RERANKER_COHERE_BASE_URL=http://RERANK_HOST:8082/v1/rerank
# HINDSIGHT_API_RERANKER_COHERE_MODEL=qwen3-reranker-0.6b
# HINDSIGHT_API_RERANKER_COHERE_API_KEY=dummy
# HINDSIGHT_API_RERANKER_MAX_CANDIDATES=30

Los nombres de variables son específicos del proveedor, y un error cercano es silencioso: HINDSIGHT_API_EMBEDDINGS_BASE_URL es la clave incorrecta, y Hindsight apunta silenciosamente al endpoint de incrustación de OpenAI en lugar de tu servidor local. Usa HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL. Con la ruta de reordenador compatible con Cohere, Hindsight envía el cuerpo completo estilo Cohere a HINDSIGHT_API_RERANKER_COHERE_BASE_URL; si el registro del contenedor muestra un 404 para /v1/rerank/rerank, tu compilación agrega /rerank por su cuenta y el valor debería detenerse en /v1.

Para las opciones B y C, usa el valor de HINDSIGHT_API_EMBEDDINGS_QUERY_PREFIX de Modelos de incrustación (la opción A lo deja sin establecer). Prueba la recuperación de consulta a pasaje en tus memorias reales después del primer retain.

Controlar lo que se recuerda

Con la pila en funcionamiento, el siguiente modo de fallo suele ser la ruta de escritura: Hermes predetermina auto_retain: true, por lo que cada turno de la conversación puede ser extraído al banco. Suposiciones incorrectas, planes descartados y declaraciones exploratorias se convierten en hechos buscables, y la recuperación posterior los trata como pruebas — el bucle descrito en bucles de memoria autorreforzantes. La política de captura de Hindsight entre otros proveedores se resume en proveedores de memoria para agentes comparados.

Modos de captura que existen hoy

Establecer auto_retain en false deshabilita el almacenamiento automático. No añade un cuadro de diálogo de aprobación humana antes de cada escritura. El agente aún puede llamar a hindsight_retain cuando sus herramientas lo permitan; trata el retain explícito como una captura deliberada, no una cola pendiente.

El vacío de la cola de aprobación

Un deseo común es una cola pendiente de memorias candidatas que revises y apruebes antes de que entren al banco. Hindsight bajo Hermes no proporciona ese contrato hoy. Mnemosyne para Hermes implementa escrituras por etapas específicas del proveedor en algunas versiones; esa ruta no es un estándar compartido de Hermes y no se aplica al plugin de Hindsight. Hasta que exista un flujo de aprobación de aguas arriba, el patrón viable es auto_retain: false, hindsight_retain deliberado, e inspección o eliminación en la UI del plano de control de Hindsight antes de que la siguiente sesión dependa de un hecho malo. No hay ninguna clave write_approval perdida para Hindsight que buscar en config.json.

Dirección del banco (misiones, etiquetas, directivas, modelos mentales)

La gente a menudo llama a la siguiente capa “ajuste fino” (finetuning). En Hindsight es mayormente configuración del banco, no solo config.json de Hermes: las misiones y configuraciones de extracción dirigen lo que retain conserva; las etiquetas estructuran entidades; las directivas y modelos mentales dan forma a la síntesis posterior.

Las misiones, la extracción concisa y las etiquetas reducen el ruido y mejoran la recuperación. No reemplazan apagar auto-retain cuando la precisión importa más que la completitud. Prefiere una misión de retención corta que nombre decisiones de proyecto duraderas e ignore la logística del chat; añade etiquetas de entidad solo cuando tienes una taxonomía real; añade modelos mentales para dos o tres preguntas recurrentes después de que el banco ya contenga hechos limpios.

Perfil de higiene recomendado

Un punto de partida concreto para un banco personal de Hermes:

{
  "mode": "local_external",
  "api_url": "http://HINDSIGHT_VM_IP:8888",
  "bank_id": "hermes",
  "memory_mode": "hybrid",
  "auto_recall": true,
  "recall_sync": false,
  "auto_retain": false,
  "retain_async": true,
  "recall_prefetch_method": "recall"
}

En el banco, establece una misión de retención y deja la extracción en modo concise (vía el plano de control o la API de Banks). Después de un retain explícito, abre la UI, confirma la observación y elimina errores antes de que se ejecute la consolidación o la actualización del modelo mental. Deja recall_prefetch_method en recall — reflect gasta una llamada al modelo de chat antes de cada turno e inyecta síntesis en lugar de hechos subyacentes.

Conectar Hermes Agent a Hindsight

En la VM de Hermes, instala el plugin del catálogo, luego ejecuta el asistente de configuración. Selecciona Hindsight y el modo local_external; el plugin no necesita iniciar PostgreSQL integrado ni ejecutar la pila de modelos de Hindsight localmente, y local_embedded iniciaría un segundo demonio de Hindsight junto al contenedor que acabas de ejecutar.

hermes plugins install hindsight
hermes memory setup hindsight

Habrá un conjunto interesante de opciones de rol del agente usando hindsight

hermes memory status

La conexión externa de Hindsight vive en ~/.hermes/hindsight/config.json. Una configuración ilustrativa que mantiene la captura continua (predeterminados de Hermes) es:

{
  "mode": "local_external",
  "api_url": "http://HINDSIGHT_VM_IP:8888",
  "bank_id": "hermes",
  "memory_mode": "hybrid",
  "auto_recall": true,
  "recall_sync": false,
  "auto_retain": true,
  "retain_async": true,
  "retain_every_n_turns": 1
}

Para retain solo explícito y dirección del banco, usa el perfil de higiene de Controlar lo que se recuerda en lugar de dejar auto_retain activado. recall_sync: false prioriza la respuesta interactiva pero puede inyectar contexto recuperado en el turno siguiente. Usa recuperación síncrona cuando la solicitud actual debe incorporar las memorias más recientes antes de que el modelo comience a responder. retain_async: true evita bloquear respuestas ordinarias mientras las memorias se procesan.

El predeterminado de recuperación del plugin es solo observaciones; los hechos brutos del mundo y la experiencia permanecen en el banco y fuera del prompt hasta que la consolidación haya escrito una observación, o hasta que amplíes recall_types a observation,world,experience. Ampliarlo durante la primera semana y observar el plano de control, luego estrecharlo, es un orden razonable.

La memoria integrada de Hermes permanece activa junto al proveedor; mantener MEMORY.md y USER.md activos mientras aprendes lo que Hindsight agrega está bien, y el artículo de sistema de memoria es el lugar para decidir si los archivos planos deberían permanecer.

Reinicia la pasarela (gateway) si ya está en ejecución:

hermes gateway restart
hermes memory status

El estado debe identificar Hindsight como el proveedor activo. Para una referencia más amplia de comandos, incluyendo la TUI de Hermes y los comandos de plugins, consulta la hoja de referencia de CLI de Hermes Agent.

Validar la memoria, no solo la instalación

Pídele a Hermes que recuerde un hecho desechable sobre un proyecto de prueba, inicia otra sesión y pregunta por ese hecho de nuevo. La retención es asíncrona por defecto y la extracción espera al modelo de chat, así que da un momento al servidor principal de llama.cpp antes de juzgar. Luego prueba un caso más difícil: dile a Hermes que una decisión anterior ha cambiado y pregunta cuál decisión es la actual y por qué. Revisa la UI de Hindsight y las observaciones almacenadas en lugar de asumir que memory status prueba que la ingestión y la recuperación son correctas.

Si la respuesta vuelve vacía, inspecciona el plano de control antes de cambiar modelos. Un retain puede tener éxito y aún ser invisible para la recuperación mientras recall_types sea solo observaciones y la consolidación no haya corrido — ampliar recall_types es la primera comprobación. Una conexión rechazada en el registro del servidor de incrustación significa que el contenedor no puede llegar al puerto de incrustación, y los puntajes de reordenador todos en cero significan que el GGUF es la conversión incorrecta.

Las elecciones de ruta de escritura (auto_retain, misiones, vacío de aprobación) se cubren en Controlar lo que se recuerda.

Solución de problemas y notas operativas

Un despliegue pequeño práctico son 2-4 vCPUs y 4-6 GB de RAM para la VM de API de Hindsight cuando PostgreSQL y toda la inferencia son externos. La asignación de disco aún depende de la imagen Docker elegida y las capas de imagen retenidas; asigna aproximadamente 30-40 GB inicialmente con espacio para expandir. Dimensiona el host de PostgreSQL basado en el volumen de memoria real, el rendimiento de almacenamiento y las otras bases de datos que sirve.

Hacer copia de seguridad y restaurar el banco de Hindsight

El banco de memoria es el único estado que importa, y vive en PostgreSQL. En la opción B es una base de datos que administras; en la opción A es el volumen con nombre pg0 integrado dentro del contenedor. Haz copia de seguridad independientemente del contenedor de Hindsight — recrear el contenedor sin antes capturar el volumen o la base de datos descarta el banco, y hermes backup no llega a un banco que se ejecuta en un servicio separado.

Opción B — PostgreSQL externo. Descarga la base de datos hindsight en formato personalizado, luego restáurala en una base de datos de borrador para verificar el archivo antes de confiar en él:

pg_dump -h POSTGRES_IP -U hindsight -Fc hindsight > hindsight-bank.dump

# restaurar en una base de datos de borrador para probar que el dump es utilizable
createdb -h POSTGRES_IP -U postgres hindsight-verify
pg_restore -h POSTGRES_IP -U postgres -d hindsight-verify hindsight-bank.dump

Confirma que la extensión pgvector y una recuperación de muestra existan en la copia restaurada antes de eliminar el destino del dump original. Mantén el dump en un host diferente al de la VM de Hindsight, y ejecuta esto como administrador de PostgreSQL (un rol que puede crear bases de datos) en lugar del rol de aplicación.

Opción A — contenedor todo-en-uno. La base de datos integrada es un volumen con nombre, así que detén el contenedor y empaqueta el volumen (tar) a través de una imagen descartable:

docker stop hindsight
docker run --rm -v hindsight-pg0:/data -v "$PWD":/backup alpine \
  tar czf /backup/hindsight-bank.tgz -C /data .
docker start hindsight

El punto de montaje dentro del contenedor tar (/data) es arbitrario; simplemente alía el volumen con nombre para que tar pueda leerlo. Para restaurar, detén el contenedor, limpia el volumen y desempacata (untar) el archivo de vuelta en él, o apunta el contenedor a la restauración de PostgreSQL externo de la opción B.

Toma una instantánea en tres momentos en lugar de en un horario de calendario: antes de cambiar el modelo de incrustación, antes de una actualización mayor de Hindsight o PostgreSQL, y antes de una pasada de reflect o consolidación que reescriba el banco. Una copia de seguridad que hayas restaurado en un banco de borrador vale más que una que solo hayas escrito.

Exportar, importar y migrar el banco de memoria

La copia de seguridad y la restauración protegen el banco en su lugar. Exportar/importar lo mueve entre instancias de Hindsight, y eso es lo que un cambio de modelo realmente te obliga a hacer.

Cambiar el modelo de incrustación no es una edición de configuración. Los vectores en el banco se calcularon con el modelo antiguo, y un modelo diferente — por ejemplo, el incrustador BGE de 384 dimensiones integrado versus Qwen3-Embedding-0.6B de 1024 dimensiones — escribe en un espacio diferente y usualmente un ancho diferente. No puedes re-apuntar la instancia existente al nuevo incrustador y mantener los vectores antiguos; las dimensiones deben recalcularse re-incrustando cada memoria con el nuevo modelo de incrustación.

Porque el incrustador y su configuración se establecen por instancia de Hindsight, la ruta limpia es establecer una instancia nueva con la nueva configuración de incrustación y migrar el banco a ella, en lugar de reconstruir vectores dentro de la que ya está sirviendo recuperación. La API de Hindsight también puede mover el banco, pero para un cambio de una vez, exportar/importar es la ruta más fácil e inspeccionable:

# exportar el banco desde la instancia antigua
docker exec hindsight \
  hindsight-admin export-bank \
    --bank hermes2 \
    --output /tmp/hermes2.zip

docker cp hindsight:/tmp/hermes2.zip ./hermes2.zip

ls -lh hermes2.zip
unzip -t hermes2.zip

# importar el banco en la nueva instancia
docker cp ./hermes2.zip hindsight-q06:/tmp/hermes2.zip

docker exec hindsight-q06 \
  hindsight-admin import-bank \
    --archive /tmp/hermes2.zip

unzip -t verifica el archivo antes de enviarlo a la nueva instancia. Después de la importación, re-apunta Hermes a la api_url de la nueva instancia en ~/.hermes/hindsight/config.json, reinicia la pasarela (gateway) y ejecuta la validación de memoria de antes: un hecho retenido debería recuperarse a través del nuevo incrustador. Deja el banco antiguo y sus vectores en la instancia antigua hasta que la nueva se comporte, para que aún tengas un respaldo funcional.

Monitorear, podar y mantener el banco estable

Con el banco funcionando, el trabajo diario es observar lo que el modelo de extracción ha decidido almacenar y mantener el estado derivado bajo control. Usa la UI del plano de control (hindsight-embed -p hermes ui start) para inspeccionar observaciones, puntajes de relevancia y salida de consolidación en lugar de asumir que memory status prueba que la ingestión y la recuperación son correctas. Las memorias duplicadas o desactualizadas suelen ser una extracción débil o una consolidación subejecutada, así que corrige la capa de extracción o el ciclo de consolidación antes de ampliar la recuperación.

Dos trampas de mantenimiento vale la pena probar antes de confiar en el banco. Primero, eliminar una observación no garantiza que todas las representaciones derivadas desaparezcan con ella — un hecho de reflect o un borde de grafo construido a partir de él puede sobrevivir a la eliminación, así que verifica la eliminación de extremo a extremo, la misma preocupación de procedencia cubierta en bucles de memoria autorreforzantes. Segundo, mantén HINDSIGHT_API_WORKER_ID estable entre recreaciones y fija una etiqueta de imagen específica: una tarea que estaba en curso cuando el contenedor murió queda atascada bajo el id de trabajador antiguo, y una etiqueta cambiante es una mala opción para una base de datos que pretendes conservar.

Referencias

• Código fuente y documentación de Hindsight
• Guía oficial de instalación de Hindsight
• Referencia de configuración de Hindsight
• Integración de Hindsight con Hermes
• Modelos de inferencia y proveedores de reordenación de Hindsight
• pgvector
• Servidor de llama.cpp
• Ollama