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

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

• Smooth load — keeping the computer smooth while work runs.
• Severe lag background pacing — how background starts are paced when the app is already lagging.