⚙️ agent.yaml — el token del bot y los comandos
O agent.yaml es el archivo de configuración del coach: indica qué bot de Telegram usar y cuáles slash commands aparecen en el menú. La trampa más importante: el token no vive dentro de él. El archivo solo guarda el nombre de la variable de entorno que apunta al token — el secreto real queda en ~/.env, fuera de git.
🟢 ¿Nuevo por aquí? Tres términos antes de continuar
- agent.yaml — el "panel de control" del coach en texto. Copias el
agent.yaml.exampleparaagent.yamly edita. - telegram_bot_token_env — en lugar del token sin procesar, guarda el NOMBRE de la variable (p. ej.:
HEALTH_BOT_TOKEN) que el agente lee de tu~/.env. Así el secreto nunca termina en el repositorio. - Slash command — un atajo que empieza con «/» en Telegram (p. ej.,
/checkin). Cada uno activa una rutina del coach.
📋 Copia y adapta · objetivo: registrar el bot y declarar los comandos del menú
# 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 dadosConceptos clave
El panel de control del coach.
Guarda el nombre de la variable, no el secreto.
Atajos «/» declarados en el archivo.
Dónde vive realmente el token.
📝 CLAUDE.md — el cerebro del coach es tu perfil
O CLAUDE.md es el documento que el coach lee para saber quién eres. Ahí es donde el «consejo genérico» se convierte en «un consejo para ti»: meta, análisis de sangre, variaciones genéticas, restricciones, preferencias de suplementos y —algo importante— el estilo con lo que quieres que te exijan. El repositorio incluye una plantilla; la completas con tu realidad.
📋 Copia y completa · objetivo: darle al coach tu perfil real para que cada respuesta se base en él
# 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 versiones el CLAUDE.md rellenado
- •El template está en el repositorio; el completado tiene análisis y datos genéticos reales; es información de salud sensible.
- •Mantenlo fuera de git (en el
.gitignore), junto con tus valores de seed, fotos y el~/.env. - •El repo público es el blueprint limpio — no los registros de nadie.
💡 Por qué importa el «estilo»
Un coach al que ignoras no cambia nada. Describir el tono —amable, técnico o "savage a propósito" pidiendo check-ins — hace que el LLM hable de la forma que te se mueve. Es parte del perfil tanto como la ApoB.
Conceptos clave
El CLAUDE.md aterriza cada respuesta en tu caso.
El tono también es una configuración.
Copia la plantilla y complétala con tus datos.
El archivo completado nunca se versiona.
⌨️ Los comandos slash, uno por uno
Cada slash command es un atajo que activa una rutina específica del coach. Tú no necesita de ellos — puedes simplemente conversar con normalidad —, pero te dan un botón rápido para las acciones del día. Los seis del menú vienen de agent.yaml; también está el /healthdb, que ofrece un botón con un enlace al dashboard.
📊 Cómo leer: escribir "/" abre el menú (azul), que se ramifica en los seis comandos declarados (cian). El /healthdb (ámbar, a la derecha) es un extra que envía un botón de deep-link al dashboard.
| Comando | Qué hace |
|---|---|
| /checkin | La revisión de la mañana guiada por la recuperación: empieza con la recuperación de anoche y conecta tus decisiones con el número. |
| /today | El plan de hoy —entrenamiento, comida y café—, visiblemente condicionado por el recovery (verde = esforzarte, rojo = tomártelo con calma). |
| /sofar | Muestra lo que ya registraste hoy (comida, entrenamiento, peso, café) — el acumulado del día hasta ahora. |
| /newday | Cierra el día y abre uno nuevo: útil cuando quieres empezar de nuevo antes de que se ejecute la rutina automática. |
| /supplements | Tu agenda de suplementos: qué tomar y cuándo, según lo que está en la base de datos. |
| /advice | Consejo con citas (RAG de fuentes), conciliado con tus propios datos antes de entregártelo. |
| /healthdb | Extra: envía un botón de enlace directo al dashboard, con el DASHBOARD_TOKEN guardado en una cookie HttpOnly. |
Conceptos clave
El ancla del día: recuperación → plan.
Plan de hoy y lo que ya se registró.
Consejo citado y contrastado con tus datos.
Atajo protegido al dashboard.
💬 Iniciar el bot y decir el primer "hola"
Con el token en el ~/.env e o agent.yaml listo, pones en marcha el agente y envías una mensaje común — ni siquiera necesitas un comando. La prueba mínima es exactamente esta: el bot se inicia y responde a un "hola". Detrás de ese "hola" ocurre la secuencia que ves en el diagrama: el agente lee el snapshot, razona con el LLM y devuelve la respuesta a Telegram.
📊 Cómo leer: de izquierda a derecha está el recorrido de tu mensaje; la línea discontinua es la respuesta de vuelta. El agente siempre pasa por el state.py (snapshot) antes de razonar: es lo que veremos funcionar en el próximo tema.
Conversación en Telegram (ilustrativa)
✅ La prueba que confirma esta etapa
De la lista de verificación de validación: "el agente se inicia y responde a un mensaje común en Telegram" e "los slash commands aparecen en el menú '/'". Si recibes una respuesta al enviar "hola" y los comandos aparecen al escribir "/", el bot está activo.
Conceptos clave
No necesitas un comando para conversar.
Se carga al leer el token de ~/.env.
Toda respuesta empieza por state.py.
El LLM responde en el propio Telegram.
📸 state.py — cómo se arma el snapshot
O snapshot es el retrato compacto del «ahora» que el agente lee al comienzo de cada turno: tendencia del peso, lo que comiste hoy, presión arterial, la recuperación de anoche, el patrón de sueño de 7 días y tus metas. El script state.py arma este retrato a partir de la base de datos — y puedes ejecutarlo en la terminal para ver lo que ve el coach.
🟢 ¿Nuevo por aquí?
Snapshot de sesión — no es magia ni IA: es solo una consulta determinista a la base de datos que reúne las últimas filas de cada tabla en un resumen. Ejecutar el state.py por sí solo muestra exactamente el texto que entra en el contexto del LLM antes de cualquier razonamiento.
📋 Ejecuta en la terminal · objetivo: imprimir el snapshot (peso, intake y metas) que el coach lee en 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 qué ejecutarlo por separado
Si una respuesta del coach parece "fuera de contexto", el state.py es el primer lugar que debes revisar: si la instantánea está vacía o desactualizada, faltan datos en la base de datos —no es un problema del LLM. Es tu ventana de depuración.
Conceptos clave
Arma la instantánea a partir de la base de datos.
Solo consulta, sin IA de por medio.
Qué debe aparecer en la salida.
Mira lo que realmente ve el coach.
🧲 mem.py recall — la memoria semántica
El snapshot muestra el «ahora»; la memoria semántica trae el pasado relevante. Cada mensaje se guarda con un embedding (una firma numérica del significado). Cuando preguntas algo, el mem.py recall busca los mensajes anteriores más parecidos a la pregunta — aunque no usen las mismas palabras — y se los devuelve al coach.
🟢 ¿Nuevo por aquí? Dos términos
- Embedding — un vector de números que representa el sentido de un texto. Las frases parecidas se convierten en vectores cercanos, así que la búsqueda encuentra por significado, no por palabra exacta.
- Recall semántico — «recordar por significado»: dada tu pregunta, el sistema mide la cercanía entre los embeddings y trae los recuerdos más cercanos (mediante
pgvector, en Supabase).
📋 Ejecuta en la terminal · objetivo: traer mensajes anteriores relevantes para una 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ã"🧠 La memoria es el producto
Es lo que distingue al coach de un chatbot que lo olvida todo: cruza la pregunta de hoy con tu historial y ve patrones ("cada vez que cenas tarde, baja la calidad del sueño"). De la lista de verificación: "recall semántico (mem.py recall) devuelve mensajes anteriores relevantes».
Conceptos clave
Firma numérica del significado.
Busca por significado, no por palabra.
La búsqueda por proximidad en Supabase.
El pasado relevante se convierte en insight.
🌳 El árbol de agent/
Todo lo que configuraste está en la carpeta agent/ — el agente sanitizado y autocontenido. Conviene tener el mapa en mente: en la raíz, el cerebro (CLAUDE.md) y la configuración (agent.yaml.example); anidados, los scripts, las migraciones de la base de datos y el dashboard.
📊 Cómo leer: el borde exterior es la carpeta agent/. En la parte superior están los archivos de la raíz; debajo, las tres carpetas anidadas. Los scripts que ejecutaste en este módulo (state.py, mem.py) están en scripts/.
scripts/db.py
La puerta de la base de datos: select, inserts e incluso crear el bucket de fotos (mkbucket). Solo usa la biblioteca estándar.
scripts/whoop-sync.py
Extrae recovery + sueño de la wearable a la tabla vitals. Se ejecuta en el cron de la mañana (Trilha 2.4).
scripts/supplements.py
Construye el plan de suplementos que el /supplements entrega.
scripts/advice.py
El RAG detrás del /advice: consejo con citas, conciliado con tus datos. El único que necesita requests.
✅ Autoevaluación (opcional): ¿dónde está el token del bot de Telegram?
Conceptos clave
CLAUDE.md + agent.yaml.example + AGENTS.md.
state, mem, db, whoop-sync, supplements, advice.
El schema de 14 tablas + seed.
El panel web que lee desde Supabase.
📋 Resumen del módulo
telegram_bot_token_env y declara los slash commands; el token queda en el ~/.env.state.py imprime el «ahora»; mem.py recall trae el pasado relevante.Próximo módulo:
2.4 — Wearable y programación: conectar WHOOP (OAuth), programar el whoop-sync.py y activar la revisión de la mañana todos los días.