Omniscio

Adaptive Memory Paging for Sessions

An opt-in, Windows-only feature that caps the resident memory of every Claude CLI session when the host is short on physical RAM, so Windows pages the overflow out to disk. Sessions keep running, just slower. It is off by default, and it never kills a session to free memory.

On this page

What it is

What: An opt-in, Windows-only feature that, under host physical-RAM pressure, caps the resident working set of every Claude CLI session (and the test processes they spawn) so Windows pages the overflow to the disk pagefile. Frees physical RAM; sessions keep running, just slower. Off by default.

Setting: sessionAdaptiveMemoryPaging (boolean, default false) — Settings → Performance, "Ease RAM pressure by paging busy sessions to disk".

Where to find it

It is a setting rather than a screen of its own. Open Settings and go to the Performance section, where the row reads "Ease RAM pressure by paging busy sessions to disk" — switch it on there. It is off by default, and it is Windows-only: on macOS and Linux the toggle has no effect.

Nothing else in the app changes when you turn it on. No new panel, badge or menu appears; the trimming happens quietly in the background, and only while the machine is actually short on memory.

How it behaves

Why a working-set cap, not a memory cap

The Job Object also exposes JobMemoryLimit / ProcessMemoryLimit (commit caps). We deliberately do not use them: exceeding a commit cap makes an allocation fail, crashing the session mid-task. A working-set MAXIMUM is soft — it only forces paging, so the process slows but survives. The user's requirement was "page to disk, don't kill, keep spawning".

Scope

Only the session Job Object. Test workers a session spawns are children inside that job (no breakaway), so they inherit the cap. Omniscio's own Electron processes are not in the job and are never trimmed.

Tuning

PER_PROCESS_MAX_BYTES (~1 GB) is the one knob. Too low → pagefile thrash; too high → frees too little. Tuned empirically; only engages above 85% load. Assumes an SSD with pagefile headroom.

Failure / no-op paths

  • Non-Windows → applyAdaptiveWorkingSet returns false; sampler never starts.
  • Job Object init failed at startup → applyJobWorkingSetLimit is a no-op.
  • GlobalMemoryStatusEx / kernel32 load failure → the tick skips (logs, never throws).

Source

  • adaptive-working-set.ts — sampler + hysteresis + memory read.
  • job-object-win32.ts — setJobWorkingSetLimit koffi wrapper.
  • job-object.ts — applyJobWorkingSetLimit cross-platform shim.
  • index.ts — applies at startup when enabled.
  • settings-apply.ts — re-applies live on toggle flip.
  • PerformanceSettings.tsx — the toggle.

Tests

  • adaptive-working-set.test.ts — hysteresis + injected ticks + non-Windows no-op.
  • job-object-noop.test.ts — applyJobWorkingSetLimit false off-Windows.
  • settings-apply.test.ts — live start/stop wiring.
  • session-cpu-cap.md — the soft CPU-rate cap (sibling lever on the same Job Object).
  • amc-priority-boost.md — Omniscio priority boost + adaptive E-core delegation.
  • amc-resident-floor.md — the Windows working-set floor that keeps Omniscio's own pages resident in physical RAM instead of letting them be trimmed to the pagefile.

Last verified 2026-10-06