Hermes Agent entra em dieta: como o layout v23 FTS reduz o state.db em até 78%

Se você usa o Hermes Agent há mais de algumas semanas, provavelmente já percebeu que ~/.hermes/hermes.db não para de crescer. O agente armazena cada mensagem, resultado de ferramenta e rastro de raciocínio para manter o contexto entre sessões. Mas a conta dessa memória era mais alta do que deveria — não por causa dos dados de chat em si, mas por causa de como os índices de busca os armazenavam.

Uma mudança recente incorporada na PR #65798 introduz o layout compacto v23 FTS. Em instalações pesadas, ele remove cerca de 75% da pegada do state.db e, em algumas cargas de trabalho intensivas em ferramentas, a redução chega perto de 78%. Os registros de conversa reais não são alterados; apenas os índices de busca ficam menores e mais inteligentes.

Neste artigo, vou explicar o que estava inchando o banco de dados, como o layout v23 resolve isso e exatamente o que você precisa fazer para se beneficiar.

Para contexto sobre a versão v0.19.0 mais ampla, veja nossas notas de lançamento da v0.19.0.

Por que o banco de dados estava crescendo tão rápido

O Hermes mantém o estado de longo prazo em um banco de dados SQLite em ~/.hermes/hermes.db. Cada mensagem é armazenada em uma tabela messages e indexada para busca de texto completo usando dois índices FTS5:

messages_fts — um índice com stemmer Porter para buscas em inglês
messages_fts_trigram — um índice de trigramas para busca de substrings CJK

Desde a migração do esquema v11, ambos os índices eram tabelas FTS5 inline. Isso significa que cada índice mantinha sua própria cópia privada de content || tool_name || tool_calls para cada mensagem. Os mesmos bytes eram armazenados três vezes: uma na tabela messages e uma em cada índice FTS.

Um exemplo real do issue #22478 mostrou a escala do problema:

Componente	Tamanho	% do BD
dados messages	99 MB	19,6%
dados sessions	45 MB	8,9%
índices FTS	358 MB	70,8%
Outros	3 MB	0,7%
Total	505 MB	100%

O índice de trigramas sozinho consumia 247 MB — 49% de todo o banco de dados — porque texto CJK gera muito mais tokens de trigrama que o inglês, e porque as linhas de saída de ferramentas (role=tool) também estavam sendo indexadas. A saída de ferramentas é majoritariamente payloads base64, dumps de arquivos e transcrições de delegação que ninguém pesquisa com consultas de substring CJK.

Isso não é apenas um problema de espaço em disco. Índices inline grandes também tornam as gravações mais lentas, mantêm bloqueios por mais tempo e podem saturar a E/S de disco durante sessões de gateway pesadas.

O que o layout v23 muda

O layout compacto v23 FTS faz três coisas:

Índices de conteúdo externo: os índices FTS5 não armazenam mais suas próprias cópias privadas do conteúdo das mensagens. Eles apontam para as colunas reais na tabela messages, eliminando a duplicação de 2–3x.
Índice de trigramas sem linhas de ferramentas: o índice de trigramas pula linhas onde role='tool'. Era aqui que a maior parte do inchaço residia, já que a saída de ferramentas normalmente representa ~90% dos bytes de mensagens em agentes ocupados.
Migração opcional: instalações existentes mantêm seu índice legacy funcionando exatamente como antes. Você só muda para o v23 quando executa hermes sessions optimize-storage.

A tabela messages permanece idêntica byte a byte. Seu histórico de chat, memória e sessões não são alterados. Apenas o armazenamento do índice de busca muda.

Os números: até 78% menor

A PR #65798 reporta validação tanto sintética quanto real:

Cenário	Antes	Depois
BD sintético de 30k mensagens, 60% linhas tool	463 MB	131 MB (28%)
Participação FTS nesse BD	~84%	~42%
Cópia real de 25 GB / 1,38M mensagens	25 GB	~10 GB

No banco de dados sintético, o banco encolhe de 463 MB para 131 MB — uma redução de 72%. Na cópia de produção real, a queda de 25 GB para ~10 GB é uma redução de 60%, com contagens de índice exatas e integridade FTS5 limpa. Em cargas de trabalho intensivas em ferramentas onde as linhas tool dominam, a economia pode chegar a 78% porque o índice de trigramas não armazena mais essas linhas.

Como migrar

Novas instalações criadas após essa mudança já nascem com o layout v23 automaticamente. Se você já está executando o Hermes, execute um único comando:

hermes sessions optimize-storage

O comando realiza uma operação deliberada em primeiro plano:

Verifica o espaço livre em disco antes de começar (recusa-se a executar se não houver espaço suficiente).
Rebaixa os índices legacy em tempo O(1).
Preenche os novos índices em blocos de 500 linhas, mantendo o ciclo de trabalho do bloqueio de gravação abaixo de 20% para que um gateway ou sessão CLI em execução permaneça responsivo.
Remove as tabelas shadow antigas em blocos.
Executa VACUUM para recuperar o espaço liberado.
Marca a nova versão do layout.

É seguro para Ctrl-C e retomável. Se você interromper, marcadores e resíduos são detectados na próxima execução, e o comando continua de onde parou. O agente também avisa se os resultados de busca estiverem incompletos durante a reconstrução, para não alucinar silenciosamente contexto ausente.

Se você estiver com pouco espaço em disco, pode pular a etapa de vacuum:

hermes sessions optimize-storage --no-vacuum

Após a atualização, hermes update exibe um aviso de uma linha sobre a otimização e o ganho de espaço esperado.

Quando você deve executá-lo?

Você deve executar hermes sessions optimize-storage se qualquer um destes se aplicar:

Seu ~/.hermes/hermes.db tem mais de algumas centenas de megabytes e a maior parte do tamanho são índices FTS.
Você executa um gateway com sessões longas e intensivas em ferramentas e nota picos de E/S de disco ou gravações lentas.
Você está em um VPS pequeno ou laptop com armazenamento limitado.
Você acabou de instalar o Hermes e quer confirmar que já está no layout v23.

Se você já está satisfeito com o desempenho e o uso de disco, pode esperar. O índice legacy continua funcionando; isso é uma otimização, não uma mudança que quebra compatibilidade.

E a qualidade da busca?

A mudança não remove conteúdo pesquisável do que você realmente pesquisa. Conversas e tool_calls/tool_name permanecem pesquisáveis através do índice de conteúdo externo. A busca de substring CJK em texto de conversa ainda funciona. A única diferença é que a busca de substring CJK dentro da saída de ferramentas recorre a uma consulta LIKE em vez do índice de trigramas — o que é aceitável, porque esse tipo de busca raramente é útil dentro de payloads base64 ou dumps de arquivos.

Uma revisão independente de @yoniebans em uma migração real v19→v23 confirmou que a impressão digital SHA-256 da tabela messages era idêntica antes e depois, e que as contagens de índice correspondiam exatamente.

Passos práticos

Verifique o tamanho atual do seu banco de dados:

ls -lh ~/.hermes/hermes.db

Atualize o Hermes para a versão mais recente que inclui o esquema v23:

hermes update

Execute a otimização:

hermes sessions optimize-storage

Verifique o tamanho após a conclusão:

ls -lh ~/.hermes/hermes.db

Se quiser recuperar ainda mais espaço de sessões antigas, combine a otimização com hermes sessions prune ou hermes memory clean — mas somente após fazer backup do que deseja manter.

Pontos principais

O state.db do Hermes Agent estava inchado por cópias duplicadas do índice FTS5, especialmente o índice de trigramas que indexava linhas de saída de ferramentas.
O layout compacto v23 FTS usa índices de conteúdo externo e para de indexar linhas de ferramentas para busca por trigramas, reduzindo o banco de dados em 60–78% dependendo da carga de trabalho.
Novas instalações recebem o novo layout automaticamente. Usuários existentes migram com hermes sessions optimize-storage.
A migração é retomável, segura para Ctrl-C e mantém seus dados de chat idênticos byte a byte.
A qualidade da busca é preservada; apenas a busca de substring CJK dentro da saída de ferramentas muda para um fallback LIKE.

Referências: