How UnloopMe Works Under the Hood: Sync, Intelligence, and Notifications

The Whole System in One Picture

Jump to:How sync worksWhat the server deletes

UnloopMe is split into two halves that barely talk to each other. Your phone is the fast half. It stores everything, runs simple logic, and updates the screen the instant you tap. The server is the slow, clever half. It wakes only twice a day, and when it does it thinks deeply about your data and writes the next batch of nudges.

Three arrows connect the two. The server sends a silent wake up. Your phone uploads what you logged. The server sends back fresh insights and notifications. That is the whole conversation, and crucially your phone never starts it on its own.

Throughout this guide the five modules keep the same colours, so you can follow them across every diagram.

How Sync Works: The Phone Only Wakes When Told To

Jump to:What the server deletes

Here is the surprising part. Opening the app does nothing on the network. Neither does switching tabs, pulling to refresh, or finishing onboarding. UnloopMe deliberately refuses to sync on any of those. The only thing that ever starts a sync is a silent push from the server, sent around 08:30 in the morning and 21:00 in the evening. The app can also learn a better hour for you over time.

Why so strict? Imagine someone anxiously opening the thought-spiral module at 2am. If the app synced on every open, the server would spin up its whole thinking pipeline for nothing, because there is no new data. The person just opened the screen. Push-only sync means the phone stays asleep until the server genuinely has a reason to wake it.

Each wake up does two things in order. First it uploads everything new. Then it pulls down and clears whatever the server prepared last time. That second step is the clever bit. The server does its heavy thinking in the background after the upload, so the results are ready and waiting at the NEXT wake up. You never sit and watch a spinner. Every sync feels instant because it is collecting the previous round's homework.

How Sync Stays Safe: No Duplicates, Nothing Lost

Phones are unreliable. A push can arrive twice, a connection can drop in the middle of an upload, the app can restart. So the server is built so it can never double count. Every log you make gets a unique fingerprint the moment it is created on your phone. When logs arrive, the server checks each fingerprint, and if it has already seen one it quietly ignores it.

This matters more than it sounds. Picture a hard evening where you logged six cravings in the smoking recovery module. If a flaky network made your phone upload that batch twice, without protection those six could become twelve. The app would then think you were struggling far more than you really were, and start nudging you as if you had relapsed. The fingerprint deduplication makes that impossible.

Your onboarding answers and settings are handled just as carefully. Each module's preferences are saved with one rule: insert if new, update if changed, never delete. So your declared triggers, your quit goal, and your chosen reminder times build up over time instead of being overwritten or lost.

What the Server Keeps, and What It Deletes

Jump to:How sync worksWhat happens after a notification is sent

A fair question at this point. If the server keeps thinking about you, does it hoard a growing pile of data? No. The design is closer to a kitchen than a warehouse. Raw ingredients are kept, finished dishes are handed over, and the counter is wiped.

Your raw event logs are the ingredients, and they are kept as the single source of truth, deduplicated by fingerprint. Everything the server computes from them, meaning your patterns, missions, recovery scores, brain state, and notifications, is treated as a finished dish placed in a small per client outbox.

When your phone next syncs, it pulls that outbox in a single step that reads the rows and deletes them inside the same database transaction. Read and delete happen together, so each insight is delivered exactly once and the outbox can never pile up. If the network drops before the delete commits, nothing is lost: the rows simply stay, and the next pull collects them. The phone is idempotent too, skipping anything whose fingerprint it already holds.

Notification records are the one thing kept a little longer, because the app needs to track whether each was delivered, tapped, or dismissed. Those live in a durable log that a nightly sweep prunes after a fixed retention window, and a separate cap stops any one person's queue from growing without limit. The net effect: working data is cleared as soon as it has been delivered, and only a short, bounded history is retained.

How Intelligence Is Built: Layers on Layers

Jump to:How each module finds patternsHow confidence is scored

Once your logs are safely stored, the server starts thinking. It does not run one giant algorithm. Instead it passes the same data through several layers, each asking a different question. Lower layers look at one habit. Higher layers look across habits and across time.

The first layer is per recovery track: a separate engine for each of the five habits, looking only at that habit. The second layer is combined, and it runs only if you use two or more tracks, looking for links between them. Above that sits the brain engine, which stops thinking in habits at all and starts thinking in loops. Finally a recovery science layer turns your behaviour into gentle, clearly labelled estimates of how your body and mind are healing.

Every layer produces small insight cards in the same shape: a short title, a description, a priority, and some data. Because they all look alike, the server can store them with one simple rule and your phone can read them with one simple rule. New cards get added, cards the engine still sees get reinforced and kept fresh, and cards it stops seeing slowly fade. That fading and strengthening is how the app keeps up with you instead of clinging to last month's pattern.

Sometimes the phone and the server disagree, because the phone made a quick guess while you were offline and the server later found something better. A simple ranking settles it. A real AI written insight beats a server rule, which beats the phone's quick starter guess, which beats a plain fallback. The stronger source always wins, so you never keep seeing a stale guess once a better answer exists.

How Each Module Finds Its Patterns

Jump to:How confidence is scoredThe brain engine

Every track rests on one idea from behavioural science: the habit loop of cue, routine, reward. A cue fires, you run the routine, you get a reward, and the reward wires the loop a little tighter, so it runs more automatically next time (neurons that fire together wire together). Each track's job is to rebuild the shape of YOUR loop from your logs: the cue, the timing, and the need the reward is quietly meeting.

Each module reads a different signal, because each habit speaks its own language. Here is what each one measures.

Smoking weighs your triggers (stress, after food, boredom, social) against your rituals (the morning coffee, the post-meal cigarette) and finds which ones dominate. It maps cravings across the day, which exposes ego depletion — self-control fading as the day wears on — and screens for HALT states (hungry, angry, lonely, tired) that masquerade as nicotine craving. A typical read: stress drives 42% of your cravings, and afternoons hit nearly three times harder than mornings. That is decision fatigue, not weakness.

Overthinking is the most layered track. From each mood log it reads your body's state using polyvagal theory — calm and safe, fight-or-flight, or shutdown — with intense spirals pointing to fight-or-flight. The first move it suggests changes with that state, because thinking exercises fail until the body settles. It then names the exact thinking error from CBT (catastrophising, rumination, reassurance-seeking), watches for the body signal that arrives just before the thought (a tightening chest is the earliest place to step in), and flags clusters of spirals close together as a sign of building load.

Doomscrolling, attention, and procrastination feed the same loop model with their own signals. Doomscrolling tracks the slot-machine pull of feeds and the feeling just before the first open. Attention tracks the point where focus collapses into reactive screen use. Procrastination measures initiation latency — the gap between deciding to start and actually starting — because the wall is the start, not the work.

None of this waits on the server. The moment onboarding ends, a lighter version of each engine runs on your phone against the answers you just gave, so the dashboard fills with real, personal patterns in a fraction of a second. The server later runs the heavier version, with more history and optional AI, and quietly upgrades the result.

The Brain Engine: Thinking in Loops, Not Modules

Jump to:How confidence is scoredMissions and recovery score

Above the per-module engines sits one master layer that ignores modules entirely. It does not think in smoking or scrolling. It thinks in loops — trigger, craving, behaviour, reward, repeat — and the same loop can surface as several different habits.

This matters because the brain rewards the need that was met, not the act itself. A stressed person might smoke, doomscroll, or spiral: three behaviours, one job, calm down fast. The brain engine names that hidden job (the reward need: stress relief, stimulation, avoidance, numbing, comfort, or control) and treats the behaviour as just the route your brain happened to learn. So instead of fighting the cigarette, it asks what the cigarette is for, then offers a cleaner swap that gives the same payoff without feeding the loop.

It finds loops in two ways. One is cue-to-behaviour: a behaviour that keeps following the same trigger, mood, or time of day. The other is chains, when one habit reliably leads to another in a short window: a spiral, then a scroll, then a late cigarette. There the engine isolates the first domino. It needs at least three occurrences before calling anything a loop, so a single bad day never becomes a pattern.

Prediction aims at the gap just before the craving, when a familiar cue appears but the behaviour has not happened yet (predictive coding). If your stress-to-cigarette loop clusters near 3pm on weekdays, it can say so ahead of time, with a clock time, a countdown, one move, and an honest confidence. For example: your strongest loop is stress, then cigarette, then quick relief; next likely moment around 3pm, about ninety minutes away; when your chest tightens, exhale for eight seconds first; right 7 of the last 9 times.

Learning closes the loop. The engine checks each prediction against what actually happened and adjusts, which is why the hit rate (the 7 of 9) shifts over time. The headline rewiring score is not a streak. It blends how often the interruption won, the recent trend, and your current load: the tug-of-war between the new habit strengthening and the old one fading.

One firm rule governs all of this: the neuroscience never reaches the screen. Every term above lives only in the code. On screen the voice is plain, warm, and honest. It names the real pattern ("that is avoidance, not laziness") and always hands back the way out. A test even scans every on-screen line against a banned-jargon list and expects zero hits.

How the Engine Knows a Pattern Is Real

Jump to:How each module finds patternsThe brain engine

Finding a pattern is easy. Finding a true one is the hard part. If the engine called everything a pattern, it would be a horoscope. So every candidate has to clear a few gates before it can change anything you see.

First, a minimum sample: a behaviour needs at least three occurrences to count at all, which stops one bad day becoming a rule. Second, recent events count more: older ones fade on roughly a seven-day half-life, so a habit that is dying is read as dying.

Then it computes two separate scores, because they answer different questions. Confidence asks: is this pattern real? It rises with sample size and how consistent the cue is. Predictability asks: can we call it in advance? It depends mostly on how fixed the cue is. The split matters, because a loop can be very real yet hard to time, and the app says so instead of faking certainty. The exact maths is in the box below.

Outliers are handled quietly by the same rules. A one-off log never clears the three-event floor, so it cannot become a pattern, and it decays away if it does not recur. A real but scattered burst earns high confidence but low predictability, so the app reports it yet softens the timing. Deduplicated uploads mean a repeated batch can never fake a spike, and two cues only combine into a stronger warning when each is consistent on its own.

Patterns also re-earn their place. Each sync, a pattern seen again is reinforced, its count rising and its expiry refreshed. A pattern not seen decays, its confidence dropping about 10% a cycle until it retires near 0.2. A pattern must keep proving itself or it quietly disappears, so the app never clings to a stale conclusion.

Each insight carries a stable fingerprint built from its key field (the trigger, window, app, or mood), so the same evolving insight stays one record instead of spawning duplicates. And when the phone, the server rules, and the AI disagree, a fixed order settles it: AI, then server rules, then the phone's guess, then a plain fallback.

Finally, predictions stay honest. Each is checked against what actually happened, and that hit rate is shown in plain words ("right 7 of the last 9 times"). A confident nudge that keeps missing loses its confidence on screen, automatically.

Missions, the Recovery Score, and Estimated Recovery

Jump to:The brain engineHow the app decides the tone

Patterns are only useful if they become something to do, and something to measure progress against. That is the job of three more outputs: missions, the recovery score, and estimated recovery.

Missions are not to-do items; they are counterweights to your loop, ranked by how directly they hit it. A trigger-specific mission beats a generic one, and a body mission beats a thinking one when the body is wound up. You cannot reason your way out of fight-or-flight, so if overthinking reads high arousal, breath and movement come first and the thinking exercise waits. The choice shifts with time of day, body state, spiral clusters, and withdrawal stage.

Each mission carries a little psychology. Many are if-then plans ("when X happens, I will do Y"), which lift follow-through because the decision is made ahead of time. Many use identity framing: becoming someone who does not smoke, rather than trying to quit. And some fire defensively, so a cluster of spirals can schedule a short calming buffer.

The recovery score, which the app calls momentum, sums all of this into one number from 0 to 100, with the reasons behind it. It measures approach behaviour — cravings resisted, urges delayed, offers refused — not abstinence alone, and one slip never resets it to zero. It rewards the resistance reflex getting stronger, which is what actually predicts lasting change.

Underneath sits a recovery-science engine that turns behaviour into estimated healing across five layers per track: behavioural, psychological, neurological, physical, and a forward projection. It leans on real reference points, like nicotine dependence fading and lung and heart milestones for smoking, or growing self-trust for the rest. Honesty is enforced: every score is labelled an estimate, body-related ones are marked as proxies, and no real HRV, cortisol, or dopamine is ever claimed. The scores roll up into four simple axes — Brain, Body, Momentum, Risk — with cautious forecasts like "weeks to threshold," giving recovery a long-arc shape that daily willpower numbers cannot.

How Notifications Are Made and Timed (JITAI)

Jump to:The layers a notification passes throughHow the app decides the tone

JITAI — just-in-time adaptive intervention — is a framework from behavioural medicine for giving the right support, in the right amount, at the right moment. It has five named parts, and UnloopMe uses all of them (shown below): when to consider acting, the signals that personalise the choice, the menu of things it could send, the rule that picks one, and only acting when you are genuinely in a moment of need.

So when the server thinks, it first writes a pool of candidate notifications per module, each tagged with its type and its intervention family. It does not send them all. It ranks them in tiers, so behaviour derived messages outrank pattern messages, which outrank onboarding seeded ones, which outrank predictions, which outrank generic filler. It also removes duplicates by content, so you never get the same nudge twice in a day. Only the strongest survive.

Then comes the timing decision. Instead of firing at sync time, each surviving notification is handed to the brain engine, which returns the soonest risk window for that habit as a real future moment with a minutes until value. The notification is parked there. Maya's stress to cigarette nudge is aimed at her actual mid afternoon dip, not at whatever minute her phone happened to sync. Each notification also gets an intent and an expiry tuned to its job, so in the moment interventions get a short life, milestones a long one, and plain reminders something in between. That way a nudge written in the morning can still legitimately wait for an evening window without going stale.

A delivery dispatcher then runs every couple of minutes. It claims only the notifications whose moment has arrived, sends those, and leaves the rest parked. If a send fails, because the phone is off or the network is down, it retries a handful of times with growing gaps before giving up, and it holds anything that has nowhere to land until your phone checks back in. The effect is a system that feels attentive, because it genuinely waits for your moment instead of interrupting a random one.

The Layers a Notification Passes Through

Jump to:The AI layer and its fallbacksWhat happens after a notification is sent

It is worth slowing down on a single notification, because it is built like an assembly line, where each layer adds one thing and hands it on. Separating these jobs is what keeps the system safe, because any one layer can fail or be swapped without breaking the message.

It starts as a signal, not a sentence. The data driven builders emit a structured slot that holds the family, the pattern, the prediction, the one action, and the raw data behind it. This deliberately keeps what we know about you separate from how we say it. Next, a classifier files the slot into one of nine intervention families, which fixes the message's shape. A renderer then voices the slot into plain title and body text following that family's pattern, prediction, action skeleton.

That raw text is checked immediately by the voice contract. A linter scans for banned phrases, such as therapy speak, jargon, and motivational mush, and clamps the length so nothing is cut off in the phone's preview. Only then is the text offered to the AI enhancement chain, which warms the wording. If the whole chain fails, the contract clean rules text ships untouched. The rules text is always the floor.

The finished copy is sealed into an envelope. That envelope carries an intent and expiry that say how long it stays valid, a temporal binding tag that marks it as an at this moment line that must die fast, a recurring pattern line that can wait, or a timeless line, and a dedupe key so it cannot be sent twice. The envelope then goes into the tier ranked pool, is scheduled at the brain engine's next risk window, and waits for the dispatcher.

When the moment comes, the dispatcher sends it through push. On your device one of two handlers takes over. If the app is in the foreground, the in app handler shows it. If the app is closed, the service worker renders it straight from the payload, with no extra network call. Finally your phone beacons back what happened, whether delivered, tapped, or dismissed, which advances the notification's state and feeds the efficacy and prediction accuracy learning, so the next round is a little sharper.

How the App Decides the Tone

Jump to:The AI layer and its fallbacksHow notifications are timed

Getting the timing right is only half the job. The other half is the voice. A nudge that sounds like a textbook, a therapist, or a hustle culture coach gets swiped away, or worse, makes someone in a shame spiral feel watched. So UnloopMe holds every message, whether written by a rule or by an AI, to one strict tone contract: a smart, kind friend who has seen your data and knows what usually happens next. Direct, warm, human, never preachy.

First, every message is sorted into a family by its job. There are nine of them, and each has its own shape. A risk window family warns just before a window opens. A pattern mirror family shows you one true thing about your own data. A next move family gives the single smallest action to take right now. An urge surfing family reassures you the urge will crest and pass. There are also friction (shrink the task), excuse (name the excuse before it arrives), momentum (real numbers moving the right way), failure (handle a slip with zero shame), and pact (a small personal promise, asked like a friend). Knowing the family tells the app exactly how a message should be built.

Second, there is a banned words list. Therapy and textbook phrases, brain science jargon, and motivational mush are all blocked, so neither a human writer nor an AI can drift back into the wise blog post voice the app is trying to avoid. There is even a length limit, so nothing gets cut off in the phone's notification preview.

Third, AI is used as polish, never as the foundation. A plain, correct version of the message is written by the rules first. Then an AI is asked to warm it up while obeying the same contract. The next section walks through exactly what happens when that AI is slow, missing, or wrong.

The AI Layer, and What Happens When It Fails

Jump to:How the app decides the toneHow intelligence is built

AI is the last coat of paint on a message, not its foundation, and the system is designed so that paint can be missing entirely. This matters because AI providers are the least reliable part of any stack. They time out, hit rate limits, change behaviour, or simply have no key configured. UnloopMe treats all of that as normal and routes around it.

It works as an ordered chain. The rules engine always writes a correct, contract clean version first, and that version is the floor. Then an enhancement chain is assembled from whichever providers have a key set, in a fixed order. Each link is asked only to refine the wording, never to invent the message.

The enhancer walks the chain one link at a time, giving each link a single retry. A link counts as failed if it errors, times out, returns nothing, or returns text that breaks the voice contract. On failure the enhancer moves to the next link. Whichever link succeeds, the result is tagged with the provider and model that actually voiced it, so any line can be traced back to its author later. If every link fails, the untouched rules text ships. Nothing blocks, nothing is skipped.

There are two modes worth naming. Enhancement mode providers, through LLM APIs, only rewrite existing rules text, which is what notifications use. Generation mode providers can author from scratch. Intelligence and homepage copy use a single provider rather than the full chain, but the same floor rule applies. The practical upshot is simple. No outage, rate limit, or missing key can ever cost you a nudge. The worst case is slightly less polished wording, never a missed message and never an off brand one, because the contract lint runs on the AI output too.

What Happens After a Notification Is Sent

Jump to:What the server deletes

A notification is not fired and forgotten. The app quietly tracks each one through its life so it can learn what actually worked. A message starts as written, becomes claimed by the dispatcher, then sent, then delivered to your phone. From there it can end up tapped, swiped away, or, if its moment passed before it could reach you, expired.

The app handles the messy real world gracefully. If your phone has no live connection to receive pushes, the message is held and sent again the moment your phone checks back in. If a send genuinely fails, it retries a handful of times with bigger and bigger gaps before giving up for good. And once a notification reaches a final state, it is kept for a while as memory, then tidied away automatically so the system stays lean.

This bookkeeping is what lets the app slowly get better at timing and tone. It can see which kinds of message you tap and which you ignore, without ever needing to know who you are.

Why Some Notifications Expire Fast, and the Server's Daily Rhythm

Timing creates one last problem worth explaining. A message like you are heading into your evening craving window, stay aware, is only true for a short while. Delivered at midnight it is simply wrong, and a wrong nudge erodes trust faster than no nudge at all. So the app tags how tightly each message is tied to the moment. Right now messages get a short fuse, and if they cannot reach you inside their window they are dropped, with a timeless backup, such as cravings come in waves and pass, sent instead. Messages about stable patterns can arrive any time, as long as they avoid words like today. And purely timeless tips have no fuse at all.

Underneath all of this, the server keeps a quiet daily rhythm. The morning and evening wake ups line up with natural check in and wind down moments. A small dispatcher checks for due notifications every couple of minutes. Overnight the server does its housekeeping: learning a better push hour for each person, adjusting how much it trusts its own predictions, and tidying away old records. Once a week it writes a short, plain language review that ties your week back to the triggers and goals you named at the start.

Put it all together and UnloopMe is less like a database with a screen, and more like a calm companion that watches the rhythm of your days, learns your loops, and only speaks up when it has something genuinely useful to say, in a voice that sounds like a friend.