CPU governor

Configure adaptive CPU budgets for background indexing on Windows, Linux and macOS. Reference for activation, battery policies, idle behavior, platform support and diagnostics.

CPU governor overview#

Memtrace's CPU governor manages how background indexing shares processor resources with interactive applications. Adaptive CPU budgets and scheduling priorities are designed to preserve foreground responsiveness while indexing continues. The governor responds to system load, power source, user activity and memory pressure.

The policy supports shared development workstations, battery-powered laptops and other environments where background indexing runs alongside foreground workloads. Participating workers yield at scheduling checkpoints, and progress monitoring can temporarily suspend background loops that consume CPU without advancing their work.

CPU governance operates within Memtrace. Operating-system CPU frequency settings remain unchanged. The memtrace govern command serves a separate purpose: ingesting governance documents into decision memory.

CPU governor activation policy#

The CPU governor is opt-in and defaults to off. Setting MEMTRACE_CPU_GOVERNOR=on enables adaptive budgeting, background scheduling and progress-based loop parking. With the governor disabled, CPU accounting remains available for diagnostics.

Explicit activation allows each deployment to select its resource policy. Background pacing prioritizes resource availability for concurrent applications and can extend indexing completion time. Workstations running interactive workloads and dedicated indexing hosts can therefore use different settings.

CPU governor configuration#

Set MEMTRACE_CPU_GOVERNOR in the daemon's launch environment and restart Memtrace to apply the policy. For persistent configuration, use the shell profile, service definition or process launcher responsible for starting the daemon. Retain any workspace flags required by that deployment.

memtrace stop
MEMTRACE_CPU_GOVERNOR=on memtrace start

memtrace stop
$env:MEMTRACE_CPU_GOVERNOR = "on"
memtrace start

Set MEMTRACE_CPU_GOVERNOR=off and restart to disable the policy. Removing the variable restores the current off default. The startup banner reports either CPU governor: offor the active budget. Changing an environment variable in another terminal does not reconfigure an existing daemon.

Additional controls, defaults and accepted values are listed under CPU governor in the environment-variable reference.

CPU governor resource policies#

With the governor enabled, background work normally starts with half the detected performance cores, with a minimum allowance of one core. Interactive work starts with the full performance-core allowance. A budget of 2 represents an allowance of roughly two CPU-seconds per second, enforced at participating scheduling checkpoints.

MEMTRACE_CPU_BUDGET_CORES overrides the background allowance. MEMTRACE_BACKGROUND_ON_BATTERY=reduced|off|full selects battery behavior, and MEMTRACE_CPU_IDLE_BOOST=off disables the idle boost. Idle boost can raise the allowance above the configured background budget. See Environment variables for defaults.

Enforcement is cooperative. Operations without checkpoints, including portions of history replay, and accelerator work fall outside a strict CPU cap. Sidecar scheduling uses platform facilities. The current production thermal probe reports unknown; thermal readings should therefore be treated as unavailable in diagnostics.

CPU governor platform support#

Memtrace's CPU governor supports background work on Windows, Linux and macOS Apple Silicon. The shared budgeting policy uses platform-specific scheduling and available host telemetry. Unavailable power, activity or memory signals remain neutral.

Native macOS host-signal integration is included in Memtrace 1.2.0. Apple Silicon support is architecture-based, with no M5-specific activation requirement. The validation reference records tested hardware, release details and remaining coverage.

CoreML selects the execution provider for supported embedding operations; the CPU governor controls resource scheduling. These settings are independent. Memtrace 1.2.0 requests CoreML by default on Apple Silicon with CPU fallback, while CPU governance remains opt-in. MEMTRACE_DISABLE_COREML=1 selects CPU-only execution. Actual accelerator placement depends on the model and the operations supported by CoreML.

CPU governor performance characteristics#

The governor changes when background work receives CPU time. Under contention, reduced budgets and scheduling priority leave resources available for interactive applications. Idle boost permits more background work when conditions allow. Indexing throughput depends on the active policy, hardware, power state and concurrent workload.

Evaluate foreground responsiveness alongside indexing completion time. CPU utilization describes activity at a point in time; accumulated CPU time describes total processor work. Energy consumption and battery life require separate measurements. Published measurements and their methodology are maintained in the CPU governor validation reference.

CPU governor monitoring and diagnostics#

memtrace status --json

In the cpu object, check governor, inputs, decision.reason, decision.budget_cores and decision.pause_bulk. The daemon's /api/health endpoint exposes the same diagnostics. Use the governor field to distinguish active enforcement from diagnostic accounting.

A battery or memory reason indicates a policy pause. Check the reported power state and memory pressure before investigating a stalled worker. The idle-burn watchdog monitors CPU consumption without recorded progress over a default ten-minute window, then temporarily parks registered background loops. Watchdog state and progress counters identify that condition.

For a diagnostic comparison, restart with MEMTRACE_CPU_GOVERNOR=off while retaining the same workload and other settings. An index reset is not required. Model loading, CoreML compilation, authentication and embedding circuit breakers are diagnosed separately; see Troubleshooting and memtrace warmup.