A first-person account of one bug we refused to ship again, the write-ahead fix that came out of it, and how the same don't-lose-it principle shows up again in how OpenWispr learns from you.
Before OpenWispr's write-ahead audio store existed, a dictation's audio lived only as an in-memory sample buffer while it was being transcribed. That was fine right up until it wasn't: a transcription error, the recording activity getting destroyed, or the OS killing the process mid-attempt all had the same result — the audio was gone, and there was nothing the user could do to get it back. A long, carefully-thought-out recording and a one-line note failed exactly the same way: completely, with no trace.
That's a bad trade against a genuinely rare failure. Most dictations transcribe fine on the first try. But when one doesn't, losing the only copy of what you said turns an inconvenience into an actual loss of work — and it's precisely the moment a user has the least patience for the app failing them.
The fix is a small, specific ordering guarantee: the audio is written to on-device storage before the first transcription attempt is made at all, on both the on-device and the cloud transcription paths — not after a failure is detected. Its lifetime is deliberately decoupled from any single attempt, and nothing in the app ever deletes it from an error-handling path. It's written to the app's persistent files directory rather than a cache directory, specifically because a cache is exactly what the OS is allowed to silently reclaim under storage pressure — precisely the moment a user would want their recording back.
The state tracking follows the same discipline. A sidecar file records only two things: the facts known when recording started, and — once a dictation actually lands — its result. There is deliberately no "currently transcribing" flag written to disk, because that kind of flag can lie: if the app is killed mid-transcription, a stale "in progress" marker would sit there forever, and any attempt to clean it up after the fact is itself a source of bugs. Instead, "in progress" is tracked only in memory. If the process dies, that in-memory state is simply gone — and the recording correctly, automatically reads as unfinished and offered back for retry, with no separate repair logic needed.
A transcription failure is often deterministic — the same audio through the same model tends to fail the same way twice. So when a saved recording gets retried, the app defaults to a different transcription engine than the one that just failed, rather than silently repeating the identical attempt and hoping for a different outcome. That's a small decision, but it's the difference between a retry button that's mostly theater and one that's actually a second, meaningfully different attempt.
Recordings that fail and get abandoned rather than retried immediately aren't deleted either — they sit on-device, listed as unfinished, retryable whenever you come back to them. They're only ever cleared out by an explicit, bounded retention window, and a settled (successfully transcribed) recording is treated completely differently from one that's still unresolved: retention is never allowed to be the thing that quietly loses a dictation you haven't gotten your words back from yet.
Once "don't lose the raw material" was solved for audio, the same instinct applies to something smaller but just as easy to throw away by default: every time you correct what the app produced, that correction is a signal about how you actually want to be transcribed. OpenWispr keeps that signal, gated entirely behind a single "Keep history" switch, in four layers that build on each other, cheapest first:
Personal vocabulary (L1) — corrected names and terms are remembered and applied right after transcription, plus fed back into the transcription model itself as a small decoding bias, so frequently-corrected words get heard correctly more often over time, not just fixed after the fact.
Correction corpus (L2) — every accepted dictation is recorded as what the pipeline produced versus what you actually kept, in a capped, rolling on-device log. When the two differ, that's a real correction, and it's the shared raw material the next two layers draw from.
Few-shot polish (L3) — when the optional LLM cleanup step is set to Medium or Full (not Light, and not Off, to keep the on-device model's context small), the two most similar past corrections are pulled from that log and shown to the model alongside the current dictation, so it matches how you've actually preferred your own text cleaned up — without any retraining. The matching is a straightforward keyword-overlap score, not a heavier embedding-based search, because the log is small enough that a simple scan is instant and doesn't need an extra on-device model just to do retrieval.
Periodic re-fine-tune (L4) — for anyone who wants to go further, the corrected samples can be exported from the app as a plain file. Actually retraining a model from that export happens outside this app entirely, in a separate, dedicated project — this app's job stops at handing you your own data in a usable form, not silently uploading it anywhere to be trained on.
All four personalization layers, like the audio store above them, live entirely on-device and are gated by the same "Keep history" preference: turn it off, and nothing is kept — including audio that's still sitting unfinished, which is purged outright rather than lingering. The one deliberate exception is L4's export, and it's opt-in in the most literal sense: the app writes your corrected samples to a file only when you explicitly ask it to, so you can move that file yourself if you choose to use it. Nothing about the retry safety net or the three learning layers beneath it depends on a server existing at all — the entire point of building it this way was that there's nothing to lose to a server that isn't there, and nothing that leaves your device unless you're the one who moved it.
Open source and entirely on your device. Android from Google Play, macOS from GitHub — no account, no sign-up, just a download.