HealthHermes: A Private AI Health Companion That Remembers Everything and Runs on Your Own Machine

The whole project is open source. Here's what's inside:

healthhermes/

├── SOUL.md                          ← who HealthHermes is and how it speaks

├── install.sh                       ← one command sets everything up

├── skills/

│   ├── health-logger/

│   │   ├── SKILL.md                 ← teaches Hermes when and how to log

│   │   └── scripts/

│   │       ├── log_entry.py         ← writes structured entries to SQLite

│   │       └── query_logs.py        ← reads history + detects patterns

│   └── doctor-summary/

│       ├── SKILL.md

│       └── scripts/

│           └── generate_summary.py  ← builds the full doctor report

└── cron/

    └── healthhermes.yaml            ← medication reminders via Telegram

Want to run it yourself? Three steps:

# 1. Install Hermes Agent

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash



# 2. Clone HealthHermes and install skills

git clone https://github.com/har/healthhermes.git

cd healthhermes && chmod +x install.sh && ./install.sh



# 3. Start talking

hermes

That's it. No Docker. No cloud setup. No API keys for health services. Just Hermes running locally.

My Tech Stack

How I Used Hermes Agent

Honestly? I tried to think of another way to build this and I couldn't. Here's why Hermes was the only framework that made HealthHermes possible:

1. Persistent Memory — the entire point of the product

Every health app I've used forgets you the moment you close it. Hermes doesn't. It writes to MEMORY.md and USER.md automatically and injects them into every session's system prompt. That means HealthHermes remembers your medications, your recurring symptoms, and your patterns across weeks — without me writing a single line of memory management code. This isn't a feature I added. It's just how Hermes works.

2. The Skill System — teaching the agent to think, not just execute

This blew my mind when I first understood it. Instead of writing orchestration code telling the agent what to do step by step, I wrote two markdown files (SKILL.md) that describe when a skill is relevant and how to use it. When you say "my back hurts," Hermes reads the health-logger skill description, decides on its own that this is a symptom log, and runs the Python script. No explicit command. No button press. Just natural conversation triggering real tool use.

That's actual agentic behavior — not a chatbot with if-else statements.

3. Cron Scheduler + Telegram — infrastructure I didn't have to build

Medication reminders are a critical feature for chronic illness patients. Building this from scratch would mean a separate service, a separate process, separate monitoring. With Hermes, I wrote a 20-line YAML file (healthhermes.yaml) defining three cron jobs, and Hermes's built-in scheduler picked it up automatically — firing Telegram messages at 8 AM and 9 PM daily. That's real infrastructure I got for free.

4. SOUL.md — the most important file in the project

For a health app, getting the personality wrong isn't just bad UX — it's potentially harmful. I used SOUL.md to define HealthHermes as a warm, empathetic companion with hard limits: never diagnose, never alarm, never give dosage advice. Every single interaction is filtered through that identity. Judges can read the SOUL.md file in the repo — it's 24 lines that define everything the agent is allowed to be.

What surprised me most while building this:

The moment HealthHermes started cross-referencing past entries and saying things like "I notice your dizziness appeared again today — this is the second time this week, both times in the afternoon" — that wasn't me writing pattern detection logic. That was Hermes reading the recent_similar data my skill returned and reasoning over it naturally.

It stopped feeling like a project and started feeling like something genuinely useful.

That's the Hermes difference. And that's why I built HealthHermes.

HealthHermes is not a medical device and does not provide medical advice. Always consult a qualified healthcare professional for diagnosis and treatment.