MemGuard

Lean memory behavior for long Minecraft sessions.

MemGuard is a lightweight utility mod for Fabric / Forge / NeoForge (Minecraft 1.21.1) focused on reducing avoidable allocations and making memory pressure easier to observe.

What MemGuard does

1. Reuses repeated short NBT strings

• Hook: NbtString.of(...)
• Repeated short values are reused through an LRU cache (up to 2048 entries).
• This reduces duplicate object allocations for common IDs/tags in larger modpacks.

2. Logs periodic heap snapshots

• Heap usage is sampled from server tick context.
• Warning logs are emitted when configured usage thresholds are exceeded.
• Intended for visibility and troubleshooting, not as a direct performance claim.

3. Tracks texture-atlas lifecycle (client)

• On atlas upload completion, MemGuard logs heap-used values in debug context.
• This helps correlate load phases with memory behavior.

Technical notes

• Uses mixin hooks for targeted behavior (NbtCacheMixin, ServerChunkManagerMixin / ChunkCacheMixin, TextureCacheMixin).
• No native code, no unsafe memory access.
• System.gc() is not used to force garbage collection.

Important accuracy notes

• MemGuard does not guarantee fixed FPS/MSPT/MB improvements.
• Real impact depends on modpack size, entity/world state, JVM vendor/flags, and session length.
• Expected benefit is typically higher in medium/large packs with repeated NBT patterns.

Reproducible evaluation (recommended)

To evaluate MemGuard for your own setup, compare baseline vs. MemGuard under identical conditions:

1. Same Java version, JVM args, mod list, world seed, and config.
2. Same runtime window (recommended: 30-60 minutes per run).
3. At least 3 baseline runs + 3 MemGuard runs.
4. Collect comparable metrics:

• p50/p95 MSPT (spark or similar)
• heap usage trend from logs
• allocation/GC event data (JFR or similar)

5. Compare distributions (median/p95), not single spikes.

Installation

Fabric

1. Install Fabric Loader (0.16+)
2. Install Fabric API
3. Place MemGuard jar in mods/

Forge / NeoForge

1. Install the matching loader for your Minecraft version
2. Place MemGuard jar in mods/

Compatibility

• Designed to work alongside common optimization mods.
• As with any mixin-based mod, test your exact modpack before production deployment.