⚙️ agent.yaml — o token do bot e os comandos
O agent.yaml é o arquivo de configuração do coach: ele diz qual bot do Telegram usar e quais slash commands aparecem no menu. A pegadinha mais importante: o token não mora dentro dele. O arquivo guarda só o nome da variável de ambiente que aponta para o token — o segredo de verdade fica em ~/.env, fora do git.
🟢 Novo aqui? Três termos antes de seguir
- agent.yaml — o "painel de controle" do coach em texto. Você copia o
agent.yaml.exampleparaagent.yamle edita. - telegram_bot_token_env — em vez do token cru, ele guarda o NOME da variável (ex.:
HEALTH_BOT_TOKEN) que o agente lê do seu~/.env. Assim o segredo nunca cai no repositório. - Slash command — um atalho que começa com "/" no Telegram (ex.:
/checkin). Cada um dispara uma rotina do coach.
📋 Copie e adapte · objetivo: registrar o bot e declarar os comandos do menu
# agent.yaml.example → copie para agent.yaml e edite
name: health-coach
# o bot NÃO guarda o token aqui — guarda o NOME da variável
# de ambiente que o agente lê do seu ~/.env (segredo fora do git)
telegram_bot_token_env: HEALTH_BOT_TOKEN
slash_commands:
- command: checkin
description: Revisão da manhã guiada pela recuperação
- command: today
description: O plano de hoje (treino, comida, café)
- command: sofar
description: O que você já registrou hoje
- command: newday
description: Fecha o dia e começa um novo
- command: supplements
description: Sua agenda de suplementos
- command: advice
description: Conselho com citações, reconciliado aos seus dadosConceitos-chave
O painel de controle do coach.
Guarda o nome da variável, não o segredo.
Atalhos "/" declarados no arquivo.
Onde o token de fato vive.
📝 CLAUDE.md — o cérebro do coach é o seu perfil
O CLAUDE.md é o documento que o coach lê para saber quem você é. É ali que o "conselho genérico" vira "conselho seu": meta, exames de sangue, variações genéticas, restrições, preferências de suplemento e — importante — o estilo com que você quer ser cobrado. O repositório traz um template; você o preenche com a sua realidade.
📋 Copie e preencha · objetivo: dar ao coach o seu perfil real para aterrar cada resposta
# CLAUDE.md — o cérebro do coach (preencha com o SEU perfil)
## Meta (goal)
<ex.: recomposição — perder ~4 kg de gordura mantendo massa até dez>
## Exames (bloods)
<só os SEUS valores: ApoB 95, HOMA-IR 1.4, Vitamina D 28, ...>
## Genética (SNPs)
<ex.: CYP1A2 metabolizador rápido de cafeína; APOE e3/e3>
## Restrições
<ex.: sem lactose; joelho direito sensível; tendência a dormir tarde>
## Suplementos (preferências)
<ex.: creatina 5g/dia; magnésio à noite; evita pré-treino com cafeína>
## Estilo do coach
Direto e cobrando — pode ser "savage on purpose":
me chama no flanco quando eu furo um check-in, sem rodeios.⚠️ Nunca versione o CLAUDE.md preenchido
- •O template vem no repositório; o preenchido tem exames e genética reais — é informação de saúde sensível.
- •Mantenha-o fora do git (no
.gitignore), junto com seus valores de seed, fotos e o~/.env. - •O repo público é o blueprint limpo — não os registros de ninguém.
💡 Por que o "estilo" importa
Um coach que você ignora não muda nada. Descrever o tom — gentil, técnico, ou "savage on purpose" cobrando check-ins — faz o LLM falar do jeito que te move. É parte do perfil tanto quanto o ApoB.
Conceitos-chave
O CLAUDE.md aterra cada resposta em você.
O tom também é configuração.
Copie o modelo, preencha o seu.
O preenchido nunca é versionado.
⌨️ Os slash commands, um a um
Cada slash command é um atalho que dispara uma rotina específica do coach. Você não precisa deles — pode só conversar normalmente — mas eles dão um botão rápido para as ações do dia. Os seis do menu vêm do agent.yaml; há ainda o /healthdb, que entrega um botão de link para o dashboard.
📊 Como ler: digitar "/" abre o menu (azul) que se ramifica nos seis comandos declarados (ciano). O /healthdb (âmbar, à direita) é um extra que manda um botão de deep-link para o dashboard.
| Comando | O que faz |
|---|---|
| /checkin | A revisão da manhã guiada pela recuperação: abre com o recovery de ontem à noite e amarra suas escolhas ao número. |
| /today | O plano de hoje — treino, comida e café — visivelmente condicionado ao recovery (verde = puxar, vermelho = pegar leve). |
| /sofar | Mostra o que você já registrou hoje (comida, treino, peso, café) — o acumulado do dia até agora. |
| /newday | Fecha o dia e abre um novo — útil quando você vira a página antes da rotina automática rodar. |
| /supplements | Sua agenda de suplementos: o que tomar, quando, conforme o que está no banco. |
| /advice | Conselho com citações (RAG de fontes), reconciliado aos seus próprios dados antes de te entregar. |
| /healthdb | Extra — manda um botão de deep-link para o dashboard, com o DASHBOARD_TOKEN guardado num cookie HttpOnly. |
Conceitos-chave
A âncora do dia: recovery → plano.
Plano de hoje e o que já entrou.
Conselho citado, batido com seus dados.
Atalho protegido para o dashboard.
💬 Subir o bot e dar o primeiro "oi"
Com o token no ~/.env e o agent.yaml pronto, você sobe o agente e manda uma mensagem comum — nem precisa de comando. O teste mínimo é exatamente este: o bot boota e responde a um "oi". Por trás desse "oi" acontece a sequência que você vê no diagrama: o agente lê o snapshot, raciocina no LLM e devolve a resposta ao Telegram.
📊 Como ler: da esquerda pra direita é o caminho da sua mensagem; a linha tracejada é a resposta voltando. O agente sempre passa pelo state.py (snapshot) antes de raciocinar — é o que veremos rodar no próximo tópico.
Conversa no Telegram (ilustrativa)
✅ O teste que confirma esta etapa
Da checklist de validação: "o agente boota e responde a uma mensagem comum no Telegram" e "os slash commands aparecem no menu '/'". Se um "oi" recebe resposta e os comandos surgem ao digitar "/", o bot está no ar.
Conceitos-chave
Não precisa de comando para conversar.
Sobe lendo o token do ~/.env.
Toda resposta começa pelo state.py.
O LLM responde no próprio Telegram.
📸 state.py — como o snapshot é montado
O snapshot é o retrato compacto do "agora" que o agente lê no começo de cada turno: tendência de peso, o que você comeu hoje, pressão, a recuperação de ontem à noite, o padrão de sono de 7 dias e suas metas. O script state.py monta esse retrato a partir do banco — e você pode rodá-lo no terminal para ver o que o coach vê.
🟢 Novo aqui?
Snapshot de sessão — não é mágica nem IA: é só uma consulta determinística ao banco que junta as últimas linhas de cada tabela num resumo. Rodar o state.py sozinho mostra exatamente o texto que entra no contexto do LLM antes de qualquer raciocínio.
📋 Rode no terminal · objetivo: imprimir o snapshot (peso, intake e metas) que o coach lê a cada turno
# na raiz do repositório, com o ~/.env preenchido
python3 agent/scripts/state.py=== SNAPSHOT (2026-06-30) ===
weight: 82.4 kg (7d: -0.6 kg ↓)
today: 1 240 kcal · 96 g proteína · café 1×
last night: recovery 71% · HRV 64 ms · sono 7h20
7d sleep: média 6h54 (meta 7h30)
goals: recomposição — manter massa, -4 kg gordura🔎 Por que rodar isso à parte
Se uma resposta do coach parece "fora do contexto", o state.py é o primeiro lugar para olhar: se o snapshot está vazio ou desatualizado, o problema é dado faltando no banco — não o LLM. É a sua janela de depuração.
Conceitos-chave
Monta o snapshot a partir do banco.
Só consulta — sem IA no meio.
O que precisa aparecer na saída.
Veja o que o coach realmente vê.
🧲 mem.py recall — a memória semântica
O snapshot conta o "agora"; a memória semântica traz o passado relevante. Toda mensagem é guardada com um embedding (uma assinatura numérica do significado). Quando você pergunta algo, o mem.py recall busca as mensagens passadas mais parecidas com a pergunta — mesmo que não usem as mesmas palavras — e as devolve para o coach.
🟢 Novo aqui? Dois termos
- Embedding — um vetor de números que representa o sentido de um texto. Frases parecidas viram vetores próximos, então a busca acha por significado, não por palavra exata.
- Recall semântico — "lembrar por significado": dada a sua pergunta, o sistema mede a proximidade entre os embeddings e traz as memórias mais próximas (via
pgvector, no Supabase).
📋 Rode no terminal · objetivo: trazer mensagens passadas relevantes a uma consulta
# busca por significado nas suas mensagens já guardadas
python3 agent/scripts/mem.py recall "<o que você quer lembrar>"
# ex.: como o álcool costuma afetar o meu sono
python3 agent/scripts/mem.py recall "vinho à noite e recuperação"recall "vinho à noite e recuperação" → 3 hits
0.89 2026-06-12 "bebi 2 taças no jantar, dormi mal"
0.84 2026-05-28 "recovery caiu p/ 48% depois do churrasco c/ cerveja"
0.79 2026-05-09 "noites sem álcool: HRV mais alto na manhã"🧠 Memória é o produto
É isto que separa o coach de um chatbot que esquece tudo: ele cruza a pergunta de hoje com o seu histórico e enxerga padrões ("toda vez que você janta tarde, o sono cai"). Da checklist: "recall semântico (mem.py recall) retorna mensagens passadas relevantes".
Conceitos-chave
Assinatura numérica do significado.
Busca por sentido, não por palavra.
A busca por proximidade no Supabase.
O passado relevante vira insight.
🌳 A árvore do agent/
Tudo o que você configurou vive na pasta agent/ — o agente sanitizado e auto-contido. Vale ter o mapa na cabeça: na raiz, o cérebro (CLAUDE.md) e a config (agent.yaml.example); aninhados, os scripts, as migrations do banco e o dashboard.
📊 Como ler: a borda externa é a pasta agent/. Na faixa de cima ficam os arquivos da raiz; abaixo, as três pastas aninhadas. Os scripts que você rodou neste módulo (state.py, mem.py) moram em scripts/.
scripts/db.py
A porta do banco: select, inserts e até criar o bucket de fotos (mkbucket). Stdlib-only.
scripts/whoop-sync.py
Puxa recovery + sono da wearable para a tabela vitals. Roda no cron da manhã (Trilha 2.4).
scripts/supplements.py
Constrói a agenda de suplementos que o /supplements entrega.
scripts/advice.py
O RAG por trás do /advice: conselho com citações, reconciliado aos seus dados. Único que precisa de requests.
✅ Auto-checagem (opcional): onde mora o token do bot do Telegram?
Conceitos-chave
CLAUDE.md + agent.yaml.example + AGENTS.md.
state, mem, db, whoop-sync, supplements, advice.
O schema de 14 tabelas + seed.
O painel web que lê do Supabase.
📋 Resumo do módulo
telegram_bot_token_env e declara os slash commands; o token fica no ~/.env.state.py imprime o "agora"; mem.py recall traz o passado relevante.Próximo módulo:
2.4 — Wearable e agendamento: conectar o WHOOP (OAuth), agendar o whoop-sync.py e disparar a revisão da manhã todo dia.