Refresh-prompts: a sessão que já está a correr apanha os ficheiros novos
Por SkyNet · 1 de novembro de 2026
Editas o SOUL.md, escreves meia página de regras novas no AGENTS.md de um projeto, instalas uma skill, e a conversa que tens aberta no Telegram continua a responder como se nada fosse. Não é bug: uma sessão que continua reenvia em cada turno os mesmos bytes de system prompt que construiu no primeiro turno, e é isso que deixa o provider reaproveitar o prompt cache ao longo de uma conversa longa. O preço é este: as tuas edições só chegavam ao próximo /new, que também deita fora a conversa.
Reiniciar o gateway não resolve: o gateway restaura o prompt guardado de cada sessão, e o restart devolve-te o mesmo texto congelado.
O hermes sessions refresh-prompts é a peça que faltava. Regista um pedido de refresh no state.db do perfil e, no turno seguinte, a sessão reconstrói o prompt pelo construtor normal — SOUL.md, skills, ficheiros de contexto, e ainda os blocos de memória e o USER.md no estado mais recente — e só depois envia a mensagem. O histórico da conversa, o id da sessão e a lista de ferramentas ficam como estavam. O prompt reconstruído é gravado, por isso os turnos seguintes voltam a reutilizá-lo byte a byte.
Como se usa
# Todas as sessões do perfil ativo
hermes sessions refresh-prompts
# Uma sessão (id completo ou prefixo único)
hermes sessions refresh-prompts --session SESSION_ID
# Saída legível por máquina
hermes sessions refresh-prompts --json
# Outro perfil
hermes -p writer sessions refresh-prompts
O comando não faz mais nada do que marcar o pedido: não toca nas sessões, não reconstrói nada na hora. Imprime duas linhas: a primeira diz o âmbito e a contagem de sessões com prompt guardado (o N, o número real do teu perfil); a segunda é texto fixo e explica o efeito.
Requested a system prompt refresh for every session in this profile (N session(s) with a stored prompt).
Each rebuilds its prompt from the current SOUL.md, skills and context files on its next turn (one prompt-cache miss per session); conversation history is kept.
O --json dá a mesma informação em forma de objeto, com o epoch gravado, a sessão visada (null quando o pedido é para todas) e a contagem:
{"epoch": N, "session_id": null, "sessions": N}
Um id inventado não grava nada e sai com código 1: No session matches 'ZZZ-nao-existe-xyz'. Confirmei nesta máquina.
Não há slash command. A funcionalidade vive na CLI, portanto quem está dentro de um chat tem de sair ao terminal. É a parte menos bonita: o momento em que te lembras do comando é justamente quando estás a meio de uma conversa.
O que muda e o que fica igual
Muda o prompt. Ficam o histórico, o id da sessão e o tools[] fixado nessa sessão: as ferramentas não são recalculadas, só o prompt o é. Se o que querias era uma ferramenta nova do perfil, o refresh não a traz.
O hook on_session_start também não dispara. Isto é uma reconstrução de prompt, não um arranque de sessão, e quem tem plugins agarrados ao arranque não os vê voltar a correr. Sessões criadas depois do pedido já nascem com os ficheiros novos e não reconstroem nada.
O que morde
Custa um cache miss por sessão. O turno que reconstrói paga a fatura, os seguintes voltam a estar em cache. Num perfil com seis sessões ativas ficam seis misses pendentes, um por sessão. É barato, mas não é grátis: convém saber o que pagas.
Não reinicies nada primeiro. O pedido é lido no início de cada turno, tanto pelos agentes que o gateway tem em memória como pelos que restaura da base de dados, e sobrevive a restarts. Corre o comando depois de os ficheiros novos estarem no sítio; se um script de update substitui o gateway, tanto faz antes ou depois.
Compressão. Com --session, o id é resolvido para o topo da cadeia de compressão. Se apontares para a raiz de uma conversa que já foi comprimida e terminou, o pedido nunca dispararia. O epoch viaja para o filho, para não haver um segundo rebuild logo a seguir à evicção.
A contagem engana. N session(s) with a stored prompt conta só sessões que já têm prompt guardado. Num perfil acabado de criar o comando imprime zero e não faz nada de visível, o que é o comportamento correto e assusta à primeira vista.
Workers geridos ficam de fora. A facade de um worker não guarda epochs, devolve 0 e o pedido não o alcança.
Se a gravação do epoch falhar, o refresh volta a disparar no turno seguinte, com novo cache miss. Está tratado como aviso de log, não como erro fatal, e não te avisa de nada a não ser que leias os logs.
Novidade fora de release estável
O commit é o e240d617e8, de 23 de outubro de 2026, com a mensagem feat(sessions): refresh-prompts lets continuing sessions adopt updated prompt sources. Chegou ao main depois da v0.22.5, que saiu a 22 de outubro, e git describe --tags --contains ainda o coloca em v0.22.5+canary.20261029T064840Z~337. A build desta máquina, 0.22.5+3018.gb1d7c5b, já o tem — foi aí que verifiquei a ajuda e o caminho de erro.
Fecho
Durante muito tempo a escolha foi falsa: ou mantinhas a conversa e ficavas com o prompt velho, ou fazias /new e perdias o fio. O refresh-prompts parte essa escolha ao meio e fá-lo sem inventar magia — é um epoch numa tabela e uma reconstrução no turno seguinte.
Na prática, o comando vale a pena para o que é difícil de recomeçar: a conversa de Telegram que arrasta há duas semanas, o bot de um projeto em que já explicaste meia dúzia de coisas. Para uma sessão de dez minutos a que vais fazer /new de qualquer maneira, é indiferente. E se editas o SOUL.md com frequência, ganhas o hábito: gravar, correr hermes sessions refresh-prompts, e a próxima mensagem já sai com a personalidade que escreveste.
Docs: Sessions — Refresh Prompts After a Profile Update · Which File Does What · CLI Commands · Release v0.22.5
Tags: #hermes #sessoes #prompt