macOS agent reports memory usage near 98% because only free pages are counted, while Linux agents use available memory for the same field

Description

The macOS agent reports host.memory.usage of 0.9843 (98.4%) and host.memory.free of 64 MiB on an otherwise idle host, while macOS itself reports 46% of memory free at the same time. The cause is that the macOS collector derives used memory as total - free_pages, counting reclaimable memory as used. Linux agents populate the same field from available memory instead, so the two platforms give the field incompatible meanings and only macOS looks exhausted.

Reported for the macOS agent:

host.memory.total  4294967296     (4096 MiB)
host.memory.free     67223552     (64 MiB)
host.memory.used   4227743744     (4032 MiB)
host.memory.usage  0.9843482971191406

4294967296 - 67223552 = 4227743744, so used is exactly total - free.

What the host actually reports, via vm_stat with a 16384-byte page size:

free=146MB inactive=804MB purgeable=7MB active=875MB wired=1043MB compressed=1147MB

and macOS's own summary tool disagrees sharply with the agent:

$ memory_pressure | tail -1
System-wide memory free percentage: 46%

Inactive and purgeable pages, 811 MB together here, are reclaimable on demand and are not memory pressure. Excluding them is what turns roughly half-free into 98.4% used.

The same field means something different on Linux. For agent 002 the agent reported free = 1561817088, and the host's /proc/meminfo at inspection time was:

MemTotal:        1950944 kB   ->  1997766656 bytes   (matches host.memory.total exactly)
MemFree:          777164 kB   ->   795815936 bytes
MemAvailable:    1477336 kB   ->  1512792064 bytes

The reported value tracks MemAvailable (1.51 GB), not MemFree (0.79 GB), which is why Linux agents sit at a plausible 16% to 29% usage. So Linux already excludes reclaimable cache from "used" and macOS does not.

The consequence is a false memory-exhaustion signal on every macOS endpoint. Any alerting, dashboard panel or capacity report keyed on host.memory.usage will show macOS hosts permanently near 100% while comparable Linux hosts show 20%, and the two numbers are not comparable even though they share a field name.

Note that this value is also currently frozen at the first scan, which is reported separately as a distinct defect. The two interact: because the hardware document is never refreshed, the incorrect ratio recorded at enrollment can never be superseded even after the host's memory profile changes.

Environment

• Agent under test: demo-env-macos-agent, id 006, macOS 26.5.1 (build 25F80), arm64, Apple M1 (Virtual), 2 vCPU, 4 GiB RAM, Parallels VM on MacStadium host macstadium_arm_4.
• Agent package wazuh-agent-5.0.0-latest.arm64.pkg from nightly-backup/2026-09-09, receipt com.wazuh.pkg.wazuh-agent version 5.0.0.
• VERSION.json: {"version": "5.0.0", "stage": "rc1", "commit": "2161e69"}.
• Comparison agent: demo-env-linux-deb-amd64-agent, id 002, Ubuntu 26.04, wazuh-agent_5.0.0-latest_amd64.deb from the same nightly.
• QA demo environment wqa-prod-58-demo-environment: clustered managers, one indexer, one dashboard, six enrolled agents. Not a container deployment, so there are no image digests to record.

Steps to reproduce

1. Enroll a 5.0.0 macOS agent and let the first syscollector evaluation complete.
2. Read the hardware document for that agent:

curl -sk --cert admin.pem --key admin-key.pem \
  "https://<indexer>:9200/wazuh-states-inventory-hardware/_search?size=1" \
  -H 'Content-Type: application/json' \
  -d '{"query":{"term":{"wazuh.agent.id":"006"}},"_source":["host.memory"]}'

1. On the macOS host, compare against the kernel's own page accounting and summary:

vm_stat
memory_pressure | tail -1
sysctl -n hw.memsize

1. Confirm used == total - free_pages and that inactive plus purgeable pages are excluded from the free figure.
2. Repeat steps 2 and 3 on a Linux agent and compare the reported host.memory.free against MemFree and MemAvailable in /proc/meminfo. The Linux value tracks MemAvailable.

Expected

host.memory.free, host.memory.used and host.memory.usage mean the same thing on every platform. On macOS the reclaimable pages, inactive and purgeable, are treated as available rather than used, so the reported figure is in the same range as macOS's own reporting (roughly 54% used here, not 98%).

Actual

The agent reports 98.4% used and 64 MiB free:

host.memory.free     67223552
host.memory.used   4227743744
host.memory.usage  0.9843482971191406

while the host has 804 MB inactive and 7 MB purgeable available for reclaim, and macOS reports:

System-wide memory free percentage: 46%

The Linux comparison shows the inconsistent semantics, with the reported free value matching MemAvailable rather than MemFree:

002 reported free = 1561817088
    MemFree       =  795815936
    MemAvailable  = 1512792064

Not a duplicate of

qa-known-issues.py check scored two cache candidates and the live search returned nothing:

• wazuh/wazuh#14240 "Error when building agent in macOS 11 and higher" (0.50) is a compilation failure of the macOS agent, unrelated to inventory values.
• wazuh/wazuh-dashboard-plugins#4241 "Agent reports could not be deleted" (0.50) concerns deletion of generated agent reports in the dashboard plugin, a different repo and subject.
• Live search for reclaimable inventory inactive hardware ignores reports returned nothing open.