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