Heap Snapshot Analysis

Investigate memory leaks from V8 heap snapshots (.heapsnapshot files). This skill starts when snapshots already exist: either the user provided them, DevTools exported them, or another workflow produced them. Use the helpers here to compare snapshots, group object deltas, and trace retainer paths.

IGNORE Prior Investigations

Start every investigation fresh. Do NOT read, consult, or be influenced by prior investigations found in:

• /memories/ (user, session, or repo memory)
• .github/skills/heap-snapshot-analysis/scratchpad/ (previous dated subfolders and their findings.md files)
• Any other notes from earlier sessions

Previous findings can bias the analysis toward suspects that are no longer relevant, or cause the agent to skip steps and jump to conclusions. Let the current snapshots speak for themselves. Only reference prior work if the user explicitly asks you to.

When to Use

• User provides .heapsnapshot files (before/after a workflow)
• User has heap snapshots captured by another skill or script
• Need to find what retains disposed objects (retainer path analysis)
• Comparing object counts/sizes between two snapshots
• Investigating why particular objects survive GC

Workflow

If the user needs the agent to launch VS Code, drive a scenario, and capture snapshots first, use the VS Code performance workflow skill before returning here for low-level snapshot analysis.

1. Parse Snapshots

Use the helpers in parseSnapshot.ts to load snapshots. The files are often >500MB and too large for JSON.parse as a string — the helpers use Buffer-based extraction. In scratchpad scripts, import helpers from ../helpers/*.ts.

For very large snapshots, the helper may still be too eager. Node cannot create a Buffer larger than roughly 2 GiB, so snapshots above that size can fail with ERR_FS_FILE_TOO_LARGE even before parsing. In that case, do not try to raise --max-old-space-size and retry the same full-file read. Switch to a streaming script.

import { parseSnapshot, buildGraph } from '../helpers/parseSnapshot.ts';

const data = parseSnapshot('/path/to/snapshot.heapsnapshot');
const graph = buildGraph(data);

Snapshots Larger Than 2 GiB

When a snapshot is too large to load into a single Buffer, write scratchpad scripts that scan and parse only the sections needed for the question. Use streamSnapshot.mjs for the common streaming primitives instead of copying them between scratch scripts.

Useful tricks:

• Find top-level section offsets first. Scan the file as bytes for markers like "nodes":, "edges":, "strings":, and "trace_function_infos":. This lets follow-up scripts jump directly to the large arrays instead of searching the whole file repeatedly.
• Parse snapshot.meta separately from the small header at the start of the file. Use meta.node_fields, meta.node_types, meta.edge_fields, and meta.edge_types to avoid hard-coding tuple widths.
• Stream numeric arrays in chunks. For nodes and edges, keep a small carryover string between chunks, split on commas, and process complete numeric tokens as they arrive.
• Avoid materializing the full strings table unless the investigation truly needs it. If you only need suspicious names, collect string indexes from matching nodes/edges first, then resolve only those indexes in a second streaming pass.
• If you do need many strings, store only short previews and category counters. Full source strings, ref-listing strings, and prompt payloads can dominate memory and make the analyzer become the leak.
• Write intermediate outputs to files in the scratchpad. Large heap analysis is iterative and slow; cached node ids, offsets, and retainer traces save repeated multi-minute passes.

…