# Understanding HEART **The important ideas behind HEART, in sixteen short sections. No code, and nothing to install.** Each section ends with where to read more. --- ## 1. The problem HEART solves AI is arriving in products one integration at a time. Each team picks its own model provider, its own prompts and its own way of failing, so two products from the same company may share nothing. And no common question can be put to an arbitrary product: *are you healthy, what can you do, what may you share, and who approved what you just did?* Logs and dashboards collect signals for people to read, but the product itself does not act on them. The protocols that exist work at other layers: the Model Context Protocol gives models tools, Agent2Agent lets agents hand work to each other, and the W3C Web of Things describes what a device offers. None defines how any system knows itself, looks after itself, and proves what it disclosed. HEART does. *Read more:* [the standard](/spec), [Part 1: Basics](/spec/HEART-Part-1-Basics-1.0.md). ## 2. What a HEART is A **HEART** is a small, standard part that lives inside a product, such as a thermostat, a camera, a pump station, a web shop or a robot. It is always aware of what happens inside its product, and it cares for it. The name stands for **H**olistic, **E**volving, **A**I, **R**econnaissance and **T**ending: it sees the whole system, learns safely, can use AI, keeps watch, and acts on what it knows. The words borrow from the body. A **Pulse** says "I am alive, and this is how I am". An **Arrhythmia** is an alert. The **Valve** controls what leaves the product. The inner awareness that knows everything happening inside is called **Antaryami**, a Sanskrit word for the inner witness. *Read more:* [Part 1: Basics](/spec/HEART-Part-1-Basics-1.0.md). ## 3. Three principles 1. **Awareness belongs inside the product.** Intelligence may live in the cloud, but noticing that something is wrong must happen inside, with no network. 2. **Every product speaks one language.** HEART reuses existing standards (CloudEvents, JSON Schema, OpenAPI, OAuth 2.0, Problem Details, MQTT) rather than inventing new ones. 3. **Models propose, products decide.** Nothing a model says ever acts without passing the same checks as any other request. > *An application's intelligence may live in the cloud, but its awareness and care must live within.* ## 4. The brain can live anywhere A HEART needs no large model built in. Its "brain" can be a small model on the device, a model on a nearby gateway, or a large model in the cloud. **A HEART with no brain at all still works.** This is possible because understanding a product's own API is mostly a **lookup problem**, not a reasoning problem. The list of operations is finite and written down. So a small runtime can serve requests, notice faults and raise alerts with rules and lookup alone. A model helps with messy wording and hard diagnosis. Products stay small, need no special chip, and get better on their own when better models are released. > **Knowledge lives in the system. Rules keep it safe. Models make it fluent.** *Read more:* [Core Standard](/spec/HEART-Core-Standard-1.0.md). ## 5. How a HEART speaks Every HEART answers the same few questions in the same way, on the same port, **43278**, which spells HEART on a telephone keypad (fallback 7685). | Question | Where to ask | Who may ask | |---|---|---| | Who are you? | The **Card**, at `/.well-known/heart-card.json` | Anyone | | How are you now? | The **Pulse**, at `/heart/v1/pulse`: healthy, degraded or failing | Anyone | | What is wrong? | The **alerts**, at `/heart/v1/arrhythmias` | Anyone sees the codes; the owner sees more | Every message is a standard CloudEvent, so existing tools can route it unchanged. If a product's Pulse stops arriving for three of its intervals, everyone watching treats it as unknown: a **Flatline**. The full API has 117 operations, but a small product needs only a handful. *Read more:* [API Standard](/spec/HEART-API-Standard-1.0.md), [Part 4: Connections](/spec/HEART-Part-4-Connections-1.0.md). ## 6. Fault codes everyone understands Since 1996, every car sold in the United States reports faults with standard OBD-II codes, so P0300 means "engine misfire" on any car. HEART does the same for any product, with readable codes of the form `area.problem`, such as `storage.full`, `power.battery-low` or `sensors.drift`. There are 11 areas (`system`, `power`, `connectivity`, `storage`, `performance`, `software`, `ai`, `sensors`, `actuators`, `data`, `security`) holding 64 standard codes. Makers add their own under their own domain name, so codes never clash, and a code never changes its meaning once published. An alert can carry two codes: what is seen, and why. A dashboard watching 500 products of different makes can count every `storage.full` without knowing a single brand. Inside a message a code is written bare (`"code": "storage.full"`). In logs, tickets, manuals and searches it is written **`HEART storage.full`**, so anyone can tell which list it comes from. Each standard code also has a short fixed number, its **H-number**, for small screens, blinking lights and phone calls: `H-04002` is `storage.full` (area 04, code 002). The name stays the main form, and maker codes have no H-number. Every code has its own page, with likely causes, fixes and what the HEART does by itself: look one up at [/system-code](/system-code), such as [/system-code/H-04002](/system-code/H-04002). Things that simply happen, such as `system.started`, are event types, not faults. *Read more:* [Part 3: Information Model](/spec/HEART-Part-3-Information-Model-1.0.md). ## 7. Small to start, room to grow A standard for every product must fit the smallest one. So it has three **Feature Sets**, each including the one before: | Feature Set | Adds | Suits | |---|---|---| | **Basic** | Card, Pulse, alerts, noticing and telling a person, privacy | Any product | | **Connected** | Events, questions, subscriptions, receipts of what was shared | Most applications | | **Full** | Commands, approvals, learning, and control of the product's own autonomy | Self-healing systems | Everything else (updates, schedules, fleets, AI, lifecycle and more) is an optional module a product lists in its Card. One thing is required at every level: **Tending**. Even a Basic product must notice when its main job stops, raise an alert, explain it in plain words, and tell a person, with no network. A product that only reports is monitored, not tended. *Read more:* [Track 1: Basic](/spec/HEART-Track-1-Basic.md). ## 8. Autonomy Levels: how much a product does on its own "Has AI" says nothing about what a product will do by itself. Driving had the same problem until the six SAE levels gave everyone one scale. HEART does the same for any product. When something goes wrong, four jobs must be done: **notice** it, **understand** why, **decide** what to do, and **do** it. | Level | Name | Who does what | |---|---|---| | A0 | Unaware | A person does everything | | A1 | Aware | The product notices; a person does the rest | | A2 | Explains | It notices and explains the likely cause; a person decides | | A3 | Suggests | It proposes a fix; a person approves; it carries it out | | A4 | Fixes known problems | It follows rules ("Playbooks") a person adopted in advance | | A5 | Fixes new problems | It works out fixes itself, within limits a person set | **A1 to A4 need no AI model and no network.** Three rules hold at every level: Stop always works at once; only a person can raise a level; and a higher level never means less safety. Higher is not "better", only more automatic: a web service might be A5, a medical pump A2. *Read more:* [Part 2: Autonomy Levels](/spec/HEART-Part-2-Autonomy-Levels-1.0.md). ## 9. The Valve: privacy built into the data In HEART, privacy is not a policy document. It is a label on every piece of data, in four levels: **public** → **internal** → **private** → **never-share** The **Valve** checks everything that leaves the product against these labels, and keeps a receipt of what left, so the owner can prove what was shared. Data marked `never-share`, such as a Wi-Fi password, never leaves the chip, not even to the owner's own AI model. A good rule follows: the best way to keep a secret on a device is not to put it there. A birdhouse camera, for example, never stores its location at all. *Read more:* [API Standard, privacy](/spec/HEART-API-Standard-1.0.md). ## 10. Every signal, declared once A product is full of signals: temperatures, speeds, currents, switch positions, counters. A HEART that knows them can notice problems early and give a model the facts it needs, but it could also leak one, or change one it should never touch. So every signal is declared once, in a **signal table**: its unit, its normal range, where it is read from (a pin, a register, a firmware variable), its privacy level, and three flags: **writable**, **physical** (it moves, heats or switches something in the real world) and **safety** (it is part of a safety function, so the HEART may only read it). A signal not in the table is invisible. A tool drafts the table from files engineers already have, carefully: nothing is writable by default, and a person must review and seal it before the HEART will start. *Read more:* [Signal tables](/spec/HEART-Signal-Tables-1.0.md). ## 11. The model proposes, the HEART decides When its own rules run out, a HEART may ask a model for help. It sends the fault and a summary of the signals, never raw private data. The model answers with a **Proposal**: what to change, to what value, the effect to expect, and how to undo it. A Proposal that cannot be checked or undone is refused. The Proposal then passes the same **gate** as any request. It may run on its own only if the owner listed that change for the AI in advance, inside an **envelope** (a minimum, a maximum, a largest step, a daily count and a cooldown). Even then it runs as a **Trial**, in small steps, watched, and undone automatically if it does not help. A fix that worked can become a Playbook, but only once a person adopts it. Next time, the product handles it as a reflex, in milliseconds, with no network. Over time it needs its brain less. That is the **Evolving** in HEART. *Read more:* [Track 3: Advanced](/spec/HEART-Track-3-Advanced.md), [Core Standard](/spec/HEART-Core-Standard-1.0.md). ## 12. A person must really be there The most dangerous attack on a system that lets AI act needs no bug at all: an AI agent holding a person's login looks exactly like the person, and could approve its own proposals. The rule that stops it applies far beyond HEART: **a token says which account is calling, not who is there.** So any step that must involve a person needs **proof of presence**, tied to exactly what they approve: a passkey, a confirmation on a registered phone, or a button on the device itself. Every change to who may do what is treated as dangerous, and needs approval too. A physical change asked for by an AI always waits for a person. And **Stop** always works, at once, with no approval and no network. *Read more:* [Part 6: Human Control and Safety](/spec/HEART-Part-6-Human-Control-and-Safety-1.0.md), [the security advisory](/spec/HEART-Security-Advisory-2026-001.md). ## 13. Never in the safety chain Physical safety comes before everything. A HEART stays **out of the safety chain** and out of fast control loops, and never bypasses an interlock. | Layer | Run by | The HEART's role | |---|---|---| | Safety | A certified safety system | None. It may read, at most. | | Real-time control | The existing controller | None in the loop. It may read values. | | Supervision | Operators | It advises, and acts only with guards and approval | | Maintenance | Engineers | Its main value: it explains, predicts and gathers evidence | This is why, in the example products, the EV charger's certified controller, the pump station's PLC and the 3D printer's firmware keep full control, and a pacemaker's software is never touched. Following HEART does not certify anything as safe: a product's own safety standards still apply. *Read more:* [From simulator to real device](real-devices/README.md). ## 14. A switch that can take the AI away Trust in a model must be earned by watching what it does. A model can be tricked or poisoned, and a new version may behave in ways nobody has seen. So an owner, or anyone responsible for many devices, needs a way to take the brain away, even from a device they cannot reach. A message saying "stop" can be blocked or lost. So HEART turns the switch around: a device may use a brain only while it holds a short **lease**, signed by a **Command Center** that also holds the model keys and signs every answer. **The switch is pulled by not renewing.** Within one lease period (5 minutes by default), every device it covers becomes **brainless**, even if no message reaches it. Brainless is a safe, defined state: the device loses its advice, never its heart. It keeps noticing, alerting and following the rules a person adopted. And the switch never stops the machine: a car's brakes belong to its certified controller, not to its AI. *Read more:* [Command Center profile](/spec/HEART-Command-Center-1.0.md). ## 15. Proving it, honestly A claim such as "this thermostat is HEART A4" is worthless if nobody checks it. **HEART-Rating** runs the standard's tests against a product and gives one number from 0 to 10, with caps so that one critical failure can never be hidden by many passes: any critical failure caps the rating at 3.9, labelled **Unsafe**. One rule outweighs the rest: **a product may claim only what it has passed.** **What exists today, honestly:** - A reference implementation in Rust, its daemon and a Gateway, tested against a simulated Modbus device and a mock model. - Starter templates in 17 languages and platforms, 14 of them tested. - HEART Hub at heartcortex.ai, with real devices reporting. - Docker Engine given a HEART in two ways and tested with real containers, including a live run where Claude recommended more CPU and the owner applied it. - Nine simulated products you can run. **Not yet:** nothing has run on physical hardware, and a real model has so far only advised an owner on HEART Hub. The threat analysis was done by the standard's author, so an independent security review is still needed. *Read more:* [HEART-Rating](/heart-rating/README.md), [Part 9: Testing and Certification](/spec/HEART-Part-9-Testing-and-Certification-1.0.md). ## 16. Three layers without delay HEART has one rule for time: **nothing fast ever waits for anything slow.** A product with a HEART can have three layers, each slower than the one before it. None waits on a slower one. | Layer | Where | Works in | Its job | |---|---|---|---| | **HEART** | Inside the product | Milliseconds | Notice, alert, follow the rules a person adopted, stop | | **HEART Hub** | A website, such as heartcortex.ai | Seconds | Show health to the owner, email when a device goes quiet, carry the owner's signed changes | | **Hub AI** (optional) | A model, called with the owner's own API keys | Seconds to a minute | Explain and recommend, when the owner asks | Ten ways keep that promise: 1. **Noticing happens inside**, with rules, and never asks the network. 2. **A Playbook a person adopted runs as a reflex**, in milliseconds. 3. **Stop works at once**, with no approval and no network. 4. **Reporting runs beside the HEART's own work**, with a short time limit. If the Hub is slow or away, the HEART carries on. 5. **The Hub answers a report from what it holds.** It never calls a model on the way. 6. **Watching for silence is a separate sweep.** No report waits for it. 7. **Hub AI runs only when the owner asks**, and it only recommends. Its answer is used when it comes; nothing waits for it. 8. **A late decision is refused.** An owner's signed decision more than 300 seconds old never acts, so it cannot act on a situation that has changed. 9. **The brain works on a lease.** When the lease lapses, the device becomes brainless at once. It is never stuck waiting for a model. 10. **Nobody waits on a guess.** While the owner makes a change, the device reports every 2 seconds (the faster channel). A device that sleeps says how long, so its silence is not mistaken for a fault. How long things take: | What | Time | How we know | |---|---|---| | A fault noticed inside the product | 0.4 to 1.6 s (an out-of-memory kill, a failing health check); 2.9 to 3.3 s for a restart loop, which needs several restarts | Measured: Docker with a HEART, real containers, on two machines | | Stop | At once, on the device | By design: no network, no approval | | An owner's change reaching the device | About 2 s after the owner confirms it, and its result on the page in about 4 s, plus the network. Without the faster channel: up to one reporting interval (30 s by default). | Measured in HEART Hub's tests with a test clock: 1.3 s and 3.3 s | | A silent device shown as "Not heard from" | After three reporting intervals, at least 90 s; for a sleeping device, after its sleep and a grace | By design | | Its owner emailed | Within 5 minutes after that | By design: the sweep runs every 5 minutes | | A Hub AI answer | Seconds to a minute | Depends on the model. Nothing waits for it. | | A brain cut by its Command Center | Within one lease period, 5 minutes by default | By design | *Read more:* [API Standard, design principles](/spec/HEART-API-Standard-1.0.md#11-design-principles), [HEART Hub, Sections 5.5 and 7](/spec/HEART-Monitor-1.0.md), [HEART for IoT](HEART-for-IoT.md). --- ## Where next - **See it working:** [the live demos](/monitor/demos). - **Try it in 15 minutes:** [the quick start](Quick-Start.md). - **Know what to read:** [pick your reading track](/start). - **All manuals:** [Documentation](/docs).