Apartment38/Agent-Skills

Proveedores de Memoria Externos

Instalar, configurar y verificar proveedores de memoria de terceros para Hermes Agent. Trata "instalado" y "activo en Hermes" como criterios de aceptación separados.

Principios

1. Comienza desde la documentación autorizada actual. Carga el skill hermes-agent y obtén tanto la página de instalación del proveedor como su página completa de integración en Hermes. Sigue la ruta recomendada documentada; utiliza una alternativa documentada solo cuando una restricción de compatibilidad real lo requiera.
2. Mantén las dependencias fuera del venv gestionado de Hermes. Las actualizaciones de Hermes pueden reconstruir ese venv. Prefiere pipx o un venv persistente dedicado.
3. Iguala los ABI de Python en el límite del puente. Un entorno pipx puede usar un Python más nuevo que Hermes. Agregar sus site-packages al sys.path de Hermes no es seguro cuando hay ruedas nativas involucradas. Utiliza un venv dedicado creado con el Python de Hermes cuando un envoltorio ejecuta importaciones en el proceso.
4. Usa la CLI de Hermes para la configuración. Nunca edites config.yaml manualmente; aplica la configuración con hermes config set.
5. No deshabilites el conjunto de herramientas de memoria compartida. Al reemplazar la memoria de archivos heredada, deshabilita solo las banderas de archivo/perfil integradas documentadas para el proveedor. Una desactivación general hermes tools disable memory también puede ocultar las herramientas del proveedor.
6. Ten en cuenta el almacenamiento en caché de indicaciones. Los cambios de proveedor/herramienta se aplican a las sesiones recién inicializadas. No mutes la indicación del sistema ni el esquema de herramientas de una conversación existente; reinicia la puerta de enlace y declara claramente que una sesión TUI ya en ejecución debe ser reemplazada.

Flujo de trabajo de instalación

1. Auditar antes de cambiar el estado

Registra:

• hermes --version y la versión/ruta de Python de Hermes
• versiones de paquetes del proveedor y entornos de instalación
• salida del instalador/estado del proveedor
• hermes plugins list --plain --no-bundled
• hermes config get memory.provider
• hermes memory status
• estado de la puerta de enlace

No infieras [all] o extras equivalentes de la versión base del paquete. Importa o inspecciona cada dependencia de capacidad nombrada por la documentación del proveedor.

2. Elegir una topología de aislamiento

• Usa pipx cuando el proveedor se comunique fuera del proceso o Hermes descubra un punto de entrada de paquete seguro.
• Usa un venv dedicado construido desde el Python de Hermes cuando Hermes importe código del proveedor en el proceso y el paquete incluya extensiones nativas.
• Nunca trates importlib.util.find_spec() como prueba de compatibilidad. Localiza módulos sin cargar código nativo. Realiza importaciones reales bajo el intérprete que ejecutará el proveedor.

3. Instalar proveedor y puente

Instala el perfil de características solicitado completo y su envoltorio de Hermes. Si el envoltorio incluye un comando de instalador/estado, úsalo para crear el puente de complemento persistente en $HERMES_HOME/plugins/ y verifica su importación.

Habilita los complementos de usuario explícitamente cuando Hermes los liste como opt-in:

hermes plugins enable <manifest-name>

La selección del proveedor y la habilitación de complementos generales pueden ser mecanismos separados. Verifica ambos.

4. Configurar sin duplicación

Establece el proveedor externo y, si la documentación del proveedor lo indica, deshabilita la memoria de archivos heredada mientras conservas el conjunto de herramientas de memoria:

hermes config set memory.provider <provider>
hermes config set memory.memory_enabled false
hermes config set memory.user_profile_enabled false

Usa las claves documentadas actuales del proveedor en lugar de asumir que estas son universales.

5. Reiniciar y verificar

Reinicia la puerta de enlace solo después de que la instalación, habilitación y configuración estén completas. Luego verifica:

• La puerta de enlace está activa.
• El puente/complemento de estado dice instalado e importable.
• La lista de complementos generales dice habilitado cuando los hooks/herramientas dependen de él.
• hermes memory status dice que el proveedor seleccionado está instalado, disponible y activo.
• Los diagnósticos del proveedor no tienen registros de error/fallo reales. No malinterpretes contadores, mediciones, comprobaciones omitidas o anulaciones opcionales no establecidas como fallos.

6. Ejercitar la ruta del agente Hermes

Una prueba de humo SDK independiente es necesaria pero insuficiente. Carga el proveedor a través del cargador de proveedores de memoria propio de Hermes o inicia un agente Hermes nuevo, luego verifica:

1. construcción e inicialización del proveedor;
2. el bloque de indicación del sistema del proveedor está activo;
3. los esquemas de herramientas del proveedor están expuestos;
4. escribir una memoria de prueba con una etiqueta única;
5. recuperar esa etiqueta exacta;
6. eliminar la memoria de prueba;
7. confirmar que la BD/ruta del proveedor es el almacén de Hermes previsto.

Usa aserciones y falla el comando de verificación si algún paso falla. Informa las versiones/estados observados exactos, no expectativas plausibles.

Errores comunes

• Los venv de pipx separados no están "junto a" para importaciones en proceso. El núcleo y el envoltorio pueden funcionar solos mientras Hermes no puede importar ambos de forma segura.
• Complemento descubierto no significa complemento habilitado. El descubrimiento del proveedor puede tener éxito mientras el registro de hooks/herramientas sigue siendo opt-in.
• Un comando CLI ausente no prueba un fallo del proveedor. Hermes puede cargar el proveedor mientras un instalador omitió el cli.py hermano utilizado para el descubrimiento de argparse. Diagnostica las rutas del proveedor y CLI de forma independiente, luego repara solo con un puente probado.
• El reinicio de la puerta de enlace no moderniza la conversación actual. Las nuevas sesiones de puerta de enlace y CLI usan el proveedor; un proceso TUI antiguo retiene su superficie de indicación/herramienta congelada.
• Un comando de instalación exitoso no es finalización. Requiere configuración de lectura inversa, estado de proveedor activo y un ciclo real de escritura/recuperación/limpieza.

Referencias de proveedores

• Mnemosyne + integración con Hermes, manejo de ABI de Python, puente CLI y prueba de humo determinista: references/mnemosyne-hermes.md