Module memory_guard 

Process-level RAM guardian with adaptive eviction and hard OOM protection.

Monitors RSS via platform-specific APIs and triggers tiered cache eviction when memory usage exceeds configurable thresholds (default: 5% of system RAM, lowered to mcp_max_rss_mb — 512 MB — inside a stdio MCP server). At critical levels, performs aggressive eviction and signals background tasks to abort. It never exits the process — recovery is always via eviction.

Structs

MemorySnapshot

Snapshot of current memory state for diagnostics.

Enums

PressureLevel

Functions

abort_requested

Returns true if the guardian has requested background tasks to abort.

adaptive_batch_size

Computes a memory-bounded work batch from current RSS and the guardian’s hard threshold (1.5× the configured base limit). Falls back to max_files when RSS is unavailable. The lower bound keeps progress deterministic while allowing callers to reduce in-flight work substantially under low headroom.

allocator_stats

Live heap bytes and allocator-resident bytes (stats.allocated, stats.resident), when jemalloc is the allocator. The gap between process RSS and allocated is what eviction cannot reach: allocator retention, code and thread stacks.

current_pressure

Returns the current pressure level as last observed by the guardian thread.

force_purge

Force immediate purge of all caches and jemalloc arenas.

get_rss_bytes

Current process memory in bytes, or None if unavailable: resident set size on Linux and Windows, physical footprint on macOS (see macos_footprint — resident size there hides compressed pages).

get_rss_bytes_for_pid

RSS of an arbitrary process by PID, or None if unavailable/dead.

get_system_ram_bytes

Total physical RAM in bytes, or None if unavailable.

is_under_pressure

Quick, non-allocating memory pressure check for hot loops (scanners, indexers). Reads the cached atomic flag set by the guardian thread — O(1), no syscalls.

jemalloc_purge

Force-purge all jemalloc arenas to return memory to the OS. Uses MALLCTL_ARENAS_ALL (value 4096) which is the jemalloc sentinel for “all arenas”. Logs errors instead of silently swallowing them.

peak_rss_bytes

Recorded peak RSS since process start.

reclaim_now

Return freed pages to the OS now, then measure and publish the pressure again. For work that would otherwise refuse under pressure the guardian published earlier: memory a finished request dropped is not pressure.

release_system_heap

Return glibc’s free pages to the OS. C dependencies other than tree-sitter (SQLite, regex engines) still allocate through the platform malloc, whose per-thread arenas otherwise keep every page an index build touched. macOS has no equivalent: malloc_zone_pressure_relief released nothing in measurement, which is why tree-sitter is routed to jemalloc instead.

route_tree_sitter_to_jemalloc

Route tree-sitter’s C allocations (parse trees, parser stacks, query cursors) through jemalloc, whose arenas jemalloc_purge returns to the OS. The platform malloc keeps them instead: measured on macOS, freed parser-sized blocks stayed in the footprint and malloc_zone_pressure_relief released nothing, so a daemon that parses every file of every root grew with each new root (#2075).

rss_limit_bytes

Returns the RSS limit in bytes: the max_ram_percent target, lowered to the process cap when one is installed (set_process_rss_cap).

set_process_rss_cap

Install an absolute RSS target for this process; the effective limit is the lower of it and the max_ram_percent target. 0 removes it.

start_guard

Start the background memory guardian task (idempotent). Polls every 3s (normal), 1s (under pressure), or up to 15s once RSS has been stably calm (idle backoff). Eviction rounds that reclaim nothing back off to 60s, then pause for five minutes, at every pressure level; pressure logs repeat at most once a minute per level. The callback returns whether it reclaimed memory so the guard can distinguish a real retry from an empty-cache loop.