Omniscio

Keep Omniscio resident in memory (Windows working-set floor)

A Windows-only Settings → Performance toggle that keeps Omniscio's own memory resident in physical RAM so its pages cannot be trimmed out to the pagefile, with a VirtualLock page pin as the primary mechanism, a per-process working-set floor as the fallback, and an option to serve the database from private memory.

On this page

What it is

A Windows-only Settings → Performance toggle that keeps Omniscio's own memory resident in physical RAM so its pages can't be trimmed out to the pagefile when the machine is starved. It is the memory twin of the CPU-side Boost Omniscio interface priority: where that keeps Omniscio scheduled under CPU contention, this keeps Omniscio resident under memory pressure.

The primary mechanism is the resident PIN, not the floor this page describes (updated 2026-06-28). The keepAmcResidentInMemory toggle is now default-ON, and its PRIMARY action is a true VirtualLock page-pin of the main process's DB + hot heap — needing no admin (only the working-set min raised first), because a hard working-set minimum alone is a HINT Windows trims under real pressure (measured: a 600 MB floor trimmed to 1 MB). The pin is sized from a STABLE basis (DB mapped footprint + a fixed heap allowance, NOT the trimmable live working set — a 2026-07-05 fix, after it was found unwinding from ~3.7 GB→~1.2 GB under load) so it holds through the swarm storm. SSOT: resident-lock.ts + the resident-pin contract. The working-set floor documented below is now the FALLBACK — applied only where the pin can't run (non-Windows / < 13 GB RAM / FFI unavailable). The floor details below are still accurate for that fallback; a fuller rewrite to lead with the pin is a tracked follow-up.

Escalation when the pin is DEFEATED — "Serve the database from private memory" (2026-07-14). VirtualLock can hold private (heap) pages but CANNOT hold a file-backed memory-map against Windows' cache-manager trim under sustained disk load — so on a swarm-busy machine the pin is repeatedly DEFEATED: the database's ~2 GB file-mapped window keeps getting evicted despite the lock, hard-faulting the main thread back off the busy disk (the whole-app STARVED freeze). The opt-in Settings → Performance → "Serve the database from private memory (Windows only)" toggle (keepDbInPrivateCache, default OFF, takes effect on the next restart) fixes this at the source: it opens the database with the file-mapped window OFF (mmap_size=0) and a large private page cache instead, so the hot database lives in committed heap the pin CAN hold. Trade-off: a cache miss falls to a synchronous read from disk — bounded, since the cache is sized to hold the whole database with headroom. Fully reversible: turn it off and restart. SSOT: the resident-pin contract (R9).

The pin gives memory back when the box is short — measured against what it WANTS (updated 2026-11-01). Before every pass the pin reads free physical RAM. Under the machine's critical floor it lowers its cap by the shortfall, between that floor and twice it holds, above twice it may grow. The figure that shortfall is subtracted from is the cap the pass computed for itself, never the bytes a previous pass managed to lock: measured on a 16 GB box, the old basis took the main pin from 1961 MB → 1437 MB → 0 MB inside one afternoon, and only a spike above twice the floor brought it back. The off-thread database hosts follow the same rule, pinned to their database mapping only (about 213 MB per host, never the several-hundred-MB engine heap), so their working-set floor is sized to what they actually lock. Contract rules R14 and R15.

The pin stops locking a database it cannot keep locked (updated 2026-11-11). While Omniscio's background database helpers are writing, the database engine gives the main process a fresh view of the database file after every write, and the fresh view arrives unlocked. Re-locking it every 30 seconds made the next database read throw away a fully locked view, which showed up as a half-second hitch in the window every 30 seconds on machines with a large database. The pin now checks each pass whether its lock on the database is still there. After two passes in a row where it is gone, the pin stops locking the database for the rest of that run and keeps locking Omniscio's own program code, and it says so once in the log ([ResidentLock] the database mapping did not stay locked). Expect one or two hitches in the first minute after starting Omniscio while it learns this, then none from this cause. Switching the setting off and on makes it check afresh. Setting the environment variable AMC_DISABLE_PIN_MAPPED_STAND_DOWN=1 before starting Omniscio keeps the older always-re-lock behaviour.

The problem it solves

When many Claude CLI sessions run at once, total committed memory climbs and Windows starts trimming working sets — evicting cold pages out to the pagefile to free physical RAM. Omniscio's own processes are fair game: if Omniscio has been in the background (you were in your IDE or browser), Windows will happily page out its renderer's heap. When you Alt-Tab back, Omniscio has to fault all those pages back in from disk — the window paints stale, scrolling stutters, the first click lags. That is not slow code; it is Omniscio's memory having been demoted to disk and now crawling back.

Omniscio already pushes the other direction on the session children — session working-set trimming actively evicts idle Claude CLI children toward the pagefile to keep headroom. This toggle is the counterpart for Omniscio itself: hold a floor of Omniscio's own pages resident so the window stays instant even when the box is under memory pressure.

Where to find it

Settings → Performance → Keep Omniscio resident in memory (Windows only). Off by default, reapplies live without a restart, hidden entirely on macOS / Linux.

How it behaves

What the toggle does

When on, Omniscio sets a hard working-set minimum on every one of its own Electron processes — main, renderer, GPU, utility, plus any helper renderer Electron spawns later — via Win32 SetProcessWorkingSetSizeEx with the QUOTA_LIMITS_HARDWS_MIN_ENABLE flag. A hard minimum is one Windows actually honors: it will not trim that process below the floor even under memory pressure. The companion QUOTA_LIMITS_HARDWS_MAX_DISABLE flag is set at the same time, so Omniscio only ever establishes a floor — it never caps its own working set.

The floor is 128 MB per process on a 32 GB-class machine, scaled down with the machine: residentFloorBytes(os.totalmem()) is 128 MB × (RAM ÷ 32 GB), so a 12 GB machine floors each process at 48 MB. Across Omniscio's ~5 Electron processes that reserves roughly 0.5–0.75 GB on a big box and about 0.25 GB on a 12 GB one — enough to keep each process's hot pages (the renderer heap, the main event loop, the V8 code) in RAM without hoarding memory the rest of the system needs. This is the floor that actually arms on the machines least able to spare RAM: it runs only where the resident LOCK refuses to (under 13 GiB, or no FFI).

Behaviour details:

  • Rides on a privilege Omniscio already holds — no admin needed. Setting a working-set minimum requires SeIncreaseWorkingSetPrivilege, which Omniscio already enables for its existing working-set features (win32-privileges.ts). This floor is only that working-set minimum — a strong hint Windows honors, NOT an unbreakable pin. (True page-locking is the resident pin described in the note above: VirtualLock, which — contrary to a common misconception — needs no admin either, only the raised working-set min for quota; the admin-gated SeLockMemoryPrivilege is a different API that Omniscio does not use.)
  • Self-verifying (the anti-silent-no-op guard). Right after Omniscio sets its own floor, it reads the value back from Windows (GetProcessWorkingSetSizeEx) and logs a loud [ResidentFloor] warning if the floor did not actually take. This exists because a sibling memory feature once failed a privilege check and silently did nothing in production for months — the read-back makes that failure mode loud instead of invisible.
  • Idempotent + 30s refresh. Flipping it on once is enough; a 30s interval re-applies the floor to Omniscio's main process (cheap) and catches any newly-spawned Electron child. The refresh only ever touches Omniscio's freshly-enumerated current processes, so it can never accidentally pin an unrelated app that reused an old process id.
  • Clean turn-off. Disabling sweeps the floor off the union of every process Omniscio floored AND every Omniscio process currently alive — so a child that spawned between refresh ticks cannot be left with a lingering floor.
  • Non-fatal failure mode. Any OpenProcess / SetProcessWorkingSetSizeEx failure logs [ResidentFloor] ... and degrades to a no-op; Omniscio continues normally.
  • No-op on macOS / Linux. process.platform !== 'win32' short-circuits before any kernel32 work, and the toggle is hidden in Settings on non-Windows.
  • Not touched by the session governors. This floors Omniscio's OWN processes; it has nothing to do with the Claude CLI children's Job Object. The CPU-Burst window (which lifts the session limiters) deliberately leaves the floor in place — keeping Omniscio resident is wanted during a burst, not suspended.

The honest trade-off

The reserved RAM is RAM the background sessions cannot use. Under genuine memory exhaustion that is an intentional choice — favour a responsive Omniscio window over a little extra memory for background turns — which is why it is on by default but sized to the machine (and can be turned off in Settings → Performance). It keeps a floor resident; it does not lock the whole app in RAM, and Windows can still page beyond the floor. If you run 1–3 sessions you will never see the symptom it fixes; it is discoverable for the user who reports "Omniscio feels sluggish when I come back to it after a heavy run."

Why these specific defaults

  • On by default, and no bigger than the machine needs. It trades a slice of RAM for window responsiveness under pressure, so the slice is capped by the machine's own size rather than being one number everywhere.
  • 128 MB per process at the 32 GB reference, scaled below it. Big enough to keep each Electron process's hot pages resident, small enough that ×5 processes stays well under ~1 GB. A tunable value, not a user-facing knob.
  • A hard floor, not a soft one. A soft SetProcessWorkingSetSize minimum is only an advisory hint Windows ignores under real pressure — a placebo for this feature's whole purpose. The hard-minimum flag is the version Windows actually honors, and it still needs no admin rights.
  • Boost Omniscio interface priority + adaptive E-core delegation — the CPU-side siblings. Those keep Omniscio scheduled under CPU contention; this keeps Omniscio resident under memory pressure. Same Settings → Performance section, same Omniscio-self / Windows-only / off-by-default pattern.
  • Session memory paging (working-set trimming) — the counterpart that pushes the session children's idle pages out to the pagefile to free RAM. This toggle holds Omniscio's own pages in; that one pushes the children's out.
  • Session CPU cap — the session-side CPU limiter that started this family of performance controls.

Last verified 2026-11-11