Módulo 2.2 - Loop de Aprendizado e Memória

🔁 Loop fechado

O Hermes implementa um ciclo perceive → act → reflect → save. A diferença vs um chat clássico está no reflect: após uma sequência de ações, um passo curto (modelo barato, <1k tokens) avalia "isso que acabei de fazer vale ser lembrado?" — e só então grava na memória.

💡 O ciclo em detalhes

•Perceive: recebe a Message, carrega contexto relevante da memória (top-K via FTS5 + user-rep do Honcho)
•Act: LLM principal escolhe tools, executa, responde
•Reflect: modelo barato (Haiku 4.5 / GPT-5-mini) lê o turno e produz JSON com facts_to_save, skill_candidate, user_signals
•Save: persistência seletiva — fatos vão p/ memória, skill candidates ficam pendentes de aprovação, signals atualizam o Honcho

┌───────────┐
│  Message  │ ─┐
└───────────┘  │
               ▼
       ┌───────────────┐     ┌────────────────────┐
       │   Perceive    │ ◀── │  Memory (FTS5)     │
       │ (recall top-K)│ ◀── │  Honcho user-rep   │
       └───────┬───────┘     └────────────────────┘
               ▼
       ┌───────────────┐
       │     Act       │  (tools + LLM principal)
       └───────┬───────┘
               ▼
       ┌───────────────┐
       │   Reflect     │  (LLM barato → JSON)
       └───────┬───────┘
               ▼
       ┌───────────────┐
       │     Save      │  facts | skill | user-signal
       └───────────────┘

💾 Memória persistente

A memória é um SQLite local em ~/.hermes/memory.db com 3 camadas:

📊 As 3 camadas

conversations — turnos raw com timestamp/canal (TTL configurável, default 365 dias)
facts — fatos curados pelo reflect step ("usuário usa PostgreSQL 16, prefere snake_case, deploy em Hetzner") — sem TTL
skills — workflows reutilizáveis aprovados pelo usuário, em formato agentskills.io

✓ O que FAZER

✓Backup semanal do memory.db — é o cérebro do agente
✓Rodar /memory prune mensalmente — remove fatos contraditos
✓Revisar facts antes de compartilhar o DB
✓Versionar o schema com alembic se você customizar

✗ O que NÃO fazer

✗Editar o DB com 2 processos do Hermes rodando — corrompe WAL
✗Salvar TTL = infinito em conversations sem prune — o DB cresce sem fim
✗Deixar TTL muito baixo (<30d) — o agente vira amnésico

🔍 Busca FTS5

Em vez de embeddings caros, o Hermes usa SQLite FTS5 — índice invertido com ranking BM25 nativo. Funciona offline, ocupa pouco disco, e responde em milissegundos mesmo com centenas de milhares de turnos.

📊 Performance real

~5 ms — query típica em 50k conversas (M2 Air)
~50 MB — tamanho do DB com 1 ano de uso pesado
0 USD — custo por query (vs ~$0.0001 com embeddings)
BM25 — ranking padrão; ajuste pesos com bm25(fts, 5.0, 1.0)

-- Schema FTS5 do Hermes (simplificado)
CREATE VIRTUAL TABLE conversations_fts USING fts5(
  content,
  channel UNINDEXED,
  user_id UNINDEXED,
  ts UNINDEXED,
  tokenize = 'porter unicode61'
);

-- Recall típico: top-5 por relevância + recência
SELECT content, ts,
       bm25(conversations_fts, 5.0, 1.0) AS score
FROM conversations_fts
WHERE conversations_fts MATCH 'deploy hetzner OR coolify'
ORDER BY score, ts DESC
LIMIT 5;

💡 Dica

FTS5 não substitui embeddings em todo caso — para busca semântica pura ("encontre conversas sobre saúde mental" quando a palavra "saúde" nunca aparece), embeddings vencem. O Hermes deixa ativar um backend híbrido (memory.backend: hybrid) que combina FTS5 + embeddings opcionais via sqlite-vec.

🎨 Criação autônoma de skills

Quando o reflect step detecta que você repetiu um workflow ≥3x (ex: "exportar JSON do n8n → simplificar → mandar pra mim"), o Hermes propõe uma skill no formato agentskills.io: um SKILL.md com frontmatter YAML descrevendo trigger, mais arquivos auxiliares.

Detecção

Reflect identifica padrão recorrente

Heurística: ≥3 turnos com sequência similar de tools + verbos semelhantes na intenção.

Proposta

Agente redige SKILL.md candidato

Inclui frontmatter (name, description, trigger) + passos + scripts auxiliares.

Aprovação

Você dá /skills approve N

A skill vai para ~/.hermes/skills/ e fica disponível em todas as sessões futuras.

Trigger automático

Quando o trigger casa, a skill é injetada no contexto

Modelo "vê" o SKILL.md como instruções extras — sem retraining, sem fine-tune.

---
name: n8n-flow-summary
description: Resume um JSON exportado do n8n em 5 bullets
trigger: "json do n8n|exportei do n8n|workflow n8n"
tools_required: [filesystem, code]
---

# Passos

1. Ler o JSON com `read_file`
2. Rodar `python scripts/normalize.py` p/ extrair nodes
3. Para cada node: nome, tipo, role no fluxo
4. Devolver 5 bullets em PT-BR

## Anti-padrões
- Não listar credenciais
- Não traduzir nomes de nodes nativos

💡 Dica

Skills mais bem-sucedidas costumam ter ≤200 linhas e descrição com triggers explícitos — o LLM seleciona a skill certa por casamento de descrição, então seja específico.

👤 Honcho user modeling

O Hermes integra com Honcho — um engine open-source de user representations. Em vez de você manter um system prompt gigante com suas preferências, o Honcho constrói (via dialectic agent) um modelo evolutivo de quem você é, atualizado a cada conversa.

💡 O que o Honcho extrai

•Preferências técnicas: linguagens, stack, padrões de código
•Estilo de comunicação: PT-BR direto, sem emojis, bullets curtos
•Contexto pessoal: projetos ativos, papéis, ferramentas do dia-a-dia
•Anti-preferências: "não use frases como 'great question'"

⚠️ Atenção — privacidade

A memória nativa do Hermes (SQLite + FTS5) é 100% local. O Honcho, por padrão, pode rodar local OU usar o serviço hospedado (api.honcho.dev). Se você lida com dados sensíveis, force honcho.backend: local no config — caso contrário, user representations vão para o servidor deles.

honcho:
  enabled: true
  backend: local          # ou "cloud" para api.honcho.dev
  app_id: hermes-pessoal
  user_id: ${USER}
  inject_into_context: true
  inject_max_tokens: 800  # limita o quanto entra no prompt

🌐 OpenRouter — 200+ modelos

O OpenRouter é o provider padrão recomendado: 1 chave, 1 endpoint OpenAI-compat, e acesso a Anthropic, OpenAI, Google, Mistral, DeepSeek, Meta, xAI, Cohere, modelos open-source via Together/Fireworks e muito mais. Trocar de modelo = trocar 1 string no YAML.

📊 Comparativo prático (preços OpenRouter ~ mai/2026)

anthropic/claude-opus-4.7 — $15 / $75 (in/out por 1M tok) · latência ~3s · melhor raciocínio + tool-use
anthropic/claude-sonnet-4.6 — $3 / $15 · ~1.5s · sweet-spot para uso diário
anthropic/claude-haiku-4.5 — $1 / $5 · ~0.6s · reflect step e roteamento
openai/gpt-5 — $5 / $20 · ~2s · forte em código longo
openai/gpt-5-mini — $0.40 / $1.60 · ~0.8s · fallback barato
google/gemini-2.5-pro — $2.5 / $10 · contexto de 2M tokens
deepseek/deepseek-v3.2 — $0.30 / $1.10 · ~1.2s · ótimo custo/benefício open-weight

# Estratégia comum: modelo forte para act, barato para reflect
provider:
  name: openrouter
  api_key: ${OPENROUTER_API_KEY}
  models:
    main:    anthropic/claude-sonnet-4.6
    reflect: anthropic/claude-haiku-4.5
    routing: openai/gpt-5-mini
  fallbacks:
    - openai/gpt-5
    - google/gemini-2.5-pro
  prompt_caching: true   # OpenRouter passa para Anthropic/OpenAI

✓ O que FAZER

✓Usar modelo diferente p/ reflect (sempre barato)
✓Habilitar prompt_caching — corta 80% do custo em conversas longas
✓Definir fallback — quando Anthropic está em rate-limit, salva o dia
✓Monitorar gasto com /cost --month

✗ O que NÃO fazer

✗Usar Opus 4.7 como main sem necessidade — gasta 5x sem ganho perceptível
✗Trocar de modelo no meio de uma sessão longa — quebra prompt-cache
✗Mandar dados sensíveis para modelos open-source self-hosted sem TLS

💡 Dica de escolha

Regra prática: Sonnet 4.6 para tudo no dia-a-dia; Haiku 4.5 para reflect/routing/cron; Opus 4.7 só para refactor grande de código, planning de arquitetura ou debugging brutal. GPT-5 entra quando Sonnet trava em algum estilo de problema (Sonnet tende a "esgotar opções"; GPT-5 explora mais).

✅ Resumo do Módulo

✓

Loop fechado de aprendizado

Perceive → act → reflect → save: o agente cura sua própria memória sem você ter que ditar.

✓

Memória em 3 camadas

conversations (TTL), facts (sem TTL), skills (aprovadas) — tudo em SQLite local.

✓

FTS5 substitui embeddings na maioria dos casos

~5ms por query, ~50MB para 1 ano de uso, zero custo de inferência.

✓

Skills criadas sozinhas

Padrão agentskills.io — trigger + passos + scripts; aprovação humana antes de ativar.

✓

Honcho personaliza sem prompt eterno

User representations evolutivas — escolha backend: local se a privacidade importa.

✓

OpenRouter desbloqueia 200+ modelos

Sonnet 4.6 main, Haiku 4.5 reflect, Opus 4.7 sob demanda, fallback automático.

Próximo módulo:

Módulo 2.3 — 🔬 Anatomia de uma requisição: trace passo-a-passo de uma mensagem do Telegram até a resposta, com latência real de cada um dos 6 hops.

← Voltar para Trilha Próximo →