feat(memory): add safe-point SessionBank budget governor

[PhilipJohnBasile]

This extracts the SessionBank memory governor from #336 as one reviewable system.

It adds an opt-in controller behind MTPLX_MEMORY_GOVERNOR=1. The controller samples process memory, applies hysteresis to SessionBank budget changes, and mutates the bank only after acquiring the model lock nonblocking and confirming that foreground, scheduler, restore, commit, MTP, and postcommit work are idle. Sampling happens before the lock is acquired.

Measurement

Command:

python3 scripts/bench_memory_governor.py --observe-iterations 200000 --apply-iterations 50000 --batches 40 --output docs/benchmarks/sessionbank-memory-governor-no-model-20260826.json

Apple Silicon arm64, Python 3.14.7:

• observe: 1,594 ns/op mean, 1,679 ns/op p95, 627,176 ops/s
• safe apply: 1,032 ns/op mean, 1,169 ns/op p95, 968,946 ops/s
• unsafe rejection: 651 ns/op mean, 729 ns/op p95, 1,536,454 ops/s
• correctness: 50,000 safe applications and 50,000 rebalances; zero unsafe applications and zero unsafe rebalances

This is a synthetic controller-overhead measurement. It does not load a model, import MLX, or simulate a live macOS memory-pressure event. The tracked JSON receipt includes the exact command, host, configuration, and SHA-256 hashes of the measured inputs.

Validation

/Users/pjb/git/MTPLX/.venv/bin/python -m pytest -q tests/test_memory_governor.py tests/test_memory_pressure_guard.py tests/test_session_bank.py tests/test_session_bank_env_caps.py tests/test_server_openai.py tests/test_no_mlx_imports.py
# 435 passed

python3 -m compileall -q mtplx/memory_governor.py mtplx/server/openai.py tests/test_memory_governor.py scripts/bench_memory_governor.py
# passed

/Users/pjb/git/MTPLX/.venv/bin/python -m ruff check mtplx/memory_governor.py tests/test_memory_governor.py scripts/bench_memory_governor.py
# passed

/Users/pjb/git/MTPLX/.venv/bin/python -m ruff check --ignore F841 mtplx/memory_governor.py mtplx/server/openai.py tests/test_memory_governor.py scripts/bench_memory_governor.py
# passed

git diff --check
# passed

A full Ruff run without the exclusion still reports the existing last_history_role F841 in mtplx/server/openai.py; the same failure reproduces on untouched upstream/main.

Excluded from this PR

• native adaptive tuning and policy hooks
• prefill, concurrency, and speculative decoding controls
• unified-memory and expert-residency systems
• OTLP export
• replay, semantic-anchor, and expert-locality systems
• systems API, dashboard, README, changelog, and workflow changes

[youssofal]

Thanks. The safe-point rule is the right property and I want it: touch the bank only after taking the model lock without blocking, and only when the foreground, scheduler, restore, commit, MTP and postcommit stages are all idle.

The problem is that there is already a governor for the bank budget. It comes from the memory plan (plan-driven defaults, a dynamic ceiling with early pressure, a structured 507 when an out-of-memory is projected, SSD spill), plus the #447 and #450 admission work now in 2.11.2. Two controllers would fight over the same budget.

So the plan is to fold your safe-point apply into that governor, with your name on it, rather than merge a second controller. On hold until then. Your synthetic measurement is useful either way as the ceiling on the overhead.

[PhilipJohnBasile]

@youssofal Agreed: the memory-plan governor should remain the single owner of the bank budget. Please fold the safe-point apply mechanism into that controller rather than introducing this as a competing governor.

The invariant to preserve is nonblocking acquisition of the model lock, followed by rechecking that foreground, scheduler, restore, commit, MTP, and postcommit work are idle before any bank mutation. Sampling remains outside that lock. The existing synthetic receipt measures controller overhead only, not live pressure/OOM protection. I am leaving the branch held for your governor integration, with no second-controller changes.