macOS: available memory misdetected as 0 MB — embedding model never loads, markdown/memory tools unusable

[hiepknor]

Summary

On macOS (arm64), MemoryManager::initialize reports available memory: 0 MB and skips loading the embedding model, even though the machine has 16 GB RAM with ~38% free system-wide. As a result every embedding-dependent tool (codegraph_index_markdown, codegraph_memory_*, semantic search) fails with Memory manager not initialized, in both MCP mode and --run-tool one-shot mode. There is no flag or env var to override the check.

Environment

• codegraph-server v0.19.0 (f0a6dbb), installed via npm install -g @astudioplus/codegraph-mcp
• Built: 2026-06-30T18:07:10Z with rustc 1.93.1
• macOS 26.5.1 (build 25F80), Apple Silicon (arm64), 16 GB RAM

Reproduction

codegraph-mcp --run-tool codegraph_index_markdown \
  --tool-args '{"path":"/path/to/project/docs"}'

Log output:

INFO codegraph_server::memory: [MemoryManager::initialize] available memory: 0 MB
WARN codegraph_server::memory: [MemoryManager::initialize] only 0 MB free — skipping embedding model to avoid OOM; semantic search disabled (graph-only)
WARN codegraph_server::mcp::server: Failed to initialize memory manager: Other("insufficient memory (0 MB free) to load embedding model; running graph-only")
...
Tool 'codegraph_index_markdown' failed: Failed to index markdown: Memory manager not initialized

Actual memory state at the same moment:

$ memory_pressure -Q
System-wide memory free percentage: 38%

$ vm_stat | head -6
Mach Virtual Memory Statistics: (page size of 16384 bytes)
Pages free:                                     4258.
Pages active:                                 191648.
Pages inactive:                               188635.
Pages speculative:                              2717.

Likely cause

macOS deliberately keeps the free page count near zero (~66 MB here) and parks reclaimable memory in inactive/speculative/purgeable pages. If the check reads only free pages (or a stat that rounds down to 0 MB), it will conclude 0 MB on virtually every healthy Mac. "Available" on macOS should be roughly free + inactive + speculative + purgeable — e.g. sysinfo's available_memory() handles this correctly.

Suggested fix

1. Compute available (reclaimable) memory rather than free memory on macOS.
2. Treat a reading of 0 as "unknown" and proceed (or warn) instead of hard-disabling the embedding model — 0 is almost certainly a detection failure, not a real state.
3. Provide an escape hatch (e.g. CODEGRAPH_SKIP_MEMORY_CHECK=1 or --min-free-mb 0) so users can override the heuristic.

Impact

All embedding-dependent functionality is silently unavailable on macOS: codegraph_index_markdown, search_docs, codegraph_memory_*, semantic/similarity search. Graph-only tools work fine.

[Znbiz]

Fixed by #12 (item 1 in the description / "Memory-gate" fix in the CHANGELOG).

The root cause matches what's described here: available_memory == 0 (a real sysinfo reading under memory pressure, as on this machine) was treated as "no memory available" and the server hard-skipped the embedding model — no override existed. The fix changes the interpretation of 0 to "reading unknown" instead of "no memory", so the server attempts to load the embedding model instead of automatically degrading to graph-only.

This directly addresses suggestion #2 from the issue (treat 0 as unknown, don't hard-disable). We didn't add a CODEGRAPH_SKIP_MEMORY_CHECK/--min-free-mb escape hatch (suggestion #3) since the 0-as-unknown fix already unblocks the reported case, but that's still worth adding separately if there are environments where a genuinely low (but nonzero) reading needs to be overridden.

PR: #12

[anvanster]

I am reviewing the PR. Will probably integrate it into next release with additional features.

[anvanster]

Fixed on branch fix/macos-memory-detection (PR incoming; will land in the next release).

Root cause confirmed. The RAM gate before the ONNX model load reads sysinfo::available_memory(), which returns 0 on your macOS build because reclaimable memory is parked in inactive/speculative/purgeable pages that aren't counted as free — so the gate concluded "0 MB free, skip the model" and disabled every embedding-dependent tool. (We already call available_memory() rather than free_memory(); the 0 is coming from inside sysinfo on newer macOS, matching the ~3 GB reclaimable your vm_stat shows.)

The fix:

1. A 0 reading is now treated as a detection failure, not a real state (a running process always holds memory), so the model loads anyway instead of hard-disabling. A genuine low-but-nonzero reading still falls back to graph-only to avoid the OOM-kill the gate exists to prevent.
2. New escape hatch: CODEGRAPH_SKIP_MEMORY_CHECK=1 (also true/yes) bypasses the gate entirely, in both MCP and one-shot --run-tool modes. Documented in the README.

One caveat in the interest of honesty: I couldn't reproduce the 0 locally (macOS 26.3 here reports a healthy ~7.5 GB available), so the fix is covered by unit tests over the gate policy and by reasoning about the failure mode rather than by reproducing the exact symptom on your build. If you're able to try a pre-release build once it's out, confirmation from your environment would be appreciated.

Thanks for the unusually precise report — the vm_stat / memory_pressure breakdown made this quick to pin down.