health-agent-infra 0.1.1

Governed runtime + skills for a multi-domain personal health agent (recovery, running, sleep, stress, strength, nutrition).

Health Agent Infra

A governed local agent runtime for personal health data. Claude Code + Garmin today; MCP-portable and multi-source on the roadmap.

A Claude Code agent reads your own health data, emits per-domain proposals bounded by codified rules, and commits auditable recommendations you review the next day. Every decision is logged to a local SQLite database on your machine; nothing leaves your device.

For technical users comfortable with a CLI who use Claude Code and want agent recommendations they can audit, reproduce, and keep local.

• Local-first. State lives in a SQLite file under your home directory. No cloud, no account, no remote telemetry.
• Governed, not generative. Python owns mechanical decisions (classification bands, policy rules, transactional commits); markdown skills own rationale and uncertainty. Skills never change an action; code never writes prose.
• Auditable by construction. Pulls, proposals, rule firings, synthesis, and final recommendations all land in typed tables. Inspect anytime with hai doctor, hai explain, hai stats, or plain SQL.

Install

pipx install health-agent-infra                      # or: pip install -e .
hai init --with-auth --with-first-pull               # scaffolds state + config + skills,
                                                     # prompts for Garmin credentials,
                                                     # backfills the last 7 days
hai daily                                            # tomorrow morning: pull → clean → propose → synthesize → commit
hai stats                                            # local funnel: syncs, recent runs, daily streak

Prefer the non-interactive path? Run hai init on its own, then hai auth garmin separately. hai init is idempotent and safe to re-run. Full CLI surface in reporting/docs/agent_cli_contract.md.

Six domains in v1

recovery · running · sleep · stress · strength · nutrition

Each domain ships its own schemas, classification bands, policy rules, and a readiness skill, and is wired into the synthesis X-rule catalogue that reconciles across domains. Nutrition is macros-only in v1 — see reporting/docs/non_goals.md.

Local-first runtime at a glance

pull / intake  →  projectors  →  accepted_*_state_daily tables
                                        │
                                        ▼
                         hai state snapshot --as-of <date>
                                        │
                                        ▼
                 domain skills emit DomainProposal × 6
                                        │ hai propose
                                        ▼
                              proposal_log
                                        │
                                        ▼
   Phase A X-rules (X1–X7) → runtime applies mutations to drafts
                                        │
                                        ▼
             daily-plan-synthesis skill overlays rationale
                                        │
                                        ▼
         Phase B X-rules (X9) → action_detail adjustments
                                        │
                                        ▼
  ATOMIC COMMIT: daily_plan + x_rule_firings + N recommendations
                                        │
                                        ▼
             hai review schedule / record / summary

• Local state memory — accepted_*_state_daily tables hold the canonical per-domain day-level state the runtime reasons over.
• Decision memory — proposal_log, daily_plan, x_rule_firing, and recommendation_log preserve what the agent proposed, what synthesis changed, and what was finally committed.
• Outcome memory — review_event and review_outcome record how the plan went, so the full decision/outcome history stays on-device.

See reporting/docs/architecture.md for the full pipeline and the code-vs-skill boundary.

Roadmap

• Runtime portability via MCP. Expose the agent-safe CLI surface as an MCP server so any agentic runtime (Claude Code, Codex, others) can drive it. Today the project is Claude Code–native; the CLI contract is already annotated agent-safe vs. interactive, which maps cleanly onto MCP tool schemas.
• Multi-source wearables. Apple Health, Oura, Whoop. The adapter protocol (core/pull/protocol.py) is already source-agnostic; the per-domain evidence contract needs to broaden before additional sources land. Community adapters welcome — see reporting/docs/how_to_add_a_pull_adapter.md.
• Skill-narration eval harness. Currently deferred; see safety/evals/skill_harness_blocker.md.

What this is not

• Not a medical device, not hosted, not multi-user, not an ML loop. See reporting/docs/non_goals.md.
• Not meal-level nutrition in v1 — macros only.
• Not an MCP server yet (see Roadmap).
• Not a skill-narration eval harness yet (see Roadmap).

Dig deeper

1. Positioning & role map — reporting/docs/personal_health_agent_positioning.md
2. Query taxonomy — reporting/docs/query_taxonomy.md
3. Memory model — reporting/docs/memory_model.md
4. Architecture overview — reporting/docs/architecture.md
5. Explainability surface — reporting/docs/explainability.md
6. X-rule catalogue — reporting/docs/x_rules.md
7. Non-goals (scope discipline) — reporting/docs/non_goals.md
8. State schema — reporting/docs/state_model_v1.md
9. 10-minute reading tour — reporting/docs/tour.md
10. Extension path — pull adapter — reporting/docs/how_to_add_a_pull_adapter.md
11. Extension path — new domain — reporting/docs/how_to_add_a_domain.md
12. Eval capture — reporting/artifacts/flagship_loop_proof/2026-04-18-multi-domain-evals/

CLI surface

# Evidence + intake
hai pull [--live] --date <d>                   # Garmin CSV / live pull
hai clean --evidence-json <p>                  # raw → CleanedEvidence + RawSummary
hai intake gym|exercise|nutrition|stress|note|readiness ...

# State
hai state init | migrate | read | snapshot | reproject

# Per-domain debug
hai classify --domain <d> --evidence-json <p>
hai policy   --domain <d> --evidence-json <p>

# Agent flow (use `hai daily` for the whole loop)
hai daily                                       # morning orchestrator
hai propose  --domain <d> --proposal-json <p>
hai synthesize --as-of <d> --user-id <u>

# Persistence + review
hai writeback --recommendation-json <p>         # recovery-only legacy direct path
hai review schedule | record | summary [--domain <d>]

# Auth + config + helpers
hai auth garmin | status
hai config init | show
hai doctor                                      # freshness + health checks
hai stats                                       # local funnel (sync + command history, daily streak)
hai exercise search --query <free-text>

# Evals
hai eval run --domain <d> | --synthesis [--json]

Repo layout

For a one-page orientation of every top-level entry (active vs historical vs generated) see REPO_MAP.md. The package itself:

src/health_agent_infra/
├── cli.py                          # hai dispatcher
├── core/
│   ├── schemas.py  validate.py  config.py
│   ├── synthesis.py  synthesis_policy.py
│   ├── writeback/  state/  clean/  pull/  review/
│   ├── memory/  explain/  research/
│   └── intake/
├── domains/
│   ├── recovery/  running/  sleep/  stress/  strength/  nutrition/
│   └── each: schemas.py classify.py policy.py [+ signals/intake]
├── skills/
│   ├── recovery-readiness/  running-readiness/  sleep-quality/
│   ├── stress-regulation/  strength-readiness/  nutrition-alignment/
│   ├── daily-plan-synthesis/  intent-router/  expert-explainer/
│   └── strength-intake/  merge-human-inputs/  writeback-protocol/
│       reporting/  safety/
├── evals/                          # packaged eval runner + scenarios
└── data/garmin/export/              # committed CSV fixture
reporting/                          # see reporting/README.md
├── docs/                            # architecture, x_rules, non_goals, ...
├── artifacts/flagship_loop_proof/   # eval runner captures
├── plans/                           # post-v0.1 roadmap + historical phase docs
└── experiments/                     # frozen Phase 0.5 / 2.5 prototypes
safety/                             # see safety/README.md
├── tests/                           # 1200+ unit + contract + integration
├── evals/                           # eval-doc reference + skill-harness pilot
└── scripts/                         # legacy pre-rebuild demo shim

What's proven in v1

• Six domains end-to-end: classify → policy → skill proposal → synthesis → writeback → review.
• Ten X-rule evaluators across two phases with atomic transactional commits.
• Garmin live pull via OS keyring (hai auth garmin + hai pull --live).
• Idempotent synthesis with optional --supersede versioning.
• 28 eval scenarios (18 domain + 10 synthesis); skill-narration axis explicitly deferred (see safety/evals/skill_harness_blocker.md).
• 1200+ tests covering every band, every R-rule, every X-rule, atomic transaction semantics, writeback invariants, and skill-boundary contracts.

Contributing

See CONTRIBUTING.md.