Memory Leak Hunter: Prove It, Fix It, Show It Flat

What it does

Finds and fixes memory leaks with proof. It builds a growth test that repeats one unit of work, shows memory climbing, diffs heap snapshots to find what's growing, follows the reference chain back to its root, fixes that reference, and re-runs the same test to show memory now stays flat.

Why it exists

"Memory keeps going up" has three different causes: a real leak, a cache still warming up, and allocator fragmentation. Fixing the wrong one wastes days, and restarting the process on a timer just hides the bug. This skill classifies the growth before touching code.

How it works

1. Builds a repeatable growth test around one request, job or message, and records the heap at checkpoints after garbage collection.
2. Classifies the curve: steady growth (leak), rise then flat (cache warming up), or heap flat while RSS grows (fragmentation or native memory).
3. Diffs two heap snapshots and follows the reference chain to its root, using a bundled tool table for Python, Node.js, Java and Go.
4. Matches the chain against a bundled catalog of leak patterns (listeners never removed, unbounded caches, closures, unclosed resources, stuck goroutines and tasks), including look-alikes that aren't leaks.
5. Fixes the reference, not the symptom, then re-runs the same growth test and checks behaviour is unchanged.

What you get

Growth per unit of work before and after, the retaining chain with snapshot evidence, the fix, how behaviour was checked, and any remaining risk such as native memory.

When not to use it

One-off high memory use with no growth, tuning garbage collector settings, or native memory corruption bugs.

See it in action

Request:

Use the memory-leak-hunter skill on worker.py. Our message worker's memory climbs steadily until it gets OOM-killed after about a day. simulate.py feeds it fake messages the way the queue consumer does.

Result: It traced the leak to an event-bus handler subscribed per message and never removed, explained why growth accelerated, fixed it with an unsubscribe in a finally block, and correctly left a bounded lru_cache alone. Checked independently: 322 MB and 8,500 leaked handlers after 8,000 messages → flat, 0 handlers. The complete, unedited output, the inputs, and the before/after files are in examples/memory-leak-hunter.

Known limitations

• Works from a reproduction of the workload; leaks that only appear under production traffic patterns need a matching harness.
• Native memory (C extensions, off-heap buffers) shows up as RSS growth without heap growth; it identifies this case but the fix is runtime-specific.
• Heap snapshots of very large processes can be slow and big; it prefers allocation diffs on a smaller reproduction.

FAQ

Will it just add a restart or raise the memory limit? No. It fixes the reference that keeps memory alive and mentions restarts or limits only as temporary stopgaps.

How does it tell a cache from a leak? From the growth curve: a cache rises then flattens at its size limit; a leak keeps growing with the number of requests. In the demo it correctly left a bounded cache alone.

Which languages does it support? Python, Node.js, Java and Go have bundled tool guidance; C, C++ and Rust are covered at the tool-pointer level.

Compatibility

Works with any agent that supports the SKILL.md standard. The demo was run with Claude Code (claude-sonnet-5-5) on Python. The bundled tool table covers Python, Node.js, Java and Go. Needs shell access to run the growth test; without it, it gives you the harness and commands.

Open source

Part of claude-rigor-skills: 33 MIT-licensed skills that make AI show its work. Documentation: https://github.com/hemapriyan-rk/claude-rigor-skills/tree/main/skills/memory-leak-hunter