La semana pasada fui a buscar un pequeño error y encontré cinco copias del mismo software.
El software es hermes-memory-pgvector, un complemento de código abierto que mantengo. Proporciona a una flota de agentes de IA una memoria compartida y duradera en PostgreSQL y pgvector, de modo que los demás agentes puedan recordar lo que aprende uno. Se publica en PyPI. Puedes instalarlo con pip.
Y, sin embargo, en mi propio servidor se ejecutaba desde una copia de trabajo de git oculta dentro del árbol de código fuente de otro proyecto, a una limpieza rutinaria de ser eliminada. También había una copia vendorizada en mi repositorio de infraestructura que no utilizaba nada, un directorio de compilación obsoleto, una caché de paquetes y un enlace simbólico hecho a mano, creado minutos antes para evitar que todo el montaje se viniera abajo.
Ese es el tipo de configuración que heredas de ti mismo seis meses después y que no puedes justificar de inmediato.
Por qué pip install no era suficiente
Esta es la parte que realmente explica el lío.
El framework anfitrión descubre los complementos de memoria explorando directorios. Busca en su propia carpeta de complementos incluida y en una carpeta de complementos del usuario un subdirectorio que contenga un __init__.py donde se mencione la clase correcta. Ese es todo el mecanismo de descubrimiento. Nunca inspecciona los paquetes de Python instalados y no hay registro de puntos de entrada.
Así que pip install instaló mi complemento en la máquina, correctamente y en el entorno adecuado, pero el framework no podía verlo. Perfectamente instalado. Completamente invisible.
Ante eso, lo obvio es poner una copia donde el explorador sí busque. Copiar la carpeta al repositorio de despliegue. Descargar allí el código junto al framework. Crear un enlace simbólico. Cada una de esas decisiones es razonable por sí sola, y juntas son la forma de acabar con cinco copias y un despliegue que nadie puede explicar.
La solución: dejar de luchar contra el explorador
La versión que publiqué esta semana añade un comando, que se ejecuta una sola vez después de la instalación:
pip install hermes-memory-pgvector
hermes-pgvector install
Ese segundo comando escribe un pequeño adaptador en la carpeta que lee el explorador: unas pocas líneas cuya única función es importar el paquete real instalado con pip. El explorador encuentra un directorio y queda satisfecho. Python resuelve la importación hacia la biblioteca correctamente instalada.
Esa única capa de indirección reduce cinco copias a una. Para actualizar, basta con actualizar el paquete con pip y reiniciar. Para volver atrás, basta con fijar la versión anterior. Nada está incluido como copia vendorizada, nada se descarga como copia de trabajo, nada se desincroniza, y las tareas rutinarias de mantenimiento en el repositorio de otra persona ya no pueden llevarse por delante mi capa de memoria.
Qué más salió a la luz
Consolidar el despliegue significó volver a leer el código como es debido, lo que sacó a la luz varios errores reales que merece la pena mencionar:
Una búsqueda de subcadena que no era tal. Al editar una memoria almacenada, se comparaba tu texto con la base de datos usando SQL LIKE, donde % es un comodín. Una memoria que contuviera "revenue grew 15% YoY" podía coincidir con filas no relacionadas y modificarlas. Las barras invertidas tenían el problema opuesto: una ruta de archivo de Windows no coincidía con nada en absoluto, sin que se avisara de ello.
Una cola que descartaba trabajo mientras afirmaba haber terminado. El escritor en segundo plano aceptaba escrituras y, al apagarse, si estaba ocupado, abandonaba todo lo que seguía en cola sin dejar constancia en los registros.
Un error engañoso. Si configurabas el complemento con un modelo de embeddings cuyo tamaño de salida era incorrecto, recibías un 404 de una ruta alternativa que no tenía relación, en vez de «se esperaban 768 dimensiones; se obtuvieron 1024».
Nada de esto era exótico. Eran problemas que una lectura cuidadosa permite encontrar, pero que una suite de pruebas que pasa no detecta.
La lección que sigo aprendiendo una y otra vez
Cuando un despliegue es un desastre, normalmente ese desastre está diciendo algo cierto sobre el diseño.
Las cinco copias no eran fruto del descuido. Cada una era una solución provisional racional. Eran un síntoma, y el problema de fondo era que mi paquete no podía ser descubierto de la manera en que debía ser instalado. Arreglar las soluciones provisionales una por una habría producido un desastre más ordenado. Corregir la brecha de descubrimiento hizo innecesarias esas soluciones.
Si mantienes algo que la gente instala de una manera y despliega de otra, merece la pena cerrar esa brecha. Probablemente esté intentando decirte algo.
hermes-memory-pgvector tiene licencia BSD-3 y está disponible en GitHub y en PyPI.
