---
title: Reclaim disk space (shrink a large Omniscio database)
---

# Reclaim disk space (shrink a large Omniscio database)

## What it is

Omniscio's database file can grow to several gigabytes over months of use. **Settings → Diagnostics → Reclaim disk space** clears stale cached data and schedules a one-time compaction on the next restart that physically shrinks the file — and the archive of older conversations too, when it holds enough empty space.

### Why the file only ever grows, and which job shrinks it

Omniscio keeps everything — your projects, sessions, and every chat message — in a single SQLite database file called `mission-control.db`, stored in Omniscio's app-data folder. SQLite files only ever **grow**. When Omniscio deletes rows (most often the cached "turn layouts" in `session_turns_cache` that speed up reopening old chats), the freed space is **not** returned to your disk — SQLite keeps it inside the file as reusable empty "free pages". After heavy use, a database can sit at, say, 2.8 GB on disk even though only ~1.4 GB of it is real data and the rest is reclaimable empty space.

There are two separate jobs that touch this file, and it's worth knowing which one does what:

- **Backups** (automatic + the "Back up now" button) copy the whole database to a timestamped folder. A backup is a page-for-page copy of your live database — empty pages included — that is then **compressed** before it is encrypted, so **a backup is smaller than the live file** (roughly a quarter of its size in our measurements on real databases) — but it does _not_ shrink the live file. These automatic backups are **encrypted and tied to this computer** (see [Are my automatic backups encrypted?](#are-my-automatic-backups-encrypted) below). (Backups used to briefly freeze Omniscio while they ran; they no longer do — see [Why backups no longer freeze Omniscio](#why-backups-no-longer-freeze-amc) below.)
- **The archive of older conversations is shared between backups instead of re-copied every time.** Omniscio moves older conversations into a separate archive file, which on a busy install can be many gigabytes. Copying all of it into every backup, several times a day, wrote tens of gigabytes for a few megabytes of actual change — so a new backup now _points at_ the previous backup's archive when that copy is still recent, and takes a fresh one at least once a day. Two things are worth knowing: every backup folder is still complete and restores on its own (the shared archive is a real file in each folder, not a shortcut that can dangle), and **the archived-conversation part of a backup can be up to a day older than the backup itself** — your live database is still captured fresh every few hours.
- **Compaction** is the only thing that actually **shrinks** the file. It rewrites the database — or, when it holds enough empty space, the archive of older conversations — without the empty free pages. Because that rewrite locks the database and can take many minutes on a multi-gigabyte file, Omniscio never does it silently in the background while you're working — it runs **once, at startup, behind the splash screen**, and almost always only when you've asked for it.

The "Reclaim disk space" button is how you ask for it.

## Where to find it

The control lives in **Settings → Diagnostics**, on the **Session turns cache** card, which shows the database's current size on disk beside a **Reclaim disk space** button. That card is the whole surface — there is no timer to set and no other screen that triggers a compaction. The work itself happens later, on the splash screen at the next launch, so nothing you do here interrupts what you are working on.

## How it behaves

### How to use it

1. Open **Settings → Diagnostics** and find the **Session turns cache** card. It shows your current **Database size** on disk.
2. Click **Reclaim disk space**. A confirmation dialog ("Reclaim disk space?") explains that it will clear the cached turn layouts and compact the database on the next launch, shows how much space the database currently uses, and reassures you that **your conversations are not affected**.
3. Confirm with **Clear & schedule**. Omniscio clears the cache immediately and shows a banner: _"Database optimization is scheduled — restart Omniscio to reclaim disk space."_
4. **Restart Omniscio when convenient.** Nothing happens until you do — Omniscio deliberately does **not** relaunch itself (an unprompted exit would kill any running sessions). On the next launch you'll briefly see _"Reclaiming disk space…"_ on the splash screen while the file is rewritten. If your archive of older conversations also holds 1 GB or more of empty space, the splash then shows _"Compacting the database…"_ while the archive is rewritten, which can take much longer (see [The archive of older conversations is compacted too](#the-archive-of-older-conversations-is-compacted-too)). Then Omniscio opens normally with a smaller database.

Clearing the cache without restarting is harmless — your sessions simply rebuild their cached layout the next time you open them. The restart is only needed to physically shrink the file.

### What happens at the next restart

On the next launch, before the main window opens, Omniscio checks the "compact on next startup" flag. If it's set, Omniscio:

1. **Clears the flag and writes that to disk first**, _before_ compacting. This is a deliberate safety step: if the machine lost power or crashed in the middle of compaction, the flag is already cleared, so Omniscio won't get stuck trying to compact again on every single boot.
2. Shows _"Reclaiming disk space…"_ on the splash screen.
3. Checks free disk space and decides what's safe to do (see [Safety](#safety)).
4. Rewrites the database without its free pages, then folds the freed space out of SQLite's write-ahead log so the file on disk actually gets smaller.
5. Shows _"Disk space reclaimed"_ and continues booting.

If the archive of older conversations holds 1 GB or more of empty space, Omniscio then compacts it too (see [The archive of older conversations is compacted too](#the-archive-of-older-conversations-is-compacted-too)), and the splash shows _"Compacting the database…"_ before the window opens.

The main-database part takes a few seconds on a small database and minutes on a multi-gigabyte one; a large archive can take many minutes. Your conversations, projects, and settings are untouched — compaction only removes empty space, it never removes data.

### When Omniscio schedules a compaction for you

Almost always, compaction only runs because _you_ clicked **Reclaim disk space**. Omniscio also schedules one itself, once, after a large cleanup of old data. The first case is the main database:

Omniscio keeps every chat message — including the high-volume background **status messages** that heavy multi-agent use generates (tool-activity and recovery bookkeeping). Those status rows are now cleaned up on their own once their session has been finished for a couple of weeks, so the database stops growing without bound. The **first** time that cleanup runs on a database that had already grown very large, it frees so much space at once that Omniscio also schedules a single compaction on the next restart — so the reclaimed space is actually returned to your disk instead of sitting inside the file as empty pages. You'd see the same one-off _"Reclaiming disk space…"_ splash on a restart you didn't explicitly schedule.

This happens at most once on a backlogged database. Ongoing day-to-day cleanup is tiny and never schedules a compaction — there is still no continuous or timer-based compaction. Your conversations (your messages and the assistant's replies) are never touched by this cleanup; only disposable status rows from long-finished sessions are.

### The archive of older conversations is compacted too

Conversations from long-inactive sessions live in a separate archive file, `mission-control-archive.db`, beside the main database (see [Why the backups folder no longer balloons](#why-the-backups-folder-no-longer-balloons)). It only ever grows too: space freed inside it stays inside the file. Two things now return that space to your disk; in both cases the rewrite itself happens at startup, behind the splash screen:

- **A one-time automatic compaction.** The cleanup described above now also runs on the archive: for sessions that ended more than 14 days ago, the same bulky tool-output status rows are removed from the archive as well. Your own messages and the assistant's replies are never touched. It runs in the background, paced to stay out of your way; it starts once the main-database cleanup has caught up, and if you quit Omniscio it resumes where it stopped. (On a copy of a real archive it removed about 1.8 million rows.) Once it has fully caught up, Omniscio schedules **one** compaction of the archive for the next start — but only if the archive has never been compacted and holds at least 1 GB of empty space.
- **Reclaim disk space.** The button also compacts the archive at the next restart, whenever it holds at least 1 GB of empty space.

**What you'll see.** The splash shows _"Compacting the database…"_ while the archive is rewritten, and the main window opens when it is done. On a large archive this is a long wait: on a copy of a real archive it took **14.8 minutes** and shrank the file from **17.5 GB to 7.5 GB**; a slower disk may take longer. Your conversations are untouched — the rewrite only removes empty space.

**When it holds back.**

- **It happens once.** Afterwards the archive reuses its own freed space, so the automatic request never comes back for it. If an attempt is interrupted (you quit during the splash), the archive is left exactly as it was and Omniscio waits 7 days before trying again automatically; **Reclaim disk space** works at any time.
- **It waits for a search-index rebuild.** While a rebuild of the archive's search index is unfinished, the compaction is skipped for now, because moving rows under a half-built index could silently misalign it. It is also skipped when free disk is below about 1.2× the archive's size, like the main database's rewrite; it takes no separate safety copy, because the rewrite is crash-safe on its own.
- **It double-checks search.** After the rewrite, Omniscio compares a sample of the archive's search index against its messages; if they no longer line up it rebuilds the index in the background. (On a copy of a real archive, all 500 sampled rows still lined up.)

### Queued messages are cleaned up after 7 days

Messages you line up with [Queue a message](queue-a-message.md) ("send after the agent finishes") stay in the database after they are delivered or removed, marked as deleted. Omniscio now removes those rows 7 days after they were delivered or removed, in short steps that stay out of your way; messages still waiting to be sent are never touched. On one large install these leftover rows made up about 7% of the main database. The space they free stays inside the database file and is reused by new data — it returns to your disk only when you run **Reclaim disk space**. This cleanup never schedules a compaction by itself.

### Why backups no longer freeze Omniscio

This feature shipped alongside a fix to Omniscio's backups. Previously, every backup (on startup, on a timer, or manual) copied the database using a method that **locked Omniscio's main thread for the entire copy** — several seconds, up to ~13 seconds on a multi-gigabyte database — during which the whole app was frozen and unresponsive.

Backups now use SQLite's **online-backup** method, which copies the file in small chunks and hands control back to the app between chunks. The copy still happens, but Omniscio stays responsive throughout. You shouldn't notice backups happening at all anymore.

(Note: the backup copy is taken page for page, so it includes the live file's empty space; it is then compressed, which is why a backup ends up smaller than the live file. Compaction is what shrinks the live file itself — and once the live database is compacted, future backups are smaller too.)

### Why the backups folder no longer balloons

Omniscio keeps the message history of long-inactive sessions in a separate **cold-storage archive** file (`mission-control-archive.db`) beside the main database — on a heavily-used install it can be many gigabytes. Every backup has to include it (so a restore has your full history), but that archive rarely changes from one backup to the next.

Previously each backup wrote a _fresh full copy_ of the archive, so keeping several backups meant several copies of the same multi-gigabyte file — the backups folder could swell to tens of gigabytes. Now, when a new backup's archive is identical to one an existing backup already holds, Omniscio **shares the file** instead of copying it again — a "hard link", which is one real file on disk that several backup folders point to — while always keeping at least **two independent copies** so no single-file problem can ever leave you with just one.

The effect: each backup folder still contains a complete, restorable snapshot, but the folder as a whole uses far less disk. **Restoring, backup timing, and encryption are all unchanged** — the shared file is still encrypted, and deleting old backups still works normally (the shared data is kept until the last backup using it is removed). It's automatic and invisible; there's an off switch for troubleshooting (`AMC_DISABLE_BACKUP_ARCHIVE_DEDUP=1`), but you shouldn't need it. The folder shrinks gradually over the next few backups as the old full-copy backups age out.

**The one thing that stops the sharing:** it can only share an archive that is _unchanged_ since the previous backup. Omniscio tops the archive up about once a day, so most backups see an unchanged archive and share it. But if the app is restarted very often — many times a day, which really only happens on a developer machine — that top-up used to re-run on every single launch, so the archive was never unchanged and every backup wrote a fresh full copy. If you have ever watched the backups folder stay large while this page said it should shrink, that was why. Restarts no longer trigger an extra top-up, so the sharing now works as described.

**Your knowledge-vault files are shared the same way.** Every backup also carries a copy of your KMS vault (notes and images). A file that has not changed since the previous backup is linked to that backup's copy instead of being copied again — but only while that copy is not already shared with another backup. So once a few backups exist, every file is still held as at least two separate physical copies, and deleting an old backup never affects a newer one.

### Why the database's write log no longer grows forever

Beside your database sits a smaller companion file ending in `-wal` — the **write log**. Omniscio
writes new data there first, then folds it back into the main database a few seconds later. That
folding was always working; what was missing is that the _file_ never shrank afterwards.

SQLite reuses the write log from the start each time rather than trimming it, so the file quietly
kept whatever its largest-ever size had been — for the life of the install. On one heavily-used
machine it reached **774 MB while holding under 3 MB of actual data**: over 99% of it was empty space
that was never going to come back. Nothing was broken and nothing was slow because of it; it was
simply disk you had paid for and could not use.

Omniscio now sets a **64 MB ceiling** on that file. Past the ceiling it is trimmed back automatically
the next time data is written, so the log stays small instead of only ever growing. In normal use it
sits well under the ceiling and nothing happens at all.

**What you should expect:** if your write log had already grown large, it shrinks shortly after the
next time you start Omniscio — a one-off tidy-up taking about a tenth of a second. After that it
stays bounded on its own. There is nothing to turn on, no button to press, and your data is never at
risk: only space already folded safely into the main database is ever reclaimed.

### Are my automatic backups encrypted?

Yes. Each automatic backup's database and settings files are compressed and then **encrypted** before they're written to disk, using a secret key that lives in your computer's system keychain (the same protected store Omniscio already uses for your API keys). The key never leaves your machine and is never included in a backup.

What this protects: a backup file that gets **copied, synced to the cloud, or stolen** can't be opened on another computer — it's unreadable without the key.

What to know:

- **Backups are tied to this computer.** Because the key is bound to this machine's keychain, you can't take an automatic backup folder to a _different_ computer and restore it there. For moving to a new machine — or recovering if this computer's keychain is ever reset — use the **Backup Mirror** (Settings → Backup & Restore → "Backup Mirror"), which is encrypted with a **passphrase you choose** and is therefore portable.
- **Restoring is automatic.** When you restore on this computer, Omniscio unlocks the backup for you — you won't notice a difference. A restore first checks the backup is intact, and if the key is missing it stops and tells you (rather than damaging your current data).
- **Older backups still work.** Backups made before this change weren't encrypted; Omniscio detects that and restores them normally. Backups made before compression was added restore normally too.
- **The keychain has to be there.** Encryption depends on the key, and the key depends on your OS keychain. If the keychain is unavailable — a headless launch, a reset credential store, a changed OS account — Omniscio writes that backup as a **plain, unencrypted, uncompressed** file and warns you, rather than skipping the backup and leaving you with no copy at all. A backup folder you cannot restore from is worse than one that is readable, so this is deliberate; just check the notice if you see it and re-run the backup once the keychain is back.
- **One honest caveat.** This encrypts the backup _copies_. The live database Omniscio is actively using is still stored unencrypted on your disk, protected by your computer's normal login and (if enabled) full-disk encryption like BitLocker — encrypting that live file is a separate, larger change.

### Why launches stay fast after an update

Whenever an app update changes the database's shape, Omniscio takes a one-off **pre-migration snapshot** of the whole database first — a full copy into the backups folder (`mission-control-v<N>.db`) — so a bad update can always be rolled back. On a large database that copy takes a few seconds, and it happens _before the window opens_ (you'd see _"Backing up database…"_ on the splash). This snapshot is **required**: if it can't be written (for example, the disk is full or the data folder is read-only), Omniscio **blocks the update and stops** with a clear message instead of changing your database without a safety copy — updates only go one way, so an update that fails with no snapshot could not be undone. Free up space or fix the folder's permissions and reopen, and it continues.

That's fine once per update. But if you relaunch repeatedly while updates are landing often, re-copying a multi-gigabyte file on **every** launch is wasted time — it was the single biggest cause of a slow launch. So Omniscio now **reuses a recent snapshot**: if one was already taken in the last few hours, the next launch skips the copy and opens faster. The snapshot is **never** skipped when it's your only safety net — if you've turned automatic backups off, every upgrade still snapshots — and your periodic backups keep the rollback point fresh regardless.

### Safety

Compaction is designed to be impossible to lose data to:

- **The rewrite is crash-safe.** SQLite's `VACUUM` is transactional — if it's interrupted (power loss, crash, force-quit), the original database is left completely intact. Worst case, the file just didn't shrink this time.
- **It skips itself when disk is tight.** Rewriting the database temporarily needs scratch space roughly the size of the file. If your free disk space is less than ~1.2× the database size, compaction is **skipped entirely** (and logged) rather than risk filling the disk — you can free up space and try again. People often reclaim _because_ their disk is full, so failing safe here matters.
- **It takes a belt-and-suspenders safety copy when there's plenty of room.** If free disk is comfortably large (~2.2× the database size or more), Omniscio first writes a `mission-control-precompact.db` snapshot into the backups folder before compacting. If that snapshot fails, compaction still proceeds (the rewrite is crash-safe on its own). Omniscio deletes that copy once it is more than 7 days old, so it does not sit in the backups folder for good.
- **It fails open if disk space can't be measured.** On the rare system where Omniscio can't read free-space figures, it proceeds with the (crash-safe) rewrite rather than refusing.

### Limits and non-goals

- **It's opt-in and one-time, with automatic exceptions after a large cleanup.** Each "Reclaim disk space" click schedules exactly one compaction for the next restart. Omniscio schedules one _for_ you after the first large cleanup of old background status messages (see [When Omniscio schedules a compaction for you](#when-omniscio-schedules-a-compaction-for-you)), and it compacts the archive of older conversations once, after that archive's own cleanup (see [The archive of older conversations is compacted too](#the-archive-of-older-conversations-is-compacted-too)). There is still no _continuous_ or timer-based compaction — it is too heavy to run silently while you work.
- **It requires a restart.** Clearing the cache happens instantly, but the file only shrinks on the next launch. Omniscio won't restart for you.
- **It doesn't delete your data.** Compaction only removes empty space. Your conversations, projects, settings, snippets, and recipes are all preserved. (If you want to _free up_ space by removing old chats, that's archiving/deleting sessions — a different action.)
- **Backups are smaller than the live file, but only compaction shrinks the live file.** A backup's copy of the main database is page-for-page — empty pages included — and is then compressed (roughly a quarter of the size in our measurements), so it is smaller than the live file; the live file itself only shrinks when you compact. (The separate multi-gigabyte cold-storage archive is de-duplicated across backups automatically, see [Why the backups folder no longer balloons](#why-the-backups-folder-no-longer-balloons), and its backup copies are compressed the same way — so the backups _folder_ is much smaller even before you compact.)

## Related

The cache compaction clears is the same one described on the [Lazy content load](lazy-content-load.md) page — clearing it only means each session rebuilds its layout the first time you reopen it. The other two storage surfaces are the weekly configuration backup on [Setup backup](setup-backup.md) and the full encrypted snapshot on [Backup mirror](backup-mirror.md). If what you need to reclaim is memory rather than disk, see [Memory reclaim](memory-reclaim.md).

- [lazy-content-load.md](lazy-content-load.md) — the `session_turns_cache` that compaction clears is the same cache that makes cold-mounting a session instant; clearing it just means the first reopen of each session rebuilds its layout.
- [setup-backup.md](setup-backup.md) — the weekly encrypted **configuration** backup emailed to Gmail (a different, much smaller bundle that never contains your chats).
- [backup-mirror.md](backup-mirror.md) — the full encrypted snapshot (database included) written to a cloud-sync folder.