Memory reclaim (free RAM automatically when the machine runs low)

What it is

What it does

When your computer's free memory runs low and stays low, Omniscio automatically frees some up so the machine doesn't start swapping to disk and feeling slow. It works in two levels of aggressiveness — a safe one that's on by default, and a powerful whole-computer one that's off by default and opt-in.

• Tier 1 — tidy Omniscio's own idle sessions (on by default, safe). Every running Claude session holds a chunk of memory even while it sits idle waiting on you. When free RAM drops below your threshold and stays there, Omniscio "trims" the memory of its own idle sessions — it asks Windows to move their unused pages out of RAM (the pages come back automatically the instant that session is used again). It only ever touches sessions that are not mid-reply and not waiting for your answer to a question, so it can never interrupt work. This is a Windows effect; on macOS and Linux the trim does nothing (the app just skips it).

• Tier 2 — reclaim across your whole computer (opt-in, advanced, Windows only). The stronger option empties the unused memory of every program on the machine and clears Windows' standby cache — a system-wide cleanup, the same thing tools like RAMMap's "Empty Standby List" do. Because that touches the whole system it needs Windows administrator rights, so Omniscio installs a tiny helper once, with your approval (a single Windows admin prompt), and then runs it on demand without prompting again. It ships off and hidden until it's fully hardened.

Both levels share one trigger: your computer's free memory staying below a set percentage. Omniscio does not react to a single brief dip — memory has to stay low for a few readings in a row, and there's a cool-down between reclaims, so it never thrashes (repeatedly trimming would itself make the machine feel slower, the opposite of the goal).

Where to find it

Settings → Performance, where the on/off switch and the free-memory trigger point live. Tier 2 sits behind the app's unreleased-feature gate.

How it behaves

How to turn it on or off

Tier 1 lives in Settings → Performance:

• "Reclaim RAM automatically when memory runs low" — the on/off switch (on by default).
• "Reclaim when free memory drops below ___ % free" — the trigger point. When free RAM stays below this percentage of your total memory, the automatic tidy-up kicks in. Higher = reclaims sooner; lower = only under real pressure. Default 15%.

No restart is needed — the setting applies live.

Tier 2 is an in-development feature, hidden by default. It appears only when you enable it from Settings → Lab (or launch with AMC_SHOW_MEMORY_RECLAIM_ADVANCED=1). Turning it on triggers a one-time Windows administrator prompt to install the elevated helper. Turning it back off uninstalls that helper (one more admin prompt) so nothing elevated is left behind; while it's off, no system-wide reclaim runs. Day-to-day use never re-prompts — only the install and the uninstall do.

When it applies

• Your computer's free memory has stayed below the threshold for a few consecutive checks (Omniscio checks about once a minute), and the cool-down since the last reclaim has passed.
• Tier 1 additionally only trims sessions that are idle — finished their turn, not waiting on a question or plan approval. The active session you're talking to, and any session mid-reply, are never touched.
• Tier 2 additionally requires Windows and that you've opted in (the elevated helper is installed).

When it does NOT apply

• On macOS or Linux, the memory-trim is a Windows-only system call, so Tier 1 runs but has no effect and Tier 2 is unavailable. (Omniscio's primary platform is Windows.)
• On a brief memory spike — a single reading below the threshold won't trigger anything; pressure has to be sustained.
• Right after a reclaim — the cool-down prevents back-to-back reclaims of the same tier.
• On sessions that are working or waiting on you — Tier 1 skips them by design.

Why a percentage, not "number of sessions"

Most slowness while running Omniscio is RAM exhaustion → disk swap-thrash, not "too many sessions." Reacting to actual free memory targets the real cause directly, and a percentage generalizes across machine sizes — "15% free" means the same kind of danger on a 16 GB laptop and a 64 GB workstation. (On a 64 GB box, Tier 2's default 25% ≈ 16 GB free.)

How it relates to the other memory features

Omniscio has a few overlapping ways to keep memory healthy; this one is the pressure-triggered reclaimer:

• Memory reclaim (this page) — fires when free memory runs low. Tier 1 trims Omniscio's idle sessions; Tier 2 (opt-in) reclaims the whole computer.
• Release idle sessions — a time-based reaper: fully releases (closes) the background process of a session that's sat idle for many minutes, re-opening it transparently on your next message. Harder reclaim, different trigger. See slow-computer.md.
• Working-set trim scheduler — the older idle-time-based trim of Omniscio's own sessions; memory reclaim reuses the same safe trim primitive but drives it off memory pressure instead of idle time.

For a full "my computer feels slow" walkthrough, see slow-computer.md.

For agents

Where it lives in code

• src/main/services/memory-reclaim/memory-reclaim-decision.ts — the pure decision: given free%, per-tier {enabled, threshold}, and the sustained-pressure + cool-down state, decides which tier fires this check.
• src/main/services/memory-reclaim/memory-reclaim-scheduler.ts — the 60-second scheduler: reads free memory from the pure sampler, applies the decision, and drives the Tier-1 trim / Tier-2 invoke.
• src/main/services/memory-reclaim/system-wide-reclaim-win32.ts — the Tier-2 Windows helper: install (one admin prompt → a scheduled task whose reclaim command is embedded inline, so no user-editable script ever runs elevated), invoke (no further prompts), status, and remove.
• src/main/services/ws-trim.ts — the shared, safe working-set trim primitive Tier 1 reuses.
• src/shared/types/settings/system/streaming-memory-settings.ts — the four settings (memoryReclaimEnabled, memoryReclaimFreePercent, memoryReclaimAdvancedEnabled, memoryReclaimAdvancedFreePercent).

The full engineering contract (test-locked invariants + safe-change checklist) is .claude/memory/contracts/memory-reclaim-contract.md.

Related

Related

• slow-computer.md — the free-first "my computer feels slow" guide.
• Omniscio’s unreleased-feature (“Lab”) gate — how Tier 2 stays hidden until it ships.