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

# Memory reclaim (free up RAM automatically when your computer 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](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](slow-computer.md).

## For agents

### Where it lives in code

- [src/main/services/memory-reclaim/memory-reclaim-decision.ts](../../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](../../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](../../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](../../src/main/services/ws-trim.ts)
  — the shared, safe working-set trim primitive Tier 1 reuses.
- [src/shared/types/settings/system-settings.ts](../../src/shared/types/settings/system-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](../../.claude/memory/contracts/memory-reclaim-contract.md).

## Related

### Related

- [slow-computer.md](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.