Memory governor
How NYXDB bounds memory — ramp and block watermarks, admission control, and spill under pressure.
The memory governor keeps the engine inside a memory budget under sustained over-RAM ingest, without OOMing and without silently dropping data. It samples process RSS plus allocator stats on the flush cadence and drives admission control.
Watermarks
| Watermark | Level | Behavior |
|---|---|---|
| Ramp | ~0.80 of the limit | Admission switches to a graduated delay; seal and spill become aggressive. |
| Block | ~0.95 of the limit | Admission is blocked outright (with a throttled warning) to prevent OOM. |
The admission decision is driven by the max of several factors — tail size, seal lag, and the memory factor — so whichever pressure is highest sets the ramp.
Admission control
- Ramp (delay) — at the ramp watermark, writes are admitted with a graduated delay that also drives seal/spill aggressiveness.
- Block (reject) — at the block watermark, new writes are rejected until pressure drops. No write bypasses the watermark check.
Spill
When pressure exceeds the watermark, spillable raw tail chunks serialize to disk and are read back through the page cache, so the committed tail stays bounded even when it exceeds RAM.
Heap pressure that crosses a tier triggers a memory-profile dump, surfaced in
system.memory_profile (top-N allocation
sites). That table is empty on engines built without allocator profiling
(e.g. macOS dev builds).
TODO-verify: the exact memory-limit flag/setting name and the precise watermark fractions for your release. Values above reflect the governor's documented design (ADR-075).