# Hearth **So that every new carer, nurse and hospital ward knows how to look after somebody — in that person's own words — without them having to explain themselves all over again.** [![tests](https://github.com/topeuph-ai/hearth/actions/workflows/tests.yml/badge.svg)](https://github.com/topeuph-ai/hearth/actions/workflows/tests.yml) Margaret has dementia. Her daughter, a district nurse, a support worker and a day centre all help look after her. Each time somebody new arrives, the same things have to be said again: speak to her left side, she is deaf on the right; she settles if you talk about her allotment; please don't move her chair. **Hearth keeps those things in one place, written down once, and shares them with the people Margaret chooses.** Her family and carers each keep a copy on their own phone or computer. Anybody can suggest something to add; Margaret, or whoever looks after the record for her, decides what goes in. There are photographs, and recordings of her voice, for the things words don't catch. **No company holds it.** The record lives only on the devices of the people around Margaret — there is no database in the middle for anybody to run, sell, lose or shut down. It is locked so only her circle can open it, and it keeps working between devices in the same house when the internet goes down. What it holds follows a national standard for exactly this kind of record, [PRSB "About Me"](https://theprsb.org/standards/aboutme/) — what matters to the person, how to communicate with them, what to please do and please not do. Nothing medical: no medicines, no diagnoses. *Hearth is an early working demonstration, not yet used for a real person. Free and open source.* > ### 📖 [New to Hearth? Read *Hearth in plain words*](docs/hearth-in-plain-words.pdf) > > **For anybody who is not a programmer.** Eight pages with pictures: how > Hearth works, who can do what, what "locked" means, and how it differs from > paper passports and other care-record apps. What is not finished is said > plainly. --- ## The problem this is trying to solve Somebody with a learning disability, or dementia, or a long-term condition, is seen by a lot of different people. A district nurse. A support worker. A GP. A hospital ward. Their daughter. Each of those people writes things down in their own organisation's system, and those systems do not talk to each other. So the person explains themselves again, every time, to everybody — how to talk to them, what frightens them, what helps. There is already a national standard for exactly this: the PRSB **About Me** standard. The problem was never what to write down. It was **where to put it.** ### Why nobody has solved it Every previous attempt built a shared place to put the record. And whoever builds that place becomes **the operator** — the organisation legally responsible for holding sensitive information about a vulnerable person, contributed by seven other organisations, and still around in twenty years' time. Almost nobody wants that job. Microsoft tried it with HealthVault and closed it in 2019, taking the data with it. **So this has no operator.** The record lives on the devices of the people in the circle, and nowhere else. A professional is not depositing information into somebody else's system — they are sharing from their own, which is a different thing legally as well as technically. That is the whole idea. Everything else here is a consequence of it. --- ## What it deliberately is not **It is not a clinical record**, and it must not become one by accident. No medications, no diagnoses, no care plan. The About Me standard says the same thing about itself. That boundary is doing real work. It keeps clinical safety certification (DCB0129), clinician liability and the heaviest data protection questions out of scope entirely. > **Do not add clinical fields without understanding what they drag in with > them.** --- > ## 🧊 One file in this repository must never be edited > > `dnas/aboutme/zomes/integrity/aboutme/src/lib.rs` > > **Why:** a circle is identified by a fingerprint taken of that file once it is > compiled. Change the file and you change the fingerprint, which means every > circle anybody has ever made becomes unreachable. Their records stay on their > own hard drives and no future version of this app will ever open them again — > with no error message, anywhere, to explain it. > > **Not even comments.** Adding a comment block was measured to change the > fingerprint (`dd942cac…` became `941f0b41…`), because the compiler stores line > numbers for its error messages. Undoing the comment restored it exactly, which > also tells us the build is reliable and the comment really was the difference. > > All the work happens in the interface and the coordinator zome. Neither of > those affects the fingerprint. CI fails the build if the file moves. > > If it genuinely has to change, that is a planned migration, not an edit: it > was done once, in September 2026. The new version installs beside the old one, > nobody's circles are lost, and each holder carries their circle across — see > [docs/upgrades.md](docs/upgrades.md). --- ## Trying it ### ⬇️ [Download the Windows installer](https://github.com/topeuph-ai/hearth/releases/latest) > **This is an early demo.** It exists to show the idea is possible, not to be > relied on. Please do not put real information about a real person into it. One file, about 115MB. Everything it needs is inside — no Rust, no Node, no separate downloads, no server to run. **Windows only for now.** For Mac or Linux, see [docs/building-it.md](docs/building-it.md), and **do not compile it yourself** — that produces a different fingerprint and a private network of one. Build the app around the released `hearth.webhapp` instead. ### Three things will happen on Windows. None of them means anything is wrong. **1. Windows will try to stop it opening.** You will see *"Windows protected your PC"*. Click **More info**, then **Run anyway**. This happens to any application whose publisher has not bought a signing certificate, which costs money this project does not have. It is not a judgement about the file. In some NHS settings that will not be acceptable, and it is worth saying so — it is a cost, not a fault. **2. For the first minute after downloading, it may refuse to start.** Nothing happens, or Windows says *"Access is denied"*. The file is not deleted and not quarantined. Your antivirus is holding the file open while it scans it, and 115MB takes a moment. **Wait a minute and try again.** That is exactly what happened here on 9 September 2026, and it cleared on its own. **3. If it works but never finds the other person, it is almost certainly your antivirus.** Everything on your own machine looks fine. No error appears anywhere. It simply never sees anybody else. Norton, Kaspersky, Avast, ESET and most workplace networks inspect secure connections by quietly re-signing them. Your browser accepts this. Holochain does not, and refuses to connect rather than trust something it cannot check. **The fix is one line.** Add this address to your antivirus's list of sites to leave alone: ``` dev-test-bootstrap2.holochain.org ``` Then **close the app and open it again** — it will not retry a connection that has already failed, so until you restart it the fix looks like it did nothing. Verified here with Norton 360. Everything else on your machine stays protected exactly as it was. The longer explanation is in [docs/building-it.md](docs/building-it.md). --- ## The one thing this project most needs **Two computers have run this — and kept working with the internet unplugged, until they were restarted.** On 14 September 2026, a desktop and a laptop on the same home wifi, each with the 0.2.2 release: somebody joined a circle through its door, offered a suggestion and had it accepted. Then the broadband was unplugged, the record was changed on one machine, and the change arrived on the other. **Restarted with the internet still gone, they never found each other.** Holochain 0.7 forgets where other devices are when it stops, and relearns it from an internet server. **On 19 September a field-test build fixed that.** With a version of Holochain that looks for devices on the local network, both machines were restarted with the broadband unplugged and found each other in about a minute — the laptop had joined by scanning a QR code off the other screen. That build is not for general use yet, so released Hearth still has the limit. The whole story is in [what is proven](docs/what-is-proven.md#two-machines-and-then-no-internet). Not yet tried: two machines in different places, finding each other across the internet. If you are somewhere else and have a Windows computer, that is the half hour that would tell this project the most. See [what is proven and what is not](docs/what-is-proven.md), which is the honest inventory and the page to trust if anything here sounds more finished than it is. --- ## How it works, briefly **A circle** is a private network for one person. It is created around the public key of whoever holds it, and that key is baked into the circle's identity. A different holder produces a completely different network. Circles cannot see each other. That is a fact about the mathematics, not a setting somebody could get wrong. **An invitation** is the holder's signature over your public key. You show it at the door, and every existing member checks it themselves. There is nobody to ask for permission, because there is nobody in charge. Because it is signed over *your* key, an invitation cannot be passed on to somebody else. **Only the person may write their own About Me.** Being in a circle lets you read it and confirm you have read it. It never lets you write somebody else's account of themselves. **Anyone may suggest something**, and only the holder decides what goes in. A son remembers what his mother enjoyed; a support worker notices what settles her. A record only one person may write throws all of that away. **A professional's whole job is one tap** — confirming they read a particular version. It costs them almost nothing, and it is the thing families currently have no way of knowing at all. > **What that tap proves, and what it does not.** It proves a particular key > said it had read a particular version. The role beside it — "district nurse" — > is typed in by that person and **nothing checks it.** The interface says > "claimed" every single time, and it must keep doing so. A family could > reasonably rely on a tick that means more than it does. **The holder can remove somebody, and name a successor.** Removing somebody changes the circle's key, so they cannot read what is written next. A successor, named in advance, can take the circle on if the holder cannot — after a waiting period everybody sees, in which the holder can say "I'm still here", and a check by somebody else. **A pass** shows chosen parts of the record to somebody passing through — a ward nurse, a paramedic — for as long as the holder chooses, without them joining. There is more detail, including what the reviews found and what they missed, in [docs/how-it-works.md](docs/how-it-works.md). --- ## What it cannot do Said here rather than buried, because these are the honest limits. **Holding the device is holding the keys.** Since 0.2.7 the record, suggestions, photographs, sound and video are locked to the circle, so a copy on somebody's disk is unreadable without the circle's key. But the key lives on the same device, and the released app does not yet ask for a password. That is the largest gap, and it is decided, not yet built. How members describe themselves is not locked yet either. See [docs/encryption.md](docs/encryption.md). **Removing somebody cannot take back what they have read.** The holder can remove a person: they get none of what is written afterwards, because a new key is made that they are never given. What they already had, they keep. That is not evasion, it is arithmetic: once somebody has legitimately read something, nobody can un-read it. No system anywhere can do this. **A stranger cannot find the record.** A paramedic who has never heard of this has no way to discover it exists. A **pass** lets the holder show chosen parts to a professional passing through without them joining — but only while the holder's device is on, and somebody still has to hand them the pass. Paper solved finding it with a sticker on a fridge, and we have not. **Devices in the same house talk to each other through the internet.** Released Holochain cannot find a device in the same room, so joining can take a minute or two and a video can take ten. A field-test build of Holochain fixes it; see [docs/latency.md](docs/latency.md). **Nothing has had a human security review.** Four AI reviews and an audit of our own found and fixed real problems — see [docs/threat-model.md](docs/threat-model.md). Nobody who does this for a living has looked, and that is the review this project most needs. --- ## Where the code lives | | | |---|---| | `dnas/aboutme/zomes/integrity/` | the rules — **frozen, see above** | | `dnas/aboutme/zomes/coordinator/` | the functions the app calls | | `ui/` | the interface | | `tests/tests/adversarial.rs` | 41 tests written as attacks, run on every push | | `docs/` | everything below | **Built with Holochain 0.7.0** (hdk 0.7.0, hdi 0.8.0), read from the source at tag `holochain-0.7.0` rather than from documentation, which lags badly. --- ## The documents Read the first one before the others. | | | |---|---| | [what-is-proven.md](docs/what-is-proven.md) | **Start here.** What is tested, what is built but unwatched, what is not built. If anything else disagrees with it, this page is right | | [threat-model.md](docs/threat-model.md) | One page: what is at risk, what stands in the way, what is left, and how sure each answer is | | [encryption.md](docs/encryption.md) | Design note: locking the record with a key that changes when somebody is removed | | [migration-batch.md](docs/migration-batch.md) | Every change waiting for the frozen rules, in one list to decide item by item | | [multimedia.md](docs/multimedia.md) | Photos, sound and video in the record: what the standards ask, what was decided, and how it would be built | | [licensing.md](docs/licensing.md) | What licence Hearth is under, and what shipping Holochain inside the app asks of us | | [hard-questions.md](docs/hard-questions.md) | The questions a sceptical reviewer would ask, and the honest answer to each — including where the answer is not software | | [building-it.md](docs/building-it.md) | Building, running the demo, packaging the desktop app, and every trap already paid for | | [how-it-works.md](docs/how-it-works.md) | The membrane, revocation, and why offline is not a failure | | [upgrades.md](docs/upgrades.md) | How a circle survives a new version — and why neither a patch nor a minor release does it today | | [hearth-in-plain-words.pdf](docs/hearth-in-plain-words.pdf) ([web page](docs/hearth-in-plain-words.html)) | **For anybody who is not a programmer.** How Hearth works in plain words, with diagrams, and how it differs from other ways of sharing a care record | | [holochain-roadmap.md](docs/holochain-roadmap.md) | Holochain's own plans, read 24 September 2026, and what each means for Hearth — 0.7.1 security fixes, 0.8 app upgrades, local discovery not before 1.0 | | [to-a-product.md](docs/to-a-product.md) | What stands between this and something usable, in the order it blocks | | [standard-and-gap.md](docs/standard-and-gap.md) | Field by field against the PRSB About Me standard | | [DPIA.md](docs/DPIA.md) | Data protection assessment | | [medical-device-determination.md](docs/medical-device-determination.md) | Why this is not a medical device, with the intended purpose statement and the line that would change it | | [dtac-position.md](docs/dtac-position.md) | Where Hearth stands against DTAC, and the question DTAC cannot currently answer | | [standards-position.md](docs/standards-position.md) | Every standard and regulation that applies, and the honest status of each | | [EHIA.md](docs/EHIA.md) | Equality and health inequalities impact assessment — including who this could leave out, and how it could widen the inequality it means to narrow | | [latency.md](docs/latency.md) | Why joining takes ninety seconds | | [prior-art.md](docs/prior-art.md) | What has been tried before, and what became of it | | [what-to-borrow.md](docs/what-to-borrow.md) | What paper got right that we have not | | [outer-ring.md](docs/outer-ring.md) | Letting somebody read without joining | | [storyboard.md](docs/storyboard.md) | The demonstration, scene by scene | | [funding.md](docs/funding.md) | Where the money might come from | | [hearth-explained.md](docs/hearth-explained.md) | What Hearth is, how it works, and where to get it — the version to hand to somebody | | [the-case.md](docs/the-case.md) | Why Hearth exists, how it differs from what already exists, and the questions anybody will ask — with the honest answers | --- ## Running it yourself Two windows on one machine, each a separate person with a separate store, talking to each other with nothing in between: ```bash cd ui && npm run demo ``` Full instructions, and the things that will otherwise cost you an afternoon, are in [docs/building-it.md](docs/building-it.md). --- ## The demonstration Two laptops and a phone. A person, their daughter, a nurse. The daughter writes something. It appears on the nurse's screen. **Take the internet away and keep the local network** — it carries on working. Take a device out of the room, change something, bring it back — it catches up. The first half of that was shown on two real machines on 14 September 2026 — for as long as nobody restarts. Restarting without the internet was shown to work on 19 September with a field-test build of Holochain, and will reach released Hearth when official Holochain has local discovery. Taking a device away and bringing it back has not been tried on two machines yet. > There is no account and no company holding the record. If I am hit by a bus > tomorrow, nobody's circle depends on me. --- ## Licence **Hearth's own code is Apache License 2.0.** See [LICENSE](LICENSE). **The installer also contains Holochain and lair-keystore**, which are licensed under the [Cryptographic Autonomy License 1.0](https://opensource.org/license/cal-1-0). Their source is at , and Hearth's rules are built with Holochain's HDK, which is under the same licence. What that asks of anybody distributing Hearth is set out in [docs/licensing.md](docs/licensing.md). Built by one person who is not a software engineer, with AI assistance, and the design decisions are his. [What that means in practice](docs/what-is-proven.md#who-is-building-this-and-with-what).