Hermes sessions: canais, handoff, resume e switch entre CLI e Telegram

O mapa que separa sessão, canal, tópico, thread, title, session_id e home channel — para você dominar o Hermes sem confundir roteamento com contexto.

A ideia central é simples, mas o Hermes tem várias camadas: a sessão real mora no banco SQLite, o gateway mantém um índice de roteamento ativo e cada plataforma decide como isolar contexto com base em DM, grupo, thread ou tópico. Quando isso fica claro, você entende duas coisas importantes: o que é “a conversa” de verdade e o que é só o lugar onde ela está sendo acessada.

Fontes usadas nesta página

Esta página foi construída combinando help real do Hermes, documentação oficial e código-fonte local do repositório. A documentação oficial foi tratada como fonte de verdade; o código serviu para confirmar detalhes de implementação e limites práticos.

• hermes --help
• hermes sessions --help
• hermes version
• Docs oficiais: /docs/user-guide/sessions, /docs/reference/slash-commands e /docs/user-guide/messaging/telegram
• Código local: gateway/session.py, gateway/slash_commands.py, hermes_cli/commands.py e hermes_state.py

Help real desta instalação

$ hermes version
Hermes Agent v0.16.0 (2026.6.5) · upstream 86f2946f
Project: /home/hermes/.hermes/hermes-agent
Python: 3.11.15
OpenAI SDK: 2.24.0
Up to date

$ hermes sessions --help
usage: hermes sessions [-h]
                       {list,export,delete,prune,optimize,repair,stats,rename,browse}
                       ...

O modelo mental certo

Para virar especialista em sessions no Hermes, vale separar cinco conceitos:

A pegadinha clássica é confundir session_id com chat. Um chat do Telegram pode apontar para uma sessão. Um tópico novo pode apontar para outra. E a CLI pode retomar uma sessão criada originalmente no Telegram, desde que esteja olhando para o mesmo perfil e para o mesmo banco de sessões.

As camadas de armazenamento

A documentação oficial de sessions e o código da camada de estado convergem para este desenho:

Trecho estrutural documentado do banco

~/.hermes/state.db
├── sessions
├── messages
├── messages_fts
├── messages_fts_trigram
├── state_meta
└── schema_version

Em outras palavras: se você quer procurar, exportar, renomear, retomar ou analisar histórico, pense primeiro em state.db. Se você quer entender por que uma mensagem nova caiu numa sessão específica, pense em session_key + sessions.json.

O que realmente entra em contexto

A documentação oficial faz uma distinção importante: o Hermes salva a história inteira, mas não reenvia “todos os bytes de tudo” em cada turno. O modelo recebe o prompt de sistema, a janela ativa da conversa e o que o Hermes injetar explicitamente naquele turno. Arquivos, áudio, imagens e ferramentas podem deixar rastros textuais na sessão, mas não ficam sendo replayados integralmente para sempre.

Isso explica por que uma sessão longa ainda pode ser retomada sem necessariamente carregar a mídia original inteira, e também por que /compress existe: o custo explode mais por texto verboso do que por “existência histórica” da sessão no banco.

Como o gateway decide qual sessão usar

O arquivo gateway/session.py é a referência principal da implementação. Ele constrói uma session key determinística a partir da origem da mensagem. É isso que diz se duas mensagens entram na mesma sessão ou não.

Trecho essencial da lógica em gateway/session.py

DM:
  agent:main:<platform>:dm:<chat_id>
  agent:main:<platform>:dm:<chat_id>:<thread_id>

Group/channel:
  agent:main:<platform>:<chat_type>:<chat_id>:<user_id>

Thread/topic compartilhado:
  agent:main:<platform>:<chat_type>:<chat_id>:<thread_id>

session_id, title e lineage

O session_id é a identidade técnica da conversa. O title é a identidade humana. E o lineage aparece quando uma conversa vira continuação de outra, especialmente após compressão ou branching.

• /title Meu Projeto atribui um nome humano.
• hermes -c "Meu Projeto" retoma a mais recente naquela linhagem.
• Quando há compressão e continuação, o Hermes cria títulos como Meu Projeto #2, #3 etc.
• O banco tem parent_session_id justamente para representar essa cadeia.

Canais, chats e home channel

“Canal” no Hermes não significa “a sessão mora ali”. Significa onde o gateway entrega mensagens por padrão. Isso aparece em cron jobs, em envios automáticos e no handoff da CLI para uma plataforma de mensageria.

No Telegram, você define isso com /sethome. Em seguida, a CLI pode usar esse destino para fazer /handoff telegram. Em plataformas com threads, o gateway tenta criar uma thread/tópico novo para receber a continuação da mesma sessão.

Como trabalhar com sessões na CLI

A CLI é a superfície mais completa para curadoria de histórico e retomada explícita. O help e a docs oficiais expõem três caminhos principais: continuar, resumir e navegar.

Telegram: DMs, tópicos e multi-session mode

O Telegram é a superfície mais rica para entender o conceito de “uma conta, várias sessões”. A documentação oficial descreve dois mecanismos diferentes:

1. extra.dm_topics: tópicos declarados pelo operador em config.yaml.
2. /topic: modo multi-session dirigido pelo usuário dentro da DM.

1) DM topics configurados pelo operador

Aqui o administrador declara tópicos fixos no Telegram DM. Cada um ganha thread_id e vira uma sessão isolada com chave do tipo:

agent:main:telegram:dm:<chat_id>:<thread_id>

Isso é ótimo para workspaces permanentes como Research, Website ou General, inclusive com skill auto-carregada por tópico.

2) /topic: multi-session DM mode

Este é o modo “ChatGPT-style multi-session DM” documentado nas docs do Telegram do Hermes. O usuário ativa com /topic dentro da DM do bot, e dali em diante pode criar vários tópicos paralelos. Cada tópico é uma sessão independente.

Quando esse modo está ativo, a DM raiz vira um lobby de sistema: comandos como /status e /help continuam funcionando, mas prompts normais são rejeitados e você é empurrado para All Messages / tópicos. Isso é proposital: o objetivo é evitar que a conversa principal “vaze” para fora dos workspaces paralelos.

Dá para levar uma sessão da CLI para o Telegram?

Sim. Esta é a funcionalidade oficial de cross-platform handoff documentada em /docs/user-guide/sessions.

O fluxo oficial é:

1. você está numa sessão ativa da CLI;
2. roda /handoff telegram;
3. a CLI verifica se o gateway está rodando e se o Telegram tem home channel configurado;
4. o gateway cria um novo tópico/thread quando a plataforma suporta isso;
5. o destino é reamarrado ao mesmo session_id;
6. o Hermes injeta uma mensagem sintética de confirmação e continua lá.

Resumo operacional do handoff descrito na docs

/handoff telegram
→ valida plataforma + home channel
→ marca a sessão como pending
→ gateway cria thread/tópico no destino
→ rebinda o destino ao mesmo session_id
→ responde no novo lugar
→ CLI sai com dica de /resume

Então, para CLI → Telegram, a resposta é: sim, nativamente, com preservação do session_id.

E há um detalhe importante que a prática mostra: mesmo se você esquecer de fazer o handoff, ainda consegue trazer a sessão da CLI para o Telegram depois, porque o gateway pode rebinder o chat atual para um session_id já existente.

Receita prática: listar chamados na sessão nova e continuar no Telegram

Se a sua ideia é abrir uma sessão nova só para listar chamados, identificar o que importa e depois continuar no Telegram, o fluxo mais limpo é este:

1. na CLI/TUI, abra uma sessão nova com /new;
2. opcionalmente, dê um título cedo com /title chamados-hoje ou outro nome curto e único;
3. peça ao Hermes para listar os chamados e ajudar a identificar quais você quer tratar;
4. quando a resposta terminar, rode /handoff telegram;
5. no Telegram, continue no tópico/thread criado pelo gateway.

Fluxo recomendado para esse caso

/new
/title chamados-hoje

# depois de listar e identificar os chamados:
/handoff telegram

Na prática, isso significa que o Telegram não recebe só um resumo. Ele passa a apontar para a mesma sessão persistida em state.db. Então a conversa sobre a lista de chamados, o raciocínio usado para separar os itens e as respostas anteriores continuam disponíveis como histórico daquela sessão.

Se você abrir a sessão no Desktop, o modelo de persistência continua o mesmo, mas a rota documentada de forma explícita e auditável para levar a conversa ao Telegram nesta instalação continua sendo a da CLI/TUI com /handoff telegram. Se preferir operar a partir do Telegram depois, mas não quiser depender do handoff naquele momento, o caminho manual continua válido: /sessions all + /resume <session_id>.

E se eu esquecer o handoff?

Você ainda consegue “capturar” no Telegram uma sessão que começou na CLI. Esse ponto não é um handoff formal disparado pela CLI; é um rebind manual via comandos de sessão do gateway.

O fluxo prático mais confiável é:

1. no Telegram, abra o chat ou tópico onde quer continuar a conversa;
2. rode /sessions all para listar sessões de todas as superfícies, não apenas do Telegram;
3. se a sessão da CLI estiver sem título, use /sessions all full para incluir sessões sem nome;
4. copie o session_id da sessão desejada;
5. rode /resume <session_id> nesse mesmo chat/tópico;
6. o gateway troca o mapeamento do chat atual para aquela sessão persistida.

Captura manual de sessão da CLI no Telegram

/sessions all
# se não aparecer, tente:
/sessions all full

/resume <session_id>

Isso funciona porque o gateway aceita /resume <session_id> diretamente e, ao resolver a sessão-alvo, regrava a associação da origem atual para aquele session_id. Em paralelo, o parser de /sessions permite o modo all, que amplia a listagem para todas as sources e não só para a plataforma corrente.

O que o teste real de handoff mostrou

Além da leitura de docs e código, houve uma validação prática nesta instalação com duas sessões nomeadas test-chat e test-telegram. O ponto mais útil do teste foi separar o que o Telegram diz ao usuário do que fica gravado em state.db.

Na própria conversa do Telegram, o bot afirmou que aquele chat era a continuação de test-chat vinda do CLI/TUI. Isso combina com o banco: a leitura mais provável é que o Telegram tenha passado a apontar para o mesmo session_id de test-chat, enquanto a sessão local do lane Telegram foi finalizada com session_switch.

O mesmo teste também ajudou a interpretar ended_at: ele não significa “sessão de Telegram” ou “sessão de CLI” por si só. Significa apenas que aquela linha da tabela sessions foi finalizada. O que muda por superfície é o evento que dispara esse encerramento.

Limite atual do /sessions no Telegram

A validação prática mostrou outro limite importante: no gateway/Telegram, as listagens de sessão retornam no máximo 10 itens por chamada. Isso vale para:

• /sessions
• /sessions all
• /sessions full
• /sessions all full

Os modificadores all e full mudam o filtro, mas não removem o cap:

• all amplia a busca para outras sources;
• full inclui sessões sem título;
• nenhum deles pagina ou aumenta a quantidade.

Isso foi confirmado no código local do gateway: gateway/slash_commands.py chama query_session_listing(..., limit=10), e hermes_cli/session_listing.py interrompe a coleta quando atinge esse teto. Então, hoje, a leitura correta é: Telegram mostra o top 10 conforme o filtro escolhido, não “todas as sessões”.

Listagem prática por canal

Para reconciliação rápida entre Desktop, CLI/TUI e Telegram, o formato mais útil nesta instalação passou a ser uma listagem minimalista por canal: apenas nome — id, seguida de um resumo final. O helper operacional criado para isso lê diretamente o state.db e separa cli, tui e telegram.

Script operacional

/home/hermes/scripts/hermes-sessions-by-source.py

Por padrão, ele mostra sessões raiz e já sai no formato preferido para consulta humana e copy/paste.

$ /home/hermes/scripts/hermes-sessions-by-source.py --no-color
CLI
- hermes chats - sessoes — 20260618_081507_004727
- restart hermes desktop — 20260614_101607_ddd7be

TUI
- test-chat — 20260618_140459_664514

TELEGRAM
- test-telegram — 20260618_061247_fef4ba8b

RESUMO
- cli: 3
- tui: 12
- telegram: 4
- não-telegram: 15
- total: 19

Quando você precisa enxergar continuações/filhas além das raízes, use --all. Quando precisa depurar mais detalhes, use --detailed. Mas, para operação diária, o padrão minimalista costuma ser o mais claro.

Dá para voltar do Telegram para a CLI?

Sim, mas o caminho é diferente. Hoje não existe um /handoff cli documentado para ser rodado no Telegram. O que existe é a possibilidade de a CLI retomar a mesma sessão persistida no banco.

Em termos práticos, o retorno é assim:

1. você descobre o título ou, de preferência, o session_id da conversa;
2. na CLI, usa hermes -r <session_id>, hermes -c <título> ou /resume <título>;
3. a CLI carrega a conversa do mesmo state.db e continua dali.

Teste real desta instalação: retomando na CLI uma sessão que nasceu no Telegram

$ hermes chat -q 'Responda apenas com o session_id atual.' --resume 20260617_112852_340d6c01 -Q --pass-session-id
↻ Resumed session 20260617_112852_340d6c01 "Uso Codex Michel" (4 user messages, 89 total messages)

20260617_112852_340d6c01

O que usar para “switch” na prática

Se a sua meta é ser rápido operando sessões, use esta matriz mental:

Existem slash commands na CLI e no Telegram?

Sim, nos dois. A docs oficial de slash commands e o arquivo hermes_cli/commands.py deixam isso explícito: o Hermes tem duas superfícies de slash command, ambas derivadas de um COMMAND_REGISTRY central.

• CLI slash commands → despachados pela CLI, com autocomplete.
• Messaging slash commands → despachados pelo gateway, com ajuda e menus por plataforma.

Trecho real do registro central

CommandDef("new", ... aliases=("reset",))
CommandDef("topic", ... gateway_only=True)
CommandDef("handoff", ... cli_only=True)
CommandDef("sethome", ... gateway_only=True)
CommandDef("resume", ...)
CommandDef("sessions", "Browse and resume previous sessions", "Session")

O que o Telegram tem a mais em relação à CLI

O Telegram não é só “um cliente remoto”. Na prática, ele adiciona capacidades próprias de organização de sessão:

• tópicos privados em DM;
• multi-session mode via /topic;
• root DM como lobby de sistema;
• home channel e thread de cron;
• restituição de sessão antiga em um tópico com /topic <session-id>.

Em contrapartida, a CLI continua sendo o ambiente mais forte para navegação profunda, export, prune, rename e retomada manual precisa.

Pitfalls e limites reais

1. Mesmo perfil importa. As sessões vivem dentro do home do perfil ativo. Se você mudar de profile, está olhando outro universo de sessões.
2. Home channel não é session store. Ele ajuda em entrega e handoff, mas o histórico verdadeiro continua no banco.
3. /handoff não é bidirecional via comando. O fluxo oficial é sair da CLI para uma plataforma; a volta é por resume.
4. Esquecer o handoff não mata a continuidade. Você ainda pode rebinder o Telegram para a sessão da CLI com /sessions all + /resume <session_id>.
5. /sessions no Telegram não é listagem completa. Hoje o gateway corta em 10 resultados por chamada, mesmo com all e full.
6. resume por ID depende do mesmo perfil. Se você mudar de profile, muda o universo de sessões disponíveis.
7. Thread e group não se comportam igual. Em geral, thread/tópico tende a ser compartilhado; grupo sem thread tende a isolar por usuário.
8. /topic é específico do Telegram DM. Não confundir com threads de Discord ou Slack.
9. /topic <session-id> não é sinônimo de “puxar qualquer sessão”. Nas docs, ele é focado em restaurar sessão anterior dentro do topic mode do Telegram.
10. Compressão não é deleção. Ela cria continuidade de sessão; não apaga o histórico do banco.
11. source não é “canal atual”. No banco, ele marca onde a sessão nasceu; depois um handoff/rebind pode atendê-la em outra superfície.

Receitas rápidas de especialista

Levar trabalho da CLI para o Telegram

1. No Telegram, rode /sethome no destino.
2. Garanta que o gateway está rodando.
3. Na CLI, durante a sessão ativa, rode /handoff telegram.
4. Continue no novo tópico/thread criado pelo gateway.

Capturar no Telegram uma sessão da CLI quando você esqueceu o handoff

1. No Telegram, abra o chat ou tópico onde quer continuar.
2. Rode /sessions all.
3. Se a sessão da CLI não aparecer, rode /sessions all full.
4. Lembre que a listagem do Telegram para em 10 itens; se ainda não aparecer, confirme pela CLI/Desktop.
5. Copie o session_id da sessão certa.
6. Rode /resume <session_id>.
7. Continue dali no Telegram: o chat atual passa a apontar para essa sessão.

Voltar para a CLI depois de continuar no Telegram

1. No Telegram, confirme o título da sessão com /title ou liste com /sessions.
2. Na CLI, use hermes -c "título" ou hermes -r <session_id>.
3. Se quiser outra conversa paralela, não dê reset na atual: abra outro tópico no Telegram ou use outro resume na CLI.

Operar vários projetos paralelos no Telegram

1. Na DM do bot, ative /topic.
2. Crie um tópico por projeto.
3. Use /new apenas para resetar o tópico atual; para trabalho paralelo, prefira criar outro tópico.

Veredito direto

Se eu resumisse tudo em uma frase operacional, seria esta: o Hermes separa persistência, roteamento e superfície. O banco SQLite guarda a verdade da sessão; o gateway mapeia chats/tópicos para essa verdade; CLI e Telegram são maneiras diferentes de entrar na mesma infraestrutura.

Então, respondendo de forma objetiva ao que você queria validar:

• Sessions no Hermes existem de verdade como objeto persistido, não só como “histórico visual”.
• Canais e tópicos influenciam roteamento, não substituem a sessão canônica.
• CLI → Telegram: sim, com /handoff telegram.
• Esqueceu o handoff? Ainda assim dá para capturar no Telegram uma sessão da CLI com /sessions all + /resume <session_id>.
• /sessions no Telegram tem cap prático de 10 itens; all e full mudam o filtro, não a quantidade.
• source no banco indica origem, não necessariamente a superfície atual depois do handoff.
• Resume por ID: sim, nesta instalação, para sessões de cli, tui e telegram no mesmo perfil / mesmo state.db.
• Telegram → CLI: sim, por resume na CLI; não via um /handoff cli simétrico.
• Slash commands existem na CLI e no Telegram.
• “Switch” existe, mas em dois sentidos: switch de sessão local e switch de superfície/plataforma.

Fontes finais e referências de código

• Docs oficiais: https://hermes-agent.nousresearch.com/docs/user-guide/sessions
• Docs oficiais: https://hermes-agent.nousresearch.com/docs/reference/slash-commands
• Docs oficiais: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram
• Código: /home/hermes/.hermes/hermes-agent/gateway/session.py
• Código: /home/hermes/.hermes/hermes-agent/gateway/slash_commands.py
• Código: /home/hermes/.hermes/hermes-agent/hermes_cli/commands.py
• Código: /home/hermes/.hermes/hermes-agent/hermes_cli/session_listing.py
• Código: /home/hermes/.hermes/hermes-agent/hermes_state.py