📜 The LLM and the brain (CLAUDE.md)
The coach’s “intelligence” isn’t in some magic code — it’s in a prompt: a text file called CLAUDE.md that describes who you are e how the coach should speak. It's the brain loaded at the start of each turn. Change its contents and you change the coach.
🟢 New here?
- LLM — “Large Language Model,” the kind of AI model that runs behind ChatGPT/Claude. It has no access to your life: it only knows what you write in the prompt. That’s why the
CLAUDE.mdexists — it’s where you tell it your data. - System prompt — the fixed text that goes with EVERY message, before your question. It defines the role ("you are a health coach"), the rules, and the context. At its core, the coach is an LLM with a very well-written prompt.
O CLAUDE.md comes as model (template) in the repository, with blanks for you to fill in. Six blocks make up the brain: profile, goals, lab results, DNA, restrictions, and style. Below is an excerpt illustrative (these aren’t real values — you never commit your filled-in version):
📄 CLAUDE.md — the coach's brain (illustrative excerpt)
# Perfil
Nome, idade, sexo, altura, peso atual e composição.
# Metas
- Baixar ApoB; ganhar massa magra; dormir melhor.
# Exames (bloods)
- ApoB, LDL-C, Lp(a), hs-CRP, HOMA-IR, Vitamina D...
- (os SEUS valores reais ficam aqui — NÃO versionar)
# Genética (SNPs)
- CYP1A2: metabolizador rápido de cafeína
- MTHFR: metilação reduzida -> preferir folato metilado
- VDR: resposta à vitamina D abaixo da média
# Restrições
- Sem amendoim. Álcool ocasional.
- NUNCA mexer em medicação; encaminhar ao médico.
# Estilo do coach
- Direto, mecanismo-aware: cita o "porquê" no MEU corpo.
- Não diagnostica. Marca o que for clínico para o médico.💡 Why this matters
The LLM is generic out of the box. What makes it your coach is the CLAUDE.md + database data. Same model, different prompt, completely different advice: specificity is what makes the magic work—“specific beats generic.”
Key concepts
The AI model; it only knows what's in the prompt.
The brain: profile, goals, exams, DNA, rules, style.
It comes with gaps; you fill in your own.
Same model, your prompt = your advice.
📸 Session snapshot
O CLAUDE.md is stable (who you are). But the coach also needs the now: how you woke up, what you ate today, your blood pressure. This comes from session snapshot — a compact snapshot assembled by the state.py and read on every turn, directly from the database.
The snapshot brings together six things: weight (trend), today's intake, blood pressure (BP), the yesterday's recovery, o 7-day sleep pattern and the goals. That’s why the coach never “guesses”: it reads the current state before reasoning. Below is an illustrative example of what the agent sees:
📸 SESSION SNAPSHOT (read every turn — illustrative numbers)
peso 82.1 kg (tendência ▼ -0.4 / 7d)
intake hoje 1180 kcal · 96 g proteína
BP último 118 / 76
recovery 71% (verde) · HRV 64 · RHR 52 [ontem]
sono 7d média 7h05 · ontem 7h20
metas ApoB ↓ · massa magra ↑📊 How to read: on every turn, the state.py (green) reads the database AND the memory (cyan), puts together the snapshot with CLAUDE.md, and only then does the LLM reason. The dashed line is the response coming back. The coach always starts from the current state, never from nothing.
Key concepts
A compact snapshot of "now," read at every turn.
The script that builds the database snapshot.
Weight, intake, BP, recovery, 7d sleep, goals.
The coach never guesses; it reads the state first.
🧲 Semantic memory
The snapshot shows the now. But the coach’s real gold is remembering weeks ago — “the last time you drank wine late, your recovery fell to 48%.” This isn’t an exact-word search; it’s a search for meaning. This is the role of semantic memory (mem.py recall).
🟢 New here?
- Embedding — turning text into a vector of numbers that captures your meaning. Similar phrases become nearby vectors. So “I had a glass of wine yesterday” ends up close to “I drank alcohol at night,” even without a word in common. In HealthOS, embeddings come from OpenAI.
- pgvector — a Postgres extension (the Supabase database) that stores these vectors and finds the closest ones next from a search. That's what makes “recall similar messages for me” possible in milliseconds.
The flow is simple: every message becomes an embedding and is stored. When you ask something new, the question also becomes an embedding, and the pgvector brings back the memories closest in meaning. That’s how the coach “surfs” your history and spots patterns.
📊 How to read: from left to right—text becomes a number (embedding), the number is stored and compared in pgvector, and recall brings back the memory with the closest meaning. The coach doesn't need you to use the same words as before.
Key concepts
Text becomes a vector that captures the meaning.
Postgres extension that finds nearby vectors.
Brings up a memory similar in meaning, not in wording.
It’s how the coach sees weeks, not just the last msg.
📚 Advice RAG
You saw a tip from an expert or influencer ("16-hour fasting melts fat"). The command /advice the coach does reconcile this tip with the your numbers — and returns an answer cited, explaining where the tip applies to you and where it doesn’t. The golden rule: your data always wins.
🟢 New here?
RAG (Retrieval-Augmented Generation) — “retrieval-augmented generation.” Instead of the LLM answering only with what it “remembers,” it first search relevant material (here: the external tip + your test results/goals) and generates the response based on that material, citing the source. Result: less guesswork, more grounding in what’s yours and what was said.
✗ Standalone tip (without RAG)
- ✗"16-hour fast for everyone" — without checking your HOMA-IR or your sleep.
- ✗Repeats what the influencer said, without a source or your context.
- ✗Disappears in the next conversation; it doesn't become your default.
✓ /advice (with RAG)
- ✓"The idea makes sense for insulin resistance; YOUR HOMA-IR is already good, so the benefit is small."
- ✓Cites the tip AND your markers; shows where it got each part.
- ✓Conflict between the tip and your data? Your data expires.
⚖️ Who wins the tiebreaker
An internet tip is an average; your lab results are about you. When the two disagree, the /advice is instructed to prioritize the your number and clearly state where the tip doesn’t apply. It still isn’t medical advice — it’s material to take to your clinician.
Key concepts
Finds material, then generates content citing the source.
The command that reconciles the advice with you.
Shows where each part of the answer came from.
In a conflict, your number takes precedence.
🚩 Risk flags in practice
Each blood marker and each DNA SNP on the panel maps to a risk flag — a rule that connects the “why” in your body to a action: a supplement in the stack, a target, or a warning. That’s what turns lab results sitting idle into mechanism-aware advice. Follow the rule → action path in the diagram.
📊 How to read: the cyan inputs (SNP + marker) combine in the flag (green). The flag splits into two actions: adjust the supplement stack (green) or raise an alert for the doctor (red). No input on its own becomes an action — it's the combination that matters.
Key concepts
Rule that links DNA + test to an action.
Each marker/SNP points to a flag, target, or supplement.
The flags shape the supplement set.
The clinician, not the coach, decides what is clinical.
⚠️ Limits — where AI stops
The better AI gets, the more dangerous it is to forget what it no is. The coach is a logging and reasoning tool—not a doctor. Two technical limits and one golden rule wrap up this module.
⚠️ The two technical limits
- •Hallucination — the LLM can make up a number, a mechanism, or a citation with complete confidence. It sounds right even when it’s wrong.
- •Lost context — if something isn’t in the snapshot or that turn’s recall, the coach simply doesn’t know it. It reasons about what was loaded, not everything.
- •DNA samples mailed in degrade — the clinic’s panel and Ancestry’s may not match.
🩺 The golden rule
Treat every the coach’s suggestion as a question to ask your doctor, never as an order to follow. The coach is explicitly instructed to not diagnose e a not change medication — it flags clinical concerns and refers you to a clinician. Where AI helps: organizing, remembering, cross-referencing, and proposing hypotheses. Where it stops: any clinical decision.
✅ Self-check (optional): the coach suggests starting a new supplement. What’s the right approach?
Key concepts
Can be confident and wrong at the same time.
Only knows what was loaded in that turn.
Doesn’t prescribe medication; refers you to a clinician.
Every suggestion goes to the doctor.
🔐 Security
Health data is sensitive, and the coach's brain (your CLAUDE.md filled in) is the most sensitive of all. HealthOS is locked by default: private database, server-only access, RLS with no policies, and secrets kept out of git.
🟢 New here?
- RLS (Row-Level Security) — “row-level security”: a Postgres feature that decides who can read each row. In HealthOS, it stays enabled without any policy — in other words, the public (anon) key can’t read anything. It’s locked down by default.
- Service-role key — the Supabase admin key that works around RLS. Only the server uses it, and it lives in
~/.env, never in the browser or in git. It’s what gives the coach access to your data; exposing it opens everything up.
✓ What the design guarantees
- ✓Supabase project private, in your account.
- ✓RLS enabled, no policies: the anon key can’t read anything.
- ✓service-role only on the server; secrets in
~/.env, outside git.
✗ What to never version-control
- ✗Your
CLAUDE.mdfilled in (profile + real test results). - ✗The key
SUPABASE_SERVICE_ROLE_KEYand the other keys. - ✗The file
~/.envand the seed's actual values.
🔑 Two keys, two worlds
A anon is public and harmless (with RLS and no policies, it reads nothing). The service-role is king: it opens everything, so keep it only on the server, in the ~/.env. Nothing leaves your project except the LLM and embedding calls you choose to make.
Key concepts
Connected without policies: no one outside can read it.
Master key, server only, in ~/.env.
The database is yours, in your account.
CLAUDE.md filled out + secrets never committed to version control.
📋 Module summary
Next:
Track 2 — Step by step: from scratch to a live coach — accounts, Supabase database, the agent and bot, wearable, and scheduling.