memlab

memlab is an open-source framework from Meta for detecting JavaScript memory leaks and analyzing heap snapshots across browsers, Node.js, Electron.js, and Hermes. You describe a browser interaction as a Puppeteer-driven scenario (a URL, an action, and a step back), and memlab automatically takes heap snapshots before and after, diffs them, filters out known-safe growth, and clusters the results into representative retainer traces that show exactly why an object is still reachable from the GC root.

Beyond leak detection, the memlab CLI bundles a heap-analysis toolbox (memlab analyze), an interactive heap viewer, Node.js memory-assertion APIs for unit tests, and MemLens for visual, in-browser memory debugging. A companion @memlab/mcp-server package exposes the same heap-analysis APIs as MCP tools so AI coding assistants like Claude Code and Cursor can investigate leaks conversationally.

What You Get

• A memlab run --scenario <file> CLI workflow that drives Puppeteer, takes heap snapshots, and reports clustered memory leaks with retainer traces
• An object-oriented heap-traversal API for writing custom leak detectors and programmatically analyzing .heapsnapshot files from Chromium, Node.js, Electron.js, or Hermes
• A built-in memlab analyze toolbox of heap-analysis plugins (e.g. unbound-object) for finding optimization opportunities beyond strict leaks
• MemLens, a visual in-browser memory-debugging and leak-visualization tool
• Node.js memory-assertion APIs (takeNodeMinimalHeap, hasObjectWithClassName) for writing heap-state checks directly in unit tests
• An MCP server (@memlab/mcp-server) exposing heap-analysis tools to AI coding assistants for conversational leak investigation

Common Use Cases

• Running automated E2E memory-leak regression tests against a web app’s critical user flows
• Debugging a specific reported leak by loading a .heapsnapshot and interactively tracing retainer chains
• Writing Jest/unit-test memory assertions that fail CI if an object unexpectedly survives garbage collection
• Investigating memory growth in Node.js server processes or Electron desktop apps using the same heap APIs

Under The Hood

Architecture — memlab is a Yarn/Lerna-style monorepo where packages/memlab is the umbrella CLI package that depends on @memlab/core (heap graph model and shared types), @memlab/api (the public run()/heap APIs), @memlab/cli (command parsing), @memlab/e2e (Puppeteer-driven scenario execution), @memlab/heap-analysis (built-in analysis plugins), and @memlab/lens (MemLens visualization); the CLI orchestrates these into the memlab run/memlab analyze/memlab view-heap command surface.

Tech Stack — TypeScript and JavaScript in roughly equal measure, built on Puppeteer for browser automation and Chrome DevTools Protocol heap-snapshot parsing; the visualization layer uses React (react-reconciler) for MemLens, and the whole monorepo builds with tsc and is tested with Jest and Playwright.

Code Quality — the repo has a dedicated packages/e2e test package plus Jest unit tests across the core packages, and ships an AI.md guide documenting scenario-writing pitfalls and correct Puppeteer usage for both humans and AI coding assistants; commit and release velocity (500+ commits, active weekly development) suggests an actively maintained internal-plus-open-source codebase.

API Design — the primary entry point is deliberately small: a scenario object with url, action, and back functions covers the common leak-detection case, while leakFilter callbacks and the IHeapSnapshot/IHeapNode interfaces expose progressively more power for custom detectors; the CLI (memlab run, memlab analyze, memlab trace, memlab view-heap) mirrors the same mental model as the programmatic API, keeping CLI and library usage consistent.