Hermes Agent se pone a dieta: cómo el diseño v23 FTS reduce state.db hasta un 78%

Si has estado usando Hermes Agent durante más de unas semanas, probablemente habrás notado que ~/.hermes/hermes.db no para de crecer. El agente almacena cada mensaje, resultado de herramienta y traza de razonamiento para mantener el contexto entre sesiones. Pero la factura por esa memoria era más alta de lo que debería — no por los datos de chat en sí, sino por cómo los índices de búsqueda los almacenaban.

Un cambio reciente incorporado en el PR #65798 introduce el diseño compacto v23 FTS. En instalaciones con mucho uso elimina alrededor del 75% de la huella de state.db, y en cargas de trabajo intensivas en herramientas la reducción se acerca al 78%. Los registros de conversación reales no se tocan; solo los índices de búsqueda se vuelven más pequeños e inteligentes.

En este artículo explicaré qué estaba hinchando la base de datos, cómo lo soluciona el diseño v23 y exactamente qué necesitas hacer para beneficiarte de ello.

Para contexto sobre la versión v0.19.0 en general, consulta nuestras notas de lanzamiento de v0.19.0.

Por qué la base de datos crecía tan rápido

Hermes guarda el estado a largo plazo en una base de datos SQLite en ~/.hermes/hermes.db. Cada mensaje se almacena en una tabla messages y se indexa para búsqueda de texto completo usando dos índices FTS5:

messages_fts — un índice con stemmer Porter para búsquedas en inglés
messages_fts_trigram — un índice de trigramas para búsqueda de subcadenas CJK

Desde la migración del esquema v11, ambos índices eran tablas FTS5 inline. Eso significa que cada índice mantenía su propia copia privada de content || tool_name || tool_calls para cada mensaje. Los mismos bytes se almacenaban tres veces: una en la tabla messages y una en cada índice FTS.

Un caso real del issue #22478 mostró la magnitud del problema:

Componente	Tamaño	% de la BD
datos de messages	99 MB	19,6%
datos de sessions	45 MB	8,9%
índices FTS	358 MB	70,8%
Otros	3 MB	0,7%
Total	505 MB	100%

El índice de trigramas por sí solo consumía 247 MB — el 49% de toda la base de datos — porque el texto CJK genera muchos más tokens de trigrama que el inglés, y porque las filas de salida de herramientas (role=tool) también se estaban indexando. La salida de herramientas suele ser payloads base64, volcados de archivos y transcripciones de delegación que nadie busca con consultas de subcadenas CJK.

Esto no es solo un problema de espacio en disco. Los índices inline grandes también ralentizan las escrituras, mantienen los bloqueos por más tiempo y pueden saturar la E/S de disco durante sesiones de gateway pesadas.

Qué cambia el diseño v23

El diseño compacto v23 FTS hace tres cosas:

Índices de contenido externo: los índices FTS5 ya no almacenan sus propias copias privadas del contenido de los mensajes. Apuntan a las columnas reales en la tabla messages, eliminando la duplicación de 2–3x.
Índice de trigramas sin filas de herramientas: el índice de trigramas omite las filas donde role='tool'. Aquí es donde residía la mayor parte de la hinchazón, ya que la salida de herramientas suele representar ~90% de los bytes de mensajes en agentes ocupados.
Migración opcional: las instalaciones existentes mantienen su índice legacy funcionando exactamente igual que antes. Solo cambias a v23 cuando ejecutas hermes sessions optimize-storage.

La tabla messages permanece idéntica a nivel de bytes. Tu historial de chat, memoria y sesiones no se tocan. Solo cambia el almacenamiento del índice de búsqueda.

Los números: hasta un 78% más pequeño

El PR #65798 reporta validación tanto sintética como en entornos reales:

Escenario	Antes	Después
BD sintética de 30k mensajes, 60% filas tool	463 MB	131 MB (28%)
Proporción FTS de esa BD	~84%	~42%
Copia real de 25 GB / 1,38M mensajes	25 GB	~10 GB

En la base de datos sintética, la base se reduce de 463 MB a 131 MB — una reducción del 72%. En la copia de producción real, la caída de 25 GB a ~10 GB es una reducción del 60%, con conteos de índice exactos e integridad FTS5 limpia. En cargas de trabajo con muchas herramientas donde dominan las filas tool, el ahorro puede alcanzar el 78% porque el índice de trigramas ya no almacena esas filas en absoluto.

Cómo activarlo

Las nuevas instalaciones creadas después de este cambio nacen con el diseño v23 automáticamente. Si ya tienes Hermes en marcha, ejecuta un solo comando:

hermes sessions optimize-storage

El comando realiza una operación en primer plano deliberada:

Verifica el espacio libre en disco antes de empezar (se niega a ejecutarse si no hay suficiente espacio).
Degrada los índices legacy en tiempo O(1).
Rellena los nuevos índices en bloques de 500 filas, manteniendo el ciclo de trabajo del bloqueo de escritura por debajo del 20% para que un gateway o sesión CLI en vivo siga respondiendo.
Elimina las tablas shadow antiguas por bloques.
Ejecuta VACUUM para recuperar el espacio liberado.
Sella la nueva versión del diseño.

Es seguro frente a Ctrl-C y reanudable. Si lo interrumpes, los marcadores y residuos se detectan en la siguiente ejecución, y el comando retoma donde lo dejó. El agente también te avisa si los resultados de búsqueda están incompletos durante la reconstrucción, para que no alucine silenciosamente contexto faltante.

Si te falta espacio en disco, puedes omitir el paso de vacuum:

hermes sessions optimize-storage --no-vacuum

Después de actualizar, hermes update muestra un aviso de una línea sobre la optimización y la ganancia de espacio esperada.

¿Cuándo deberías ejecutarlo?

Deberías ejecutar hermes sessions optimize-storage si se aplica alguno de estos casos:

Tu ~/.hermes/hermes.db supera unos cientos de megabytes y la mayor parte del tamaño son índices FTS.
Ejecutas un gateway con sesiones largas e intensivas en herramientas y notas picos de E/S de disco o escrituras lentas.
Estás en un VPS pequeño o portátil con almacenamiento limitado.
Acabas de instalar Hermes y quieres confirmar que ya estás en el diseño v23.

Si ya estás satisfecho con el rendimiento y el uso de disco, puedes esperar. El índice legacy sigue funcionando; esto es una optimización, no un cambio disruptivo.

¿Qué pasa con la calidad de búsqueda?

El cambio no elimina contenido buscable de nada que realmente busques. Las conversaciones y tool_calls/tool_name siguen siendo buscables a través del índice de contenido externo. La búsqueda de subcadenas CJK en texto de conversación sigue funcionando. La única diferencia es que la búsqueda de subcadenas CJK dentro de la salida de herramientas recurre a una consulta LIKE en lugar del índice de trigramas — lo cual está bien, porque ese tipo de búsqueda rara vez es útil dentro de payloads base64 o volcados de archivos.

Una revisión independiente de @yoniebans en una migración real v19→v23 confirmó que la huella SHA-256 de la tabla messages era idéntica antes y después, y que los conteos de índices coincidían exactamente.

Pasos prácticos

Comprueba el tamaño actual de tu base de datos:

ls -lh ~/.hermes/hermes.db

Actualiza Hermes a la última versión que incluya el esquema v23:

hermes update

Ejecuta la optimización:

hermes sessions optimize-storage

Verifica el tamaño después de que termine:

ls -lh ~/.hermes/hermes.db

Si alguna vez quieres recuperar más espacio de sesiones antiguas, combina la optimización con hermes sessions prune o hermes memory clean — pero solo después de hacer copia de seguridad de lo que quieras conservar.

Puntos clave

El state.db de Hermes Agent estaba hinchado por copias duplicadas del índice FTS5, especialmente el índice de trigramas que indexaba filas de salida de herramientas.
El diseño compacto v23 FTS usa índices de contenido externo y deja de indexar filas de herramientas para búsqueda por trigramas, reduciendo la base de datos entre un 60–78% según la carga de trabajo.
Las nuevas instalaciones obtienen el nuevo diseño automáticamente. Los usuarios existentes lo activan con hermes sessions optimize-storage.
La migración es reanudable, segura frente a Ctrl-C y mantiene tus datos de chat idénticos a nivel de bytes.
La calidad de búsqueda se preserva; solo la búsqueda de subcadenas CJK dentro de la salida de herramientas pasa a un fallback LIKE.

Referencias: