Bragproof

← Reports

@memlab/mcp-server

Starts with no setup2.313.0npm

Installed, started with no arguments, no environment and no input, and listed its tools. Run 2026-11-16.

Needs to start: nothing
Returns a result when called with no setup: 0 of 5 tools tried
Contacts while installing and starting: nothing

160tools listed
0hosts contacted
0files written
0.5 sto start
295dependencies

What it contacted

Nothing besides the npm registry it was installed from. Watched from outside its sandbox while it was installed and started with no input. Its tools may still contact things when called.

Starting it

npx -y -p @memlab/mcp-server@2.313.0 memlab-mcp

Installing a package runs its code. Use a sandbox for anything you have not read.

Calling its tools

5 tools that take no input and look read-only were called once with nothing. 0 returned a result.

memlab_snapshot_summaryNo usable answer tool reported an error: Error: No heap snapshot loaded. Use memlab_load_snapshot first.
memlab_find_nodes_by_classNo usable answer tool reported an error: Error: Pass class_name (exact) or name_pattern (regex/substring); one of the two is required.
memlab_search_nodesNo usable answer tool reported an error: Error: No heap snapshot loaded. Use memlab_load_snapshot first.
memlab_retainer_summaryNo usable answer tool reported an error: Error: No heap snapshot loaded. Use memlab_load_snapshot first.
memlab_check_healthNo usable answer tool reported an error: Error: No heap snapshot loaded. Use memlab_load_snapshot first.

During the calls it contacted nothing it had not already contacted.

Only tools whose names read like looking something up, with no required input, are tried, five at most. Tools that need input, and anything that sounds like it changes or sends something, are not called.

What its tools tell an agent

In the tool descriptions, nothing that talks about the user, other tools or private files, or uses hidden characters.

3 tools with commands in capitals or very long text
  • Very long description in memlab_eval: 3000 characters or more
  • Gives the agent orders in memlab_finding_index: vered combos" rule stops depending on someone remembering. IMPORTANT: a verdict of NEW is only as good as the index behind it. A newly-created index is pre-seeded with
  • Gives the agent orders in memlab_duplicate_objects: till collapse together (override with `ignore_properties`). IMPORTANT — read the Verdict column before quoting any number. Numeric property VALUES are not recoverable fr

Common and usually harmless: it is how many makers stress how a tool should be used.

Found by simple pattern rules in each tool's description (up to 3,000 characters), quoted as written. Parameter descriptions are not scanned. A clean result is not a safety review.

Tools

memlab_load_snapshot file_path, alias, keep_previous, repeat_notes, quiet, suppress_suggestions, max_file_size_mb, max_nodes, max_edges, force, force_reload, light, async
Load and parse a .heapsnapshot file. This builds indexes, computes the dominator tree, and calculates retained sizes. Returns a quick diagnosis highlighting potential issues. Accepts a local absolute path, a manifold:// URL, or a bare snapshot filename (resolved against the nest_server_nodejs_heap_snapshots bucket and fetched automatically). Multiple snapshots can be kept resident — pass keep_previous:true to load several for diffing/comparison; switch between them with memlab_snapshots. Cost note: the load working set is several× the file size and the dominator pass runs uninterruptibly, so large/deep snapshots are memory- and time-heavy — run the server with a large heap (MEMLAB_MAX_OLD_SPACE_MB when started by the memlab plugin or bin/memlab-cli.js, which pass --max-old-space-size explicitly and so override NODE_OPTIONS; otherwise NODE_OPTIONS="--max-old-space-size=8192"), load one snapshot at a time (omit keep_previous) on large heaps, and prefer memlab_sequence_analysis (transient per-snapshot loads) when you only need trend/growth across a ladder. A node/edge-count ceiling (max_nodes/max_edges) refuses pathologically large loads before they wedge the server; the ceiling auto-scales from the server's configured --max-old-space-size (an 8 GB server admits the ~1.1 GB / ~14M-node / ~55M-edge Nest tier by default), and force:true self-sizes from the header counts so a one-off oversized load needs no manual max_nodes/max_edges. A light load (light:true) skips the dominator pass the ceiling exists to bound, so the auto-scaled ceiling does not apply to it — an explicitly passed max_nodes/max_edges still does.
memlab_snapshot_header file_path
Peek a .heapsnapshot's header (node/edge counts, capture time, file size) WITHOUT loading it — no dominator pass, so it can never wedge or OOM the server the way a full memlab_load_snapshot can. Reports whether the capture fits under the current auto-scaled load ceiling, this app's node/edge density, and — when it doesn't fit — the estimated largest same-app capture that WOULD fit, so you can select a loadable snapshot in one step instead of attempting an oversized load. Accepts a local absolute path, a manifold:// URL, or a bare snapshot filename (resolved against the nest_server_nodejs_heap_snapshots bucket and fetched automatically; the download is reused by a subsequent memlab_load_snapshot). Use this to triage which capture in a size band to load before committing to the expensive load.
memlab_snapshot_summary exact_retained_size, snapshot
Get an overview of the loaded heap snapshot: total nodes, edges, size, and per-node-type breakdown with count and self size. By DEFAULT retained size per type is reported as a cheap RANGE (lower bound = Σ self size, upper bound = Σ retained size) computed in a single O(N) pass — the exact dominator-deduped retained size needs a per-type dominator walk that can stall/OOM the server on very large heaps. Pass `exact_retained_size:true` ONLY when the user explicitly asks for the exact figure. Includes anomaly detection for high-count classes. Follow up with memlab_class_histogram for a per-class breakdown, or memlab_duplicated_strings to find string duplication.
memlab_largest_objects limit, offset, node_type, exclude_types, collapse_subtrees, snapshot
Find the top N objects by retained size in the loaded heap snapshot. Filters out internal/meta objects. Use node_type to filter to a specific type (e.g., "object", "closure") or exclude_types to remove noisy types (e.g., "string"). Shows a content preview for each node. By default it collapses multiple views of the SAME dominator subtree (e.g. Client → Request → … → Map all at one retained size on a single in-flight request) into one representative row so the list is not dominated by ~20 duplicate rows; pass collapse_subtrees:false to see every node.
memlab_get_node node_id, snapshot
Look up a heap node by its numeric ID. Returns full details including size, type, detachedness (attached / detached / unknown), distance from the root in hops, dominator, location, and string value if applicable.
155 more tools
memlab_find_nodes_by_class class_name, name_pattern, order, node_type, output_mode, limit, offset, snapshot
Find heap nodes by constructor/class name, exactly (class_name) or by case-insensitive regex/substring (name_pattern). Matches ANY node type by default (object, closure, array, string, native, …) — pass node_type to narrow. Ordering is controlled by order: the biggest by retained size (default), or the newest by node id. If the exact name matches nothing, reports near-miss names and the types they exist under instead of a bare "not found". Follow up with memlab_retainer_trace on a result node to see why it is retained, memlab_get_references to inspect its properties, or memlab_retainer_summary to find common retainer patterns across all instances.
memlab_get_references node_id, limit, offset, edge_filter, sort_by, exclude_primitives, compact, snapshot
Get outgoing edges (references) from a heap node, sorted by target retained size (or `sort_by` self size or name). Shows what objects this node points to — its properties, elements, and closure captures. Supports edge_filter (match by edge name), exclude_primitives (drop string/number targets) and offset (pagination) so a node with thousands of references can be explored beyond the first page. Complements memlab_get_referrers (incoming edges). Use memlab_object_shape for a quick property overview, or memlab_closure_inspection for closure-specific analysis.
memlab_get_referrers node_id, limit, offset, edge_filter, sort_by, compact, snapshot
Get incoming edges (referrers) to a heap node, sorted by source retained size (or `sort_by` self size or name). Shows what objects hold references to this node. Supports edge_filter (match by edge name) and offset (pagination) so a widely-referenced singleton can be explored beyond the first page — e.g. "which referrers are NOT the dev-only Debug alias?". Complements memlab_get_references (outgoing edges). Use memlab_retainer_trace to see the full GC root path.
memlab_retainer_trace node_id, mode, max_depth, max_nodes, max_siblings, show_sizes, expand, exclude_dev, snapshot
Get the shortest path from a GC root to a specific heap node. This shows why the object is retained in memory by walking the pathEdge chain. Use memlab_retainer_summary to trace multiple instances of a class and group by common retainer patterns. Use memlab_get_referrers / memlab_get_references to explore incoming/outgoing edges from a node. When the shortest path crosses an edge only a DEV build has (React `_owner`/`_debug*`, Fast Refresh, a devtools module or console handle), it shows the shortest PRODUCTION path instead (`exclude_dev`, default true) and names the dev edge, or says that no production path exists.
memlab_detached_dom output_mode, group_by, offset, limit, classify_dev_only, run_dir, paths, segment, only_with_retainer_path
Find detached DOM elements still retained in memory. These are common sources of memory leaks — DOM nodes removed from the document but kept alive by JavaScript references. Supports count-only and ids-only modes for large result sets. Use group_by to aggregate by dominator (accountable owner), element tag, retainer pattern, or data-testid. Prefer group_by: "dominator" when you intend to act on the result: it groups by the nearest non-detached DOMINATOR, so releasing that one object provably frees the whole group. The other groupings key on a shortest retainer path, which need not dominate the nodes — they report an "Owners" column (distinct accountable dominators) so a group split across many owners is not mistaken for a single fix. Reports a pinned-vs-GC-eligible split: detached nodes with a retainer path to a GC root are actual leaks, while nodes with no retainer path found are typically GC-eligible (transient / weak-only) and should be excluded from leak totals — set only_with_retainer_path to list/aggregate just the pinned ones. Pass `run_dir` (or `paths`) for a LADDER: the detached population per rung with a per-cycle rate and the per-element breakdown of what grew. A single census is a working-set number; the rate is what makes it a leak. ⚠ Full-heap scan — slow on very large heaps (millions of nodes); use count-only / ids-only modes and group_by to bound output.
memlab_duplicated_strings limit, offset, min_count, concatenated, include_node_ids, snapshot
Find duplicated string instances in the heap. Shows strings that appear multiple times, ranked by total retained size — a common source of memory waste. Use after memlab_class_histogram shows high string counts. ⚠ Full-heap scan — slow and memory-heavy on very large heaps (millions of nodes); raise min_count to bound the work.
memlab_stale_collections limit, min_stale_count, min_stale_retained_size, detect_modes, ownership_edges, timeout_ms, max_children_per_collection, snapshot
Find Map, Set, and Array collections holding stale references. Detects: (1) detached DOM / unmounted Fiber nodes, (2) entries with a status/state property stuck at terminal values (PENDING, FAILED, TIMED_OUT, etc.), and (3) orphaned entries with no referrers outside the collection. Use detect_modes to control which heuristics are applied.
memlab_global_variables limit, timeout_ms, snapshot
Find non-built-in global variables on the Window object (browser) or global object (Node.js), sorted by retained size. These are application-specific globals that may indicate memory issues. ⚠ Full-heap scan — slow on very large heaps (millions of nodes).
memlab_search_nodes name_pattern, type, min_retained_size, min_self_size, is_detached, output_mode, offset, limit, timeout_ms, snapshot
General-purpose search for heap nodes by combining filters: name pattern (regex), node type, minimum retained/self size, and detachment status. Results sorted by retained size. Supports count-only and ids-only modes for large result sets. ⚠ Full-heap scan — slow on very large heaps (millions of nodes); narrow with node type / min size filters and use count-only or ids-only modes.
memlab_query_objects handle, class_name, node_type, property_name, is_detached, native_context, retained_by, self_size, retained_size, sort_by, offset, page_size, max_name_length, snapshot
Query heap objects by any combination of filters in ONE call, instead of chaining class search, node search and property inspection: class or node name (regex), node type, an outgoing property or edge name (regex), detached or not, the owning realm (`native_context`), what retains it exclusively (`retained_by`: closure contexts, detached DOM, the console, event handlers), and self / retained size ranges like "1MB-" or "10KB-1MB". Results are sorted (retained size by default, ties by id) and paged with `offset` / `page_size`; the last few queries are cached per snapshot, so paging does not rescan. Each row is a node id in the queried snapshot, ready for `memlab_get_node`, `memlab_retainer_trace` or `memlab_closure_inspection`. Examples: the 50 largest closures with a `callback` property (`node_type: "closure", property_name: "^callback$"`); every detached object over 1 MB (`is_detached: true, retained_size: "1MB-"`).
memlab_native_contexts handle, breakdown, limit, snapshot
Split ONE snapshot by JavaScript realm: the page, each iframe, extension isolated worlds, detached windows, Node `vm` contexts. Lists every NativeContext with the bytes it owns alone, plus the bytes SHARED by several realms and the bytes no realm reaches (engine internals). Ownership starts from each object's map (object → map → meta-map → NativeContext) and spreads along strong edges. Pass `breakdown` (a NativeContext id, "shared" or "unattributed") for the largest classes in that bucket. To filter any object query by realm, use `native_context` on `memlab_query_objects`. To compare SEPARATE page and worker snapshots instead, use `memlab_realm_summary`.
memlab_retained_by handle, kind, top_classes, snapshot
How much of the heap is retained ONLY through each kind of retainer: closure contexts, detached DOM nodes, the DevTools console, and event handler functions. An object counts when the roots reach it, but no longer do once the walk refuses to step into that kind of retainer, so removing every such retainer would free it. Reports objects, self bytes and share of the heap per kind, with the largest classes. Kinds can overlap (an object can depend on a context AND a handler), so rows are not added up. To list or histogram the objects of one kind, pass `retained_by` to `memlab_query_objects` or `memlab_class_histogram`.
memlab_allocation_sites class_name, node_type, node_id, sort_by, limit, offset, depth, snapshot
WHO ALLOCATED these objects: group live objects by the JavaScript stack that allocated them, from a capture recorded with allocation tracking (a .heaptimeline, or a snapshot taken while tracking was on). Filter by `class_name` (regex) and `node_type`, or pass one `node_id` for its stack. Sites are ranked by bytes or count and paged; each shows the allocating function, script, line and column, and the frames above it. Pair it with an id-matched `memlab_diff_snapshots` drill-down to see where the objects that survived were allocated. Captures without tracking say so.
memlab_get_property node_id, property_name, edge_type, snapshot
Look up a specific property (outgoing edge) of a heap node by name and return the target node with full details. Useful for traversing the object graph step by step (e.g., get the __proto__, stateNode, or memoizedState of a node).
memlab_object_shape node_id, node_ids, from_result, class_name, sample_count, include_internal, non_null_only, limit, snapshot
Show the shape/structure of one or more heap objects: all named properties with target node types and sizes. Filters out internal/hidden edges to show only user-visible properties. Supports batch inspection via node_ids to compare multiple objects side-by-side in a single call. Accepts a class_name instead of ids: every other tool reports classes by NAME (memlab_class_histogram, memlab_sequence_analysis, memlab_leak_report), so requiring an id here forced a memlab_find_nodes_by_class round-trip — a second whole-heap scan, on a server where loading the snapshot took minutes — just to answer "what shape is this class?".
memlab_class_histogram limit, offset, min_count, min_retained_size, min_self_size, name_pattern, node_type, native_context, retained_by, include_retained_size, max_retained_classes, max_dominator_walk, suppress_suggestions, snapshot
Show per-constructor/class instance count and total self size. Useful for identifying which types of objects dominate memory. By DEFAULT (`include_retained_size:false`) it returns a counts + self-size histogram in a single O(N) pass with NO dominator walk — fast and safe on snapshots with millions of nodes; rows are sorted by self size. ⚠ Only pass `include_retained_size:true` when the user EXPLICITLY asks for dominator-aware retained sizes: that path walks the dominator tree and is the slow/memory-heavy part on large heaps. To stay tractable it then computes EXACT retained only for the heaviest `max_retained_classes` non-leaf classes (flat string/number classes are exact for free) and marks the rest with an upper-bound "~"; even so, on very large heaps with deep PromiseReaction/Context chains it can be slow and may hit the analysis time budget (returning "~" estimates) or, on older unbounded builds, time out the request entirely. Use min_count/min_self_size/min_retained_size to filter; `native_context` limits it to one realm and `retained_by` to objects retained only through closure contexts, detached DOM, the console or event handlers. Follow up with memlab_find_nodes_by_class to inspect specific classes, or memlab_retainer_trace on a sample node to see why objects are retained.
memlab_dominator_subtree node_id, limit, include_internal, snapshot
Show the direct children in the dominator tree for a given node — i.e., objects whose retained size is exclusively attributed to this node. These are the objects that would be freed if this node were garbage collected. Useful for understanding what composes a large retained size.
memlab_closure_inspection node_id, max_scope_depth, min_retained_size, max_variables, snapshot
Inspect a closure (function) OR a suspended generator/async frame to show its captured/live variables. For closures, walks the FULL scope chain via "previous" edges on V8 Context objects, reporting variables at each scope depth. For generators (suspended async functions), additionally decodes the `parameters_and_registers` array and resolves register slots to source variable names where the value is also context-allocated. Shows the function name, source location, and all bound variables with types and sizes. Critical for diagnosing closure- and suspended-async-based memory leaks where a frame unintentionally retains large objects. To find, heap-wide, the captured variables no live code can read any more, use `memlab_dead_context_variables`.
memlab_dead_context_variables handle, script, min_retained_size, offset, page_size, contexts_per_scope, fields_per_context, snapshot
Find captured variables that no live code can read, heap-wide. Closures created in one scope share one Context, so a variable read only by a callback that is gone stays alive as long as ANY sibling closure does. Using the source scope tree V8 embeds in the snapshot (V8 15.6+ / Chrome 156+), this checks every Context slot against the closures and suspended async frames still on the heap and reports the slots nothing live can read, grouped by scope and ranked by the bytes they retain. Each row gives the script, the scope name and source offsets, the Context id and the dead value ids, ready for `memlab_retainer_trace` or `memlab_closure_inspection`. Snapshots from older V8 have no scope tree; the tool then says so and lists how many contexts could not be checked. Scripts that own contexts but have no scope tree are listed at the end.
memlab_find_by_property property_name, property_value, property_value_node_id, edge_type, output_mode, limit, timeout_ms, snapshot
Find all objects that have a specific property name (outgoing edge). Useful for identifying objects with React internals (__reactFiber$, __reactProps$), custom data structures, or framework-specific markers. Use property_value_node_id for reverse referrer lookup — finding all objects whose named property points to a specific node (e.g., "which objects have their callback property pointing to closure @700467?"). Results sorted by retained size.
memlab_aggregate name_pattern, type, min_retained_size, min_self_size, is_detached, group_by, metrics, limit, snapshot
Aggregate heap nodes by type, name, or name prefix. Returns grouped statistics (count, total self size, aggregate retained size) sorted by retained size. Retained size uses dominator-aware aggregation (no double-counting).
memlab_reports report, limit, snapshot
Run curated memory analysis reports — like Chrome DevTools Memory panel views. Use "list" to see available reports, pick one by name, or use "full_analysis" to run all reports for a comprehensive triage.
memlab_retainer_summary class_name, name_prefix, shape, from_result, node_ids, sample_strategy, sample, max_depth, compact, framework_filter, include_properties, exclude_dev, snapshot
Trace retainer paths for multiple instances of a class (or a specific set of node IDs) and group by common patterns. Instead of tracing one node at a time, this samples N instances and shows how many share each retainer path pattern. Essential for confirming whether leaked objects share a single root cause. Use node_ids to cluster retainer patterns for specific nodes (e.g., example_node_ids from duplicated_strings). Set compact=true for abbreviated paths that use 50-70% fewer tokens.
memlab_diff_snapshots before_path, after_path, before, after, baseline, target, limit, min_count_delta, min_size_delta, include_value_classes, hide_zero_size_delta, identity, class_name, detail, offset, page_size, set_active
Compare two heap snapshots: classes that grew, shrunk, appeared or disappeared between "before" and "after". When both captures come from the SAME isolate (one tab session, no reload; detected automatically), objects are also matched by V8 object id, which V8 keeps stable for an object across every snapshot of one isolate: per class, how many objects are NEW (allocated after "before" and still alive), how many were DELETED, and their allocated and freed bytes — so churn shows as N new + N deleted rather than as Δ0. Pass `class_name` with `detail` to list the new or deleted objects themselves, largest first and paged, as ids ready for memlab_retainer_trace. Each side accepts either a resident snapshot handle (from memlab_snapshots) or a file path — resident handles are reused in place, so diffing a ladder you already loaded never re-parses a file. By default the "after" snapshot becomes the active snapshot (set set_active:false to leave your active snapshot unchanged). For an ordered sequence of 3+ snapshots, use memlab_sequence_analysis instead.
memlab_sliced_strings limit, min_parent_size, snapshot
Find V8 sliced and concatenated string nodes and identify the parent strings they reference. Sliced strings share backing storage with a parent string — if the parent is a large string (e.g., a multi-MB CSV response), all slices keep the entire parent alive. This is a common cause of hidden memory leaks where small substring references retain massive parent strings. Shows parent strings ranked by parent string size.
memlab_string_patterns prefix_length, min_count, min_total_size, limit, snapshot
Group strings by common prefix and show aggregate counts and sizes. Instead of seeing 20 individual histogram entries for CSV strings that all start with the same header, see them grouped: "Strings matching prefix: 20 instances, 250 MB total." Useful for identifying families of related strings like API responses, repeated log messages, or duplicated data.
memlab_check_health snapshot
Run all heuristic health checks in one call and return a prioritized list of findings. This is the recommended first step after loading a snapshot — it replaces calling 4-5 individual tools to triage.
memlab_auto_investigate top_n, focus, snapshot
One-shot deep analysis: finds the top retained objects, traces each retainer chain to the GC root, identifies pinch points (small objects retaining large subtrees), and detects unbounded caches. Returns a structured report with root causes and suggested fixes. Use this as the first tool after loading a snapshot to get immediate actionable findings.
memlab_pinch_points limit, min_retained_size, min_ratio, snapshot
Find "pinch points" — small objects that retain disproportionately large subtrees in the dominator tree. These are the most impactful objects to free: a single cache, map, or closure whose removal would reclaim the most memory. Returns objects ranked by retained_size/self_size ratio, filtered to actionable user-code objects (excludes V8 internals).
memlab_cache_analysis limit, min_entries, min_retained_size, collection_types, detect_object_caches, detect_identical_entries, sample_entries, compact_samples, summary_only, snapshot
Detect unbounded caches — Map, Set, and Array objects that are large and likely missing eviction logic. The #1 cause of Node.js memory leaks. Reports entry count, retained size of the entries (dominator-deduped, so values also held elsewhere still count) and of the container, owner object, and whether entries use WeakRef. Use this after memlab_auto_investigate or memlab_check_health flags suspicious collections.
memlab_trace_dominators node_id, max_depth, min_retained_size, collapse_promises, show_siblings, snapshot
Auto-walk the dominator tree from a starting node, following the largest dominated child at each level until reaching leaf data or a depth limit. Returns the full chain with size annotations in a single call — eliminates the 10+ sequential get_references calls typically needed to trace from a top retainer to the actual data. Collapses repetitive Promise/PromiseReaction chains. Shows top children at the terminal node. Use as the primary tool after identifying a large retainer via auto_investigate or largest_objects.
memlab_shape_histogram limit, offset, min_count, min_retained_size, class_name, name_pattern, sort_by, exact_retained_size, exclusive_retained, snapshot
Group objects by their property structure (shape/hidden class). Objects with the same set of property names are grouped together, revealing distinct record types. Much more useful than class_histogram when most objects are generic "Object" — this tells you exactly what data structures exist and how much memory each shape consumes. Essential for data-heavy apps where millions of "Object" instances hide 3-5 distinct record shapes. By DEFAULT retained size per shape is reported as a cheap RANGE (lower = Σ self size, upper = Σ retained size) from a single O(N) pass; sorting/filtering by retained uses the upper bound. The exact dominator-deduped value needs a per-shape dominator walk that can stall/OOM the server on very large heaps — pass `exact_retained_size:true` ONLY when the user explicitly asks for it.
memlab_shape_census_diff run_dir, segment, paths, cycles_per_rung, class_filter, name_pattern, top, min_growth, max_props, include_settle, max_file_size_mb
Per-SHAPE growth across a LADDER: group objects by their property set at every rung and report the series, the per-cycle rate and the fit — the shape-level equivalent of `memlab_leak_report`.

Use this the moment a class-level tool blames `Object`. On a data-heavy app most of the heap IS `Object`, so "`Object` grew by 377,959, retainer `Map.table`" names nothing; the same ladder grouped by shape reads `{event,timestamp} ~0 -> 53,029`, `{data,timestamp,type} ~0 -> 31,299`, `{bottom,left,right,top} ~0 -> 12,822` — i.e. "the growth is telemetry records and DOMRects" — in one call. `memlab_shape_histogram` answers this for ONE snapshot; `memlab_census_diff` answers it across a ladder but per CLASS. This is the missing cell.

With `include_settle` (default on when the round captured a settle rung) each shape also gets its post-idle count and a drained/held verdict, so in-flight backlog is separated from retention in the same table. Pass `class_filter: "Object"` to look only at plain objects, which is usually what you want. Rungs are loaded one at a time and dropped, so a long ladder costs wall clock rather than memory.
memlab_growth_cohort class_name, shape, node_type, cohort, top, snapshot
Group the NEWEST instances of a population by who holds them — top referrer edges, top shapes, top root-path heads, and their dominator-deduped retained size.

V8 assigns heap-snapshot node ids monotonically as objects are allocated, so the highest-id members of a class ARE the ones created most recently: the tail IS the growth cohort. That is the population a ladder measured growing, and it is usually not the population a whole-class question answers about.

The point is the DISAGREEMENT. This reports the cohort next to the whole population, so "the newest instances are held by `X` while the class at large is held by `Y`" is visible in one call — the signature of a large static collection sitting beside a small accumulating one, where only the second grew. A retainer voted over the whole population names the static one every time.

Select with `class_name`, `shape` (a property set), or both. Needs a snapshot loaded, ideally the LAST rung of a ladder.
memlab_prune_run run_dir, mode, keep, keep_sidecars
Reclaim the disk a round's snapshots occupy, by COMPRESSING them (default) or deleting them.

One sweep captured 101 snapshots at 358-526 MB: ~40 GB, and nothing in the tooling managed it — a hunt on a smaller disk dies mid-sweep, after the leases that produced the rungs have been spent.

Compression is the default and is NOT a one-way door: a heap snapshot is JSON and gzips ~5-10x, and the snapshot loader resolves `<rung>.gz` transparently, so a compressed round stays fully analysable at the cost of one decompression per rung opened. Deleting IS one-way — a rung cannot be re-captured, the isolate it came from is gone — so it is opt-in and `dry_run` is the way to see what would go first.

Sidecar index files (`<rung>.memlab-index.json`) are kept by default: they are ~1% of a rung and they are what lets a pruned round still answer class- and shape-level questions instantly.
memlab_quick_diagnosis top_objects, top_classes, top_strings, exact_retained_size, snapshot
Combined diagnosis tool that returns snapshot summary, top objects by retained size, class histogram, and duplicated strings in a single call. Saves 3-4 round trips and reduces token overhead from repeated headers. Use this as the first analysis tool after memlab_load_snapshot for an immediate comprehensive overview. By DEFAULT every section runs in a single O(N) pass (the class histogram reports retained size as a lower/upper-bound range rather than the exact dominator-deduped value), so it is safe on large heaps. Pass `exact_retained_size:true` ONLY when the user explicitly wants exact per-class retained sizes — that adds a per-class dominator walk that can stall or OOM the server on snapshots with millions of nodes.
memlab_referrer_summary node_id, limit, min_count, sample_ids, snapshot
Group all incoming references (referrers) of a node by edge name and source class. Answers "how many things reference this node, and via which edge names?" — essential for understanding why an object is retained and whether a single edge name dominates. Saves multiple eval round trips when investigating event listener accumulation, cache retention, or shared object references.
memlab_event_listener_leaks min_listeners, limit, check_zombies, extra_event_properties, detect_shapes, analyze_contexts, snapshot
Detect EventEmitter-style listener accumulation — the #1 cause of memory leaks in event-driven apps. Scans for: (1) objects with _events/_listeners/_subscriptionsForType properties (Backbone/Node.js, EventSubscriptionVendor), and (2) accumulations of {callback, context}-shaped objects (custom event systems like WAWebEventEmitter, Signal, etc.). Detects arrays with >N entries (accumulation), entries where the context/ctx object has no other referrers (zombie listeners), and multiple entries with the same callback (mount/unmount leaks). Use extra_event_properties to detect app-specific event container property names (e.g., "#eventMap" for private class fields). ⚠ Full-heap scan — slow on very large heaps (millions of nodes).
memlab_find_by_shape properties, shape, exclude_properties, class_name, output_mode, follow_property, limit, snapshot
Find all objects that have a specific set of property names (multi-property intersection search). Unlike find_by_property which searches for a single property, this finds objects matching a "shape" — objects that have ALL of the specified properties. Useful for finding instances of a specific record type, data structure, or component when you know its property names but not its constructor.
memlab_module_present names, suggest, snapshot
Pre-flight: does a class/constructor appear in this heap AT ALL? Answers "is the code I am about to instrument actually running on this surface", which is a different question from "is it leaking" and much cheaper to ask. Ask it BEFORE building a round on a module. A whole leak-hunt — instrumented debug diff, gated fix, module-level A/B — was once built around a class the app under test never constructs (it belonged to a legacy player the surface had replaced), and nothing in the workflow prompted the one query that would have shown zero instances. Absent is reported as ABSENT rather than as a count of 0, with near-miss names when something similar exists, because "0 instances" and "you spelled it differently" need different next steps. Light-snapshot safe: reads names and self sizes only, no dominator pass.
memlab_weakmap_entries node_id, limit, sort_by, snapshot
Enumerate the key-value pairs of ONE WeakMap (node_id is REQUIRED — this is not a global scan). WeakMaps back DataStore, private fields, and metadata caches; since keys are weakly held, their entries reveal which objects are associated and what metadata is stored. First locate a WeakMap with memlab_find_nodes_by_class("WeakMap") (or memlab_largest_objects), then pass its node id here.
memlab_map_entries node_id, limit, sort_by, snapshot
Enumerate the entries of ONE Map or Set (node_id is REQUIRED — this is not a global scan). The companion to memlab_weakmap_entries for strongly-held collections. The KEYS are usually the whole diagnosis of an unbounded cache: a Store/singleton Map keyed by "(filter,timeRange,interval)" or a query hash tells you the cache DIMENSION that is driving growth — which is exactly what you cannot see from a class histogram or retainer trace alone. Shows each key (string keys inlined verbatim), the value class, and value retained size. First locate a Map/Set with memlab_find_nodes_by_class("Map") / ("Set") (or memlab_largest_objects), then pass its node id here.
memlab_get_value node_id, property_name, snapshot
Decode the actual numeric value of a V8 SMI (Small Integer) or heap number node. V8 stores numbers as either SMI nodes (value encoded as id >> 1, self_size 0) or heap number nodes (IEEE 754 doubles). This tool decodes them and shows which objects reference the number and via which property name, providing the context needed to understand what the number represents. Essential when inspecting numeric properties like counters, capacities, or sizes that appear as opaque "smi number" or "heap number" nodes.
memlab_get_string node_id, max_length, show_structure, snapshot
Resolve any V8 string node to its full text value. Handles all V8 string encodings: flat strings, concatenated strings (ConsString with first/second tree), sliced strings (substring of a parent), and cons strings. Returns the resolved text value and optionally shows the internal string tree structure. Essential when investigating event names, log messages, or error strings that V8 stores as concatenated string trees rather than flat strings.
memlab_search_strings pattern, limit, min_length, max_length, show_referrers, snapshot
Search the content (stringValue) of all string nodes in the heap snapshot. Unlike memlab_search_nodes which searches by node name/class, this searches the actual text content of strings. Essential for finding string constants (error messages, event names, config keys, URLs) and tracing them back to their origin. Scope, because the two are easy to confuse: this sees ONLY the values of heap string nodes. Class and constructor names (what memlab_class_histogram and memlab_search_nodes report) live in the snapshot name table and are NOT string nodes, so a class name will not be found here no matter how many instances exist — the result says so and points at the right tool when the pattern matches node names. Sliced strings are also skipped, since they share a parent string's storage. Supports exact substring match and regex patterns. ⚠ Full-heap scan over every string's content — slow on very large heaps (millions of nodes); use a specific pattern and a small limit.
memlab_eval mode, code, timeout_ms, max_result_bytes, save_as, dry_run, sample, prelude, section, restrict_to_ids, async, max_nodes, snapshot
Execute arbitrary JavaScript code against the loaded heap snapshot. The code runs in a sandboxed VM with access to `snapshot` (IHeapSnapshot), `utils` (@memlab/core utils), and `helpers` (plugin utility functions). Assign your result to the `result` variable. No require/process/fs/network access. Read-only heap analysis only. A whole-heap eval that would outlast the client tool timeout: pass `async: true` and poll memlab_job_status (memlab_start_job runs any other tool the same way).

**IHeapNode API:** Each node has: `.id`, `.name`, `.type`, `.self_size`, `.retained_size` (alias: `.retainedSize`), `.edge_count`, `.is_detached`, `.referrer_count` (alias: `.numOfReferrers`), `.isString`, `.hasPathEdge`, `.pathEdge`, `.dominatorNode`, `.location` (script_id/line/column).
**Traversal:** Use `node.references` (outgoing edges, iterable with for-of) and `node.referrers` (incoming edges, iterable with for-of). Each edge has: `.name_or_index`, `.type` (property/element/context/internal/hidden/shortcut), `.toNode`, `.fromNode`.
**Iterating all nodes:** `snapshot.nodes.forEach(node => { ... })` — NOT for-of. It stops early ONLY on `return false`; a bare `return` is "skip this node" and keeps walking all 3-7M of them while reading like an early exit.
**Helper cheat-sheet — prefer these over hand-rolled scans.** They are indexed and memoized per snapshot, so a second call is index-speed rather than another full pass: `helpers.byClass(name)` / `helpers.byTypename(name)` / `helpers.withProp(name)` return id arrays; `helpers.hasShape(id, ["a","b"], {exact})` is the CORRECT shape test and `helpers.shapeKeys(id)` / `helpers.ownProps(id)` its building blocks; `helpers.rootPath(id)` is the GC-root path without hand-writing the `pathEdge` loop; `helpers.mapEntries(id)` / `helpers.setElements(id)` enumerate Maps/Sets correctly. **`helpers.props()` is for INSPECTION, not shape matching** — on a node with no property edges it falls back to internal/hidden edges and adds synthetic keys, so a shape test written against `Object.keys(props(id))` returns zero matches on objects that plainly have the shape. Call `mode: "describe_env"` for the full surface and its gotchas.
**Get node by ID:** `snapshot.getNodeById(id)` returns IHeapNode or null.
**String values:** `node.toStringNode()?.stringValue` for string nodes.
**Caveat — retained_size is unreliable here:** inside eval, `node.retained_size`/`.retainedSize` can read back ~0 for every node on some loads. Node counts, property/edge walks, and string values ARE trustworthy. For authoritative retained sizes call `helpers.retainedSize(id)` (number) / `helpers.retainedSizes([ids])` (a `Record<id, bytes>` object, NOT an array) — they re-resolve the node on the real snapshot — or use the dedicated tools (`memlab_largest_objects`, `memlab_class_histogram`, `memlab_pinch_points`, `memlab_object_shape`).

**Example — inspect Map entries (use the helper; do NOT hand-roll the backing-store walk — browser slots are `internal`-typed and
memlab_for_each filter_code, map_code, reduce_code, initial_value, limit, timeout_ms, snapshot
Structured map/filter/reduce over all heap nodes. Provide a filter predicate to select nodes, an optional map to transform them, and an optional reduce to aggregate results. All code strings receive `node` (for filter/map) or `acc, item` (for reduce), plus `utils` and `helpers` in scope. Returns an array of mapped results (capped at `limit`) or the reduced value.
memlab_array_group_by node_id, element_property, group_by, second_property, limit, snapshot
Iterate through array (or Map/Set) elements, extract a named property from each, and group/count by the target value. Eliminates the most common memlab_eval boilerplate — "iterate array, extract property, group by shape" — in a single tool call. Example: given a listener array where each element has a "context" property, this reports "649× ChatMsgsCollection, 1× MsgCollection, 1× Mirror". Use group_by to control grouping: "name" (constructor name), "type" (node type), or "id" (unique node IDs).
memlab_intern_opportunities limit, min_copies, min_savings, summary_only, snapshot
Identify string interning opportunities by grouping duplicated strings by the property name and parent object shape that holds them. Shows total savings per (property × shape) combination — the key metric for deciding where to add a string interning pool. Also surfaces ARRAY-ELEMENT / columnar duplication (strings held as elements of a rowsAsArray / string[][] result buffer — a common Nest mysql2/Drizzle shape) as first-class groups keyed by column index and array-owner shape, folded into the within-load headline; these are marked with a filled square and fixed by interning at the array-construction/parse site. The within-load figure is split at the canonical 128-char intern cap into cappable (<=128 chars, what the recommended fix reclaims) vs over-cap (longer strings the cap skips), so the headline matches what a compliant fix actually reclaims. Replaces the manual workflow of: duplicated_strings → retainer_summary → codebase grep. Retention-aware: flags groups whose duplicated instances are ALSO held by another structure (e.g. a raw array/matrix) as "co-retained" — interning the property there reclaims ~0, so the savings are reported separately and you must dedupe the shared source instead. The headline "within-load capturable" figure also excludes framework/infra-owned strings (HTTP headers, cookies, auth tokens, Next.js URL/cache context), measurement-harness content (the CDP/devtools bridge injected to drive the session — an injected bundle can be the single largest "opportunity" in a driven snapshot while reclaiming nothing in production), and low-ROI groups (high-cardinality + long strings, where the intern pool costs more than it saves), reporting each in its own bucket; and it flags concatenated-string (rope) buildup, which is accumulation rather than duplication and cannot be interned. ⚠ Full-heap scan (builds string-duplication groups) — slow and memory-heavy on very large heaps (millions of nodes); raise min_copies / min_savings to bound it.
memlab_object_cost_breakdown class_name, node_id, sample_size, show_property_table, snapshot
Show per-instance V8 memory cost breakdown for a class or shape. Reports: object header overhead, heap number vs SMI property costs, property backing store costs, and collection storage overhead. Compares the measured cost with the cost after moving numeric properties into typed-array columns; sizes follow the field width of the capture (4-byte compressed or 8-byte). Use when a cache or array of objects uses more memory than expected — the gap is often V8 overhead, not a code bug.
memlab_snapshots action, handle, quiet, suppress_suggestions, terse, max_name_length, table_format, repeat_notes
Manage the multi-snapshot session: list resident snapshots, switch the active one, or unload one to free memory. Also toggles session-level output controls (quiet header, suppress suggestions, terse) to trim repeated boilerplate tokens. Load several snapshots with memlab_load_snapshot({keep_previous:true}) then switch between them by handle. Node ids are only valid within the snapshot they came from. `repeat_notes` reprints the standing explanatory notes that tools print once per session.
memlab_property_distribution property, class_name, shape, top_k, min_count, snapshot
For a given object class/shape and property, report the value cardinality plus the top-K most frequent values with their counts. The key tool for diagnosing cardinality explosions (e.g., an OpenTelemetry metric attribute, a cache key, or a per-record field whose unbounded distinct values blow up memory). Complements memlab_shape_histogram (which groups by property *names*) by showing the distribution of a single property's *values*.
memlab_growth_signals limit, min_entries, min_retained_size, snapshot
Heuristically flag collections that look like they grow without bound, from a SINGLE snapshot (no baseline needed). Detects Maps/Sets keyed by timestamps or sequential integers (time-series / append-only logs) and large ever-growing Arrays. Use when you have only one snapshot and want to guess what is accumulating, before confirming with a diff against a later capture.
memlab_server_status
Cheap liveness/health check: returns instantly with the server VERSION, process RSS, uptime, and the resident snapshots. The version answers "is the attached server actually my local build?" — a running server keeps old code in memory after a rebuild, and the only previous way to tell was a hand-rolled JSON-RPC initialize handshake. Use it to confirm the server is responsive (vs. stuck behind a heavy scan) and to watch RSS against the snapshot-size ceiling. Scan tools are time-budgeted (timeout_ms) so a heavy scan returns cleanly instead of wedging the server; if a call ever seems hung, this check should still answer immediately.
memlab_dev_artifacts limit, explain, min_retained_size, only_dev, show_roots, summary_only, snapshot
Classify large retainers as production-relevant vs. dev/automation-only (browser snapshots). Flags any object retained ONLY through a dev/extension global (__REACT_DEVTOOLS_GLOBAL_HOOK__, __REDUX_DEVTOOLS_EXTENSION__, window.Debug, …), through a Blink accessibility cache (AXObjectCacheImpl/AXNodeObject/AXDirtyObject) inflated by CDP-driven automation building the a11y tree, OR through the attached inspector's console — objects passed to console.log / a dev-build devConsole are held by DevTools/CDP via "(Global handles) → … / DevTools console" edges (and can pin a whole detached DOM subtree, e.g. a logged {node} ref), which are GC'd once DevTools/automation detaches. All three are measurement artifacts that should not be counted as production leaks. Reports total bytes attributable to them so "241 MB leak!" headlines that are really DevTools / a11y-cache / console retention get caught.
memlab_sequence_analysis run_dir, segment, paths, limit, min_growth_count, monotonic_only, cycles, include_artifacts, repeat_notes, max_file_size_mb
Trend analysis across an ORDERED sequence of >=2 heap snapshots (the canonical "is anything growing unboundedly?" tool). Loads each snapshot transiently (does NOT change your active snapshot), builds per-class histograms, and reports each class's value at every step plus a growth verdict: "monotonic-up" (grew every step — strongest leak signal) vs "grew-net" (grew overall but not every step — often GC/navigation noise) vs flat/shrank. Also lists classes new since the baseline. Paths may be local, manifold:// URLs, or bare filenames.
memlab_ladder_probe run_dir, segment, paths, code, metrics, cycles, cycles_per_rung, probes, visibility_probe, prelude, include_settle, auto_visibility, label, timeout_ms, max_nodes, max_file_size_mb
Run ONE numeric probe across an ORDERED ladder of snapshots and report the series, the per-cycle rate and a linear fit. This is the "what is the rate of X?" tool, where X is any population YOU can express — not one of the built-in class histograms.

`memlab_leak_report` and `memlab_sequence_analysis` answer this for CLASSES. Every other question — how many `{callback, context}` listener records are held per event, how many entries a named cache holds, how many update records match a shape, how large a specific registry has grown — has to be written as an eval, and answering it across a six-rung ladder by hand costs a load + eval + save + unload per rung and a manual diff at the end. That friction is enough that the question often just does not get asked, so the round reports a class-level verdict and the actual finding goes unmeasured.

Differs from `memlab_eval_across`, which requires every snapshot to be RESIDENT simultaneously — impossible for a ladder of large captures. This resolves PATHS, reuses any rung that happens to be resident, and otherwise loads and drops one graph at a time, restoring your active snapshot when it finishes.

Report `r2` alongside the slope: "grew at every step" is one bit and any noisy drift satisfies it, whereas a slope with r2 near 1.0 is the signature of an unbounded per-cycle leak and is what separates it from a cache filling toward a plateau.
memlab_census_diff run_dir, segment, baseline, target, kinds, top_n, max_file_size_mb
Take the detached-DOM and listener-record census at TWO rungs and diff them per class / per callback in one call. This is the mandated baseline-vs-final comparison: run the census on BOTH ends and compare the per-class distribution, not just the two totals.

Two totals that match are NOT a negative result — they are also consistent with one population being swapped for another of the same size, which is a real observed shape. The per-row diff is what makes the negative claim: "777 nodes across 66 classes, zero change on every one" is a finding; "777 at both ends" is a guess.

Replaces the ~30-line eval that otherwise gets rewritten every round (build {class -> count} on each rung, diff the maps by hand), and loads one graph at a time so it works on a ladder of 250-540 MB captures.
memlab_artifact_budget target, baseline, max_file_size_mb
ONE number for "how much of this heap is not the application", broken down by source — and, with a baseline, how much of the growth was the app rather than the tooling. Composes what otherwise takes three separate tools and a manual reconciliation: `memlab_app_heap` (bundle/code/app split), `memlab_dev_artifacts` (React DEV, Fast Refresh, CDP console, a11y) and the JIT-warmup family that `dev_artifacts` explicitly does NOT count.

Run it before quoting any growth number. Composing only two of the three produces a confident wrong answer, not a visible gap: one measured round showed +67 MB of aggregate growth that was ~85-90% React DEV tooling with app memory flat, and across a single sweep the artifact share ranged from 2.0% to 18.5%. With `baseline` set, **app_delta is the headline** — it is the only figure in the report that a production build would also show.
memlab_leak_report run_dir, segment, paths, cycles, content, limit, min_growth_count, monotonic_only, include_artifacts, baseline_run_dir, auto_baseline, compact, include_settle, max_file_size_mb
One-call leak triage across an ORDERED ladder of >=2 heap snapshots: runs the growth-trend pass, then gathers per-class EVIDENCE from the final snapshot and returns a single table — class, per-rung counts, Δ and Δ/cycle, how much of it is dev/automation-retained, the dominant retainer, and a verdict hint. Exists because the trend pass alone cannot tell a leak from an artifact: every hunt then ran memlab_dev_artifacts and a retainer trace by hand on each grower and joined the three outputs mentally, which is the step that gets skipped right before something is reported as a production leak. Composes memlab_sequence_analysis with memlab_dev_artifacts and a retainer sample; costs one extra snapshot load (the last rung) on top of the ladder pass. When `run_dir` names a round that captured a SETTLE rung, every row also carries how much of its growth survived idle + GC, and a class that DRAINS is labelled backlog rather than a leak candidate — without that column the default table is mostly backlog (measured: one sweep's settle rungs retired 92,452 objects and 26.3 MB the ladder had called leaks). A round with no settle rung is stamped UNSETTLED. The verdict column is a HINT, not a conclusion — confirm a candidate with memlab_retainer_trace on the example node before calling it a leak. The retainer column votes over the class's NEWEST instances (highest node ids = the growth cohort), NOT over its whole population: voting over the population names whoever holds the most instances, which is a large STATIC collection whenever one exists and is not what grew. Rows where the two disagree are listed under the table. Paths may be local, manifold:// URLs, or bare filenames.
memlab_match_object node_id, target_handle, limit, min_score
Find the object in ANOTHER loaded snapshot that corresponds to a given object in the current one. Heap node ids are assigned per capture and are meaningless across snapshots, which is why every cross-snapshot question ("did THIS object survive?", "did THIS cache grow?") otherwise degrades into comparing aggregate class counts. This matches on identity evidence instead: class name and type (required), property-shape overlap, and the first non-framework retainer path. Returns ranked candidates with a score and the retained-size delta, NOT a single answer — object identity across captures is inferred, never proven, and the tool says so rather than presenting a guess as a fact. Both snapshots must be resident: load them with keep_previous:true and see memlab_snapshots for handles.
memlab_explain_delta baseline_handle, baseline, target_handle, target, limit, min_delta_bytes, include_artifacts, include_dev
Explain WHERE a heap grew between two loaded snapshots, attributed by dominator (who owns the new bytes) rather than by class (what the new bytes are). "Object grew by 99,418 instances" does not tell you what to fix; "the bytes hanging off CometStyleXSheet grew by 12 MB" does. Every node's SELF size is attributed to its immediate dominator's class and the two attributions are differenced, so the numbers partition the heap and add up — unlike a per-class sum of retained sizes, which double-counts nested objects and can exceed the heap. Known measurement-artifact owners (JIT warmup, CDP inspector, a11y caches, captured Error stacks) are flagged so an inspector-driven delta is not read as an application regression. Both snapshots must be resident: load them with keep_previous:true.
memlab_hypothesis run_dir, auto, paths, predicates, predicate, group_by_shape, limit, max_file_size_mb
Test one hypothesis against EVERY rung of a snapshot ladder in a single call: supply a JavaScript predicate over heap nodes and get its match count, total self size, and trend per rung. This is the "is my theory true across the whole ladder?" tool. Without it, confirming a specific theory — "the growth is Maps with a `_pending` field", "it is closures capturing `chatId`" — meant loading each rung separately and re-running a query by hand, at minutes per rung, which is why theories tended to be checked against one snapshot and generalized. Set group_by_shape to break matches down by property shape per rung instead of a single count, which answers "WHICH variant of this class is the one accumulating?" — the shape sweep that otherwise required a separate pass. Snapshots are loaded one at a time and released, so a long ladder is memory-safe.

Give each entry in `predicates` an `expect` (`grows` / `flat` / `absent` / `present`) to get a PASS/FAIL column instead of counts to interpret. A measured round carried ~15 candidate explanations and tested four, because a table of fifteen count-rows still has to be read against what you thought would happen, one row at a time. Stating the prediction up front also stops the counts from deciding, after the fact, what they showed.
memlab_ladder action, name, paths, app, interaction, cycles, build, positive_control, notes, captured_at
Name a snapshot ladder once and reference it as `ladder:<name>` from the trend tools (memlab_sequence_analysis, memlab_leak_report, memlab_hypothesis) instead of re-typing its paths on every call. Also records the capture PROVENANCE a .heapsnapshot cannot carry — app, interaction, cycles driven, build, and any planted positive control. That context is what decides whether a delta means anything, and it is gone within days if it lives only in the conversation. A ladder whose rungs are misordered produces a confident, wrong trend, which is the failure re-typing paths invites. Stored in ~/.memlab-mcp/ladders.json so it survives a server restart — the case that loses the paths in the first place.
memlab_finding_index action, retainer_path, kind, keys, fingerprint, growing_classes, round, status, fixed_behind, fixed_by_diffs, gate_state, gate_checked_on, verified_by_ab, retraction_reason, title, note, notes, combos, served_revision, preset_hash, run_dir, workstream, to, from, findings
Fingerprint a leak finding by its retainer path and check it against findings from previous rounds, so a hunt does not spend itself re-discovering a known or already-fixed leak. This is the highest-cost failure a leak hunt has: a measured round produced three findings that were all already known — two already fixed behind gates — which is an entire round spent re-deriving history. Class names cannot detect that (`Object` and `Array` top every heap); the retainer PATH can, so the fingerprint is a normalized path signature with node ids, array indices and per-capture scope ids stripped. Actions: "check" fingerprints a candidate and reports NEW / KNOWN / KNOWN-AND-FIXED / RETRACTED / ARTIFACT; a RETRACTED finding is one a previous round investigated and WITHDREW (a measurement error, a structural population mistaken for a rate) — re-deriving one costs the same round as re-deriving a fixed leak and is harder to notice, because the population really is present. ARTIFACT is the stronger statement and its own verdict: the population is real and reproducible but is NOT app memory (an automation bridge, a DevTools hook, a dev-only registry), so it must be excluded from any total rather than re-investigated; "record" adds it; "import" bootstraps history in bulk from a team doc or a JSON file; "list" prints the index; "cover" records which combos a round drove, so the "do not repeat covered combos" rule stops depending on someone remembering.

IMPORTANT: a verdict of NEW is only as good as the index behind it. A newly-created index is pre-seeded with the generic ARTIFACT families (JIT warmup, CDP network/perf/console retention, a11y caches, React Fast Refresh registries, captured Error stacks, the automation bridge bundle), so the first `check` can already answer KNOWN for a population that is documented and is not app memory — but it knows nothing about YOUR app. Seed that with `action: "import"` before trusting the first `check` of a workstream. Set `MEMLAB_FINDINGS_INDEX` to a checked-in path to share the index across hosts and operators instead of keeping it in a per-machine home directory.
memlab_app_heap show_breakdown, summary_only, snapshot
Report APP-ATTRIBUTABLE heap: total self size minus bundle/code memory, minus dev-build artifacts, minus measurement-harness content — the part of the heap that is actually the application. On a dev build the raw number is mostly not the app: a measured WhatsApp Web capture had bundle source text (`system / ExternalStringData`) at 56% of a 311 MB heap and code-related memory at roughly two thirds of the total. A leak-hunt threshold expressed against the raw total therefore mostly measures how much bundle has loaded, and is not comparable to production at all. Use this as the number to drive a hunt against and to quote in a report; use memlab_leak_report for whether anything is actually growing.
memlab_memory_partition top, drill, summary_only, snapshot
Answer "what is using the memory?" in ONE call: an exclusive partition of the heap where every byte lands in exactly one row. Seeds framework record families by their own property names, so it works on a minified build: React fibers / hooks / effects / update queues / elements, Backbone-style collections and listener records, interaction-tracing event records, module registry records and timing records, lazy-loader resource records, experiment config records, function-property memo caches (`fn.$$cache`), WebAssembly modules and SharedArrayBuffers, and the module registry. Each node is credited to the nearest family on its dominator chain; native DOM/Blink nodes go to DOM sub-families (style, layout, paint, fonts, images, DOM nodes); everything else is labelled by the module export or global on its SHORTEST retainer path, which still names shared caches that dominator tools credit to the root. Loaded code and bundle text are reported separately and excluded from the percentages. Pass `drill` with a family name to see which modules own that family.
memlab_capture out_dir, label, list_targets, target, url_filter, port, title_filter, call_timeout_s, snapshot_timeout_s
Take fresh heap snapshots of a LIVE page and/or its dedicated WORKERS over the Chrome DevTools Protocol, without a harness script. A page heap snapshot never contains its workers: one measured web app runs ~14 (backend, search, media, a 10-thread Wasm pool) holding tens of MB of JS heap that no page snapshot shows. Workers are reached through the page connection (flattened auto-attach), because a worker's own websocket never answers in headless Chrome; every command has its own deadline, so workers blocked in `Atomics.wait` are reported as unresponsive and skipped instead of hanging the call. Reports each target's JS heap use and the written file; load them with memlab_load_snapshot or compare them with memlab_realm_summary.
memlab_realm_summary paths
Compare the heaps of several REALMS captured at the same moment — a page plus its dedicated workers (memlab_capture writes them) — as one table: per realm, app memory, bundle text, loaded code and dev-only bytes, plus the WebAssembly modules and SharedArrayBuffers it holds. Shared memory is counted ONCE: every thread of a Wasm thread pool reports the same compiled module and the same SharedArrayBuffer (measured on one app: 10 pool workers each reported the same 11.8 MB module and 10 MB buffer), so a naive sum overstates the app by the pool size times the shared bytes. Each path is loaded transiently, one at a time.
memlab_path_tree min_bytes, max_lines, max_depth, root_id, snapshot
Show WHERE the memory sits as a tree: the shortest-retainer-path tree (each object hangs under the object on its shortest path from a GC root) with the app bytes of every subtree, expanded wherever a branch holds at least `min_bytes`, single-child chains collapsed onto one line. Shortest-path subtrees PARTITION the heap, so the sums add up and a cache whose entries are also referenced elsewhere still shows its real size — the dominator tree credits such objects to the root. Loaded code and bundle text count as 0. Pass `root_id` to expand one object instead of the GC roots.
memlab_model_census limit, min_models, project_to, snapshot
Per MODEL TYPE in Backbone-style collections (objects carrying `_models` and `_index`, found by shape so it works minified): how many records are loaded and what ONE record costs — own property count, object header, the out-of-object PROPERTY STORE V8 allocates once an object has more fields than fit in-object, arrays the model holds (listener lists, small arrays), and the dominator-deduped retained size per record — plus the bytes of each collection's `_index` dictionary. A record also costs whatever per-record caches key off it, so the table adds the values of Maps/WeakMaps KEYED by the records (getter memos, per-record indexes), net of what the records already retain, and projects the per-record total to `project_to` records — test accounts load a fraction of real data, and the projection is what sizes a data-proportional cache. `object_cost_breakdown` is keyed by class name and reads nothing on a minified build.
memlab_timers limit, snapshot
Pending timers and scheduled tasks, grouped by the function they will run and what that function CAPTURES. Finds React Scheduler task records by shape (`{callback, priorityLevel, startTime, expirationTime, sortIndex}` — what `setTimeout` lands in on apps that route timers through the scheduler), unwraps error-guard / time-slice wrappers down to the real callback, and for each group reports the task count, the module, the largest captured payload (its shape and its shortest-path owner) and how many of those payloads are ALSO held elsewhere. A timer that captures a record keeps it alive until it fires; one per record (an expiry timer per traced interaction, say) retains the whole population for the timer's delay, even after its owning map lets go. Cancelled tasks (null callback) still occupying the queue are counted separately.
memlab_framework_buffers config_path, snapshot
Size the framework buffers that recur in every hunt on the same stack, in ONE call, minification-safe. Generic probes: in-memory `logs` arrays, module timing records, a lazy-loader resource registry, the React Scheduler task queue, module registry tables and objects with more than 5,000 own properties. App-specific buffers (a telemetry queue, an error history, a trace store) come from a probe file: JSON `{"probes": [{"buffer", "note", and one of "module" | "global" | "property"}]}`, read from `config_path` or the MEMLAB_FRAMEWORK_BUFFERS environment variable. Each row has its entry count, held bytes (the larger of what the container dominates and what its entries retain) and what it is for. A buffer that is absent is omitted rather than reported as zero.
memlab_realm_duplication paths, min_bytes, limit
Find what is loaded TWICE across realms: given a page snapshot and its worker snapshots (memlab_capture writes them), list every module present in more than one realm with its state bytes in each realm, and the bytes that would go away if only the largest copy remained. State bytes per module come from the shortest-retainer-path partition (each object credited to the first module record on its shortest path), so the per-realm numbers add up and survive minification. Each realm's module registry table is reported as its own row. Also counts modules whose CODE is loaded in several realms even when they hold no state. Each path is loaded transiently, one at a time.
memlab_co_holders min_entries, min_overlap, include_arrays, limit, snapshot
Find collections that hold the SAME objects or are keyed by the same keys: Maps, Sets and WeakMaps (Arrays with `include_arrays`) whose keys or values overlap, grouped into clusters, with the bytes a fix would free by cutting ONE holder versus ALL of them. The dominator tree credits a shared population to whichever holder dominates it, so per-collection sizes mislead: three maps keyed by the same 1,325 trace ids showed 3.2 MB under one module and 28 KB under the others, while together they hold 12.6 MB. String keys match by value; a holder linked only through a field of its entries (one hop) is not matched. Per cluster: each holder (shortest-path owner label), its entries, how many it shares with the rest, the bytes held by it ALONE, and the union retained size (what cutting every holder frees, if nothing else holds the objects). For overlap between two CLASSES rather than collections, use memlab_overlap_matrix.
memlab_hunt_report run_json, include_interaction_log, snapshot
Render a leak hunt's run.json into the prescribed report: configuration, the rung ladder with per-cycle rates, per-combo land rates, the off-heap series, caveats and the stop reason. The report was hand-assembled on every round, including re-deriving per-cycle rates from the heartbeat log — slow, and the step where a caveat quietly fails to reach the writeup. An under-fired or under-seeded run is still worth reporting, but only if it says so, which is why caveats and land rates are rendered first-class rather than left to memory. Takes the manifest written by the hunt runner; pair with memlab_leak_report for the analysis half and memlab_finding_index to label each finding NEW or KNOWN.
memlab_event_registry min_events, limit, run_dir, segment, group_by, timeout_ms
Detector for per-model event registries (Backbone/Marionette/observer style): objects mapping event names to arrays of {callback, context} listeners, e.g. `{"change:name": [{callback, context}], "add": [...]}`. Reports top event names by total listener count, the listeners-per-host distribution, and a structural-vs-leak verdict (one listener per host = O(hosts) structural baseline; the same callback instance bound to the same host/event more than once = a re-subscription leak). Complements memlab_event_listener_leaks by understanding the registry structure across many hosts.
memlab_chain_walk start_id, head_edge, next_edges, capture_edges, max_links, show_links, snapshot
Walk a repeated linked structure from a starting node and report how deep it goes and what it holds — for closure chains (`begin` -> `context` -> `.prev` -> ...), React update queues (`.next`), LRU lists (`.next`/`.prev`), and range/interval trees (`.l`/`.r`). Exists because these get hand-written as evals, and the hand-written version reliably miscounts: it counts how many TIMES an object is captured rather than how many DISTINCT objects are captured, so a chain that pins the same element at several links reads as that many separate leaks. Measured case: a hand-rolled walk reported 6 distinct detached elements for a 6-link chain that pinned 2. This returns distinct sets by construction and reports the occurrence count alongside only when the two differ. Cycles are detected and reported rather than walked forever. Use it after a retainer trace shows the same edge name repeating — that repetition is the signal that a chain, not a single object, is the finding.
memlab_population_vs_owners record_class, record_shape, owner_edge, owner_class, limit, snapshot
Decide whether a population is STRUCTURAL (about one record per live owner) or ACCUMULATING (owners are collecting records), by counting both and reporting the ratio. This is the question that separates "a leak" from "a standing O(number-of-owners) cost", and the two need different fixes and different claims — but nothing computed it, so it got hand-written as an eval, or skipped. Measured case: 419 listener records against 391 live models is one per owner, which turned a reported leak into a per-owner cost and changed the fix. Give it the records (by class or by property shape) and the owner class. It also names the owners holding the most records, which is where a real accumulation shows up even when the overall ratio looks fine.
memlab_dominator_chain node_id, max_depth, snapshot
Walk UPWARD through the immediate-dominator chain from a node to the GC root — the accountability chain of objects that each, if freed, would free the target. Every node on the chain exclusively dominates the target, so the nearest application-owned entry is the single owner to fix. This complements the DOWNWARD memlab_dominator_subtree / memlab_trace_dominators (what a node dominates) and the edge-based memlab_retainer_trace (a shortest reference path, which need not be a dominator). Mirrors the Chrome DevTools "Retained by / dominators" chain. Each step shows retained size and the fan-in (how much extra memory the next dominator is accountable for).
memlab_duplicate_objects class_name, typename, min_count, min_dup_ratio, limit, max_string_len, ignore_properties, snapshot
Find structurally-identical DUPLICATE objects — instances that carry the same content repeated many times, which a class histogram or shape histogram cannot see (they group by class or by property-NAME set, not by VALUE). Groups object instances by a shallow content signature (sorted property names + each scalar value; object-valued props marked generically) and reports, per signature, the instance count and the reclaimable own-bytes of the redundant copies. This surfaces "materialize a canonical/default record once", "share a frozen default", or "intern the object" wins — e.g. thousands of normalized store records that are all the same all-default spec. Scope the scan with `class_name` (constructor, e.g. "Object") and/or `typename` (the `__typename` property value, e.g. "AdCreativeFeatureSpecAttachment") — for normalized GraphQL/Relay stores `typename` is usually what you want since every record is a generic `Object`. Per-instance identity fields (id, __id, __ref, key, clientMutationId) are EXCLUDED from the signature by default so records that differ only by their data-id still collapse together (override with `ignore_properties`). IMPORTANT — read the Verdict column before quoting any number. Numeric property VALUES are not recoverable from the heap-snapshot format and object-valued properties are compared only generically, so a signature made entirely of `=n`/`=o` markers matches on SHAPE alone and proves nothing about content. Those groups are reported as `shape only`, are EXCLUDED from the reclaimable total, and their byte figure is not a win. A shape-only or partial group whose sampled members ALSO disagree on an excluded identity property (e.g. `id`) is reported as `NOT duplicates`; a `content` group is not, since collapsing records that differ only by their data-id is the point of the exclusion. This matters in practice: a reported tens-of-MB "dedup" opportunity turned out to be entirely shape-only and NOT-duplicate groups — module-registry records for different modules, and linked-list cache-node sentinels grouped with live entries.
memlab_retainer_layers node_id, max_retainers, snapshot
Counterfactual retainer analysis: answer "if I cut this edge, would the object still be retained, and by what?". Enumerates the INDEPENDENT retaining edges into a node — the incoming strong edges whose source is still reachable from a GC root when the target itself is treated as a sink — so back-edges from inside the target's own retained subtree, and weak references, are excluded. The object becomes unreachable only when ALL independent retainers are cut, so a count above 1 means any single fix leaves it retained by the others. Use this BEFORE writing a fix: memlab_retainer_trace and memlab_detached_dom --group_by retainer each report ONE path/grouping, which is why a stack of caches holding the same object looks like a single retainer and a partial fix reports a misleading win. Complements memlab_dominator_chain (accountability chain upward) and memlab_retainer_trace (one shortest path).
memlab_batch load, steps, calls, stop_on_error, timeout_ms
Run several memlab tools against ONE snapshot load, in order, and return all their outputs together. The natural unit of heap work is "load snapshot X, then run these N tools", but loading is by far the dominant cost — a 380 MB / 4M-node snapshot takes minutes to parse and build a dominator tree, and an MCP session that drops (or a client that cannot attach) makes every call pay it again. Pass `load` to load a snapshot first (same arguments as memlab_load_snapshot); omit it to run against the already-resident snapshot. Steps run sequentially and see each other's side effects, so a step may depend on an earlier one (e.g. load -> check_health -> retainer_summary). Every step's tool name AND arguments are validated before step 0 runs, so a step missing a required argument fails the batch immediately instead of after the snapshot load has been paid for. NOTE ON TIMEOUTS: the whole batch runs under a single wall-clock guardrail, not one per step — size it with `timeout_ms` (e.g. 600000 for a load plus several whole-heap scans).
memlab_population_diff baseline_handle, target_handle, population, group_by, limit, min_delta
Compare the COMPOSITION of a population between two loaded snapshots, not just its size. Equal totals are not identity: a round that strands N objects and frees N others reports the same count at both ends, and reading that as "nothing leaked" is a wrong verdict a count comparison cannot catch. This breaks the population into buckets (class, dominator-owner class, node type, or object shape), reports both ends per bucket, and states which of the three cases holds — identical composition / equal totals but different composition / net growth. Populations: "detached" (all detached DOM), "class:<ClassName>", or "shape:prop1,prop2" (objects carrying all of those properties). Buckets are keyed by CLASS, never by node id, so it works across isolates too (across isolates an id-keyed comparison reports every member as both added and removed; for captures of ONE isolate, memlab_diff_snapshots matches by id). Both snapshots must be resident: load them with keep_previous:true.
memlab_dominator_attribution node_ids, population, limit, snapshot
Given several candidate retainers, measure how much of a population each one actually DOMINATES — i.e. what would really be freed by releasing it. Answers "which of these is the amplifier?" with a number instead of a plausible story. Each population member is walked up the dominator tree to the first candidate above it, so every member is attributed to exactly one candidate and the shares cannot double-count. Members that reach the root without passing any candidate are reported as an explicit unattributed remainder — those are held through paths none of the candidates control. When one candidate sits above another, a second column reports what the outer one dominates at any depth, so an ancestor is never printed as holding nothing merely because a nested candidate took its members. A candidate that comes back with ZERO is the useful result: it refutes a hypothesis that named it. Measured example: for 4,541 detached nodes the split was activeElement 3,675 / activeElementInst 0 / lastSelection 18 / 848 unattributed, which killed the "the React fiber is the amplifier" theory outright. Sizes are dominator-deduped (a nested member is not counted again under its ancestor), so the per-candidate figures are additive.
memlab_collection_trend run_dir, segment, paths, locators, cycles, max_file_size_mb
Track named collections ACROSS a snapshot ladder: entry counts per rung, with per-cycle growth. memlab_cache_analysis, memlab_stale_collections and memlab_growth_signals all answer "how big is this collection now?" on one snapshot; the question that separates a leak from a cache that has simply filled is "did it grow at every rung, and by how much per interaction?" — which needs the ladder. Collections are named by OWNER CLASS and property path ("LoggerImpl.logs", "Store.cache.entries"), never by node id: ids are per-capture, so an id would track a different object at each rung. Every instance of the owner class is measured, so both a singleton's collection and a per-instance one are visible (totals and the largest single instance are reported separately). Measured examples from one hunt: undoStack 5 → 2,205, allFamiliesByID 3 → 16,367, LoggerImpl.logs 8,790 → 20,700 — all invisible to a single-snapshot view. Loads each rung transiently in LIGHT mode (one graph resident at a time), so it is safe on ladders too large to hold in memory at once.
memlab_collection_diff run_dir, segment, paths, cycles, min_growth, limit, monotonic_only, max_file_size_mb, rank_by
Find WHICH collections grew across a snapshot ladder, WITHOUT being told their names. Censuses every Map/Set/WeakMap/WeakSet/Array on every rung, keys each by a per-capture-STABLE `<Owner>.<property>` signature, and diffs the entry counts. This is the discovery half of memlab_collection_trend, which is excellent but requires a locator you must already know — so every accumulating collection had to be found first by hand-tracing a retainer path, and the ones nobody thought to trace were never found at all. It is also the answer to the case the single-snapshot tools structurally cannot see: memlab_cache_analysis and memlab_growth_signals rank by SIZE on one rung, so they surface big-and-static collections and miss the small-but-unbounded one. This tool applies NO size floor — growth is the filter — because the store that matters most may hold 2 entries at the baseline. The signatures it emits are valid memlab_collection_trend locators: confirm a candidate, and later verify a fix, by pasting one straight in. Loads each rung transiently in LIGHT mode (one graph resident at a time), so it is safe on ladders too large to hold in memory at once.
memlab_module_attribution limit, min_bytes, name_pattern, method, snapshot
Attribute heap bytes to the MODULE that owns them, by walking the dominator tree up to the nearest module-registry export or module SCOPE (the top-level closure context a Haste `$module_<Name>` factory created, matched through its ScopeInfo — which is where module-level caches and tables actually live). Exists because in a bundled app the retainer path of every module-scope singleton begins with the same generic prefix — `Window -> require -> .context -> modulesMap -> <Module>` — which is shared by everything in the heap and therefore attributes NOTHING. A measured round sampled 12 instances of a growing class, saw that all 12 "route through modulesMap", and filed the growth as a known module-registry leak; in fact three unrelated telemetry modules were each accumulating and the registry was just the road to all of them. The sampling tool had reported "0.0% sampled" and refused to name a cause — the generic prefix is what made the wrong answer look confirmed. This reports the module name instead, so "the heap grew" becomes "TraceStore +63 MB, MetricsWindow +23 MB". Use it whenever a retainer trace bottoms out in a module registry. On a minified build module scopes rarely match (one production capture matched 18 of 19.5k, attributing 12% of the heap), so by default a second table credits each node to the module record on its SHORTEST retainer path, which still names most app bytes.
memlab_script_census limit, min_size, snapshot
Census the retained JS SOURCE TEXT in the heap, and flag the same bundle being retained more than once. Source text is routinely 46-60% of a browser heap — the single largest line item — and no other tool reports it: memlab_duplicated_strings matches byte-exactly (two builds of one bundle differ in their header and do not match), memlab_intern_opportunities only groups property values, and memlab_largest_objects shows the strings without showing that two of them are the same package set. Scripts are grouped by the PACKAGE LIST parsed from the packager header comment, not by bytes, because a re-fetch of the same package set is a near-duplicate by construction. A group with more than one member is a superseded copy still being retained — measured once at ~74 MB, 15% of that heap. Reports total source bytes, share of heap, and reclaimable bytes if superseded copies were released.
memlab_async_census limit, min_count, snapshot
Census PENDING ASYNC WORK: React-scheduler task queues (with a live-vs-cancelled split), timer callback closures, and unsettled Promises with their owner shapes. Timer and scheduler accumulation is a common cross-app leak family with no dedicated tool — it was hand-rolled during hunts, differently each time. The scheduler split in particular finds a defect nothing else reports: React's scheduler queues are ARRAY-BASED MIN-HEAPS, so `cancelCallback` only nulls the callback and the dead record stays until it reaches the root; a long-delay task at the root blocks everything behind it. Measured: 88 -> 650 tasks over 200 interactions, 65% already cancelled. A cancelled share above 25% is the signal; a long queue on its own is not.
memlab_persistent_structures min_count, sizes, snapshot
Detect persistent / structurally-shared data structures (Immutable.js Maps, Lists and trie nodes; Immer drafts; RxJS-style Subscriptions) and report how many VERSIONS are retained, with dominator-deduped bytes. Use it whenever a leak report shows growth in short minified classes (`_t`, `St`, `Ct`, `jt`) that no retainer trace explains — that is what Immutable internals look like after minification, and no other tool here knows they are a library. A persistent structure makes keeping an old version cheap BY DESIGN, so retaining every version is easy to do and nearly invisible: one measured app held 157,306 Immutable Map versions (from 1,540 at baseline) because a selector cache kept each one as a cache value. Detection is by object SHAPE, so it survives minification; an unrecognised library is reported as not detected rather than guessed at.
memlab_gate_fingerprint compare, min_count, limit, snapshot
Decide which EXPERIMENT ARM the loaded capture is in by comparing it against a capture of the other arm, for gates `memlab_app_config` cannot read. Any experiment scoped to a server-side unit — an ad account, a page, a business — is evaluated before the response is built and never ships its name to the client, so the heap holds no flag to read: arm membership then gets asserted from which command was run rather than from evidence, which is the circular reasoning `memlab_app_config` exists to end. This reads the arm from its CONSEQUENCE instead — a class or object shape present in one capture and ABSENT from the other. Absence is the load-bearing word: two captures of the SAME arm differ in nearly every count, so a 3x difference is noise and only a missing population is evidence. Returns candidate discriminators ranked by size, plus the same-arm control that has to be run before any of them is trusted.
memlab_weakref_census limit, min_count, snapshot
Census every WeakRef in the heap, split LIVE vs EMPTY (referent already collected), and group by the shape of the object holding them. Finds the "WeakRef without compaction" leak, which no other tool here can see: a list of `{element: WeakRef, record}` entries where the WeakRef correctly lets the referent go but the RECORD and the array slot are strongly held and never pruned. The collection grows forever while looking like careful memory hygiene — memlab_cache_analysis sees a normal-sized collection, memlab_stale_collections looks for detached DOM and terminal statuses rather than emptied refs, and a code reviewer sees `WeakRef` and moves on. Measured on one surface: 476 of 481 WeakRefs empty (~99% dead weight) in a list growing ~2 entries per interaction with no bound. A holder shape more than half empty is a near-certain missing-compaction bug; the fix is a prune pass or a FinalizationRegistry.
memlab_property_names pattern, min_count, limit, sort_by, snapshot
Index the heap's VOCABULARY: every distinct property name, how many objects carry it, and the classes that do. Nothing else answers "what property names exist here?" — memlab_find_by_property and helpers.withProp need the name up front, and memlab_property_distribution reports the VALUES of a name you already have. This is the way to DISCOVER an app's accumulators instead of stumbling on them in a retainer trace: a pattern like "log$|buffer|queue|cache|pending|trace" surfaces their names in one pass, and each result is then a memlab_collection_trend locator or a helpers.withProp lookup away from being measured. Also useful in reverse — a name you expected and do NOT find is evidence the code path never ran.
memlab_retention_windows pattern, ladder_span_seconds, limit, snapshot
List the retention windows this app has — timeouts, TTLs, cleanup intervals, eviction ages — before calling any growth unbounded.

A LINEAR fit over a ladder is only evidence of an unbounded leak if the ladder spans LONGER than every window that could bound the population. It usually does not: a hunt drives for 15-30 minutes and apps routinely keep things for 30 minutes. A measured sweep published "unbounded leak, r2 = 0.9996" for three populations bounded by a 30-minute cleanup timer, then retracted it — the timer was a named config key resident in the capture the entire time.

This is a NAME scan over property keys that denote a bound (`*Timeout`, `*TTL`, `maxAge`, `cleanUp*`, `retention*`, `evict*`, `*Interval`), reported with their values WHERE THE CAPTURE RECORDS THEM. Most numeric values are not recorded in a heap snapshot at all, so an unreadable value is normal and is NOT evidence the window is absent — the key name alone tells you a window exists and what to grep for in the source, which is the half that changes the verdict.

Pair with `memlab_rate_model`: this says what windows exist, that says whether the series fits a plateau.
memlab_analysis_battery run_dir, out_dir, profile, timeout_ms, wait_for_rungs, wait_timeout_ms, digest_rows, skip, probes, async
Run a round's whole analysis in ONE call, write every tool's output to disk, and return only a digest.

The snapshot load dominates the cost of every tool, so running the standard set over one resident graph costs roughly what running three of them separately does. The reason this is a separate tool from `memlab_batch` is the OUTPUT: a batch returns every result inline, and a round's worth of tool prose is tens of thousands of tokens — which is why a twenty-round sweep is impossible to read without this. Detail goes to `<out_dir>/<tool>.txt`; the digest that comes back is the audit verdict, the app-vs-artifact split, the top growers with rate and fit, census totals and the named collections.

Give it `run_dir` and it resolves the ladder, the per-rung cycle counts and the total cycles from `run.json`, so the per-cycle axis is measured rather than assumed.

When the round directory holds an invariants.json, `memlab_judges` runs in every profile and its verdict summary is in the digest. When the round captured a settle rung, `memlab_settle_check` runs in EVERY profile and its `N HELD / M DRAINED` headline is in the digest: a ladder alone cannot tell retention from in-flight backlog, and a round without that line has a leak list that is mostly backlog.

Profiles: `standard` (ladder + leak detectors), `optimization` (adds string/shape/duplication analysis), `deep` (everything, including the slower single-snapshot passes).
memlab_battery_status battery_id, wait_ms, snapshot
Report on a battery started with `memlab_analysis_battery({async: true})`, and return its full report once it has finished. With no `battery_id`, lists the batteries this server knows about.
memlab_start_job tool, args
Start ANY memlab tool as a background job and return a job id at once; collect the result with `memlab_job_status`. Use it for ladder tools (leak_report, detached_dom / event_registry with run_dir, ladder_probe, replicate, shape_census_diff, collection_diff, …) that would otherwise run past the client tool timeout and be backgrounded with no progress. The job records a note per rung loaded. A job still running after 6 h is marked abandoned, which frees its slot but does not stop a synchronous parse already under way.
memlab_job_status job_id
Report on a job started with `memlab_start_job`, and return its full result once it has finished. With no `job_id`, lists every job this server knows about.
memlab_dev_subtracted_delta baseline, target, limit, max_file_size_mb
Per-class growth from `baseline` to `target` counting only nodes a PRODUCTION build would also hold: everything reachable solely through a dev root (console handles, devtools globals, Fast Refresh registries, the automation bridge) or a dev edge (React `_owner`/`_debug*`, dev-only modules) is removed first. On a dev build this is the honest "what did the app grow" table; the raw delta is shown beside it so the dev share of each class is visible.
memlab_stale_refs limit, max_hops, snapshot
React refs (`{current}` objects) whose `.current` is DETACHED DOM, grouped by owning component and the name the ref is held under (closure variable, property, or `useRef`), with the number of fibers rendering that component. One stale ref per instance is normal (the next render overwrites it) and bounded; more stale refs than instances, or a count that climbs across rungs, is accumulation.
memlab_source_for_node node_ids, max_hops, snapshot
Which MODULE's code a node belongs to — the step from "which object" to "which file" without a code-search round trip. A closure is resolved through its context chain to the module scope its Haste factory created (exact, via ScopeInfo); any other node is first walked up its retainer path to the nearest closure or context. Also returns the bundle script URL and, when the snapshot has one, the source location (usually absent on bundled builds, which is why the module is read structurally).
memlab_module_source module, grep, gate, compare_to, around, max_matches, max_chars, snapshot
The SERVED source of one module, read from the snapshot: its `__d("<module>", …)` span in the script sources (or a script whose URL names it). Answers "is the fix served?" (`gate`: does this module's own code contain the prop), "is this a dev-compile artifact?" (`compare_to` a prod-build snapshot of the same module), and "what does this closure do?" (`grep`). Works on minified builds, where the module name survives in the `__d` call. Needs script source in the snapshot (browser captures keep it).
memlab_scope_chains min_length, module, run_dir, rungs, paths, limit
Chains of contexts that share one ScopeInfo — each call of a function pinning the previous call's scope through a closure held in a context variable. Every link is a `system / Context`, so no class count shows a chain that lengthens per interaction. Reports, per scope: the longest chain, how many chains, the linking variables and closures, the owning module and the longest chain's retained size. A chain linked only through React Compiler temporaries (`t0`..`tN`) is flagged as the dev hook-guard artifact, which a production compile does not create (confirm with `memlab_module_source` and `compare_to` a prod capture). With `run_dir` or `paths`, the longest chain per scope at every rung.
memlab_model_duplicates identity_path, class, shape, run_dir, rungs, paths, limit
Model instances that share an identity value (e.g. a message id at `__x_id._serialized`): copies of what should be one canonical record per id, which no class count can see. Reports how many identities have copies, the extra copies and their retained size, where the extras are held (the last hops of their shortest retainer path, grouped), and the most-copied identities. With `run_dir` or `paths`, the same counts at every rung, so a copy count that grows per cycle stands out.
memlab_error_callsites top_frames, skip, message, limit, detail, snapshot
Where retained Error objects were created, read from the stack frames V8 captured on each Error (a private symbol holding each frame's closure), not from the `.stack` string, which a logger may have truncated before the app frame. Groups Errors by their top frames (after `skip`), with count, distinct messages and retained size, and lists the leading frames of the biggest groups with module and source position. Also names the JSX site of retained React `_debugStack` Errors (message `react-stack-top-frame`). An Error whose `.stack` was already read has no frames left and is counted separately.
memlab_element_census component, run_dir, rungs, paths, limit
Retained React elements and fibers by component type. Fibers are split into mounted (reached by the committed tree from a root), alternate (a mounted fiber's `alternate`) and detached; elements by what holds them: the mounted tree, an alternate, a detached fiber, an update queue, a closure variable, a dev-only `_debug*`/`_owner` field, or other. Element trees pinned outside the mounted tree are what grows when a component leaks. With `run_dir` or `paths`, elements + fibers per component at every rung, sorted by growth, with the holder split at the last rung.
memlab_probes mode, set, name, code, cap, expect, note, match, prelude, snapshot
Save named probes for an app once, and have the ladder tools run them by themselves. A probe is `memlab_eval` code assigning a number to `result`, with an optional `cap` and `expect` (`flat` / `bounded`). Probes live in named sets on disk (`~/.memlab/probes.json`, or `MEMLAB_STATE_DIR`). A set with `match` is picked up automatically by `memlab_ladder_probe`, `memlab_ab_compare` and `memlab_analysis_battery` when the round's URL filter contains it; any of them also takes `probes: <set>`. Modes: `save` (one probe, or the set's `match` / `prelude`), `list`, `show` (a set's code), `forget` (a probe, or a whole set).
memlab_cache_inventory min_bytes, limit, snapshot
Inventory of MODULE-LEVEL collections (Map / Set / WeakMap / Array) — held directly by a module's scope, OR as a property of one of the module's exported functions or classes (a memoizer's `fn.$$cache`, a class static) — ranked by what their entries hold: owning module, holder, entry count, entries-retained (dominator-deduped, so values also held elsewhere still count), what the entries are keyed by and hold, and whether the module already has a clear/reset/purge/evict function — the candidates an app could drop under memory pressure, in one call. Function-property caches are found through module records, so they are listed on a minified build too; a cache shared by many functions is one row.
memlab_positive_controls run_dir, segment
Measure the round's POSITIVE CONTROLS (run.json `positive_controls`, written by the leak-hunt runner from the app preset): known accumulators that should grow with interaction. PASS means the measurement can see growth, so a flat result elsewhere is a clean surface; FAIL means a probe or the drive is blind, and every flat result in the round is suspect. An idle round (a combo, or the round directory, named "idle") reports n/a, and so does a control whose `requires_step` steps (names from run.json `steps`, `*` wildcard) all landed 0 times: that combo never exercises it.
memlab_judges run_dir, invariants, invariants_file, prelude, segment, timeout_ms, max_nodes, max_file_size_mb
Judge a leak-hunt round against its stated INVARIANTS — plain-words claims about what must hold once the app is at rest — instead of reading "what grew". Each invariant is a probe (memlab_eval code returning one number), an optional visibility probe on the same access path, and an expectation: `no-growth`, `returns-to-baseline`, `bounded` or `zero-at-rest`. Every probe runs on every driven rung and on the settle rung in ONE pass (each rung loads once). Verdicts: PASS; LEAK (broke, and the settle rung did not give it back); BACKLOG (broke while driving, drained at rest); UNSETTLED (no settle rung to tell the two apart); UNVERIFIED (0 everywhere and nothing showed the probe can see the population); ERROR. A PASS from a judge that has never been seen red is unproven.
memlab_switch_matrix arms, protects, invariants, invariants_file, prelude, timeout_ms, max_nodes, max_file_size_mb, snapshot
Prove the judges can go red: run every invariant judge (as `memlab_judges`) on several ARMS — rounds, or the two phases of one `--ab` round — where named rules (fixes, usually behind a gate) are switched off, and check that the judge each rule guards goes red with its rule off and stays green with it on. A judge that stays green with its rule off is BLIND, and every PASS it has printed is void. A rule never switched off is NOT SWITCHED, and a judge guarding no rule is UNPROTECTED; neither has been proven. Which judge a rule guards comes from each invariant's `rule` field, or from `protects`.
memlab_calibrate_judges rounds, invariants, invariants_file, run_dir, timeout_ms, max_nodes
Calibrate invariant judges against rounds KNOWN to carry the leaks they guard: each calibration round lists the judges that must go red on it, and a judge that stays green there is BLIND. Results go to a ledger keyed by what each judge measures (editing a probe invalidates its evidence; renaming it does not), and `memlab_judges` then shows, next to every verdict, whether that judge has been seen red. Rounds come from the invariants file's `calibration` section ([{run_dir, red: [judge names], note}]) or from `rounds`.
memlab_field_release_impact property, owner_class, sample_referrers, snapshot
If a fix nulls this property, how many bytes actually come back — and is the property the ONLY reference?

The question every memory fix asks, in the form fixes actually take ("release `TracedInteraction.vcMutationLog` after logging"). `memlab_island_doors` answers it for a detached island and `memlab_what_if` for a set of node ids; neither answers it for a property, so it gets hand-rolled in three evals — collect the targets and aggregate retained size, histogram the referrer counts, then dump referrer edge names to find out whether a second referrer is a real holder or the owner's own `(object properties)` backing store.

Reports: dominator-deduped retained bytes of the targets (what a release frees), the referrer-count distribution, the distinct independent holders with self-edges filtered out, and a verdict — **SINGLE DOOR** (releasing frees the bytes) or **CO-RETAINED** (releasing frees ~0, and a fix that only removes this one reclaims nothing).

Getting this wrong has a signature: the re-measurement reads as "the fix does not work" rather than "the fix is incomplete". One hunt spent four A/B capture cycles that way.
memlab_compare_rounds run_dirs, metric, min_rounds, snapshot
Compare N rounds of a sweep and surface the patterns no single round shows.

Two of them are worth the call on their own. **A per-cycle rate that lands on a whole number names a MECHANISM** — a population accumulating exactly 1 or 2 per interaction is a different and much stronger finding than "it grew", and it is what turns a trend into a fix. **A population that grows while `app_delta` is NEGATIVE is invisible** to the aggregate ladder people actually look at; a measured sweep had eight such rounds, with chains reaching 9,818 records while the heap shrank.

That sweep found both by pasting twenty digests into a table by hand, because nothing compared rounds. This reads the per-round files `memlab_analysis_battery` already wrote and builds the matrix.

Loads NO snapshots — comparing twenty rounds must not mean re-reading eighty captures. It therefore requires each round to have been analysed first; a round with no `analysis/` directory is reported as such rather than silently omitted.
memlab_verify_fix metric_kind, locator, before_paths, after_paths, cycles, expected_reduction, chain_edge, max_file_size_mb, snapshot
Decide whether a fix actually worked, by comparing the per-cycle growth RATE of one metric between a before ladder and an after ladder. hunt_runner --ab drives both arms but nothing analyses them, which is why fix write-ups stall at "A/B pending". NO RUNTIME GATE IS REQUIRED: the two arms are two sets of snapshot files passed as `before_paths` and `after_paths`, so a fix that cannot be put behind a flag — a build-only change, a local patch, a reverted commit — is verified exactly the same way. One session concluded this tool was unusable for an ungated fix and skipped A/B entirely; it is not. Metrics: "collection_length" (entries under "<OwnerClass>.<property>"), "class_count" (instances of a class), "pending_chain" (total length of the linked lists hanging off "<OwnerClass>.<property>", following `next` — the React update-queue shape), "shape_count" and "shape_self_bytes" (objects carrying ALL of a comma-separated property set — use these when the leaking population is anonymous object literals, whose class name is the useless "Object"; this is the common case for record types and the reason a session with a real A/B still had to hand-roll the comparison), "retained_size" (retained size of the LARGEST instance of a class — the figure the leak-hunt methodology asks you to quote for a fix, rather than aggregate heap). Note "retained_size" forces a FULL parse of every rung on both arms because retained sizes need the dominator pass; the other metrics load LIGHT. Compares RATES, not levels: a build difference, a warmer cache or a longer session all shift the absolute level, and only the slope per interaction says whether the thing still accumulates. Each arm therefore needs at least 2 rungs — a single snapshot per arm is refused rather than compared, because that comparison is confounded. Returns both series, both rates, the reduction, and a PASS/FAIL against expected_reduction. Loads rungs transiently in LIGHT mode, one graph at a time.
memlab_tools question, tool, enable, schema
Index of every memlab tool, grouped by the QUESTION it answers ("what is this heap made of", "is anything growing", "why is X retained", "is it real or an artifact", …). Call this first when you are not sure which tool fits, or when you suspect the server has something better than the one you were about to use — it costs one call and lists tools whose schemas have not been fetched yet, which is otherwise impossible to discover under deferred tool loading. Pass `question` to filter to matching groups, or `tool` to find which group a tool belongs to.
memlab_external_strings limit, min_bytes, modules_per_blob, sample_chars, snapshot
Attribute `system / ExternalStringData` — the LARGEST class in a typical web-app heap, and the one a retainer trace cannot explain. On a measured Ads Manager capture it was 183.7 MB across 5,797 objects (38% of heap), of which ~284 carried essentially all of it: larger than the CSSOM, larger than the Relay store, larger than every leak in that app combined. `memlab_retainer_trace` returns nothing useful for these because the character data hangs off Blink rather than off a JS object, so the usual "who holds this?" question has no answer and the biggest thing in the heap stays unattributed.

This reads the string CONTENT instead of the reference graph and names the resource: for Meta web bundles it reports the first Haste module names in each chunk (`__d("ModuleName",…)`), so "load less JS" becomes a ranked list of modules rather than a slogan. Nothing here is a leak — this is standing cost, and it is the structural baseline every leak number should be quoted against.
memlab_census paths, run_dir, metrics, class_names, cycles
Count several named POPULATIONS across every rung of a ladder in ONE pass per snapshot, and report each one's per-cycle rate.

This is the measurement a leak hunt actually repeats: "how many detached nodes / listener records / LRU cache nodes / fibers are there, at each rung, and is that number going up?" Doing it by hand means writing the same multi-flag `forEach` once per round and re-typing it for every metric — and a second pass over a multi-million-node graph aborts, because the eval node budget is cumulative. Every built-in metric here separated a real leak from a non-leak at least once.

Pair it with the settle rung: a population that keeps rising across the driven rungs AND does not move across the settle rung is a leak; one that collapses on the settle rung was in-flight backlog. Those two verdicts are indistinguishable from aggregate heap.
memlab_object_urls run_dir, paths
Unrevoked `blob:` object URLs — a leak that every heap-size metric misses, because each live URL pins its Blob in the browser blob registry, OFF the V8 heap. Counts `blob:` URL strings, the entries of an instrumented `URL.createObjectURL` register (grouped by File/Blob/MediaSource), live Blob/File wrappers, and which property edges hold the URLs. With `run_dir` (or `paths`) it counts every rung and reports per-cycle rates, plus the in-page register byte totals the leak-hunt runner records per rung (`object_url_bytes`). Without either it reads the loaded snapshot.
memlab_pending_promises run_dir, paths, top
Unsettled Promises ranked by REACTION-CHAIN length, with retained size and the production owner path. One promise that never settles keeps every `.then` callback attached to it, so the leak is a long chain on ONE promise — invisible to a count of unsettled promises. With `run_dir` (or `paths`) it takes the top promises on the last rung and reads each one, by node id, at every rung: "+N reactions/cycle on one promise" is a promise that never settles while every interaction attaches to it. Without either it ranks the loaded snapshot.
memlab_ab_compare run_dir, metrics, probes, census, prelude, timeout_ms, max_nodes, totals
Judge an A/B round (`hunt_runner --ab`) in one call: run the same probes on the OFF arm and the ON arm, fit each arm against its own cycles, and print one table with per-cycle rates, the ON/OFF ratio and a verdict per metric — FIX EFFECTIVE / PARTIAL / NO EFFECT / CANNOT JUDGE. Each arm's heap total is a row too, production-only beside raw, so a dev-only resize in one arm is not read as that arm growing more. Reads the arms from run.json `ab`. Probes are `memlab_eval` code assigning a number to `result` (as in `memlab_ladder_probe`); `census` adds built-in `memlab_census` populations. Give a metric a `cap` when the fix bounds a population at a size: a round whose OFF arm never reached the cap cannot show the fix working, and is reported CANNOT JUDGE rather than NO EFFECT.
memlab_blink_native_census run_dir, paths, min_growth, sample, limit
Native (Blink) classes that grow across a ladder — `blink::*`, performance-timeline entries, other `native` objects — each split by WHO holds its newest instances: a JavaScript holder (a promise reaction, an app array; an app change can release it) or the browser itself (performance timeline, soft-navigation heuristics; it cannot). Known fixed-capacity browser buffers (Event Timing, Layout Instability, LCP, Resource Timing, Long Tasks) are annotated with their cap, so a buffer filling up is not reported as a leak. Takes `run_dir` or `paths`.
memlab_string_prefix_census prefixes, run_dir, paths
Count strings by PREFIX on every rung of a ladder — `blob:` object URLs, `data:image/` payloads, a request-id or cache-key scheme — from each rung's sidecar index, without walking the graph. A rung with no sidecar is parsed once (light) and gets one. Reports per-rung count, distinct values and self bytes per prefix, with a per-cycle rate. Use it instead of a full-heap string walk inside `memlab_ladder_probe`.
memlab_rate_table run_dirs, metric, include_settle, snapshot
Build the per-surface, per-cycle rate table for ONE metric across several rounds — the artifact that says which surface to fix first.

A sweep produces one rate per round, and a rate on its own is not decision-useful: `+44/cycle` means nothing until it sits beside a `+323/cycle` and an exact `0`. The ranking is the finding. In a measured eight-round sweep this table was the most decision-useful thing produced, and it was assembled by hand from eight separate digests because no tool emitted it.

Unlike `memlab_compare_rounds`, this LOADS snapshots (two per round, or three with the settle rung), so it works on rounds that were never run through `memlab_analysis_battery` — at the cost of load time. It also carries the two columns that decide whether the rates are comparable at all: the settle-rung count (a population that drains on idle was backlog, not a leak) and the isolate age at baseline (the same surface measured 2.6x apart on a fresh vs. saturated isolate).
memlab_analyze_run run_json, cycles_between_rungs, top, skip_deep_dive, step_timeout_s, max_file_size_mb, snapshot
Point at a leak hunt's `run.json` and get the whole analysis protocol executed in one call: ladder trend, owner attribution for the growth, a detached-DOM population comparison between the first and last rung, dev/automation-artifact classification, and a per-grower adjudication — plus the run's own caveats (gating, relink seams, stall) carried into the write-up. `memlab_hunt_report` renders the run and `memlab_leak_report` analyses the ladder; nothing chained them, so how thorough a round got depended on how thorough the operator felt like being, which is the single largest source of variance between rounds. This runs the same sequence every time and states explicitly which steps did not run. Cost: it loads the ladder transiently for the trend, then holds the FIRST and LAST rung resident together for the attribution and population steps — size `timeout_ms` accordingly (600000+ for a multi-hundred-MB ladder), and expect several minutes. KNOWN LIMITATION, measured on two apps: the `dev_artifacts` step reliably exceeds a 200-240s step budget here (aborting at ~10.8M nodes scanned) while the same tool returns in 2-5s when called directly on the same snapshot. Unloading the baseline first does NOT change it, so residency is not the cause and the cause is not yet identified. The step is reported as UNANALYZED rather than waited out; run `memlab_dev_artifacts` yourself against the final rung, or raise `step_timeout_s`, to complete that part of the protocol.
memlab_eval_across code, handles, paths, run_dir, rungs, timeout_ms, max_nodes, stop_on_error
Run ONE `memlab_eval` program against SEVERAL snapshots and return the results side by side: resident ones by `handles`, or files by `paths` or `run_dir` + `rungs`, which are loaded one at a time and released after (a resident one is reused). Exists because the interesting questions in a leak hunt are comparative — "how many of these were there at each rung?", "did this collection grow?", "is the new population retained the same way as the old one?" — and answering them with `memlab_eval` alone costs one switch + one paste + one manual diff per rung, which is enough friction that the question often just does not get asked. The code, the sandbox and the helper surface are identical to `memlab_eval` (this calls the same implementation, not a copy), so anything that runs there runs here.

Node ids match across rungs only when they come from one isolate (one tab session, no reload; memlab_diff_snapshots reports this), so write code that computes COMPARABLE values (counts, sizes, shapes, string values) rather than code that hardcodes ids from one rung. `helpers.load(name)` still refuses cross-snapshot reads unless you pass `{allowCrossSnapshot: true}`.

The active snapshot is restored when the run finishes, including on failure, so this does not disturb an in-progress investigation.
memlab_settle_check run_dir, busy_handle, settled_handle, baseline_handle, limit, min_growth, trace_held, trace_sample
Separate RETENTION from in-flight BACKLOG by comparing a busy snapshot against one captured after the app settled (idle + forced GC). This is the measurement that a growth ladder alone cannot make: a burst of activity legitimately inflates promise chains, IndexedDB transactions, scheduler queues and request buffers, and every one of those looks exactly like a leak in a two-rung diff. Only a post-idle rung tells them apart — a class that returns to baseline was work in progress, a class that stays is retention.

Give it the busy rung and the settled rung (and optionally a pre-activity baseline, which makes the "how much of the growth came back" fraction meaningful rather than absolute). All snapshots must already be resident: load them with `keep_previous: true`.

Capture protocol for the settled rung: stop interacting, wait ~30-60s so timers, network callbacks and storage writes complete, force GC, then capture.
memlab_count_population class_name, shape, context_var, expected_max, handle, snapshot
Count one population by SEVERAL independent methods and report when they disagree.

Counting is the operation a leak hunt repeats most, and it is the one where a wrong answer is invisible: a method that cannot reach the population returns 0, which is byte-identical to the population not being there. Measured — a shape-based probe returned 0 at every rung against a closure-captured array holding tens of thousands of entries, and read as a clean negative.

So this counts by class name, by property shape, and by CLOSURE-CAPTURED VARIABLE name, whichever you supply, and treats disagreement between two methods as the headline result rather than a footnote. The context-variable method is the one nothing else offers: a variable captured by a closure is not a property of anything, so no amount of property or shape matching can see it.

Pass `expected_max` to check an observed population against a cap that is declared in SOURCE rather than visible in the heap — an LRU sized in code, a documented queue bound. One measured cache held 17,976 entries behind a nominal 1,000-entry cap, an 18x overrun that was found by accident.
memlab_island_doors seed_class, seed_node_ids, island_mode, max_owners, max_island_nodes, include_blink, limit, handle, snapshot
List EVERY production-reachable reference into an island, not just the shortest one. `memlab_retainer_trace` answers "why is this object alive by ONE path"; an island normally has several independent holders, and fixing whichever happens to be nearest a GC root reclaims nothing because the next one still pins it.

The island can be a DETACHED subtree (`island_mode: "detached"`, the default) or a LIVE one: `"reachable"` takes everything the seeds reach, which is how to ask "what are all the independent references into this accumulator's value set?", and `"dominated"` takes what the seeds exclusively own, which answers "who holds this accumulator". Walks forward from the GC roots refusing to enter the island, so each edge that crosses in is one reference a fix must remove. Refuses weak edges, dev/automation roots (DevTools console, a11y cache, dev globals) and dev edges (React DEV `_owner`/`_debug*`, Fast Refresh, devtools modules), and follows a WeakMap key->value edge only when the key is itself reachable — conditionally, because a WeakMap value IS retained while its key is live. Every refusal is counted, so "no doors" is distinguishable from "the filter hid them". Run this BEFORE writing a fix, and again after, to show each door is closed.
memlab_build_provenance expect_present, expect_absent, handle, snapshot
Assert that the build a snapshot came from actually contains the change you are measuring, BEFORE reading any before/after number. Scans the heap for marker strings from the new revision (`expect_present`) and from the revision it replaced (`expect_absent`). Without this, "the fix does not work" and "the fix was never in the build" produce identical results, and the second is far more common — a stale bundle, a gate forced at one call site but not another, a build that did not pick up the last amend. Minified bundles retain enough to check: log format strings, template literals and many function/variable names survive as heap strings. Run it on every capture in an A/B, not just the treatment arm.
memlab_console_retention target_node_id, limit, handle, snapshot
Report what an attached DevTools console is keeping alive, and answer whether a specific object depends on it. DevTools holds a global handle on every object passed to `console.log` (and to any logger that funnels there), so with the console open those objects — and everything they transitively reference — live for the whole session. Those handles are REAL GC roots in the capture but do not exist in production, so they manufacture retainer paths that are indistinguishable from genuine ones in the DevTools retainer view. This is not the same question as `memlab_dev_artifacts`, which reports what is retained ONLY via dev roots in aggregate: an object can have a perfectly real production path AND a console-mediated one, and it is the console-mediated path that a retainer trace will usually show you. Run it before trusting any trace taken with DevTools attached.
memlab_drill_to_heavy_leaf node_id, threshold, max_depth, snapshot
Follow the retained size DOWN from one node to the object actually holding it, in a single call.

A large retained size usually sits on a wrapper — a closure context, then the object it captured, then the array inside that object — and each hop has exactly one child carrying essentially all the weight. Finding the bottom means calling `memlab_dominator_subtree` once per hop and reading one row of each table; three or four round-trips to learn one fact. This walks the chain server-side while a single child keeps ≥`threshold` of the parent, stops at the first real BRANCH (where the weight genuinely splits) or at a leaf, and reports the whole chain plus the terminal object’s entry count and a size sample.

The branch point is the answer as often as the leaf is: it is where "one big thing" becomes "many things", which is where a fix has to choose what to bound.
memlab_overlap_matrix classes, handle, snapshot
Do these classes retain the SAME bytes? Reports pairwise overlap in dominator-deduped retained size, plus the combined deduped total for the whole set.

Use before quoting the value of a fix that removes more than one class. Per-class retained sizes are reported independently, so adding them is the obvious move and it double-counts every byte the classes share — which is the normal case for objects on one retention chain (a subject and the closures it holds, a record and its backing array). One measured pair reported 16.6 MB and 16.6 MB separately and ~16.6 MB combined; the naive sum overstated the fix by 2x.

Also answers the inverse question: near-zero overlap means the populations are genuinely independent, so a fix that removes one leaves the other untouched.
memlab_rate_model run_dir, segment, values, cycles_per_rung, label, harness_cycles_per_minute, production_cycles_per_minute, bytes_per_object
Is this population UNBOUNDED, or is it a working set whose size is just a function of how fast the harness drove?

Fits a straight line, a saturating curve `plateau * (1 - exp(-cycles/tau))`, and (with 4+ rungs) a one-time step followed by a line, and reports which the data actually supports, the implied plateau, and the implied retention window in cycles. A first-mount step followed by steady growth is reported as POST-STEP LINEAR, never as a plateau.

This is the distinction a short ladder cannot make and a long one makes for free. A population held by a time-boxed grace period (a temporary retain, a TTL cache, an in-flight window) is EXACTLY linear early — its size is rate x window and the window has not elapsed yet — so a 4,000-cycle ladder scores it r2 ~ 1.0 and it gets filed as an unbounded leak. Measured: one population read as linear at 4,000 cycles and plateaued by 8,000, and the finding had to be downgraded twice. The plateau is the number that decides whether to file, and it is also the number that says what the population would be at a realistic interaction rate rather than at the ~10 interactions/second a hammer drives.

Feed it the series `memlab_ladder_probe` already produced; this does no snapshot work of its own.
memlab_snapshot_budget_planner paths, budget_mb
Which rungs of this ladder can you actually hold in memory at once, and which should be probed transiently?

The guidance is already known — a few well-spaced rungs for the trend, and only the final snapshot fully loaded for the deep-dive — but applying it means knowing what each rung costs, and that is a `stat` plus an expansion factor per file that nobody does. The failure it prevents is specific: `memlab_unit_cost` needs a `baseline_handle` to report MARGINAL cost (the number that actually sizes a cap), which needs two large snapshots resident at once. A session that does not know whether that fits either never asks for the marginal number or discovers the ceiling by hitting it mid-analysis.

Reports per-rung file size, estimated resident cost at full and light parse, what fits in the budget, and a concrete plan. Does no parsing of its own — this is a `stat` and some arithmetic.
memlab_unit_cost class_name, typename, shape, handle, baseline_handle, container_id, project_caps
How much memory does ONE of these actually cost? Reports dominator-deduped retained bytes per instance for a class or an object shape, and — given two snapshots — separates the AVERAGE from the MARGINAL cost.

That distinction decides fixes. A population whose first instances drag in shared structure has a high average and a low marginal cost, so capping it saves far less than the average implies; a population with a flat per-instance cost scales linearly and a cap saves exactly what the arithmetic says. Sizing an LRU, an undo-stack cap, an eviction policy or a "is this worth interning?" decision all need the marginal number, and computing it by hand means four calls and a subtraction that is easy to get backwards.

With one snapshot you get the average and a projection table. With `baseline_handle` you also get the marginal cost between the two rungs.
memlab_identify node_id, shape, scan, limit, snapshot
Name a minified structure from its property shape. In a production bundle nearly every class is `t`, `e`, `s` or `Object`, so the first — and often longest — step of an investigation is working out what a population actually IS: a listener record, an LRU node, a React update record, an editor-history entry. This matches a node (or a bare shape) against a library of known fingerprints and reports what it is, why it matters, and what to check next.

Give it a `node_id`, or a `shape` you already have from `memlab_shape_histogram` / `memlab_find_by_shape`. With `scan: true` it sweeps the whole heap and reports every recognised structure with its population count, which is a fast way to orient in an unfamiliar app.

A name here is a strong hypothesis, not proof: shapes collide across libraries, so confirm with a retainer trace before writing it into a report.
memlab_what_if node_ids, typename, class_name, shape, breakdown, limit, cascade, snapshot
If this set of objects were freed, how many bytes would actually come back? Reports the dominator-deduped retained size of a population — the bytes that go away when it does, with nothing double-counted and nothing counted that is also reachable another way.

This is the number every fix decision needs and the one that is easiest to get wrong by hand. Summing per-object retained sizes double-counts every nested object; quoting the class total counts memory that other live code still holds; quoting a container's retained size includes internals that survive. `memlab_detached_dom` already reports it for detached subtrees as "Owner Frees" — this makes the same question askable about any set.

Specify the population by ids, class name, or property shape.
memlab_metric mode, name, value, unit, label, note, limit, snapshot
Record a measurement under a name and keep it across sessions, so a number measured today can be compared with one measured next week.

Snapshots are far too large to keep resident between sessions and node ids are per-capture, so the only thing that can persist is the measurement itself. Without this, every number from an earlier session lives in a transcript nobody reloads, and the before/after comparison that decides whether a fix worked either gets re-derived from scratch or skipped.

Modes: `record` a named value, `history` for one metric with its trend, `list` for everything recorded, `forget` to drop one. Values are stored on disk under `~/.memlab/metrics.json` (override with `MEMLAB_STATE_DIR`).
memlab_trace_all class_name, shape, node_ids, framework_filter, limit, exact_bytes, max_depth, max_trace, sample_target, exclude_dev, snapshot
Retainer-trace an ENTIRE population and cluster the paths server-side, instead of sampling a handful and hoping they are representative.

`memlab_retainer_summary` samples ~10 instances and stops early once they agree, which is the right default for a quick read but is structurally unable to find a minority path: a cluster holding 3% of the objects and 60% of the bytes is invisible to it, and that cluster is very often the leak. This traces every member (bounded, and it says so when the bound is hit), groups by structural path signature, and reports each cluster with its share of the population — so the output cost is the number of DISTINCT paths, not the size of the population.

Select by class, shape or explicit ids. Use it when a population is large enough that "are they all retained the same way?" is the question, and when a sampled answer has already been used to justify a conclusion.

On a population too large to trace whole, pass `sample_target` rather than skipping the tool: it traces a STRATIFIED sample spread across the id range and retained-size deciles, which still finds a 3% minority cluster, where the default bound truncates off the top of the id order and keeps only the oldest instances.
memlab_retainer_diff before_handle, after_handle, class_name, shape, framework_filter, limit, max_depth, max_trace, snapshot
A population grew between two snapshots — did it grow along the SAME retention path, or did a new one appear?

This is the question a count diff cannot answer and the one that decides what to fix. "42,000 → 61,000 listener records" is consistent with two completely different bugs: an existing owner accumulating faster, or a second owner that did not exist before. A count, a class histogram and a population diff all read identically in the two cases.

Clusters the full population by retainer path in BOTH snapshots and reports paths that are new, grew, shrank or vanished. Both snapshots must be resident (load with `keep_previous: true`); the active snapshot is not changed.
memlab_app_config key, min_entries, limit, samples, snapshot
Read the feature flags and config values the app was actually running with, out of the snapshot itself.

Half of "is this leak still there?" is "was the fix even enabled in this capture?" — and that gets answered by inference: the code says the cleanup is gated, the capture looks like the cleanup did not run, therefore the gate was off. That is circular, because the same evidence is what the gate is being invoked to explain. The config the app read is still resident in the heap, so the question is answerable directly.

Registries are found by SHAPE, not by name — an object with many entries whose keys look like config identifiers (`some_feature_enabled`, `web.thing.limit`) and whose values are booleans or small numbers. `key` looks up one flag across every registry found.
memlab_identity_diff before_handle, after_handle, class_name, shape, max_values, limit, snapshot
Same objects, or just the same number of objects? Matches a population across two snapshots by CONTENT rather than by node id. Use it across isolates (a reload, another session); between captures of ONE isolate, memlab_diff_snapshots matches by V8 object id, which is exact.

The distinction decides what kind of bug this is. A population whose members are replaced between captures is churn — a rate problem, and capping or reusing is the fix. A population whose members all persist is retention, and the fix is releasing them. The two look identical in every count-based diff, which is what `memlab_diff_snapshots` and a class histogram report.

The content key is the object's property names plus the string and boolean values it holds. That is a stand-in for identity, not identity: objects with identical content are indistinguishable to it. The report always states how distinct the keys actually were, so a weak answer is visible as one.
memlab_next_measurement goal, snapshot
What can the snapshots currently loaded actually support — and which capture would change that?

Every wrong conclusion in a leak hunt has the same shape: a claim that needed a measurement nobody took, argued from one that happened to be available. One rung cannot show a trend. Two rungs cannot separate in-flight work from retention. A light snapshot cannot support any statement about retention at all. None of those limits appears in the output of the tools that produce the numbers.

Reports the gaps in the CURRENT evidence base, worst first, each with the specific capture or call that closes it. It only reports gaps it can verify from what is resident — it is not a model of your investigation, and silence about something is not endorsement of it.
memlab_replicate runs, code, label, min_r2, min_delta, slope_ratio_tolerance, timeout_ms, max_nodes, max_file_size_mb, snapshot
Ask whether a measured effect REPRODUCES across two or more independently-driven runs, and refuse to call it real until it does. This is the gate that separates a finding from a one-off, and it is the one gate that cannot be replaced by looking harder at a single run.

Give it the same numeric probe and the ladders from N separate runs (or the pre-measured `series` if the snapshots are gone). It fits each run independently and returns REPRODUCED / REPRODUCED_UNSTABLE / REPRODUCED_FLAT / NOT_REPRODUCED / INCONCLUSIVE. `REPRODUCED_FLAT` is its own verdict on purpose: every run agreeing the series is flat is a RESULT, not a failed measurement, and reporting it as NOT_REPRODUCED reads like the latter.

Why it exists: a detached-DOM finding once passed every other gate — r2 = 1.0000, permanent across 9 minutes of idle with forced GC, 97% concentrated under a single dominator, dominator-deduped sizing, an app-side retainer path that `memlab_dev_artifacts` classified as production — and failed to reproduce on all three follow-up runs. Every one of those checks was passed by a one-off. Run this BEFORE writing a finding up, not after.
memlab_round_audit run_dir
Read a leak hunt's `run.json` and say whether the round can carry a conclusion at all — BEFORE anyone reads its numbers. Checks rung count, ladder continuity (a mid-run page reload silently splits the ladder into two V8 isolates), per-step landing (a declared surface that never actually opened), step exceptions, the content-mutation confound, verified gating, and the overall cycle landing rate.

Every one of these is already in the manifest and nothing was reading it. The failures this catches are rounds that LOOK complete: one was written up as valid with two of its ten declared operations at 58/165 and 0/165; another was split by a page reload and read as "the app shrank, cleanest round on record" when its valid segment said the opposite.

Returns TRUSTWORTHY / CAVEATED / UNTRUSTWORTHY. Run it first; `memlab_analyze_run` answers what the round MEASURED, this answers whether the round is worth measuring.
memlab_dom_audit min_instances, limit, visible_estimate, snapshot
Budget the ATTACHED DOM and rank the surfaces worth virtualizing. This is an OPTIMIZATION tool, not a leak tool — the elements it reports are all live and correctly retained; the point is that there are too many of them.

Element count drives style recalculation, layout, and per-element Blink side-data (`ComputedStyle`, `UniqueElementData`, `NodeRareData`) independently of any leak, so a surface rendering 400 rows when 15 are on screen pays for all 400 on every recalc. That cost never shows up in a leak report, because nothing is leaking.

Reports the total attached element count, the per-tag split, and — the actionable part — a per-COMPONENT census recovered from StyleX debug class names (`WAWebChatCell__styles.cell` names the module) and `data-testid`. A component with a high instance count and a fixed per-instance element cost is a list, and a list is what virtualization is for.

What this can and cannot see: the element count is exact (validated against `document.querySelectorAll("*").length` on a live page — 364 vs 363, per-tag counts matching). CONTAINMENT is not available: a heap snapshot exposes parent, child, sibling and document links all as the same edge type, so "which container holds these rows" cannot be reconstructed from a capture — measured 1,286 element-to-element edges across 364 elements, most with 3-4 apparent parents. Nor is viewport visibility. For those, drive the live page instead.
memlab_sparse_elements min_capacity, max_occupancy, min_group_bytes, limit, max_hops, snapshot
Find integer-keyed objects and arrays whose ELEMENTS BACKING STORE is mostly holes — memory V8 has allocated and the application never uses. This is the waste a class histogram cannot see: the store is a `(object elements)` FixedArray charged to no class, and each instance is individually small, so the cost only appears once instances are grouped by owner. Two distinct causes are separated in the output: sparse/strided keys (indices scattered across a range the store must span) and over-allocation (capacity far past the highest key). Groups are labelled by the nearest named property up the retainer chain (`getterImpl.$$cache`), which is what you can grep for. Complements memlab_cache_analysis (entry counts in Maps/Sets) and memlab_object_cost_breakdown (where one class’s bytes go).
memlab_anonymize_snapshot file_path, output_path, audit_only, mode, salt, extra_patterns, keep_patterns
Rewrite a .heapsnapshot so it can be shared: replaces the content of every string on the heap, plus any property name or node name that looks like an identifier, a credential or serialized DOM — while KEEPING class names, function names and ordinary property keys, so retainer traces, histograms, dominator trees and shape analyses still work on the result. Lengths are preserved exactly, and by default so is distinctness, so duplication and interning figures stay accurate. Always reports what it did NOT remove: a capture anonymized by hand had every string value replaced and still carried 26,303 account handles as property names. Set audit_only to inspect a capture someone else anonymized without writing anything. Set salt for anything leaving your trust boundary, and reuse one salt across a set of snapshots so they stay comparable.
memlab_round_digest run_dir, include_analysis, max_metrics
The verdict table for a finished leak-hunt round, and nothing else. `memlab_analyze_run` writes ~30 KB of prose per round, which in practice gets grepped for verdicts rather than read — across a five-round sweep that is the single largest avoidable token cost in the analysis phase. This reads the run manifest plus any `*_analysis.txt` next to it and returns: the audit verdict and its blocking checks, the ladder shape (including whether a page reload split it), the per-metric rate/fit/verdict rows, and the round's own caveats. The full analysis stays on disk and is named in the output, so nothing is lost — it is just not paid for by default.
memlab_sweep_digest run_dirs, snapshot
One row per round for a whole sweep, from the files each round left on disk (run.json plus the battery output): combo, cycles, rungs, audit verdict, heap, settle, positive controls, leak-candidate count — and, per round, the leak-candidate classes that NO EARLIER round in the list reported. That last column is what tells a sweep where it found something new. Pass the run directories oldest first, or one parent directory to scan for rounds.
memlab_react_owners node_ids, shape, update_records, max_hops, limit, snapshot
Name the React COMPONENT behind a population of plain `Object`s. Fibers, hooks, update queues and update records are all `Object` in a production bundle, so every class-name heuristic — including memlab_get_referrers and helpers.owner — walks straight past them: on one measured population `owner()` returned `(none)` for 100% of 1,645 records. This walks each node up to its owning fiber (preferring `memoizedState` / `queue` / `baseQueue` / `next`) and resolves `elementType` through all three of its shapes (function closure, host string, and the `render`/`type` indirection memo and forwardRef add), then groups the population by component. Turning "Object grew 13/cycle" into "BaseTooltipSimple, 13 mounted, one record each" is the step that makes a finding filable.
memlab_react_update_queues max_chain, limit, max_hops, run_dir, paths, segment
The React eager-bailout leak family as one report. A `useState` update whose eager comparison bails out still leaves its record on `queue.pending`, which then never drains — four separate findings in this workstream have been that same shape, and each round re-derived the same three things by hand. This returns: how many queues hold a pending chain (BREADTH), how long each chain is (LENGTH), and which component owns it. The breadth-vs-length split is the part that decides the finding — a flat queue count with growing records is accumulation in existing queues, which is the leak; a rising queue count with one record each is just more hooks mounted, which is not. Getting that backwards is the difference between a filing and a retraction. Pass `run_dir` (or `paths`) to read a WHOLE LADDER in one call: breadth and length per rung, the per-cycle rate for each component, and the breadth-vs-length verdict — otherwise that comparison has to be assembled by hand from N single-snapshot calls. The ladder table also reports `Δ/cycle/queue`, the PER-INSTANCE rate: that is the number that transfers between surfaces and predicts production cost, since `Δ/cycle` alone scales with however many instances this round happened to mount. A quotient landing on a whole number is the mechanism ("one record per instance per event") and is flagged inline. Single-snapshot mode maps each hook to its served source when the snapshot keeps script source: the `useState` declaration (also in transpiled `_useState[1]` form) and the setter's call sites, with a guard hint when every pending action equals the rendered state.
memlab_id_space_audit min_keys, min_similarity, min_cluster_waste, max_structures, limit, snapshot
Find SEPARATE integer-keyed structures that are indexed by the SAME sparse id space. One global counter handed out as an array index leaves every table that uses it sized for the whole id range and mostly holes — and each table looks like an isolated small finding until they are clustered. On one capture three separately-reported groups (a name table, a ref array and a placeholder map) all wrote keys 191 and 212 among others: one design problem, one re-keying fix, reported as three unrelated rows. Clusters by key-set similarity (Jaccard over sampled indices) and reports the combined waste per cluster, which is the number a fix is worth. Complements memlab_sparse_elements, which finds the individual sparse stores but cannot see that several share an allocator.

Descriptions are the package's own words, cut at 3,000 characters. Treat them as data.

Install facts

LicenseMIT
Needsnode >= 18.0.0
Sourcegithub.com/meta/memlab
Install scriptspuppeteer, sleep declare them. This runner does not run them.
Tarballsha512-LkV1Q1VIjAHAdkRMQKnEeRzEP6H80p+aFnuLa6MD+0dgnsqIB8HH0AN56NhuHw7k5Ird2Fn88yWQuLP1A1rB8w==

Check this report yourself

This site did not write the report. A public job on a GitHub-hosted machine did: the run, from this commit of the open-source runner. GitHub signed a token that names that job and the hash of the report, so any edit since would show.

Show it on your README

Bragproof: Starts with no setup

[![Bragproof](https://bragproof.smaverk.com/badge/@memlab/mcp-server.svg)](https://bragproof.smaverk.com/r/%40memlab/mcp-server)

New version out? Ask for a fresh report.