Adaptive Memory Paging for Sessions

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

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

Tests

• tests/unit/process/adaptive-working-set.test.ts — hysteresis + injected ticks + non-Windows no-op.
• tests/unit/process/job-object-noop.test.ts — applyJobWorkingSetLimit false off-Windows.
• tests/unit/services/settings-apply.test.ts — live start/stop wiring.

For agents

How it works

A 5-second sampler (src/main/process/adaptive-working-set.ts) reads host RAM-in-use via GlobalMemoryStatusEx.dwMemoryLoad (0–100). Hysteresis:

• load > 85% → apply a per-process working-set MAXIMUM (~1 GB) to the singleton session Job Object (JOB_OBJECT_LIMIT_WORKINGSET).
• load < 70% → clear it.

The 15-point band prevents flapping. The limit is written through the Job Object's shared writeBasicLimits() path, so it composes with — never stomps — the CPU-rate cap, below-normal priority, and adaptive E-core affinity that may also be active on the same job.

Related

• 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.