Skip to content
Back to search

hermes-life-os

Personal OS agent that learns who you are, detects life patterns, and grows smarter about you every day. Memory + Cron + Atropos RL

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Lethe044/hermes-life-os with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Lethe044/hermes-life-os'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lethe044--hermes-life-os/badge.svg)](/listings/lethe044--hermes-life-os)

HTML

<a href="/listings/lethe044--hermes-life-os"><img src="/api/listings/lethe044--hermes-life-os/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Works with four LLM backends - pick whichever you already have. The provider is auto-detected from whatever key is set (or force one with `--provider`).

pip install "hermes-life-os[all]"

# Option A - free, fully local, no API key:
ollama serve
ollama pull llama3.1

# Option B / C / D - pick one:
set ANTHROPIC_API_KEY=sk-ant-...
set OPENAI_API_KEY=sk-...
set OPENROUTER_API_KEY=sk-or-...

hermes-life-os --mode onboard
hermes-life-os --mode morning
hermes-life-os --mode chat

# force a specific backend regardless of which keys are set:
hermes-life-os --mode morning --provider anthropic

Prefer running from source instead of installing? Clone the repo and use `python demo/demo_life_os.py ...` in place of `hermes-life-os ...` above (same flags, same behavior) - see [Project Structure](#project-structure).

Or run it with Docker - zero Python setup

# pull the pre-built image - no clone needed:
docker run --rm -it -e ANTHROPIC_API_KEY=sk-ant-... \
    -v hermes-life-os-data:/root/.hermes \
    ghcr.io/lethe044/hermes-life-os:latest --mode morning

Or build it yourself, and get a fully free trial paired with a local Ollama container (no API key at all):

git clone https://github.com/Lethe044/hermes-life-os.git
cd hermes-life-os

docker compose up -d ollama
docker compose exec ollama ollama pull llama3.1
docker compose run --rm hermes-life-os --mode onboard

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 2,419 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/images/social-preview.png" alt="Hermes Life OS: the personal OS that remembers, plans and grows with you" width="720">
  3. </p>
  4. # Hermes Life OS 🧠
  5. [![Tests](https://github.com/Lethe044/hermes-life-os/actions/workflows/tests.yml/badge.svg)](https://github.com/Lethe044/hermes-life-os/actions/workflows/tests.yml)
  6. [![PyPI](https://img.shields.io/pypi/v/hermes-life-os)](https://pypi.org/project/hermes-life-os/)
  7. [![Python Versions](https://img.shields.io/pypi/pyversions/hermes-life-os)](https://pypi.org/project/hermes-life-os/)
  8. [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  9. [![GitHub stars](https://img.shields.io/github/stars/Lethe044/hermes-life-os?style=flat&color=yellow)](https://github.com/Lethe044/hermes-life-os/stargazers)
  10. [![Last commit](https://img.shields.io/github/last-commit/Lethe044/hermes-life-os)](https://github.com/Lethe044/hermes-life-os/commits/main)
  11. **The personal OS that grows with you.** Track how you feel, plan your day, keep your life
  12. organised, and let an agent connect the dots. Local first, encrypted if you want, no account needed.
  13. [Quick start](#quick-start) · [Tool reference](docs/TOOLS.md) · [Command line](docs/CLI.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
  14. > Built for the NousResearch "Show us what Hermes Agent can do" hackathon.
  15. ## Quick Tour
  16. Ask in plain language; Hermes calls the right tool and answers from your own data.
  17. <p align="center">
  18. <img src="docs/images/demo.svg" alt="Hermes planning a day around free time and showing a life wheel" width="760">
  19. </p>
  20. | You want to | Say something like | Tool |
  21. | --- | --- | --- |
  22. | Test a habit on yourself | "no coffee after 2pm for 14 days, watch my sleep" | `start_experiment` |
  23. | Set a rule that warns you | "warn me if sleep stays below 6 hours for 3 days" | `add_tripwire` |
  24. | Budget your week | "at least 10 hours of deep work a week" | `set_time_budget` |
  25. | Check your estimates | "how good am I at estimating?" | `get_estimate_accuracy` |
  26. | See if the week is too full | "can I do everything due this week?" | `get_workload_forecast` |
  27. | Look back at what happened | "what did I get done in the last two weeks?" | `get_life_timeline` |
  28. | Pick today's focus | "my top three today are the report, the gym and calling mum" | `add_priority` |
  29. | Get a plan | "plan my day" | `plan_my_day` |
  30. | Check in on your life | "rate my health 7 and money 3" | `log_life_wheel` |
  31. | Keep a backlog | "add Dune to my books" | `add_library_item` |
  32. | Use your own calendar app | "export my calendar" | `export_calendar` |
  33. | Empty your head | "remind me to look into cello lessons" | `add_to_inbox` |
  34. | Close the week | "start my weekly review" | `start_weekly_review` |
  35. | Learn something for good | "quiz me on my Spanish cards" | `review_flashcards` |
  36. | See the money picture | "what is my net worth?" | `get_net_worth` |
  37. | Move a big goal forward | "start a project: launch the website" | `add_project` |
  38. | Stop forgetting follow-ups | "I am waiting for a quote from the plumber" | `add_waiting` |
  39. | Undo a mistake | "put the rent task back" | `restore_deleted` |
  40. | Understand yourself | "what affects my sleep?" | `get_correlations` |
  41. All 313 tools are listed in the [tool reference](docs/TOOLS.md).
  42. ## Contents
  43. - **Start here:** [What it does](#what-it-does) · [Architecture](#architecture) · [Quick start](#quick-start) · [Chat mode](#chat-mode)
  44. - **Your data:** [Encryption](#encryption-at-rest-optional) · [Automatic backups](#automatic-backups) · [Restore](#restore) · [Health check](#health-check-doctor) · [Data export](#data-export)
  45. - **Planner:** [Tasks, agenda](#planner-tasks-body-metrics-subscriptions-people--todays-agenda) · [Priorities, plan my day, life wheel, library](#daily-priorities-plan-my-day-life-wheel-library--calendar-export) · [Inbox, weekly review](#inbox--weekly-review) · [Flashcards, net worth](#flashcards--net-worth) · [Projects, waiting for](#projects--waiting-for) · [Experiments, tripwires, foresight](#experiments-tripwires--foresight) · [Time blocks, objectives, recipes, trips](#time-blocks-objectives-recipes--trips) · [Chores, routines, decisions](#chores-expiry-dates-routines-gift-ideas--decisions) · [Recently deleted](#recently-deleted-recommendation-ledger--pinned-backups)
  46. - **Insights:** [Pattern detection](#pattern-detection) · [Life review](#life-review---the-flagship-retrospective-report) · [Dashboard](#dashboard)
  47. - **Connect:** [Telegram](#telegram-bot) · [Discord](#discord-bot) · [Slack](#slack-bot) · [Local REST API](#local-rest-api) · [Plugins](#plugin-system-add-your-own-tools-no-fork-required)
  48. - **Project:** [Project structure](#project-structure) · [What's new](#whats-new) · [Running tests](#running-tests)
  49. ## What It Does
  50. Tell it how you feel. Log what you ate. Track your sleep.
  51. Over time it starts connecting dots you haven't: energy crashes after poor sleep,
  52. mood dips on low-hydration days, focus drops when stress spikes.
  53. Every morning it briefs you. Every evening it reflects with you.
  54. Every week it tells you what the data says about your life.
  55. **The longer you use it, the more it knows. The more it knows, the more useful it becomes.**
  56. ## Architecture
  57. ```mermaid
  58. flowchart TD
  59. A([👤 You share something]) --> B
  60. B[🧠 REMEMBER<br/>Mood · Sleep · Meals<br/>Stress · Focus · Habits] --> C
  61. C[🔍 RECALL<br/>Search memory<br/>for context] --> D
  62. D[📊 DETECT PATTERNS<br/>Correlations across<br/>all life dimensions] --> E
  63. E[📋 BRIEF<br/>Personalized insight<br/>based on YOUR data] --> F
  64. F([🌱 Hermes knows you<br/>a little better today])
  65. G([⏰ Cron Schedule<br/>07:00 Morning<br/>12:00 Midday<br/>18:00 Evening<br/>23:00 Consolidate<br/>Mon 08:00 Weekly]) --> C
  66. style A fill:#2980b9,color:#fff
  67. style F fill:#27ae60,color:#fff
  68. style G fill:#8e44ad,color:#fff
  69. style D fill:#e67e22,color:#fff
  70. ```
  71. ## Hermes Features Used
  72. | Feature | How It's Used |
  73. |---------|--------------|
  74. | **Memory** | Stores every mood, meal, sleep entry, workout, stress log - recalls before every response |
  75. | **Skills** | Life OS playbook defines daily rhythm, pattern detection rules, and briefing format |
  76. | **Cron** | Automated briefings at 07:00, 12:00, 18:00, 23:00, and weekly Monday reviews |
  77. | **Gateway** | Delivers briefings via terminal - extensible to Telegram, email, SMS |
  78. | **Subagents** | Pattern detection runs across all health dimensions in parallel |
  79. | **Atropos RL** | Reward function trains Hermes to be more personal and memory-driven over time |
  80. ## Tracking Capabilities
  81. | Category | What Hermes Tracks |
  82. |----------|-------------------|
  83. | 🥗 Nutrition | Meals, calories, protein/carbs/fat, daily totals |
  84. | 😴 Sleep | Duration, quality score, 7-day averages |
  85. | 💧 Hydration | Daily water intake with progress bar |
  86. | 💪 Fitness | Workouts, duration, intensity, weekly count |
  87. | 🧘 Mental | Stress levels, meditation sessions, gratitude logs |
  88. | 🎯 Focus | Deep work sessions, distractions, quality scores |
  89. | ✅ Habits | Streaks, best streaks, completion tracking |
  90. | 🎯 Goals | Progress percentages, milestones, notes |
  91. | 😊 Mood & Energy | Daily scores, trend detection, dip alerts |
  92. | 💰 Spending | Expenses by category, daily/period totals |
  93. | 🤝 Social | Time connecting with others, quality, trend |
  94. | ☕ Substances | Caffeine, alcohol, or anything else - amount, frequency |
  95. | 📚 Reading | Sessions, minutes, pages, titles |
  96. | 💊 Medication | Dose taken/skipped, adherence % by medication |
  97. ## Pattern Detection
  98. Hermes automatically detects and surfaces:
  99. - Mood dips lasting 3+ consecutive days
  100. - Sleep deprivation affecting focus and mood
  101. - Energy crashes correlated with nutrition gaps
  102. - Stress spikes and their triggers
  103. - Habit streaks worth celebrating
  104. - Goal stalls that need a nudge
  105. - Hydration gaps on high-stress days
  106. ### Correlation Engine
  107. `demo/analytics.py` computes real Pearson correlation coefficients between
  108. tracked metrics (mood, sleep, stress, energy, hydration) using daily-averaged
  109. values from memory. A pair is only surfaced when there's enough data
  110. (4+ overlapping days by default) and the relationship is meaningful
  111. (|r| >= 0.4). Each result reports the direction (positive/negative), strength
  112. (weak/moderate/strong), and the number of days behind it - no external
  113. dependencies required (pure Python stdlib).
  114. **Lagged (predictive) correlations:** same-day correlation can't tell you
  115. whether poor sleep caused today's low mood, or whether being stressed
  116. already caused last night's poor sleep - it just says the two move
  117. together. `compute_lagged_correlations()` shifts one metric forward by
  118. 1-2 calendar days (correctly handling gaps from unlogged days) before
  119. correlating, which at least points the arrow of time forward: "a higher
  120. X on one day tends to be followed by a higher/lower Y N days later."
  121. Both same-day and lagged results feed every surface that already shows
  122. insights (chat replies, `detect_patterns`, the static and live
  123. dashboards, the weekly email) automatically, plus a dedicated
  124. `get_correlation_insights` tool for a deeper, on-demand analysis over
  125. a custom day range - just ask "what patterns have you noticed in my
  126. data?" or "what predicts my mood?".
  127. ## Reward Function
  128. ```mermaid
  129. pie title Life OS Reward Components
  130. "Briefing Sent - Delivered via send_briefing?" : 30
  131. "Memory Used - Recalled AND remembered?" : 25
  132. "Pattern Detected - Called detect_patterns?" : 20
  133. "Personalization - Referenced real context?" : 15
  134. "Tool Coverage - Used expected tools?" : 10
  135. ```
  136. ## Quick Start
  137. Works with four LLM backends - pick whichever you already have. The
  138. provider is auto-detected from whatever key is set (or force one with
  139. `--provider`).
  140. ```bash
  141. pip install "hermes-life-os[all]"
  142. # Option A - free, fully local, no API key:
  143. ollama serve
  144. ollama pull llama3.1
  145. # Option B / C / D - pick one:
  146. set ANTHROPIC_API_KEY=sk-ant-...
  147. set OPENAI_API_KEY=sk-...
  148. set OPENROUTER_API_KEY=sk-or-...
  149. hermes-life-os --mode onboard
  150. hermes-life-os --mode morning
  151. hermes-life-os --mode chat
  152. # force a specific backend regardless of which keys are set:
  153. hermes-life-os --mode morning --provider anthropic
  154. ```
  155. Prefer running from source instead of installing? Clone the repo and use
  156. `python demo/demo_life_os.py ...` in place of `hermes-life-os ...` above
  157. (same flags, same behavior) - see [Project Structure](#project-structure).
  158. ### Use it without an AI model
  159. Every tool also runs straight from the shell, with no language model and no API key:
  160. ```bash
  161. hermes-life-os-tool run add_task text="Pay rent" due=friday priority=high
  162. hermes-life-os-tool run plan_my_day
  163. hermes-life-os-tool list --match calendar
  164. ```
  165. See [docs/CLI.md](docs/CLI.md) for arguments, scripting and cron examples.
  166. ### Or run it with Docker - zero Python setup
  167. ```bash
  168. # pull the pre-built image - no clone needed:
  169. docker run --rm -it -e ANTHROPIC_API_KEY=sk-ant-... \
  170. -v hermes-life-os-data:/root/.hermes \
  171. ghcr.io/lethe044/hermes-life-os:latest --mode morning
  172. ```
  173. Or build it yourself, and get a fully free trial paired with a local
  174. Ollama container (no API key at all):
  175. ```bash
  176. git clone https://github.com/Lethe044/hermes-life-os.git
  177. cd hermes-life-os
  178. docker compose up -d ollama
  179. docker compose exec ollama ollama pull llama3.1
  180. docker compose run --rm hermes-life-os --mode onboard
  181. ```
  182. ## All Demo Modes
  183. | Mode | What Happens |
  184. |------|-------------|
  185. | `onboard` | First-time setup - Hermes learns who you are |
  186. | `morning` | Daily briefing based on all your patterns |
  187. | `checkin` | Midday log - mood, habits, quick nudge |
  188. | `evening` | Evening reflection - wins, struggles, patterns |
  189. | `weekly` | Sunday review - what this week says about you |
  190. | `nutrition` | Log meals and get nutrition insights |
  191. | `sleep` | Log sleep and get sleep analysis |
  192. | `fitness` | Log workouts and track fitness patterns |
  193. | `mental` | Log stress, meditation, and gratitude |
  194. | `focus` | Log deep work sessions and productivity |
  195. | `health` | Full health dashboard - all data in one view |
  196. | `dream` | **Dream journal** - log dreams, detect patterns, sleep/stress correlation |
  197. | `chat` | **Interactive conversation** - type anything |
  198. ## Chat Mode
  199. ```bash
  200. python demo/demo_life_os.py --mode chat
  201. ```
  202. Type naturally. Hermes responds using everything it knows about you.
  203. Type `exit` to leave.
  204. Example conversations:
  205. - "I feel stressed today, any advice?"
  206. - "Log my lunch - grilled chicken and rice, about 600 calories"
  207. - "How has my sleep been this week?"
  208. - "I just ran 5km, log it"
  209. - "What patterns are you seeing in my data?"
  210. - "I logged 4 hours of sleep by mistake, it was actually 7" - Hermes recalls
  211. the entry and corrects it
  212. - "Delete that last mood entry, I misclicked" - Hermes finds and removes it
  213. (asks for confirmation first)
  214. - "Set a goal to sleep 7+ hours a night" - Hermes tracks this automatically
  215. from your actual logged sleep, no manual progress updates needed
  216. - "How am I doing on my goals?" / "How does this week compare to last week?"
  217. - "Has anything been unusual lately?" / "How was I in March?"
  218. ## Multi-Profile (shared households)
  219. ```bash
  220. python demo/demo_life_os.py --mode morning --profile alex
  221. python demo/dashboard.py --profile alex
  222. ```
  223. By default everything lives at `~/.hermes/life-os/` (unchanged, single
  224. person). Passing `--profile <name>` (or setting `LIFE_OS_PROFILE`) fully
  225. isolates that person's data under `~/.hermes/life-os/profiles/<name>/` -
  226. so a household can share one install without mixing anyone's mood/sleep/
  227. habit data. Omitting `--profile` always keeps working exactly as before.
  228. ## Multi-User (real accounts for the local API & Slack bot)
  229. ```bash
  230. python demo/users.py add alex --profile alex --role owner
  231. python demo/users.py add sam --profile sam
  232. python demo/users.py list
  233. ```
  234. Profiles isolate data; this registry is what turns a profile into a
  235. *person who can log in*. Each user gets their own API key (shown once,
  236. stored only as a salted PBKDF2 hash) that resolves to their own profile
  237. automatically - so a whole household or small team can share one running
  238. `hermes-life-os-api` server or one Slack bot, and everyone only ever
  239. sees their own data:
  240. ```bash
  241. curl -H "X-API-Key: <alex's key>" http://127.0.0.1:8765/api/health
  242. # {"status": "ok", "profile": "alex", "user": "alex"}
  243. ```
  244. Fully opt-in and non-breaking - a single `LIFE_OS_API_KEY`/`--profile`
  245. keeps working exactly as before if you never touch `users.py`. Full
  246. setup, including linking a user to their Slack account, in
  247. [docs/MULTI_USER.md](docs/MULTI_USER.md).
  248. ## Plugin System (add your own tools, no fork required)
  249. ```bash
  250. mkdir -p ~/.hermes/life-os/plugins
  251. cp demo/plugins_examples/dice.py ~/.hermes/life-os/plugins/
  252. python demo/demo_life_os.py --mode chat
  253. # "roll a d20 for me"
  254. ```
  255. Drop a `.py` file defining a `TOOLS` list and a `dispatch(name, inp)`
  256. function into `~/.hermes/life-os/plugins/`, and Hermes' LLM agent can
  257. call it like any built-in tool - next start, no core code changes. A
  258. broken plugin is skipped and reported, never crashes the app; a plugin
  259. can't shadow a built-in tool name. `python demo/plugins.py` lists
  260. everything currently loaded. Two ready-to-copy examples ship in
  261. `demo/plugins_examples/` (a dependency-free dice/coin-flip tool, and a
  262. profile-aware screen-time tracker showing how to persist your own data).
  263. Full plugin API and a "share it with others" guide in
  264. [docs/PLUGINS.md](docs/PLUGINS.md).
  265. ## Encryption at Rest (optional)
  266. ```bash
  267. set LIFE_OS_ENCRYPTION_KEY=your-passphrase-here
  268. python demo/demo_life_os.py --mode morning
  269. ```
  270. Off by default - nothing changes unless you set this. When set, every
  271. data file (profile, habits, goals, nutrition, sleep, etc.) and every line
  272. of `memory.jsonl` is encrypted at rest with a key derived from your
  273. passphrase (PBKDF2-HMAC-SHA256 + Fernet/AES). Existing plaintext data is
  274. read transparently and gets encrypted the next time it's written - no
  275. separate migration step. **There is no password recovery** - if you lose
  276. the passphrase, that data is unrecoverable by design. Requires
  277. `pip install "hermes-life-os[encryption]"` (or `pip install cryptography`
  278. if running from source).
  279. **Changing your passphrase:** use `hermes-life-os-rekey` rather than
  280. just setting a new `LIFE_OS_ENCRYPTION_KEY` - the latter would leave
  281. your existing files encrypted under the *old* key, unreadable. The
  282. re-key tool decrypts everything with the old key, rotates the salt, and
  283. re-encrypts everything with the new one in one step (it also works to
  284. enable encryption for the first time, or disable it entirely):
  285. ```bash
  286. hermes-life-os-backup # back up first
  287. hermes-life-os-rekey --old-key "old pass" --new-key "new pass"
  288. hermes-life-os-rekey --new-key "new pass" # enable for the first time
  289. hermes-life-os-rekey --disable # decrypt everything back to plaintext
  290. ```
  291. As of v1.38.0 re-keying covers every data store (spending, social,
  292. substance, reading, medication, achievements, templates, budgets and
  293. reminders as well as the original nine). Before that fix it only
  294. re-encrypted nine files, so after a passphrase change the others could no
  295. longer be decrypted and silently read back as empty. Backups written while
  296. a passphrase is set are encrypted too (see "Automatic Backups").
  297. ## Time Blocks, Objectives, Recipes & Trips
  298. Five more stores plus three read-only helpers, all local, per profile,
  299. encrypted with the rest of your data when encryption is on, and covered by
  300. backup, restore, export and the doctor.
  301. ```
  302. "block 9 to 10:30 tomorrow for deep work" "when am I free for 45 minutes?"
  303. "schedule the report task this week" "how did I spend my week?"
  304. "objective for Q4: run 100 km" "I ran 12 km today"
  305. "save my lentil soup recipe" "plan soup for dinner on Friday"
  306. "make a shopping list from the meal plan" "trip to Rome Nov 1 to Nov 4"
  307. "what triggers my headaches?" "find everything about Rome"
  308. ```
  309. - **Time blocks** (`add_time_block`, `get_day_plan`, `update_time_block`,
  310. `delete_time_block`, `finish_time_block`, `find_free_time`, `schedule_task`,
  311. `get_time_allocation`): put work on the clock. Overlaps are refused, the day
  312. plan shows blocks and free gaps (07:00 to 22:00), `find_free_time` lists the
  313. first free slots, `schedule_task` places a task in the first slot that fits
  314. and the allocation report shows where the hours went by category. Finishing a
  315. block can complete its task. A block starting within 15 minutes is nudged.
  316. - **Objectives and key results** (`add_objective`, `add_key_result`,
  317. `record_key_result`, `get_okrs`, `update_okr`, `delete_okr`): an objective for
  318. a week, month, quarter (`2026-Q4`) or year with measurable key results
  319. (upward or downward targets). Progress is compared with the share of the
  320. period that has passed: ahead of pace, on track, slightly behind or behind.
  321. Objectives ending within a week below 70% are nudged and shown in the agenda.
  322. - **Recipes and meal plan** (`add_recipe`, `get_recipes`, `get_recipe`,
  323. `update_recipe`, `delete_recipe`, `suggest_recipes`, `plan_meal`,
  324. `get_meal_plan`, `clear_meals`, `log_planned_meal`, `shopping_from_plan`):
  325. recipes scale to any serving count, `suggest_recipes` surfaces what you have
  326. not cooked lately, planned meals can repeat on several days, logging a
  327. planned meal creates the meal entry, and `shopping_from_plan` adds the
  328. combined ingredients to your shopping list (skipping what is already there).
  329. - **Trips** (`add_trip`, `get_trips`, `get_trip`, `update_trip`, `delete_trip`,
  330. `add_packing_items`, `pack_items`, `remove_packing_items`,
  331. `add_itinerary_item`, `remove_itinerary_item`): dates, budget, a packing list
  332. from a template (basic, documents, flight, city, beach, hiking, winter,
  333. business) and a day-by-day itinerary. A trip within three days with unpacked
  334. items is nudged; an ongoing trip shows today's plan in the agenda.
  335. - **Symptom triggers** (`get_symptom_triggers`): compares your symptom days with
  336. sleep, stress, water, caffeine, alcohol, nicotine and workouts of the day
  337. before, plus triggers you named yourself. Patterns in your own data, not
  338. causes and not medical advice.
  339. - **Search everything** (`search_everything`): one search over tasks, notes,
  340. lists, people, subscriptions, savings, debts, countdowns, supplies, symptoms,
  341. recipes, the meal plan, trips, objectives, time blocks, reminders, habits and
  342. goals, with the id to use next to every hit.
  343. - **Closing summary** (`get_closing_summary`): an end-of-day or end-of-week
  344. review of what got done, what was logged, what is still open and what is next.
  345. - **Repair suggestions** (`get_repair_suggestions`): for each problem the doctor
  346. finds in planner data, the exact tool call that fixes it. Read-only.
  347. The proactive nudges and `get_today_agenda` include the new sources, and the
  348. doctor checks the five new stores (blocks, objectives, recipes and planned
  349. meals it cannot read, trips with unusable dates, shared ids).
  350. ## Chores, Expiry Dates, Routines, Gift Ideas & Decisions
  351. Five more stores and a combined calendar, all local, per profile, encrypted
  352. with the rest of your data when encryption is on, and covered by backup,
  353. restore, export, rekey and the doctor.
  354. ```
  355. "water the plants every week" "I watered them"
  356. "my passport expires 2027-03-01" "I renewed my insurance for 12 months"
  357. "morning routine: water, stretch, journal" "tick stretch"
  358. "a poetry book for Ayse" "I bought the scarf"
  359. "I chose the standing desk, review in a month" "how did the desk decision turn out?"
  360. "what is coming up this week?"
  361. ```
  362. - **Chores** (`add_chore`, `complete_chore`, `get_chores`, `update_chore`,
  363. `delete_chore`): anything that repeats on a schedule (every 10 days, weekly,
  364. every 3 months, yearly). The next due date counts from the day it was
  365. done, so a late chore never piles up. Overdue and due-today chores are
  366. nudged and shown in the agenda.
  367. - **Expiry dates** (`add_expiry`, `get_expiries`, `renew_expiry`,
  368. `update_expiry`, `delete_expiry`): a passport, a licence, insurance, a
  369. warranty. Each has a reminder window (30 days by default); inside it the item
  370. is nudged and listed in the agenda. Renewing moves the date forward (a new
  371. date, or a number of months) and keeps a history.
  372. - **Routines** (`add_routine`, `get_routines`, `check_routine_step`,
  373. `update_routine`, `delete_routine`): named checklists with their own
  374. schedule (daily, weekdays, weekends or chosen days). Tick steps per day (or
  375. `all`), see the streak of fully done days (days a routine is not scheduled
  376. do not break it) and find unfinished routines in the agenda.
  377. - **Gift ideas** (`add_gift_idea`, `get_gift_ideas`, `update_gift_idea`,
  378. `delete_gift_idea`): ideas per person with price and occasion, marked idea,
  379. bought or given. Names from your people list link to their birthday: the list
  380. shows birthdays with no gift bought yet, and a birthday within a week with
  381. saved ideas but nothing bought is nudged.
  382. - **Decisions** (`add_decision`, `get_decisions`, `review_decision`,
  383. `update_decision`, `delete_decision`): the options, the choice, why, what you
  384. expect and how confident you are, with a review date (30 days by default).
  385. When it arrives Hermes asks how it went; reviewed decisions show how your
  386. confidence compares with the outcomes.
  387. - **Week ahead** (`get_week_ahead`): one calendar for 1 to 14 days over due
  388. tasks, time blocks, planned meals, birthdays, renewals, debts, countdowns,
  389. chores, expiry dates, trips and decisions to review, with overdue items first.
  390. `search_everything` now covers the five new stores, the closing summary shows
  391. chores and decisions that are waiting, and `get_repair_suggestions` and the
  392. doctor check them (a chore interval it cannot read, an expiry date or review
  393. date that is not a date, a routine without steps, an unknown gift status,
  394. shared ids).
  395. ## Recently Deleted, Recommendation Ledger & Pinned Backups
  396. Three safety nets, all local, per profile, encrypted with the rest of your data
  397. when encryption is on, and covered by backup, restore, export and the doctor.
  398. ```
  399. "I deleted the wrong task" "what did I delete this week?"
  400. "put the rent task back" "empty the trash"
  401. "which recommendations did I follow?" "I followed the sleep suggestion"
  402. "keep today's backup for good"
  403. ```
  404. - **Recently deleted** (`get_trash`, `restore_deleted`, `empty_trash`): what
  405. the planner's delete and clear tools remove is kept for 30 days. This covers
  406. whole tasks, notes, people, subscriptions, savings goals, debts, countdowns,
  407. supplies, time blocks, objectives, recipes, planned meals, trips, chores,
  408. expiry dates, routines, gift ideas, decisions and list items (also
  409. `clear_done_tasks`, `clear_checked_items`, `remove_list_items`, `delete_list`
  410. and `clear_meals`). One delete or clear is one trash entry; restoring it puts
  411. all of its entries back. Not covered: logged entries (use `undo_last_log`),
  412. parts of an entry (a key result, a packing item) and habits, goals, budgets,
  413. reminders and templates. `empty_trash` removes one item, everything older than
  414. N days or all of it for good.
  415. - **Recommendation ledger** (`get_recommendation_history`,
  416. `mark_recommendation`): every suggestion `get_recommendations` gives is filed
  417. with when it first appeared and how often. Mark one followed or skipped. For
  418. suggestions built on a daily average (sleep, hydration, stress) the ledger
  419. later compares that metric in the week before with the days after, with
  420. "moving the right way" or "about the same". It is arithmetic on your own logs,
  421. not proof of cause and not medical advice. An open suggestion that has not
  422. appeared for 30 days closes itself.
  423. - **Pinned backups** (`pin_backup`, `unpin_backup`): a pinned backup is never
  424. rotated away and does not count towards the keep limit (at most 10 pins).
  425. `get_backup_status` lists them. Pin one before a big clean-up.
  426. The doctor and `get_repair_suggestions` check the trash and the ledger, and
  427. `search_everything` searches the ledger.
  428. ## Daily Priorities, Plan My Day, Life Wheel, Library & Calendar Export
  429. ```
  430. "my priorities today: finish the report, gym, call mum" "plan my day"
  431. "I finished the report" "move yesterday's priorities to today"
  432. "rate my life: health 7, career 8, money 3" "how is my life wheel?"
  433. "add Severance to my shows" "I finished Dune, 5 stars" "what should I read next?"
  434. "export my calendar"
  435. ```
  436. - **Priorities**: at most three a day, free text or an open task. Completing a priority also
  437. completes its task. Hermes nudges you in the afternoon when some are still open.
  438. - **Plan my day**: priorities first, then overdue and due tasks, each placed in a free gap of your
  439. time blocks using the task's `minutes` estimate (30 by default). The default is a dry run;
  440. `apply=true` saves time blocks. Tasks already planned are never placed twice.
  441. - **Life wheel**: health, career, money, relationships, growth, fun, environment and purpose, each
  442. 1 to 10, with bars, the change since the previous check-in and the lowest areas.
  443. - **Library**: books, movies, shows, games, podcasts and courses with status (want, doing, done,
  444. dropped), progress, a 1 to 5 rating, a suggestion for what to pick up next and yearly stats.
  445. - **Calendar export**: an `.ics` file in your exports folder with time blocks, task due dates,
  446. birthdays (repeating yearly), countdowns, trips, expiry dates, chores, renewals and decision
  447. reviews. Event ids are stable, so re-importing updates events instead of duplicating them.
  448. Import it in Google Calendar (Settings > Import & export), Apple Calendar or Outlook.
  449. All three new stores are included in backup, restore, export, the doctor, search and the
  450. recently deleted list.
  451. ## Inbox & Weekly Review
  452. ```
  453. "inbox: look into cello lessons" "what's in my inbox?"
  454. "make the cello one a task for Friday" "drop the lamp idea"
  455. "start my weekly review" "save my review: wins shipped v1.49, focus on scales and taxes"
  456. ```
  457. - **Inbox**: capture first, decide later. `process_inbox_item` turns an item into a task (with
  458. due date, priority and minutes), a note, a library item or a priority, and removes it from
  459. the inbox only when the new entry was created.
  460. - **Weekly review**: shows the last seven days (finished tasks, priorities done, time blocks,
  461. overdue, unsorted inbox, the life wheel's lowest areas) and what you planned to focus on last
  462. week, then saves your wins, lessons, rating and next week's focus. `create_tasks=true` turns
  463. the focus items into tasks due next Monday.
  464. ## Flashcards & Net Worth
  465. ```
  466. "add flashcards: casa = house, perro = dog (deck spanish)" "quiz me"
  467. "I knew that one" "how are my flashcards doing?"
  468. "my savings account is 4200" "my loan is 1800 (liability)" "what is my net worth?"
  469. "show my net worth trend for 12 months"
  470. ```
  471. - **Flashcards**: Leitner boxes 1 to 5 with return intervals of 1, 3, 7, 16 and 35 days. Hermes
  472. shows the front of the next due card, reveals the back on request and records whether you knew
  473. it. Stats cover cards per deck and box, mastered cards and your accuracy.
  474. - **Net worth**: assets minus liabilities from the balances you record. Every update is kept, so
  475. you get the change since the last update and a month-end trend. Amounts have no currency.
  476. ## Projects & Waiting For
  477. ```
  478. "start a project: launch the website, due December 1" "add a task to the website project: write copy"
  479. "how is the website project going?" "pause the website project"
  480. "I am waiting for the contract from Sam, check in Friday" "I chased Sam, ask again in 3 days"
  481. "the contract arrived" "what am I waiting for?"
  482. ```
  483. - **Projects**: an outcome with a status (active, paused, done), an optional due date and a tag.
  484. Tasks carrying the tag count toward progress; Hermes shows the next action and warns about
  485. overdue projects and active projects with no open task. Deleting a project keeps its tasks.
  486. - **Waiting for**: things you handed to someone else, each with a follow-up date. Due items show
  487. in the agenda and as a nudge; `chase_waiting` records a follow-up and pushes the date out.
  488. ## Experiments, Tripwires & Foresight
  489. ```
  490. "start an experiment: no coffee after 2pm, watch my sleep for 14 days" "how is the coffee experiment going?"
  491. "warn me if my sleep stays below 6 hours for 3 days" "if more than 5 tasks are overdue, tell me to stop adding new ones"
  492. "can I actually do everything due this week?" "what did I get done in the last two weeks?"
  493. ```
  494. - **Experiments**: pick one metric Hermes already tracks and a length. Hermes compares the days
  495. before the start with the days of the experiment and reports both averages, the change, an
  496. effect size and a verdict (better, worse, no clear effect, not enough data). It needs at least
  497. three days with a reading on each side. It is a hint about your own numbers, not proof of
  498. cause. Conclude an experiment to keep its result and your decision (keep, drop, unsure).
  499. - **Tripwires**: a metric, a direction (above or below), a threshold and how many days in a row
  500. it must hold. A tripped wire shows its message in the agenda and as a nudge. Live counts
  501. (`overdue_tasks`, `open_tasks`, `inbox_items`, `overdue_follow_ups`) use the current value.
  502. - **Workload forecast**: minutes of work due per day (30 when a task has no estimate; tasks that
  503. already have a time block are skipped) against free time in the day plan, capped at eight
  504. hours. Overloaded days come with suggested moves. Read-only.
  505. - **Life timeline**: what happened, newest day first. Filter with `kinds` (tasks, priorities,
  506. blocks, library, trips, reviews, wheel, decisions, waiting, experiments, health, focus).
  507. - **Time budgets**: a weekly hour budget per time block category, as a minimum or a limit,
  508. checked against blocks done since Monday and blocks still planned. From Thursday on, a nudge
  509. when one is short or over.
  510. - **Estimate accuracy**: how long finished tasks really took (from focus sessions with the same
  511. task name) against their estimate. With three such tasks the workload forecast scales by it.
  512. ## Project Structure
  513. ```mermaid
  514. graph LR
  515. A[hermes-life-os] --> B[skills/]
  516. A --> C[environments/]
  517. A --> D[demo/]
  518. A --> E[tests/]
  519. A --> F[docs/]
  520. B --> B1[life-os/SKILL.md<br/>Daily rhythm playbook]
  521. C --> C1[life_os_env.py<br/>Atropos RL environment]
  522. C --> C2[life_os_config.yaml<br/>Training config]
  523. D --> D1[demo_life_os.py<br/>CLI / chat / voice orchestration]
  524. D --> D2[storage.py<br/>Persistence layer]
  525. D --> D3[patterns.py<br/>Trend detection]
  526. D --> D4[analytics.py<br/>Pearson correlation engine]
  527. D --> D5[tools.py<br/>dispatch_tool + TOOLS schema]
  528. D --> D6[scheduler.py<br/>Cron-style trigger engine]
  529. D --> D7[notifications.py<br/>console/webhook/Telegram/email]
  530. D --> D8[run_scheduler.py<br/>Production scheduler entry point]
  531. D --> D9[plugins.py<br/>Community tool plugin loader]
  532. D --> D12[life_score.py<br/>Composite 0-100 wellbeing score]
  533. D --> D13[achievements.py<br/>Streak &amp; milestone badges]
  534. D --> D14[wrapped.py<br/>Shareable summary card]
  535. D --> D15[recommendations.py<br/>Rule-based suggestion engine]
  536. D --> D16[weather.py<br/>Open-Meteo weather correlation]
  537. D --> D17[life_review.py<br/>Quarterly/yearly retrospective report]
  538. D --> D18[leaderboard.py<br/>Opt-in household/team leaderboard]
  539. D --> D19[prompts.py<br/>Deterministic daily reflection prompts]
  540. D --> D20[moon.py<br/>Local moon phase correlation]
  541. D --> D21[sleep_debt.py<br/>Sleep debt & bedtime suggestions]
  542. D --> D22[heatmap.py<br/>GitHub-style SVG contribution heatmap]
  543. D --> D23[focus_timer.py<br/>Terminal Pomodoro timer]
  544. D --> D10[users.py<br/>Multi-user registry]
  545. D --> D11[slack_bot.py<br/>Slack Socket Mode bot]
  546. E --> E1[test_life_os_env.py]
  547. E --> E2[test_analytics.py]
  548. E --> E3[test_storage.py]
  549. E --> E4[test_tools.py]
  550. E --> E5[test_scheduler.py]
  551. E --> E6[test_notifications.py]
  552. style B1 fill:#27ae60,color:#fff
  553. style C1 fill:#8e44ad,color:#fff
  554. style D1 fill:#2980b9,color:#fff
  555. style D6 fill:#e67e22,color:#fff
  556. style D7 fill:#e67e22,color:#fff
  557. style D9 fill:#c0392b,color:#fff
  558. style D10 fill:#c0392b,color:#fff
  559. style D11 fill:#c0392b,color:#fff
  560. ```
  561. `demo_life_os.py` used to be a single ~1600-line file. It's now a thin
  562. CLI/chat/voice orchestration layer that imports its storage, pattern
  563. detection, and tool-dispatch logic from focused sibling modules -
  564. each independently testable and reusable.
  565. ## Scheduling & Notifications
  566. `demo/scheduler.py` implements the "Daily Rhythm" cron table from
  567. `skills/life-os/SKILL.md` (07:00 morning, 12:00 midday, 18:00 evening,
  568. Monday 08:00 weekly, 20:00 proactive nudge check) as a dependency-free
  569. polling loop. The scheduling logic itself (`due_entries`) is pure and
  570. fully unit tested; the actual briefing generation and delivery are
  571. injected as callables, so the core engine has no dependency on the
  572. OpenAI client or network access. The 20:00 nudge check is LLM-free
  573. (see "Proactive Nudges" above) and stays silent when there's nothing
  574. worth flagging.
  575. Since v1.37.0 the scheduler loop also accepts a `dynamic_source` hook for
  576. things that are not a fixed (time, mode) pair. `run_scheduler.py` plugs
  577. in `reminders.scheduler_source`, so every timed reminder you create with
  578. `create_reminder` is delivered through the same notification channel at
  579. its saved time (see "Reminders" below), at most once per day, and a
  580. failing source or notifier never stops the loop.
  581. `demo/notifications.py` delivers briefings through a pluggable channel,
  582. selected via `HERMES_NOTIFY_CHANNEL`: `console` (default), `webhook`,
  583. `telegram`, or `email` (SMTP). All channels are stdlib-only. A failed
  584. remote channel never crashes the scheduler - it's caught, logged, and
  585. the briefing still prints to console.
  586. To run the scheduler in production:
  587. ```bash
  588. set ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY / OPENROUTER_API_KEY / a running ollama
  589. set HERMES_NOTIFY_CHANNEL=telegram
  590. set TELEGRAM_BOT_TOKEN=...
  591. set TELEGRAM_CHAT_ID=...
  592. python demo/run_scheduler.py
  593. ```
  594. ## Voice Mode
  595. ```bash
  596. python demo/demo_life_os.py --voice
  597. # or pin a backend/model explicitly:
  598. python demo/demo_life_os.py --voice --provider anthropic --model claude-sonnet-5
  599. ```
  600. Speak to Hermes directly. It listens via microphone, processes your input using
  601. everything it knows about you, and responds out loud via system TTS.
  602. No extra API key needed - uses built-in Windows/Linux speech synthesis.
  603. To stop: say or type `exit`
  604. ---
  605. ## Dashboard
  606. ```bash
  607. pip install "hermes-life-os[dashboard]" # or: pip install matplotlib (running from source)
  608. hermes-life-os-dashboard
  609. hermes-life-os-dashboard --days 60 --compare-days 7 --out my-report.html
  610. ```
  611. Turns your logged mood/sleep/stress/energy/hydration data and the
  612. correlations Hermes already detects (e.g. "poor sleep tracks with lower
  613. mood, r=0.62") into a single self-contained HTML report with charts -
  614. opens straight in your browser, no server, nothing leaves your machine.
  615. Needs no LLM/API key at all - it's pure local data analysis. Includes a
  616. retrospective section comparing this week to last week (`--compare-days`
  617. changes the window size), color-coded by whether the change is favorable -
  618. a stress increase shows red, a mood increase shows green.
  619. ![Example dashboard trend chart](docs/images/dashboard-example.png)
  620. *Example output from 28 days of sample data - your own chart will reflect
  621. whatever you've actually logged.*
  622. ## Live Web Dashboard
  623. ```bash
  624. pip install "hermes-life-os[web]" # or: pip install flask
  625. hermes-life-os-web
  626. # open http://127.0.0.1:8080
  627. ```
  628. The interactive, always-current counterpart to the static HTML report
  629. above - same trends/correlations/retrospective/habit data, served as
  630. JSON and rendered client-side with Chart.js, so switching the day-range
  631. re-fetches and re-draws instantly instead of regenerating a file.
  632. Localhost-only by default and read-only (no API key needed, unlike the
  633. Local REST API below) - it only ever reads your own data for your own
  634. browser. See `demo/web_dashboard.py`'s docstring before changing
  635. `--host` beyond `127.0.0.1`.
  636. ## Goal Tracking
  637. Goals can track themselves from real data instead of needing manual
  638. progress updates - just tell Hermes what to track:
  639. - "Set a goal to sleep 7+ hours a night" -> auto-tracks against your
  640. logged sleep, direction "at_least"
  641. - "Set a goal to keep stress under 4" -> direction "at_most"
  642. - "How am I doing on my goals?" -> recomputes and reports current progress
  643. Progress is the average of the linked metric over a rolling window
  644. (7 days by default) relative to the target, clamped to 0-100%. Goals
  645. without a linked metric keep working exactly as before - a plain
  646. percentage you update manually.
  647. ## Health Data Import
  648. ```bash
  649. pip install hermes-life-os
  650. hermes-life-os-import --apple-health export.xml
  651. hermes-life-os-import --csv my_data.csv
  652. hermes-life-os-import --csv my_data.csv --dry-run # preview without writing
  653. ```
  654. Reduces manual one-entry-at-a-time logging by bulk-importing data you
  655. already have, with real historical dates preserved (not stamped "today"):
  656. - **Apple Health** (`export.xml` from Health app -> profile icon -> Export
  657. All Health Data): imports Sleep Analysis and Dietary Water records,
  658. aggregated per day.
  659. - **Generic CSV**: any file with a `date` column (YYYY-MM-DD) plus any
  660. subset of `sleep_hours, mood, stress, energy, hydration` columns - works
  661. for a Google Fit CSV export or your own spreadsheet.
  662. Imported entries are tagged so they're distinguishable from entries
  663. logged live through chat.
  664. ## Calendar Import (meeting load vs. mood/stress)
  665. ```bash
  666. hermes-life-os-calendar --ics calendar.ics
  667. hermes-life-os-calendar --ics calendar.ics --dry-run
  668. ```
  669. Correlates meeting-heavy days with mood/stress/sleep - no OAuth or live
  670. API needed, just a standard `.ics` export (Google Calendar: Settings ->
  671. Import & export -> Export; Outlook: File -> Save Calendar; Apple
  672. Calendar: File -> Export). Only timed events count toward meeting hours
  673. (all-day events are skipped); recurring events count once, on their
  674. start date. Once imported, ask Hermes "is my stress linked to
  675. meeting-heavy days?" or check the dashboard's Correlations section.
  676. ## Deeper Analysis: Anomalies & Before/After Comparisons
  677. - "Has anything been unusual lately?" -> flags statistical outlier days
  678. (e.g. "today's stress was far above your normal range")
  679. - "Did starting meditation on March 1st actually help?" -> compares
  680. metric averages before vs. after a specific date, instead of just a
  681. fixed weekly window
  682. - "How was I in March?" / "Summarize last month" -> pulls real averages
  683. and notable entries (gratitude, dreams, notes) for any date range you
  684. ask about
  685. ## Proactive Nudges
  686. The scheduler (see above) includes a daily check (20:00 by default) that
  687. looks for anything worth flagging - an unusual day, a goal falling
  688. behind, a monthly budget that is over or nearly used up - using the same
  689. deterministic analysis as the tools above, with no LLM call needed. It stays silent on days with nothing notable, so it
  690. won't spam you.
  691. ## Data Export
  692. ```bash
  693. hermes-life-os-export --json backup.json --csv summary.csv
  694. ```
  695. Your data isn't locked in. `--json` writes a complete backup (every
  696. memory entry plus every data store - profile, habits, goals, all the logs,
  697. spending, budgets, reminders, templates and so on - unmodified, as readable
  698. JSON even when encryption is on, since you asked for a copy to take
  699. elsewhere). `--csv` writes
  700. a daily summary in the same shape `hermes-life-os-import --csv` expects -
  701. export, edit in a spreadsheet, and re-import elsewhere if you want.
  702. ## Telegram Bot
  703. ```bash
  704. set TELEGRAM_BOT_TOKEN=... # from @BotFather
  705. set TELEGRAM_CHAT_ID=... # your own numeric chat id
  706. hermes-life-os-telegram
  707. ```
  708. Talk to Hermes from your phone - no server, no webhook, just long
  709. polling (keep the process running, e.g. in `tmux`/`screen` or as a
  710. background service). Only messages from `TELEGRAM_CHAT_ID` are ever
  711. processed, so your data stays private even if someone finds your bot's
  712. username. See `demo/telegram_bot.py`'s docstring for the exact setup
  713. steps (getting a token and finding your chat id).
  714. **Model reliability note:** this project defines a lot of tools (27+).
  715. Small/CPU-friendly local models (e.g. `llama3.2:3b`) can struggle to use
  716. them reliably - they may log things you didn't ask for, or occasionally
  717. emit a raw tool-call attempt as plain text instead of actually calling
  718. the tool (Hermes detects and filters that specific failure so you never
  719. see raw JSON, but the underlying action still won't happen). `llama3.1`
  720. (8B) is noticeably more reliable via Ollama, at the cost of being slower
  721. on CPU-only machines (several minutes per reply). Any cloud provider
  722. (Anthropic/OpenAI/OpenRouter) is both faster and more reliable if you
  723. have API access.
  724. ## Discord Bot
  725. ```bash
  726. pip install "hermes-life-os[discord]" # or: pip install discord.py
  727. set DISCORD_BOT_TOKEN=... # from the Discord Developer Portal
  728. set DISCORD_USER_ID=... # your own numeric Discord user id
  729. hermes-life-os-discord
  730. ```
  731. The Discord counterpart to the Telegram bot above - same idea (talk to
  732. Hermes, log meals from a photo, send a voice message), different
  733. platform. Uses discord.py's own event-driven client under the hood
  734. (rather than the Telegram bot's hand-rolled long-polling loop), so it
  735. works in a DM or in any server channel the bot can see. Only messages
  736. from `DISCORD_USER_ID` are ever processed - everyone else is silently
  737. ignored. See `demo/discord_bot.py`'s docstring for the exact setup
  738. steps (creating a bot application, enabling the Message Content
  739. intent, and finding your user id). The same vision-model requirement
  740. for photo meal logging applies here - see the Photo Meal Logging
  741. section below.
  742. ## WhatsApp Bot
  743. ```bash
  744. pip install "hermes-life-os[whatsapp]" # or: pip install flask twilio
  745. set TWILIO_ACCOUNT_SID=...
  746. set TWILIO_AUTH_TOKEN=...
  747. set WHATSAPP_ALLOWED_NUMBER=whatsapp:+1XXXXXXXXXX # your own number, E.164
  748. hermes-life-os-whatsapp
  749. ```
  750. The third chat platform, via Twilio's WhatsApp API. Unlike the
  751. Telegram bot (polling) and Discord bot (websocket client), this is a
  752. webhook server - Twilio pushes messages to it, so it needs to be
  753. reachable from the internet (`ngrok http 8766` works well for personal
  754. use with Twilio's free WhatsApp Sandbox). Same feature set as the
  755. other two: plain text, photo-based meal logging, and voice-note
  756. transcription. Every incoming request's Twilio signature is verified
  757. before anything is processed, on top of the same single-number
  758. authorization the other bots use. Full setup steps (sandbox join code,
  759. webhook URL) are in `demo/whatsapp_bot.py`'s docstring. The same
  760. vision-model requirement for photo meal logging applies here too - see
  761. the Photo Meal Logging section below.
  762. ## Slack Bot
  763. ```bash
  764. pip install "hermes-life-os[slack]" # or: pip install slack_bolt
  765. python demo/users.py add alex --profile alex
  766. python demo/users.py link alex slack U0123ABC # your Slack member ID
  767. set SLACK_BOT_TOKEN=xoxb-...
  768. set SLACK_APP_TOKEN=xapp-...
  769. hermes-life-os-slack
  770. ```
  771. The fourth chat platform, and the first one built multi-user from the
  772. start: DM the bot and it's automatically routed to *your* profile, so a
  773. whole household or team can share one bot process. Uses Socket Mode (a
  774. persistent websocket, via Slack's own `slack_bolt` framework) - same
  775. "no public server, no webhook" philosophy as the Telegram bot, just
  776. using Slack's officially supported connection handling instead of a
  777. hand-rolled polling loop. Works single-user too (`SLACK_ALLOWED_USER_ID`,
  778. same pattern as the Discord/Telegram bots) if you don't need the
  779. multi-user registry. Same photo-based meal logging support as the other
  780. bots. Full setup (creating the Slack app, required scopes, finding your
  781. member ID) in `demo/slack_bot.py`'s docstring and
  782. [docs/MULTI_USER.md](docs/MULTI_USER.md).
  783. ## Local REST API
  784. ```bash
  785. pip install "hermes-life-os[api]" # or: pip install flask
  786. set LIFE_OS_API_KEY=some-long-random-string
  787. hermes-life-os-api
  788. ```
  789. A lightweight, localhost-only HTTP API for third-party integrations
  790. that don't want to (or can't) go through an LLM at all - Apple
  791. Shortcuts, Android Tasker, a browser extension, a home-screen widget,
  792. an Alfred/Raycast workflow, `curl` in a cron job, etc. Exposes the
  793. same tools the chat agent uses:
  794. ```bash
  795. curl -H "X-API-Key: some-long-random-string" http://127.0.0.1:8765/api/tools
  796. curl -H "X-API-Key: some-long-random-string" -X POST \
  797. -d '{"score": 8}' http://127.0.0.1:8765/api/tools/log_mood
  798. ```
  799. Binds to `127.0.0.1` by default and refuses to start without
  800. `LIFE_OS_API_KEY` set - every request needs it as an `X-API-Key`
  801. header. See `demo/local_api.py`'s docstring for the full endpoint list
  802. and the security notes on exposing this beyond your own machine. For a
  803. step-by-step Apple Shortcuts / Android / browser bookmarklet setup, see
  804. [docs/SHORTCUTS.md](docs/SHORTCUTS.md).
  805. ## Weather Correlation
  806. ```
  807. "does the weather affect my mood?"
  808. "any connection between rain and my energy levels?"
  809. ```
  810. `demo/weather.py` fetches historical daily weather (temperature,
  811. precipitation) for a place you name, via Open-Meteo's free, keyless API
  812. (https://open-meteo.com) - no signup, no API key, no cost - and
  813. correlates it against your tracked metrics the same way the core
  814. correlation engine does. This is the only tracker that makes a network
  815. call (every other one is 100% local), and it only ever does so when
  816. explicitly asked, sending nothing but the place name you provide.
  817. ## Life Review - the flagship retrospective report
  818. ```bash
  819. hermes-life-os-review --days 90 # a quarter -> hermes-life-review.html
  820. hermes-life-os-review --days 365 --out my-year-review.html
  821. ```
  822. The "big" report - ties together everything else Hermes tracks into
  823. one self-contained HTML page: your Life Score trend chart, best/toughest
  824. day, a period-over-period retrospective (this quarter vs. the one
  825. before), every correlation detected (same-day and lagged), achievements
  826. earned, and habit streaks. Same "no server, no JS build step" approach
  827. as the dashboard, just built for a much longer lookback window - a
  828. quarter or a year, rather than 30 days. Doesn't include weather
  829. correlation automatically, since that's the one feature that touches
  830. the network - ask for it separately if wanted.
  831. Need something printable or shareable outside a browser? `--format
  832. pdf` renders a two-page PDF version with the same data (Life Score,
  833. retrospective, correlations, achievements, habits) on a light,
  834. print-friendly background:
  835. ```bash
  836. hermes-life-os-review --days 90 --format pdf --out my-quarter.pdf
  837. ```
  838. `hermes-life-os-wrapped` supports the same trick even more simply -
  839. just name the output file `.pdf` instead of `.png` and it's picked up
  840. automatically:
  841. ```bash
  842. hermes-life-os-wrapped --out hermes-wrapped.pdf
  843. ```
  844. ## Leaderboard - opt-in household/team comparison
  845. ```
  846. "join the leaderboard"
  847. "show me the leaderboard"
  848. ```
  849. Builds on the multi-user system (see [docs/MULTI_USER.md](docs/MULTI_USER.md)):
  850. a friendly, opt-in ranking across every profile on the install, by
  851. average Life Score, current logging streak, and achievements earned.
  852. **Nobody is included by default** - a profile only appears after
  853. explicitly opting in (`join_leaderboard`, or `python demo/leaderboard.py
  854. join`), and leaving again takes effect immediately. Only those three
  855. numbers are ever shared across profiles - no journal content, no raw
  856. logged entries, and nothing ever leaves the machine.
  857. ## Streak Freezes
  858. Habits (`update_habit`) now bank a **streak freeze** every 7 days of an
  859. active streak, up to 3 at once - a small forgiveness mechanic so one
  860. missed day doesn't erase weeks of consistency:
  861. ```
  862. "I meditated" (7 days running) -> "Habit 'meditate': streak 7 days (best: 7) - earned a streak freeze! (1 available)"
  863. "I missed meditating today, use a freeze" -> "Habit 'meditate': streak protected with a freeze! Still at 7 days (best: 7). 0 freeze(s) left."
  864. ```
  865. No freeze banked and a day's missed? The streak resets to 0, same as
  866. always - freezes are a bonus for consistency, not a way around ever
  867. having an off day.
  868. ## On This Day & Daily Prompts
  869. ```
  870. "what was I doing on this day last year?"
  871. "give me a reflection prompt"
  872. ```
  873. Two small additions aimed at journaling depth, not just numbers:
  874. - **On This Day** (`get_on_this_day`) - a nostalgia lookup: finds
  875. memory entries logged on today's month/day in previous years, most
  876. recent first.
  877. - **Daily Prompt** (`get_daily_prompt`, `demo/prompts.py`) - a rotating
  878. reflection question, deterministic by calendar date (same day always
  879. returns the same prompt, and it changes daily) - no state to persist,
  880. no randomness to make testing flaky.
  881. ## Contribution Heatmap
  882. ```bash
  883. hermes-life-os-heatmap --days 365 --out heatmap.svg
  884. hermes-life-os-heatmap --days 90 --out heatmap.html # wrapped with stats
  885. ```
  886. A GitHub-style calendar heatmap of your logging activity - darker
  887. squares for more active days, same five-level palette as GitHub's own
  888. contribution graph. Pure SVG (no matplotlib needed), so it's fast and
  889. embeddable anywhere that accepts raw SVG or an `<img>` tag. `.html`
  890. output wraps it with active-day/streak stats above the grid.
  891. ## Moon Phase Correlation
  892. ```
  893. "does the full moon affect my mood?"
  894. ```
  895. `demo/moon.py` correlates lunar phase against tracked metrics, purely
  896. via local astronomical calculation - unlike weather.py, this makes
  897. *zero* network calls; the phase is computed on-device from a known
  898. reference new moon date. Offered in the same evidence-based spirit as
  899. every correlation Hermes computes: not because lunar effects on mood
  900. are scientifically established (most rigorous research says they
  901. aren't), but because it's a fun, harmless pattern to check against your
  902. own data - if Hermes finds nothing, that itself is the honest answer.
  903. ## Sleep Debt & Suggested Bedtime
  904. ```
  905. "how much sleep debt do I have?"
  906. "what time should I go to bed if I'm waking up at 7?"
  907. ```
  908. `demo/sleep_debt.py` sums the shortfall between a target sleep duration
  909. (default 8h) and what's actually logged over a recent window - only
  910. days with a logged sleep value count, so gaps in logging are never
  911. mistaken for debt. `get_suggested_bedtime` factors existing debt into
  912. tonight's recommended bedtime, nudged earlier gradually (a quarter of
  913. the debt per night, capped at 1h extra) rather than proposing something
  914. unrealistic in a single night.
  915. ## Day-of-Week Insights
  916. ```
  917. "what's my best day of the week?"
  918. "is my mood worse on Mondays?"
  919. ```
  920. `demo/day_of_week.py` buckets already-logged mood, energy, stress,
  921. sleep, hydration, meeting-hours, and readiness by weekday, then reports
  922. which day averages best and worst for each metric - lower is treated
  923. as "best" for stress specifically, since a calmer day is the good
  924. outcome there. Purely local arithmetic over `daily_averages()`, no new
  925. tracking of its own; a metric needs at least two distinct weekdays
  926. logged before Hermes will call one "best" and another "worst".
  927. ## Habit Milestones
  928. ```
  929. "how close am I to a milestone on my habits?"
  930. ```
  931. `demo/habit_milestones.py` looks at every habit with an active streak
  932. and counts down to its next round-number milestone (7, 14, 30, 50,
  933. 100, 150, 200, 365, 500, 1000 days, doubling beyond that). This is a
  934. different lens than the near-milestone nudge already surfaced
  935. opportunistically by `recommendations.py` - `get_habit_milestones`
  936. gives the full countdown list for every active habit on demand, rather
  937. than waiting for one habit to get close enough to be worth a nudge.
  938. ## Logging Consistency
  939. ```
  940. "how consistent have I been with logging?"
  941. "which trackers have I been neglecting?"
  942. ```
  943. `demo/consistency.py` (`get_logging_consistency`) reports the
  944. percentage of recent days that had at least one entry logged, overall
  945. and broken down per tracked metric. A metric that's never been logged
  946. in the window is simply left out of the breakdown rather than shown as
  947. a discouraging 0% - an unused tracker isn't "inconsistent", it's just
  948. unused.
  949. ## Time-of-Day Insights
  950. ```
  951. "am I happier in the mornings?"
  952. "is my stress worse at night?"
  953. ```
  954. `demo/time_of_day.py` (`get_time_of_day_insights`) buckets individual
  955. logged entries into Morning/Afternoon/Evening/Night by the hour they
  956. were logged and reports which time of day is best and worst per
  957. metric - a companion to Day-of-Week Insights that looks at time-of-day
  958. rather than day-of-week, and works entry-by-entry rather than one
  959. daily average, since mood at 8am and mood at 8pm on the same day
  960. should land in different buckets.
  961. ## Month-over-Month Comparison
  962. ```
  963. "how is this month going compared to last month?"
  964. ```
  965. `demo/monthly_summary.py` (`get_monthly_comparison`) compares this
  966. calendar month so far against the same day-count span at the start of
  967. last calendar month - e.g. running it on the 10th compares days 1-10
  968. of each month, not the whole of last month against a partial current
  969. one. Handles month-length edge cases (a 31-day January comparing
  970. against a 28/29-day February) by capping the previous-month span at
  971. that month's own last day. Built on top of the existing
  972. `compare_periods()` averaging/delta logic, just with calendar-month
  973. date ranges instead of rolling day windows.
  974. ## Habit Personal Bests
  975. ```
  976. "am I close to beating my meditation streak record?"
  977. ```
  978. `demo/habit_pb.py` (`get_habit_pb_progress`) compares every habit's
  979. current streak against its own personal-best streak - a new best, a
  980. tie, or how many days remain to tie it. This is a different, often
  981. more motivating lens than the fixed round-number countdown in Habit
  982. Milestones: a habit whose best streak is 12 will never feel "close" to
  983. milestone 14, but "2 days from tying your best" always does.
  984. ## Workout Summary
  985. ```
  986. "give me a fitness recap"
  987. "how's my workout streak?"
  988. ```
  989. `demo/workout_summary.py` (`get_workout_summary`) totals recent
  990. workouts, breaks them down by type, and reports the current
  991. consecutive-day workout streak. The streak always looks at your full
  992. workout history rather than just the requested lookback window, so a
  993. streak that started 40 days ago still shows correctly even when asking
  994. for a 30-day summary.
  995. ## Meditation Summary
  996. ```
  997. "how's my meditation practice going?"
  998. ```
  999. `demo/meditation_summary.py` (`get_meditation_summary`) totals recent
  1000. meditation sessions and reports what percentage of days in the window
  1001. had at least one session - multiple sessions on the same day count
  1002. once toward that consistency figure.
  1003. ## Gratitude Recap
  1004. ```
  1005. "what have I been grateful for lately?"
  1006. ```
  1007. `demo/gratitude_recap.py` (`get_gratitude_recap`) totals recent
  1008. gratitude entries, surfaces the most recurring words across them as a
  1009. lightweight signal for recurring themes (not real NLP, just frequency
  1010. counting with a small stopword list), and lists the most recent items.
  1011. ## Meal Summary
  1012. ```
  1013. "give me a nutrition recap"
  1014. ```
  1015. `demo/meal_summary.py` (`get_meal_summary`) totals recent meals,
  1016. reports average calories per meal and per logged day, breaks meals
  1017. down by meal time (breakfast/lunch/dinner/snack), and lists the most
  1018. frequently logged foods (case-insensitively, so "Salad" and "salad"
  1019. count together).
  1020. ## Hydration Summary
  1021. ```
  1022. "how well have I been hitting my water goal?"
  1023. ```
  1024. `demo/hydration_summary.py` (`get_hydration_summary`) rebuilds daily
  1025. totals from the raw hydration log (rather than the single "today"
  1026. counter, which only reflects the current calendar day), then reports
  1027. the average glasses/day against your goal, how many logged days hit
  1028. it, and the current consecutive-day goal-met streak.
  1029. ## Focus Summary
  1030. ```
  1031. "give me a productivity recap"
  1032. ```
  1033. `demo/focus_summary.py` (`get_focus_summary`) totals recent focus
  1034. sessions and reports total/average duration, average quality,
  1035. completion rate, total distractions, and the most common task.
  1036. ## Dream Recap
  1037. ```
  1038. "what are my recurring dream themes?"
  1039. ```
  1040. `demo/dream_recap.py` (`get_dream_recap`) totals recent dreams and
  1041. surfaces which symbols or emotions recur across multiple distinct
  1042. dreams (a symbol mentioned twice in the same dream only counts once,
  1043. so recurrence reflects a genuine pattern across nights rather than
  1044. repetition within one dream). Dreams have no dedicated storage file of
  1045. their own - they live only in the shared memory log - so this reads
  1046. from `get_recent_memory` rather than a `load_*()` function like the
  1047. other summary tools.
  1048. ## Stress Summary
  1049. ```
  1050. "give me a stress recap"
  1051. "is my stress getting better or worse?"
  1052. ```
  1053. `demo/stress_summary.py` (`get_stress_summary`) reports the average
  1054. stress score, a first-half-vs-second-half trend within the window
  1055. ("improving", "worsening", or "steady" - a difference under 1 point on
  1056. the 0-10 scale is treated as steady, to avoid flip-flopping on small
  1057. amounts of data), how many days crossed a high-stress threshold, and
  1058. the most common triggers.
  1059. ## Habit Consistency, Mood Impact & Overview
  1060. ```
  1061. "how consistent have I really been with meditation?"
  1062. "does meditating actually improve my mood?"
  1063. "how are my habits doing overall?"
  1064. ```
  1065. `update_habit` now also records every check-in (done, missed, or
  1066. protected with a freeze) as a `habit_completion` entry in the shared
  1067. memory log, alongside the existing streak counters in `habits.json`.
  1068. This unlocks three new views built on that real per-check-in history
  1069. rather than just the current streak state:
  1070. - `demo/habit_consistency.py` (`get_habit_consistency`) - the
  1071. percentage of check-ins that were successful for each habit, which
  1072. can tell a very different story than the current streak (a short
  1073. current streak can follow a long run of consistency, or vice versa).
  1074. - `demo/habit_correlation.py` (`get_habit_mood_impact`) - compares
  1075. average mood on days a given habit was completed versus days it was
  1076. missed. This is naturally forward-looking: it only reflects habit
  1077. check-ins recorded after this feature shipped, and needs mood logged
  1078. on both completed and missed days to say anything meaningful.
  1079. - `demo/habit_overview.py` (`get_habit_overview`) - a single combined
  1080. dashboard over Habit Milestones, Habit Personal Bests, and Habit
  1081. Consistency, for a general "how are my habits doing" question
  1082. instead of picking one specific angle. Reuses each module's own
  1083. formatter, so the wording matches calling that tool directly.
  1084. ## Reading Pace
  1085. ```
  1086. "how fast am I reading Atomic Habits?"
  1087. "log_reading('War and Peace', pages=40, total_pages=1225)"
  1088. ```
  1089. `log_reading` now accepts an optional `total_pages` for a book.
  1090. `demo/reading_pace.py` (`get_reading_pace`) computes pages/day for a
  1091. specific title and, once a total page count has ever been logged for
  1092. it, estimates the remaining days and a finish date at the current
  1093. pace. Without a `total_pages` on file it still reports the pace, just
  1094. without an estimate - there's nothing to count down to.
  1095. ## Spending Trends
  1096. ```
  1097. "which spending categories are trending up?"
  1098. ```
  1099. `demo/spending_trends.py` (`get_spending_trends`) compares spending
  1100. per category over a recent window against the equal-length window
  1101. before it - a different angle than the existing Spending Summary,
  1102. which only totals a single window. A category that's new or has
  1103. stopped appearing still shows up, with 0 on the missing side, rather
  1104. than silently disappearing from the comparison.
  1105. ## Substance-Sleep Impact
  1106. ```
  1107. "does caffeine affect my sleep?"
  1108. ```
  1109. `demo/substance_correlation.py` (`get_substance_sleep_impact`)
  1110. compares average sleep hours on days a given substance was logged
  1111. versus days it wasn't. This compares same-calendar-day entries rather
  1112. than "the following night", since a sleep log's date is whatever day
  1113. it was logged (typically the morning after waking) and there's no
  1114. reliable way to know which night it refers to otherwise.
  1115. ## Social Insights & Mood Impact
  1116. ```
  1117. "who have I been spending time with lately?"
  1118. "does socializing actually improve my mood?"
  1119. ```
  1120. `demo/social_insights.py` (`get_social_insights`) breaks recent social
  1121. interactions down by who they were with - time spent, average quality,
  1122. and the most frequent contact - a different angle than the existing
  1123. Social Summary, which only totals the whole window.
  1124. `demo/social_correlation.py` (`get_social_mood_impact`) compares
  1125. average mood on days with a logged social interaction versus days
  1126. without one, using the same same-calendar-day comparison convention as
  1127. Habit Mood Impact and Substance-Sleep Impact.
  1128. ## Medication Streak
  1129. ```
  1130. "how consistent have I been with taking my Vitamin D?"
  1131. ```
  1132. `demo/medication_streak.py` (`get_medication_streak`) reports the
  1133. current and longest consecutive-day streak of taking a specific
  1134. medication or supplement - a different angle than the existing
  1135. Medication Adherence, which only reports an overall percentage for the
  1136. lookback window rather than a day-by-day streak.
  1137. ## Workout Mood Impact
  1138. ```
  1139. "does exercising actually improve my mood?"
  1140. ```
  1141. `demo/workout_correlation.py` (`get_workout_mood_impact`) compares
  1142. average mood on days a workout was logged versus days without one,
  1143. using the same same-calendar-day comparison convention as Habit Mood
  1144. Impact, Substance-Sleep Impact, and Social Mood Impact.
  1145. ## Life Review, Now Conversational (and Two More Matplotlib Crash Fixes)
  1146. ```
  1147. "give me a fuller review of the last quarter"
  1148. ```
  1149. Fixing `wrapped.py`'s matplotlib crash last round turned up the exact
  1150. same bug in two more report generators: `demo/dashboard.py` and
  1151. `demo/life_review.py` both imported matplotlib at module level and
  1152. called `sys.exit(1)` if it wasn't installed - which would have killed
  1153. the whole bot/API process the first time a text-only caller touched
  1154. either module in an environment without matplotlib. Both now use a
  1155. shared `_get_pyplot()` lazy-import helper (`dashboard._get_pyplot()`,
  1156. reused by `life_review.py`) that raises a normal `ImportError` only
  1157. when a chart is actually about to be rendered; `build_dashboard_data()`
  1158. and `build_life_review_data()` need no plotting library at all.
  1159. That fix made `demo/life_review.py`'s data cheap to expose
  1160. conversationally too: new `format_life_review_summary()` gives a text
  1161. version - life score trend, best/toughest day, correlation insights,
  1162. a retrospective comparison against the prior period, badges earned -
  1163. available as `get_life_review`, alongside the existing
  1164. `hermes-life-os-review` HTML/PDF CLI. It's the deeper counterpart to
  1165. `get_wrapped`'s quick recap.
  1166. ## Proactive Nudges & Wrapped, Now Conversational
  1167. ```
  1168. "is there anything I should know about?"
  1169. "give me my wrapped for the last 30 days"
  1170. ```
  1171. Two more existing-but-CLI/scheduler-only features are now ordinary
  1172. tools: `demo/nudges.py`'s deterministic anomaly and off-track-goal
  1173. checker (previously only run by the scheduler for proactive
  1174. notifications) is now available on demand as `get_nudges`, and
  1175. `demo/wrapped.py`'s "Spotify Wrapped"-style period recap - average
  1176. life score, mood, sleep, stress, best day, badges earned - is now
  1177. available as text via `get_wrapped`, alongside its existing
  1178. `hermes-life-os-wrapped` image-card CLI.
  1179. Getting `get_wrapped` working safely surfaced a real bug: `wrapped.py`
  1180. imported matplotlib at module level and called `sys.exit(1)` if it
  1181. wasn't installed - fine for a CLI script, but it would have killed the
  1182. entire bot/API process the first time a text-only caller tried to use
  1183. it in an environment without matplotlib. The matplotlib import is now
  1184. lazy, living inside `render_wrapped_image()` (the only function that
  1185. actually needs it) and raising a normal `ImportError` instead of
  1186. exiting the process; `build_wrapped_stats()` and the new
  1187. `format_wrapped_summary()` need no plotting library at all.
  1188. ## Correlation Refactor, Reading Mood Impact & Insights Digest
  1189. ```
  1190. "what stands out in my data lately?"
  1191. "does reading affect my mood?"
  1192. ```
  1193. Habit Mood Impact, Substance-Sleep Impact, Social Mood Impact, and
  1194. Workout Mood Impact had each grown their own near-identical
  1195. "average metric X on days condition Y held versus days it didn't"
  1196. implementation. `demo/correlation_utils.py` now holds that logic once
  1197. - `compute_metric_impact_by_presence()` for checks where "it didn't
  1198. happen" is inferred from absence (workouts, substances, social
  1199. interactions, reading), and `compute_metric_impact_by_status()` for
  1200. checks where "it didn't happen" needs its own explicit record (a habit
  1201. logged as missed, as opposed to a habit that was never checked in on
  1202. at all). Every existing correlation tool now calls one of these two
  1203. functions internally; their public functions, return shapes, and
  1204. wording are unchanged.
  1205. That shared foundation made two things cheap to add:
  1206. - **Reading Mood Impact** (`demo/reading_correlation.py`,
  1207. `get_reading_mood_impact`) - the same day-vs-day mood comparison,
  1208. now for reading sessions.
  1209. - **Insights Digest** (`demo/insights_digest.py`,
  1210. `get_insights_digest`) - runs every correlation check at once
  1211. (workout/social/reading vs mood, every tracked habit vs mood, every
  1212. logged substance vs sleep) and surfaces only the findings with a
  1213. meaningful difference, instead of the person needing to know which
  1214. of seven-plus separate tools to call, or call all of them just to
  1215. see if anything stands out. A digest that repeats "not enough data"
  1216. seven times isn't useful, so anything below the threshold (default
  1217. 1.0 points/hours) is silently omitted.
  1218. ## Export & Backup, Now Conversational
  1219. ```
  1220. "export my data as csv"
  1221. "back up my data right now"
  1222. ```
  1223. Hermes Life OS has always had a full data-export system
  1224. (`demo/data_export.py` - JSON/CSV/Markdown) and rotating automated
  1225. backups (`demo/backup.py`), but until now they could only be triggered
  1226. by running those scripts directly. `demo/export_tool.py` wraps them as
  1227. two ordinary tools, `export_data` and `backup_now`, so they can be
  1228. triggered from a normal conversation - picking a sensible default
  1229. output path under the active profile's `exports/` or `backups/`
  1230. directory so nobody has to supply one. `export_data` is for taking
  1231. your data elsewhere (a spreadsheet, Obsidian, Notion); `backup_now` is
  1232. for safekeeping in place.
  1233. ## Habit-Linked Goals
  1234. ```
  1235. "update_goal('meditation streak', linked_habit='meditate', target_streak=30)"
  1236. ```
  1237. `update_goal` now supports a third way to track progress, alongside
  1238. manual and metric-linked: `linked_habit` + `target_streak` ties a
  1239. goal's progress directly to a habit's actual current streak (e.g. "hit
  1240. a 30-day meditation streak"), computed via a new
  1241. `compute_habit_goal_progress()` in `analytics.py` - the habit-tracking
  1242. counterpart to the existing metric-tracking `compute_goal_progress()`.
  1243. `check_goal_progress` refreshes habit-linked goals from the live
  1244. streak the same way it already refreshes metric-linked ones. A goal is
  1245. manual, metric-linked, or habit-linked - not more than one at once.
  1246. ## Quick-Log Templates
  1247. ```
  1248. "save my usual breakfast as a template"
  1249. "log my usual breakfast"
  1250. ```
  1251. `demo/templates.py` lets you save a named shortcut for a specific
  1252. `log_*` tool call with fixed parameters (`save_log_template`), then
  1253. replay it later with one call (`use_log_template`) instead of
  1254. re-typing the same details every time - `list_log_templates` and
  1255. `delete_log_template` round it out. Templates can only ever point at
  1256. `log_*` tools, never at export/backup/goal/habit-management or any
  1257. other tool, so replaying one can only ever add a new log entry, never
  1258. trigger a side effect beyond what the person explicitly asked to save.
  1259. ## List, Delete Habits & Goals
  1260. ```
  1261. "what habits do I have set up?"
  1262. "delete my old 'read more' goal"
  1263. ```
  1264. A real gap: a brand-new habit with a 0-day streak (created via a
  1265. missed first check-in, or one that's since dropped to a 0-day streak
  1266. with no past best) was invisible everywhere - `get_habit_milestones`
  1267. and `get_habit_pb_progress` both explicitly exclude habits with no
  1268. active or past streak, and the health dashboard only lists active
  1269. ones. `list_habits` now shows every habit regardless of streak status.
  1270. `delete_habit` and `delete_goal` round out basic CRUD for both -
  1271. before this, there was no way to remove a habit or goal at all once
  1272. created, only `delete_entry` for individual memory entries.
  1273. ## Budgets
  1274. ```
  1275. "set a 400/month budget for groceries"
  1276. "how am I doing on my budgets this month?"
  1277. ```
  1278. `demo/budgets.py` is the project's first forward-looking money tool -
  1279. every existing spending feature (`log_expense`, `get_spending_summary`,
  1280. `get_spending_trends`) is retrospective, reporting what already
  1281. happened, with no concept of a limit. `set_budget` saves a per-category
  1282. monthly limit; `get_budget_status` compares it against actual spending
  1283. logged so far in the current calendar month (reusing `load_spending`,
  1284. no new tracking of its own) and flags any category that's over.
  1285. `list_budgets` shows the raw limits, and `delete_budget` removes one.
  1286. Setting a budget for a category that already has one overwrites the
  1287. limit rather than creating a duplicate.
  1288. ```
  1289. "will I stay within my budgets this month?"
  1290. "how did I do on my budgets over the last 3 months?"
  1291. "where is my money going outside my budgets?"
  1292. ```
  1293. Three more tools build on the same data (v1.37.0):
  1294. - `get_budget_forecast` projects month-end spending from this month's
  1295. pace so far and says how much you can still spend per remaining day.
  1296. Each budget is `over`, `will_exceed` or `on_track`, and projections
  1297. made in the first days of the month are flagged as rough.
  1298. - `get_budget_history` looks back over the last N completed months
  1299. (default 3, max 24) and shows spending per month and how many months
  1300. went over. Budgets are not versioned, so every month is measured
  1301. against the current limit.
  1302. - `get_unbudgeted_spending` lists this month's spending in categories
  1303. that have no budget at all, biggest first.
  1304. Spending categories now match budgets case-insensitively, so an expense
  1305. logged as "Food" counts against a "food" budget (before, it was silently
  1306. missed). Budgets that are over, or at least 80% used, also show up in the
  1307. proactive nudge check and `get_nudges`.
  1308. v1.38.0 adds two more things:
  1309. ```
  1310. "set a 400 budget for groceries and warn me at 90%"
  1311. "what should my budgets be?"
  1312. ```
  1313. - `set_budget` takes an optional `alert_pct` (1-100) so a budget can warn
  1314. earlier or later than the default 80% (0 removes a custom value), and it
  1315. now rejects a negative, non-numeric or infinite limit instead of storing
  1316. it (a numeric string such as "400" is accepted and converted).
  1317. - `suggest_budgets` proposes a monthly limit for every spending category
  1318. that has no budget yet: the average of the last few completed months
  1319. (default 3, months without spending count as zero) plus a 10% buffer
  1320. (`buffer_pct`), rounded up to a tidy number. It only suggests; use
  1321. `set_budget` to adopt one.
  1322. ## Reminders
  1323. ```
  1324. "remind me to stretch every day at 9am"
  1325. "remind me to call mom on sundays"
  1326. "what reminders do I have set?"
  1327. ```
  1328. `demo/reminders.py` gives user-defined reminders a real, queryable home
  1329. for the first time - `scheduler.py`'s schedule was entirely hardcoded
  1330. (morning/checkin/evening/weekly/nudge_check/backup), with no mechanism
  1331. for a person to define their own. `create_reminder` saves free-text
  1332. reminders with an optional time hint and optional days of the week;
  1333. `list_reminders` and `delete_reminder` round out CRUD.
  1334. As of v1.37.0 reminders are actually delivered. Times are normalized to
  1335. 24-hour `HH:MM` (`9am`, `9:30pm` and `17:30` all work; a bare `9` is
  1336. ambiguous and rejected), and while `hermes-life-os-scheduler` is running
  1337. each timed reminder is sent through your notification channel at its
  1338. saved time on the days it applies to, once per day. A two-minute grace
  1339. window means a slow poll cannot skip one. A reminder with no time is a
  1340. day-level note, and one whose time cannot be understood is saved but
  1341. never fires (the agent tells you so when you create it).
  1342. ```
  1343. "change my stretch reminder to 6:30pm"
  1344. "pause my stretch reminder while I'm away"
  1345. "what reminders do I have today?"
  1346. ```
  1347. - `update_reminder` changes the text, time and/or days of an existing
  1348. reminder (`time=""` removes the time, `days=[]` means every day).
  1349. - `pause_reminder` / `resume_reminder` switch a reminder off and on
  1350. without deleting it. Paused reminders are marked in `list_reminders`.
  1351. - `get_todays_reminders` lists what applies today in time order.
  1352. v1.38.0 adds one-off and short-term reminders:
  1353. ```
  1354. "remind me on 2026-11-02 at 9am to renew my passport"
  1355. "remind me in 20 minutes to check the oven"
  1356. "snooze that reminder for 15 minutes"
  1357. "clear my old one-off reminders"
  1358. ```
  1359. - `create_reminder` and `update_reminder` accept an optional `date`
  1360. (`YYYY-MM-DD`), making a one-off reminder that applies on that date only
  1361. and ignores `days`.
  1362. - `remind_me_in` sets a one-off reminder N minutes from now (1 to 1440).
  1363. - `snooze_reminder` delays any reminder so it fires again in N minutes
  1364. (default 10); its normal time is suppressed until then.
  1365. - `clear_past_reminders` deletes one-offs whose date has passed. Recurring
  1366. and upcoming reminders are never touched.
  1367. ## Goal Deadlines
  1368. ```
  1369. "update_goal('finish the report', deadline='2026-03-01')"
  1370. "what goal deadlines am I about to miss?"
  1371. ```
  1372. `update_goal` now accepts an optional `deadline` (`YYYY-MM-DD`).
  1373. `demo/goal_deadlines.py` (`get_goal_deadlines`) lists every
  1374. deadline-bearing goal sorted by urgency, with overdue goals surfaced
  1375. first and how many days overdue they are - so a goal with a deadline
  1376. never silently falls off the radar the way a plain progress percentage
  1377. can.
  1378. ## Focus Timer
  1379. ```bash
  1380. hermes-life-os-focus 25 --task "writing"
  1381. hermes-life-os-focus 25 --task "deep work" --break 5
  1382. ```
  1383. A terminal Pomodoro-style countdown that logs itself on completion, via
  1384. the exact same `log_focus_session` path a chat-based request uses - so
  1385. this isn't a separate timer app you also have to remember to log
  1386. afterward. Ctrl+C during the countdown stops it early and does **not**
  1387. log a session (an abandoned session isn't a completed one).
  1388. ## Markdown / Obsidian / Notion Export
  1389. ```bash
  1390. hermes-life-os-export --markdown ./obsidian-vault/hermes
  1391. hermes-life-os-export --markdown ./notes --days 90
  1392. ```
  1393. Adds a third export format alongside JSON and CSV: one file per day
  1394. (`YYYY-MM-DD.md`) with YAML frontmatter for that day's numeric metrics
  1395. and a bulleted list of everything logged - filename convention matches
  1396. Obsidian's Daily Notes plugin exactly, and Notion's markdown importer
  1397. reads YAML frontmatter as page properties, so the same export folder
  1398. drops into either tool with no conversion step.
  1399. ## Semantic Memory Search
  1400. `recall` searches by exact keyword; ask Hermes something like "have I
  1401. felt this way before?" or "find entries about feeling overwhelmed" (even
  1402. if you never used that exact word) and it can fall back to
  1403. `semantic_recall` - a local, free embedding search via Ollama (`ollama
  1404. pull nomic-embed-text` first) or OpenAI:
  1405. ```bash
  1406. set EMBEDDING_PROVIDER=ollama # or openai; auto-detects from OPENAI_API_KEY otherwise
  1407. ```
  1408. Embeddings are cached per entry and only recomputed when that entry's
  1409. text actually changes.
  1410. ## Oura Ring Import
  1411. ```bash
  1412. set OURA_PERSONAL_ACCESS_TOKEN=... # https://cloud.ouraring.com/personal-access-tokens
  1413. hermes-life-os-oura --days 30
  1414. ```
  1415. No OAuth flow - just a personal access token from Oura's own dashboard.
  1416. Imports real sleep duration (merges directly with manually logged and
  1417. Apple-Health-imported sleep) and your daily readiness score (a new
  1418. tracked metric - ask "is my readiness linked to sleep or stress?").
  1419. ## Weekly Email Summary
  1420. ```bash
  1421. set HERMES_SMTP_HOST=smtp.gmail.com
  1422. set HERMES_SMTP_PORT=587
  1423. set HERMES_SMTP_USER=you@gmail.com
  1424. set HERMES_SMTP_PASSWORD=... # an app password, not your real password
  1425. set HERMES_SMTP_TO=you@gmail.com # optional, defaults to HERMES_SMTP_USER
  1426. hermes-life-os-weekly-email
  1427. hermes-life-os-weekly-email --days 30 --compare-days 7
  1428. ```
  1429. Emails the same self-contained report `hermes-life-os-dashboard`
  1430. generates - trend charts, correlations, retrospective, habit streaks -
  1431. straight to your inbox. Not wired into the scheduler by default (not
  1432. everyone has SMTP configured); schedule it yourself with your OS's own
  1433. task scheduler if you want it automatic weekly:
  1434. ```
  1435. Linux/macOS (cron): 0 8 * * 1 hermes-life-os-weekly-email
  1436. Windows (Task Scheduler): weekly trigger, action = same command
  1437. ```
  1438. ## Voice Notes (Telegram)
  1439. ```bash
  1440. pip install "hermes-life-os[voice]" # or: pip install faster-whisper
  1441. ```
  1442. Send the Telegram bot a voice note instead of typing - it's downloaded
  1443. and transcribed locally (a free Whisper model via `faster-whisper`, no
  1444. cloud API, no per-minute cost) before being processed exactly like a
  1445. typed message. The reply is prefixed with what Hermes heard, so you can
  1446. catch a bad transcription. `WHISPER_MODEL` (default `base`) controls
  1447. speed vs. accuracy - `tiny` is fastest, `small`/`medium` are more
  1448. accurate but slower on CPU-only machines. Without `faster-whisper`
  1449. installed, voice notes get a clear "couldn't process" reply instead of
  1450. silently failing.
  1451. ## Photo Meal Logging (Telegram, Discord, WhatsApp &amp; Slack)
  1452. Send any of the four bots a photo of your meal (with an optional
  1453. caption) and a vision-capable LLM identifies what's in it and logs it
  1454. - no separate step needed. OpenAI's and Anthropic's default models
  1455. already support vision. On Ollama, pull a vision-capable model
  1456. yourself (`ollama pull llava`) and point Hermes at it explicitly
  1457. (`set HERMES_MODEL=llava` or `--model llava`) - Ollama's default
  1458. text-only models (like `llama3.1`) will simply ignore the image.
  1459. ## Automatic Backups
  1460. Hermes takes a timestamped local backup of your data every day at
  1461. 20:30 (right after the evening nudge check), keeping the 7 most recent
  1462. by default and pruning older ones. Backups live alongside your other
  1463. data (`<profile dir>/backups/`). Run it manually anytime:
  1464. ```bash
  1465. hermes-life-os-backup # keep the default 7
  1466. hermes-life-os-backup --keep 14 # keep the 14 most recent
  1467. ```
  1468. A backup holds the whole memory journal plus every data store registered
  1469. in `storage.DATA_STORES` (18 of them), and a small `_meta` block with the
  1470. format version. Before v1.38.0 only nine stores were included, so the
  1471. nightly backup silently left out spending, reminders, budgets and more.
  1472. Older backups still restore fine; they just lack those sections.
  1473. If `LIFE_OS_ENCRYPTION_KEY` is set, backups are encrypted with it, so an
  1474. encrypted profile no longer leaves a plaintext copy of itself in
  1475. `backups/`. Keep the passphrase: an encrypted backup cannot be read
  1476. without it.
  1477. Through chat, `backup_now` takes a backup on demand and `get_backup_status`
  1478. reports how many exist, when the newest was taken, its size, whether it is
  1479. complete and whether it is encrypted. (`backup_now` always keeps at least
  1480. one backup; a `keep` of 0 or a nonsense value from the agent used to be
  1481. able to delete the backup it had just written.) If backups exist but the
  1482. newest is 3 or more days old, or cannot be read, the proactive nudges
  1483. say so.
  1484. ## Restore
  1485. ```bash
  1486. hermes-life-os-restore --list # backups of this profile, newest first
  1487. hermes-life-os-restore --latest --dry-run # show exactly what would change
  1488. hermes-life-os-restore --latest # asks for confirmation first
  1489. hermes-life-os-restore backup-2026-10-01-203000.json --only spending,budgets --yes
  1490. hermes-life-os-restore backup.json --profile alex
  1491. ```
  1492. Until v1.38.0 backups could be written but never read back. Restoring is
  1493. deliberately a command-line action, not a chat tool. It is built to be
  1494. hard to get wrong:
  1495. - The whole file is validated before anything is written - every section
  1496. must have the right shape and every `--only` name must exist. One
  1497. problem and nothing is touched.
  1498. - Sections that are in the backup replace the current data; sections that
  1499. are not in it (for example spending, when restoring an old backup) are
  1500. left alone.
  1501. - A safety copy of your current data is written to
  1502. `backups/pre-restore-<timestamp>.json` first. These files are never
  1503. rotated away, so a mistaken restore can itself be undone by restoring
  1504. the safety copy.
  1505. - `--dry-run` shows the per-section before/after counts and writes
  1506. nothing. Without `--yes` you are asked to confirm.
  1507. - Data goes through the normal storage functions, so with
  1508. `LIFE_OS_ENCRYPTION_KEY` set the restored files are encrypted. To restore
  1509. an encrypted backup, set the same passphrase it was written with.
  1510. ## Health Check (Doctor)
  1511. ```bash
  1512. hermes-life-os-doctor
  1513. hermes-life-os-doctor --profile alex --json
  1514. hermes-life-os-doctor --strict # warnings also fail (exit status 1)
  1515. ```
  1516. Hermes' storage layer is deliberately forgiving: a file it cannot read
  1517. (wrong passphrase, corruption) quietly loads as empty so the app keeps
  1518. running, which also hides the problem until the data is overwritten. The
  1519. doctor is a read-only check that makes such problems visible and never
  1520. changes anything. It looks at every data store (readable, valid JSON,
  1521. right shape, consistent with the encryption key), the memory journal
  1522. (unreadable lines, duplicate ids), leftover `.tmp` files from an
  1523. interrupted write, backups (any at all, age of the newest, readable,
  1524. complete, older ones unreadable), reminders (a time that can never fire,
  1525. clashing ids, past one-offs) and budgets (bad limits, duplicate
  1526. categories, out-of-range alert thresholds), the day-start setting (an
  1527. invalid `LIFE_OS_DAY_START_HOUR` is flagged instead of silently ignored)
  1528. entries dated in the future (a sign of a wrong computer clock or a bad
  1529. import), persistent entry ids (rows that share an id, journal entries
  1530. linked to a row that no longer exists) and the planner stores (a task due
  1531. date, renewal date or birthday that cannot be read, an unknown body metric,
  1532. an unusable savings target, a symptom without a valid severity, shared ids). Exit status is 0 unless there is an error (or, with `--strict`, a
  1533. warning). The same report is available in chat as `run_health_check`.
  1534. ## Planner: Tasks, Body Metrics, Subscriptions, People & Today's Agenda
  1535. Until v1.42.0 Hermes tracked what you already did. Four new stores cover what
  1536. is still ahead of you, and one tool pulls them together. All of it is local,
  1537. per profile, encrypted with the rest of your data when encryption is on, and
  1538. included in backup, restore, export and the doctor.
  1539. ```
  1540. "add a task: renew passport, due friday, high priority"
  1541. "what's on my plate?" "I did the passport thing"
  1542. "weight 80.5 today" "how is my weight trending?"
  1543. "my blood pressure was 120/80" "set a weight goal of 75 kg"
  1544. "add Netflix, 15 a month, renews on the 20th"
  1545. "I paid Netflix" "what do my subscriptions cost per month?"
  1546. "add Ayse, birthday 03-07, keep in touch every 14 days"
  1547. "I called Ayse" "who should I catch up with?"
  1548. "what's on my agenda today?"
  1549. ```
  1550. - **Tasks** (`add_task`, `list_tasks`, `complete_task`, `update_task`,
  1551. `delete_task`, `get_task_summary`, `clear_done_tasks`): due dates (`today`,
  1552. `tomorrow`, `in 3 days`, `in 2 weeks`, a weekday name or `YYYY-MM-DD`),
  1553. priority, tags and repeats (`daily`, `weekdays`, `weekly`, `monthly`).
  1554. Completing a repeating task moves it to its next due date instead of
  1555. closing it. A task is found by id or by words from its text; an ambiguous
  1556. match is reported rather than guessed.
  1557. - **Body metrics** (`log_body_metric`, `get_body_trend`, `set_body_goal`):
  1558. weight, body fat, waist, hips, resting heart rate, blood pressure (systolic
  1559. and diastolic), blood glucose, temperature and SpO2, with unit conversion
  1560. (lb to kg, F to C, mmol/L to mg/dL), plausible-range checks, a weekly rate
  1561. of change from a least-squares fit, and goals with an estimated arrival
  1562. date. Readings are backdatable, editable through `edit_log` and fed into the
  1563. memory journal. This is a log of your own numbers, not medical advice.
  1564. - **Subscriptions** (`add_subscription`, `list_subscriptions`,
  1565. `update_subscription`, `cancel_subscription`, `resume_subscription`,
  1566. `delete_subscription`, `get_subscription_summary`, `pay_subscription`):
  1567. weekly, monthly, quarterly and yearly payments with the monthly equivalent
  1568. of each, the total, and what renews soon. Dates that have passed roll
  1569. forward and month ends are clamped (the 31st becomes the 28th). Paying a
  1570. subscription also logs it as an expense in its category.
  1571. - **People** (`add_person`, `list_people`, `get_person`, `update_person`,
  1572. `delete_person`, `log_contact`, `get_people_due`): birthdays (`MM-DD` or
  1573. `YYYY-MM-DD`, Feb 29 falls on Mar 1 in other years), an optional
  1574. keep-in-touch goal in days, a contact history and who is overdue.
  1575. - **Today's agenda** (`get_today_agenda`): overdue and due tasks, today's
  1576. reminders, renewals within 3 days, birthdays within 7 days, overdue
  1577. catch-ups, habit streaks that need a check-in today and budget alerts, in
  1578. one answer. Empty sections are left out.
  1579. The proactive nudges now also mention an overdue task, a renewal within three
  1580. days, a birthday and an overdue catch-up (at most two of these per run), and
  1581. the doctor reports planner entries it cannot act on: an unreadable due date,
  1582. renewal date, birthday or metric, and ids shared by two entries.
  1583. ## Lists, Savings Goals, Symptoms & Notes
  1584. Four more everyday trackers, all local, per profile, encrypted with the rest of
  1585. your data when encryption is on, and covered by backup, restore, export and the
  1586. doctor.
  1587. ```
  1588. "add milk, eggs and bread to the shopping list" "I got the milk"
  1589. "start a savings goal: holiday, 2400 by 2027-06-01" "I put 300 into the holiday fund"
  1590. "headache, 6 out of 10, about 90 minutes, stress" "how often did I have headaches this month?"
  1591. "note: gift idea for Ayse, a tea set #gifts" "what notes do I have about gifts?"
  1592. ```
  1593. - **Lists** (`add_list_items`, `get_list`, `get_lists`, `check_list_item`,
  1594. `remove_list_items`, `clear_checked_items`, `delete_list`): named checklists
  1595. for things that are not tasks. The default is `shopping`; any other name
  1596. (packing, movies, ...) works. Add several items in one go ("milk, eggs,
  1597. bread"), tick them off while you shop, clear what is ticked afterwards. An
  1598. item already open on the list is skipped instead of duplicated, and an item is
  1599. found by id or by words from its text.
  1600. - **Savings goals** (`add_savings_goal`, `contribute_to_savings`, `get_savings`,
  1601. `update_savings_goal`, `delete_savings_goal`): a target, an optional deadline
  1602. and starting balance. Add money or take some out (backdated if you like);
  1603. you see the percentage, what is left, your real pace over the last 90 days
  1604. (a starting balance does not count), the day that pace gets you there, and
  1605. with a deadline whether you are on track and how much to put aside per month.
  1606. A goal whose deadline is within two weeks shows up in the proactive nudges
  1607. and in today's agenda.
  1608. - **Symptoms** (`log_symptom`, `get_symptom_summary`): headaches, back pain,
  1609. heartburn and the like with a severity from 1 to 10, an optional duration,
  1610. suspected triggers and notes. The summary gives the count, average and worst
  1611. severity, entries per week, days since the last one, the most common
  1612. triggers, whether it is getting more or less frequent, the worst weekday and,
  1613. when you log sleep, the average sleep on symptom days against other days.
  1614. Symptoms join `list_logs`, `edit_log`, `delete_log`, `undo_last_log`,
  1615. backdating and `log_many`. A personal log, not a diagnosis or medical advice.
  1616. - **Notes** (`add_note`, `list_notes`, `search_notes`, `update_note`,
  1617. `delete_note`): a quick-capture inbox with tags and pins; search finds notes
  1618. containing all your words in the text or tags.
  1619. The doctor now also reports savings goals with an unusable target or deadline,
  1620. symptom entries it cannot use, list items and notes without text, and ids shared
  1621. by two entries; entries dated in the future are checked for body readings and
  1622. symptoms as well.
  1623. ## Income, Debts, Countdowns & Supplies
  1624. Four more trackers, all local, per profile, encrypted with the rest of your data
  1625. when encryption is on, and covered by backup, restore, export and the doctor.
  1626. ```
  1627. "I got paid 3000 salary" "how did the last three months go?"
  1628. "I borrowed 500 from Ali, due the 15th" "I paid Ali 200"
  1629. "Mehmet owes me 120 for dinner" "who owes what?"
  1630. "count down to the holiday on 2026-12-20" "how long since I quit smoking?"
  1631. "I have 30 vitamin D pills, one a day" "when do I run out?"
  1632. ```
  1633. - **Income and cash flow** (`log_income`, `get_cash_flow`): income is a tracker
  1634. like the others (list, edit, delete, undo, backdate, `log_many`). The cash
  1635. flow report puts income next to your logged spending per month: net, the
  1636. share of income you kept, the average of finished months and your income
  1637. sources, and it says so when you have spent more than you earned this month.
  1638. - **Debts** (`add_debt`, `record_debt_payment`, `get_debts`, `update_debt`,
  1639. `delete_debt`): money you owe (`owe`) and money owed to you (`owed`, also
  1640. "lent"). Record partial payments (backdated if needed; you cannot pay more
  1641. than what is open), see both sides with a net figure, and overdue flags. A
  1642. debt that is overdue or due within three days appears in the proactive nudges
  1643. and in today's agenda.
  1644. - **Countdowns** (`add_countdown`, `get_countdowns`, `update_countdown`,
  1645. `delete_countdown`): days until an event, or days since one (past dates are
  1646. fine). A yearly countdown always points at its next anniversary and counts the

Lines 2,001–2,419 are not shown. The link to the file on GitHub has every line.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.