Mapa da trilha
Conteúdo detalhado
🏗️ Componentes Core
TUI, gateway de mensagens, toolsets e MCP.
Interface de terminal construída com Textual/Rich que renderiza markdown, código com syntax highlight, streaming token-a-token e suporta edição de prompts multilinha.
É o front-end primário do Hermes — entender a TUI elimina 80% do atrito diário e revela atalhos críticos como `/help`, `/clear`, `/cost`.
Render loop, autocomplete de slash-commands, histórico persistente em SQLite, paste detection automática, painel de tokens em tempo real.
Camada que normaliza entrada de CLI, Discord, Slack, webhook HTTP e cron em um único `Message` interno antes de invocar o LLM.
É a peça que permite "rodar o mesmo agente no Discord e no terminal" sem duplicar lógica.
Adapter pattern, fila assíncrona, idempotência por message_id, rate-limit por canal, fan-out de respostas.
Toolsets agrupam ferramentas relacionadas (filesystem, shell, web, code, memory) que podem ser habilitadas/desabilitadas via YAML.
Carregar tudo polui o contexto e degrada a qualidade. Toolsets cirúrgicos = respostas melhores.
Tool registry, JSON-schema dos parâmetros, permissões por toolset, lazy-load on-demand.
Model Context Protocol — padrão aberto da Anthropic que o Hermes consome como cliente, plugando servidores stdio ou HTTP.
Permite reutilizar centenas de servidores MCP existentes (GitHub, Notion, Postgres, Playwright) sem escrever código.
Transport (stdio/http), tool discovery, resources, prompts, sampling reverso.
Scheduler embutido que dispara prompts/ferramentas em cron-expressions sem depender do crontab do SO.
Habilita o agente a "trabalhar enquanto você dorme" — relatórios diários, monitoramento, recoleta de contexto.
APScheduler, persistência de jobs, timezone, retry com backoff, output para canal de saída.
`config.yaml` central que define provider, modelo, toolsets, MCPs, prompts de sistema e canais — versionável no git.
Tudo-como-código: você commita a configuração e qualquer máquina reproduz o mesmo agente.
Override por env-var (`${VAR}`), profiles (dev/prod), validação via Pydantic, hot-reload com `/reload`.
🧠 Loop de Aprendizado e Memória
Como o agente cria skills sozinho, memória curada, FTS5, Honcho, agentskills.io, providers.
Ciclo perceive→act→reflect→save que registra cada interação e extrai padrões reutilizáveis sem intervenção manual.
É o que diferencia o Hermes de um chat: ele fica mais útil a cada uso.
Reflection step, threshold de salvamento, skill candidates, anti-overfitting.
Armazenamento SQLite local com 3 camadas: conversa raw, fatos curados, skills.
Sem memória, todo dia é dia 1. Com memória, o agente lembra preferências e decisões.
TTL por camada, decaimento de relevância, pruning, exportação.
Full-Text Search 5 do SQLite — índice invertido com BM25, snippet e highlighting.
Permite "lembrar" sem precisar de Pinecone/embeddings caros — funciona offline.
Tokenizer porter, prefix queries, ranking BM25, virtual tables.
Agente detecta repetições, propõe uma skill (SKILL.md + scripts), você aprova ou edita.
Transforma "fiz 3x" em "agora é automático" sem você abrir editor.
Spec agentskills.io, frontmatter YAML, descrição trigger, isolamento por skill.
Engine de personalização que constrói um theory-of-mind do usuário a partir das conversas.
Personalização real sem prompt eterno: o agente sabe que você prefere Python tipado e PT-BR direto.
Dialectic agent, user representations, app/session/user namespacing.
Gateway HTTP que abstrai Anthropic, OpenAI, Google, Mistral, Meta, DeepSeek e modelos open-source sob a API OpenAI-compat.
Trocar Claude Sonnet por GPT-5 vira mudar 1 linha no YAML — sem reescrever código.
Roteamento por preço/latência, fallback automático, billing unificado, prompts caching cross-provider.
🔬 Anatomia de uma requisição (trace end-to-end)
Trace passo-a-passo de uma mensagem do Telegram até a resposta, com timing real de cada hop.
POST HTTPS do Telegram Bot API para o endpoint registrado em setWebhook, com payload JSON do update.
Único hop fora do seu controle — entender o budget de 5s do Telegram impede retry duplicado.
TLS keep-alive, secret_token, deduplicação por update_id, ack <5s, processamento async.
Normalização do update em Message interno + lookup do toolset/profile do usuário no registry.
Lookup remoto aqui é anti-padrão (200ms+); RAM-first mantém o hop trivial.
Adapter pattern, registry warm cache, lazy-load, /reload para refresh.
Monta o contexto para o LLM: últimas N mensagens, fatos via FTS5/BM25, user representation do Honcho, system prompts.
Hop mais variável — é onde caching, top-K e Honcho local/cloud mudam P95 em ordem de magnitude.
BM25 ranking, porter tokenizer, cache de user_repr (TTL 5min), prompt caching cross-provider.
Chamada ao provider via OpenRouter; latência = TTFT + (output_tokens / tokens_per_sec).
Hop dominante; escolher Haiku vs Sonnet vs Opus por intenção corta 60-80% de custo e latência.
TTFT P50 vs P99, cold-start em :free, router por intenção, streaming UX.
Quando o LLM retorna tool_calls, executor roda (em paralelo se independentes) e re-prompta o modelo com os outputs.
Cadeias de 3 tools = 10-18s reais; entender isso = não prometer "rápido" pro usuário.
asyncio.gather, paralelismo grátis se independente, streaming feedback intermediário.
sendMessage para o Telegram + INSERT em SQLite (com trigger FTS5) + enqueue de reflexão assíncrona.
Memory write NUNCA deve bloquear o usuário; reflection é background.
WAL mode, asyncio.create_task, editMessageText para streaming, retry exponencial em 429.
🛡️ Modelo de segurança e privacidade
Onde dados vivem, o que vaza, ameaças reais e hardening mínimo de produção.
Inventário de onde cada byte do Hermes vive (disco local, env, providers, Honcho) e quem pode ler.
Sem este mapa você não sabe o que vaza ao trocar de modelo ou habilitar Honcho cloud.
Local-first, redação PII pré-prompt, zero-retention SKUs, secret manager vs .env.
Catálogo priorizado: usuário malicioso, conteúdo web envenenado, skill maliciosa, provider comprometido.
Sem threat model concreto, "segurança" vira teatro — você protege o que não é alvo e ignora o alvo real.
Probabilidade × impacto, isolamento por session_id, rate-limit por user, allowlist por toolset.
Instruções escondidas em conteúdo que o agente lê (HTML invisível, comentários em código, metadados).
Mesmo modelos fortes obedecem em ~20% dos casos — defesa em camadas, não confiança no LLM.
Tags untrusted_content, strip de HTML invisível, allowlist de domínios, scanner de exfiltration.
Read tool pega segredo, write tool manda para fora — Tool Gateway tem que quebrar essa cadeia.
É o vetor mais explorado em 2025 contra agentes autônomos — vale mais que qualquer SAST.
Separation of duties, profiles read-only vs write, allowlist em web_fetch, deny em paths sensíveis.
SKILL.md + scripts arbitrários instalados de repos externos rodam com suas permissões.
Typosquat e payloads em postinstall.sh já aconteceram — npm/pypi-style de risco no Hermes.
Audit manual + grep de payload, sandbox VM, pin por commit SHA, kill-switch no YAML.
Config mínima de produção: firejail/bubblewrap, egress filtrado, audit log append-only.
Sem isso, incident response é "rezar e rotacionar tudo" — com isso, blast-radius é contível.
chattr +a, caps drop, seccomp, network namespace, aprovação humana para tools críticas.