---
title: System file cache cap (Windows) — stop the file-cache freeze
---
# System file cache cap (Windows) — stop the file-cache freeze

## TL;DR

A Windows-only switch in Settings → Performance that caps how much memory Windows spends on its
system file cache — the thing that freezes the whole computer when many files churn at once. It is
opt-in, reversible, and always goes through Windows' own administrator prompt.

## What it is

**What it is.** A Windows-only control in **Settings → Performance** (and a one-click button on a
specific inbox alert) that installs an opt-in **hard cap** on how much memory Windows uses as its
*system file cache*. It exists to prevent a specific whole-computer freeze.

**The freeze it prevents.** When many things read and write files fast — for example dozens of
Omniscio agent worktrees churning on a Windows "Dev Drive" (ReFS) — Windows can balloon its file
cache until it eats most of your RAM. Available memory then collapses, Windows starts frantically
trimming every program's memory, and the whole machine freezes for minutes. Capping the file cache
at a sane size stops it from ever ballooning that far, so the freeze can't happen.

**The size is automatic.** The cap is scaled from your machine's RAM (about 24 GB on a 128 GB
machine, scaling down for smaller machines, always within a safe floor and ceiling). You don't
choose the number — Omniscio computes it so it protects you without starving normal file caching.

## Where to find it

**How to use it.**
- Open **Settings → Performance**, expand the advanced **Memory & RAM** group, and find the
  **"System file cache cap"** card. It shows whether the cap is installed and the size it will use.
- Click **Install cache cap**. Windows shows its own **administrator (UAC) prompt** — approve it and
  the cap is set immediately and re-applied automatically on every restart.
- To undo it, click **Remove cache cap** (it asks you to confirm, then Windows prompts for admin
  again). Removing it lifts the limit completely.
- If the freeze pattern is actively happening, Omniscio also raises an inbox alert — *"Windows file
  cache is crowding out memory"* — with the same one-click **Install cache cap** button.

## How it behaves

**Safety & scope.**
- It changes a **machine-wide Windows setting**, so it *always* goes through Windows' own admin
  (UAC) prompt — Omniscio can't bypass it, and it's fully **opt-in** and **reversible**.
- Nothing on the phone/web client or the headless CLI can trigger install or remove — it's
  desktop-only and human-only by design; an AI agent can never change your machine's cache config.
- **Windows only.** On macOS/Linux the card is hidden and the feature does nothing (their file
  caches don't misbehave this way).

## For agents

**How it works under the hood.** Installing registers a Windows **SYSTEM scheduled task** that, at
every startup, calls the Windows API `SetSystemFileCacheSize` to enforce the cap; installing also
applies it right away. The cap logic is self-contained in the task itself (nothing on disk that
could be tampered with), and the low-level call is the same one field-proven on the owner's
machine.

For engineers: invariants + the source map are in the `system-cache-cap-contract`. Note the status
check reads the *actual* enforced cap via `GetSystemFileCacheSize` (works without admin), not the
scheduled task (a SYSTEM task is access-denied to an unprivileged query).

## Related

The other performance controls sit beside this one in **Settings → Performance** — keeping the
computer smooth under load, and how background work is paced during severe lag. When something is
already feeling wrong rather than merely heavy, **Computer feels slow?** is the guide to follow
first.