Mnemosyne para Hermes Agent: guía de inicio rápido de memoria local

Mnemosyne es un proveedor de memoria local-first para Hermes Agent, que almacena memoria de trabajo, hechos estructurados, datos temporales e historial episódico en SQLite local: sin servicios alojados, sin llamadas de red obligatorias y con un control de escritura inusualmente granular.

Su propiedad más útil no es la calidad bruta de la recuperación. Es la cantidad de control que expone sobre la ruta de escritura: el autoguardado de conversaciones puede restringirse por rol o desactivarse por completo, el registro de resultados de herramientas está desactivado por defecto, las operaciones explícitas de recordado y olvido siguen disponibles sin importar qué, y las versiones más recientes añaden la supresión opcional de autoeco alrededor de los límites de compresión de contexto. Esa combinación lo convierte en una opción razonable cuando se desea una memoria persistente sin convertir automáticamente cada conversación en conocimiento permanente.

Esta disciplina en la ruta de escritura importa porque la memoria de agentes tiene un modo de fallo bien documentado: la propia inferencia de un modelo puede ser capturada, recuperada más tarde como si fuera una observación y utilizada para justificar una versión aún más fuerte de sí misma. Bucles de memoria autorreforzados en agentes de IA cubre ese modo de fallo en profundidad; esta guía se centra en la configuración concreta de Mnemosyne que lo limita en la práctica. Para saber dónde se sitúa Mnemosyne en relación con los demás backends de memoria de Hermes, consulte Comparación de proveedores de memoria de agentes.

Mnemosyne en un minuto

Un proveedor de memoria típico realiza alguna versión de captura, extracción, almacenamiento, recuperación e inyección en un prompt futuro. Mnemosyne añade varias capas distintas alrededor de ese bucle básico: memoria de trabajo, recuperación semántica y léxica, hechos estructurados, información temporal, enlaces de entidades, memoria episódica, consolidación, hechos canónicos y validación de memoria. El almacenamiento es SQLite local con FTS5 y recuperación vectorial opcional, lo que lo hace considerablemente más inspeccionable que un producto de memoria exclusivo en la nube y más capaz que un archivo MEMORY.md simple.

Muy brevemente, en relación con el resto del ecosistema de proveedores de Hermes: Holographic es más simple y deliberadamente orientado a almacenes de hechos; Hindsight enfatiza la recuperación híbrida, los gráficos de conocimiento y la reflexión; Honcho enfatiza la modelización de pares y usuarios con razonamiento dialéctico; Mem0 enfatiza la extracción automática de hechos basada en LLM; y Mnemosyne combina almacenamiento SQLite local, recuperación híbrida, consolidación, hechos estructurados y controles de retención inusualmente granulares. El desglose completo, incluidos los requisitos de infraestructura y notas de autoalojamiento para cada proveedor, está en Comparación de proveedores de memoria de agentes.

Versiones actuales

A septiembre de 2026, la versión estable de PyPI es mnemosyne-memory 3.15.1, con la rama 4.0 disponible como pre-lanzamiento. Para una instalación de producción de Hermes, comience con la versión estable a menos que necesite específicamente una corrección o funcionalidad de la 4.0 y esté preparado para probar la migración de base de datos y el cambio de comportamiento. Compruebe su versión instalada con:

hermes mnemosyne version

Instalando Mnemosyne en Hermes

Active primero el propio entorno virtual de Hermes si utilizó la instalación local estándar:

source ~/.hermes/hermes-agent/venv/bin/activate

Para el soporte de incrustaciones (embeddings) local, instale el paquete núcleo con el extra de embeddings junto con el envoltorio de plugin de Hermes:

python -m pip install \
  "mnemosyne-memory[embeddings]" \
  mnemosyne-hermes

Luego registre el plugin:

mnemosyne-hermes install

Si está reemplazando un registro de plugin existente:

mnemosyne-hermes install --force

Active el proveedor y reinicie el gateway:

hermes config set memory.provider mnemosyne
hermes gateway restart

Verifique con:

hermes memory status

La salida esperada se parece a:

Provider: mnemosyne

Plugin: installed
Status: available

Instalaciones con Docker y servidores persistentes

Si Hermes se ejecuta dentro de un despliegue Docker persistente o basado en imágenes, instale en un entorno virtual secundario en el hogar de Hermes montado, en lugar del entorno Python reproducible del contenedor, para que el plugin sobreviva a las reconstrucciones de la imagen:

export HERMES_HOME=/opt/data
VENV="$HERMES_HOME/.mnemosyne/venv"
python3 -m venv "$VENV"
"$VENV/bin/python" -m pip install --upgrade "mnemosyne-memory[embeddings]" mnemosyne-hermes
"$VENV/bin/mnemosyne-hermes" install --mode wrapper --python "$VENV/bin/python"
hermes config set memory.provider mnemosyne

El venv secundario debe usar la misma versión mayor/menor de Python que el gateway de Hermes en ejecución: no lo apunte a un python3 no relacionado desde PATH. Después, reinicie el contenedor o servicio real y verifique con "$VENV/bin/mnemosyne-hermes" status junto con hermes memory status.

No desactive todo el conjunto de herramientas de memoria de Hermes

Mantenga dos conceptos separados: la memoria integrada propia de Hermes (MEMORY.md / USER.md, cubierto en detalle en Sistema de memoria de Hermes Agent) y el proveedor externo (Mnemosyne). No ejecute casualmente hermes tools disable memory al configurar un proveedor externo; dependiendo de la versión de Hermes, ese comando también puede ocultar las herramientas de proveedores de memoria externos. Use la configuración del proveedor en su lugar, como se muestra a continuación.

Estado básico e inspección

hermes memory status
hermes mnemosyne stats
hermes mnemosyne stats --global
hermes mnemosyne inspect "query"

Exporte una copia de seguridad portable:

hermes mnemosyne export \
  --output ~/mnemosyne-backup.json

La base de datos subyacente normalmente reside en ~/.hermes/mnemosyne/data/mnemosyne.db. Dado que es SQLite, la inspección y la copia de seguridad son sencillas con herramientas estándar. Para el resto de comandos de gateway, sesión y diagnóstico mencionados a lo largo de esta guía, la hoja de referencia de la CLI de Hermes Agent) es una referencia más rápida que revolver por la salida de --help.

La política de retención por defecto merece atención

El primer control que vale la pena entender es sync_roles. Los valores predeterminados actuales de Mnemosyne ya son más conservadores que las primeras versiones: la sincronización automática de Hermes predetermina las turnos del usuario en lugar de ambos (usuario y asistente); pero para una retención estrictamente explícita, desactivar por completo el autoguardado de turnos vale el paso extra. Edite ~/.hermes/config.yaml:

memory:
  provider: mnemosyne

  mnemosyne:
    sync_roles: []

Una lista vacía significa que los turnos de conversación ordinarios no se guardan automáticamente mediante sync_turn(). Las operaciones explícitas mnemosyne_remember continúan funcionando sin importar qué: la conversación normal deja de fluir automáticamente a la memoria, mientras que un “recuerda esto” explícito aún llega a Mnemosyne.

Desactivar el registro automático de resultados de herramientas

Mnemosyne también puede registrar ejecuciones de herramientas como memoria. Para una configuración conservadora, deje eso desactivado en ~/.hermes/.env:

MNEMOSYNE_LOG_TOOLS=0

Esto ya es el valor predeterminado, pero configurarlo explícitamente documenta la política en lugar de depender de una suposición sobre los predeterminados. Reinicie Hermes después:

hermes gateway restart

Con sync_roles: [] y MNEMOSYNE_LOG_TOOLS=0 juntos, ambas rutas de escritura automática principales — autoguardado de conversación y autoguardado de resultados de herramientas — están desactivadas.

Mantener la recuperación automática

Desactivar las escrituras automáticas no requiere desactivar la recuperación. Una política útil mantiene la retención automática desactivada mientras que la recuperación automática, el recordado explícito y el olvido explícito permanecen activos: la memoria debe ser fácil de leer y difícil de escribir, lo cual está cerca del opuesto de un predeterminado de “captura todo y ordénalo después”.

Añadir una instrucción duradera para el agente

La configuración del proveedor bloquea la captura a nivel de proveedor, pero el modelo aún puede decidir llamar a una herramienta de escritura explícita por iniciativa propia. Añada una política explícita a SOUL.md:

## Política de memoria a largo plazo

Mnemosyne es el proveedor de memoria a largo plazo.

No escriba nada en Mnemosyne a menos que el usuario le pida explícitamente
recordar, guardar, retener o almacenar esa información.

Si la información parece útil para futuras sesiones pero el usuario no
solicitó explícitamente que se recordara, pida permiso antes de llamar a
mnemosyne_remember o a otra herramienta de escritura de Mnemosyne.

No cree memorias duraderas a partir de su propio razonamiento, suposiciones,
resúmenes, interpretaciones, conclusiones o preferencias inferidas.

No cree memorias duraderas a partir de la salida de herramientas a menos que
el usuario pida explícitamente que ese resultado se recuerde.

Al almacenar una memoria aprobada, preserve lo que el usuario realmente
declaró. No lo embellezca con contexto o conclusiones inferidos.

Leer y recuperar memorias de Mnemosyne está permitido sin pedir permiso.

Reinicie el gateway y comience una nueva sesión después:

hermes gateway restart

/new

Esta es una política impuesta por el modelo, no una frontera dura de permisos; complementa la configuración a nivel de proveedor anterior en lugar de reemplazarla.

¿Qué pasa con memory.write_approval?

Hermes soporta memory.write_approval: true para escrituras en MEMORY.md / USER.md integradas, y Mnemosyne implementa su propio estacionamiento específico del proveedor para escrituras explícitas en versiones más recientes. Esto es prometedor, pero hay una advertencia arquitectónica que vale la pena tomar en serio: Hermes aún no expone un contrato de aprobación uniforme y neutral respecto al proveedor entre todos los proveedores de memoria externos, y la implementación pendiente/aplicar de Mnemosyne es específica del proveedor en lugar de ser parte de un estándar compartido. No asuma que la aprobación funciona correctamente solo porque la clave de configuración está presente; pruébela contra sus versiones exactas de Hermes y Mnemosyne. Hasta que la aprobación independiente del proveedor madure, combinar sync_roles: [], MNEMOSYNE_LOG_TOOLS=0 y la política de escritura explícita en SOUL.md anterior le da una línea base confiable, con la ruta de aprobación probada por separado si tiene la intención de depender de ella.

Habilitar la supresión de autoeco

Mnemosyne actual también ofrece la supresión opcional de autoeco:

MNEMOSYNE_SELF_ECHO_ENABLED=1

Ponga esto en ~/.hermes/.env, luego reinicie:

hermes gateway restart

La supresión de autoeco apunta específicamente a los límites de compresión de contexto: su propósito es reducir los casos donde la memoria que el proveedor acaba de crear se devuelve inmediatamente al agente como si fuera contexto independiente. Es intencionalmente de mejor esfuerzo y no reemplaza el filtrado de escritura: los controles de escritura impiden que memorias cuestionables entren en primer lugar, mientras que los controles de autoeco impiden que la salida reciente del proveedor rebote directamente. Ambos importan y ninguno sustituye al otro.

Una configuración conservadora de Mnemosyne

Reuniendo las piezas, una configuración de inicio para un agente de ingeniería personal autoalojado se ve así. En ~/.hermes/config.yaml:

memory:
  provider: mnemosyne

  mnemosyne:
    sync_roles: []

En ~/.hermes/.env:

MNEMOSYNE_LOG_TOOLS=0
MNEMOSYNE_SELF_ECHO_ENABLED=1

Y en SOUL.md, al mínimo:

Solo almacene memoria a largo plazo cuando el usuario lo solicite explícitamente.
No promueva conclusiones generadas por el modelo o salida de herramientas a memoria
duradera sin permiso explícito.

Pruebe que la conversación ordinaria no se retiene

Compruebe el recuento inicial primero:

hermes mnemosyne stats

Comience una nueva sesión de Hermes y diga una declaración factual simple sin pedirle al agente que la recuerde, por ejemplo:

PurpleOtter usa el puerto 48123.

Después, busque por ella:

hermes mnemosyne inspect "PurpleOtter"

Esperado: Results for 'PurpleOtter': 0. También vuelva a revisar hermes mnemosyne stats: el recuento de memoria de trabajo no debería haber aumentado debido a ese turno ordinario.

Pruebe la memoria explícita

Ahora diga el mismo tipo de declaración, pero pida explícitamente la retención:

Recuerda que BlueKoala usa el puerto 17321.

Inspecciónela, luego comience una nueva sesión y pídala de vuelta:

hermes mnemosyne inspect "BlueKoala"

/new

¿Qué puerto usa BlueKoala?

Hermes debería recuperar el valor correctamente: este par de pruebas aísla la política de ruta de escritura (nada entra sin preguntar) del mecanismo de recuperación (lo que entra sale confiablemente).

Pruebe el registro de herramientas

Con MNEMOSYNE_LOG_TOOLS=0 establecido, pida a Hermes que ejecute un comando distintivo y único:

Use the terminal tool to run:
echo tool-canary-834729

Luego busque la cadena canaria:

hermes mnemosyne inspect "tool-canary-834729"

Esperado: 0 results. Esto es una prueba mucho más fuerte que simplemente confiar en que la variable de entorno se respeta en todas partes.

Inspeccionando la base de datos

Dado que el almacenamiento es SQLite, el esquema interno es directamente inspeccionable:

sqlite3 ~/.hermes/mnemosyne/data/mnemosyne.db '.tables'

Dependiendo de la versión, puede ver tablas como working_memory, episodic_memory, facts, consolidated_facts, gists, graph_edges, memoria_facts y memory_embeddings. Esto importa al probar la eliminación: un sistema de memoria puede eliminar exitosamente una fila de memoria de trabajo mientras deja atrás un hecho derivado, un gist o un objeto de gráfico. Mnemosyne ha tenido bugs reales en esta área involucrando registros derivados huérfanos, y las versiones más recientes han afinado tanto la eliminación como el diagnóstico en consecuencia. Prefiera las rutas de eliminación y doctor/repair soportadas por el proveedor antes de eliminar filas de SQLite manualmente a menos que entienda completamente el esquema actual.

Eliminando memoria de trabajo con alcance de sesión

Un matiz: las memorias de trabajo de Mnemosyne pueden tener alcance de sesión, por lo que una fila con scope = session puede no ser visible para una eliminación independiente operando en la sesión default. Al depurar, inspeccione el alcance directamente:

SELECT id, session_id, scope, content
FROM working_memory;

El proveedor o API necesita el alcance de sesión correcto para mutar registros locales de sesión: otra razón para preferir las herramientas de administración soportadas sobre ediciones de SQL sin procesar.

Consolidación: no se apresure a sleep()

Mnemosyne puede consolidar la memoria de trabajo en representaciones de vida más larga, lo cual es útil pero es una operación mutante. Antes de habilitar una consolidación automática agresiva, inspeccione lo que está siendo capturado en realidad, verifique que los turnos ordinarios no estén entrando a la memoria inesperadamente, verifique la eliminación de principio a fin y haga una copia de seguridad de la base de datos. Luego experimente con:

hermes mnemosyne sleep

Los cambios recientes de Mnemosyne hicieron el manejo de conflictos más conservador: la similitud semántica por sí sola ya no prueba que una memoria debería invalidar a otra, lo cual es exactamente la dirección en la que un sistema de memoria de agente duradero debería moverse, como se cubre en Bucles de memoria autorreforzados en agentes de IA.

Copia de seguridad antes de actualizaciones

Cree una exportación portable antes de cualquier cambio significativo:

hermes mnemosyne export \
  --output ~/mnemosyne-backup.json

Para instalaciones importantes, también copie la base de datos local o el directorio de datos antes de actualizaciones mayores. Mnemosyne 4.x es actualmente una línea de pre-lanzamiento, por lo que una actualización de versión mayor merece más precaución que una actualización de parche rutinaria.

Configuración final recomendada

Para una instalación de Hermes de larga ejecución donde la precisión de la memoria importa más que recordar todo, la configuración duradera es: almacenamiento local de Mnemosyne activado, recuperación automática activada, autoguardado de conversación desactivado, autoguardado de mensajes del asistente desactivado, registro de resultados de herramientas desactivado, recordado y olvido explícitos activados, supresión de autoeco activada, búsqueda de sesión activada, y revisión humana para escrituras sensibles deseable una vez que la ruta de aprobación esté probada. Eso hace que Mnemosyne funcione principalmente como un almacén de memoria a largo plazo curado en lugar de un archivo de transcripción: el objetivo no es hacer que Hermes recuerde todo lo que ha dicho alguna vez, sino hacerlo recordar las cosas que aún serán ciertas cuando comience la siguiente sesión. Si ejecuta varios perfiles con diferentes proveedores o políticas de retención, Configuración de producción de Hermes Agent cubre el cableado a nivel de perfil para mantenerlos consistentes.