docs: document Neo4j memory sizing and what the sizing presets assume

[lancamat1]

Why

A customer ran every environment with Neo4j consuming all 32 GB of RAM plus swap, on databases holding under 100 MB, and asked how that was possible on a wiped instance. The configuration was 24G heap and 4G page cache — the medium sizing preset, which we ship in Docker Compose and Helm and publish in the install docs.

The docs could not have answered the question. Nothing explained what heap and page cache hold, that Neo4j reserves the whole heap at startup so resident memory reflects the setting rather than the contents, or how to size either pool for a host. Tune performance covered only INFRAHUB_* settings, so a reader with a memory problem found nothing about the process using the memory. When we recommended smaller values, the customer pushed back by citing our own enterprise sizing table.

What changed

• performance-tuning.mdx — a Neo4j memory section: the two pools and what each holds, -XX:+AlwaysPreTouch and why an oversized heap is resident on an empty database, reading the resolved values from the debug.log startup block, sizing with neo4j-admin server memory-recommendation, bounding transaction memory, and a symptoms-and-causes table.
• hardware-requirements.mdx — what the enterprise RAM figures cover, and that the database values need checking against the machine that runs Neo4j rather than assumed from the tier.
• install/enterprise.mdx — the preset heap and page cache values are defaults for a host of that size, how to override them per environment, and a warning to validate before deploying.
• upgrade/overview.mdx — the dbms.memory.transaction.total.max=0 workaround now says to restore the limit afterwards, and why.
• .vale/styles/spelling-exceptions.txt — adds Lucene.

Worth a reviewer's attention

• The preset values themselves are a separate problem. medium reserves 28 GB of 32 GB (88%) where Neo4j's own tool asks for 12G heap / 12G page cache / 8 GB reserved, and the ratio is inverted — page cache is what holds the graph. small reserves 56% and large 73%, so medium is the outlier. These docs explain how to override the preset; they do not defend its numbers. A separate issue against infrahub-helm covers changing them, and this page will need a pass if they change.
• The claim that each enterprise RAM figure covers a full deployment. Verified against the Compose presets, where every service runs on one host. Confirm it holds for how the Helm flavored charts are meant to be read.
• The 12G / 12G example in install/enterprise.mdx is scoped to a 32 GB host running only Neo4j. It sits under a table covering small through large, so check the framing reads unambiguously.
• The debug.log excerpt is a real startup block, with nothing identifying in it.

Checks

• npm run build — passes, no broken links or anchors
• vale — 0 errors, 0 warnings (installed locally; the invoke task skips silently when it is missing)
• markdownlint-cli2 — 0 errors

[cubic-dev-ai]

All reported issues were addressed across 5 files

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. Documentation-only: adds Neo4j memory-sizing guidance and a note to restore the transaction limit after migration. No product, config, auth, data, or behavior changes.

Re-trigger cubic</sub>