@memlab/mcp-server 2.1.0 → 2.3.0

package/README.md

@@ -6,6 +6,8 @@ An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that
 
 The MCP server loads and analyzes large heap snapshots in memory, which can exceed Node.js's default heap limit. You need to configure `--max-old-space-size=8192` (or higher) to avoid out-of-memory crashes. The configuration examples below include this setting.
 
+**Snapshot-size ceiling.** The server holds the full parsed graph (nodes, edges, dominator tree, indexes) resident, so its own RSS is roughly **3–5× the on-disk snapshot size**. With the recommended `--max-old-space-size=8192`, snapshots up to ~850 MB on disk have been analyzed reliably; `memlab_load_snapshot` refuses files above `max_file_size_mb` (default 900) to avoid OOM crashes that would lose all state. For larger heaps, raise both `--max-old-space-size` and `max_file_size_mb`. When loading multiple snapshots with `keep_previous: true`, each resident snapshot adds its full graph to RSS — unload ones you're done with via `memlab_snapshots`.
+
 ## Quick Start
 
 ### Option 1: Global install
@@ -126,11 +128,79 @@ console.log(`Heap snapshot written to ${snapshot}`);
 
 ### `memlab_load_snapshot`
 
-Load and parse a `.heapsnapshot` file. Builds indexes, computes the dominator tree, and calculates retained sizes.
+Load and parse a `.heapsnapshot` file. Builds indexes, computes the dominator tree, and calculates retained sizes. `file_path` may be a local absolute path, a `manifold://bucket/key` URL, or a bare snapshot filename (resolved against the `nest_server_nodejs_heap_snapshots` bucket and fetched via `manifold get`). Pass `keep_previous: true` to keep earlier snapshots resident for diffing/comparison (each gets a handle; manage with `memlab_snapshots`). `quiet` / `suppress_suggestions` set session-wide output controls to trim repeated boilerplate.
+
+```
+Input:  { file_path: "snap.heapsnapshot" | "/abs/path" | "manifold://bucket/key",
+          alias?: "before", keep_previous?: false, quiet?: false,
+          suppress_suggestions?: false, max_file_size_mb?: 900 }
+Output: { status, file_path, node_count, edge_count, total_size, handle }
+```
+
+### `memlab_snapshots`
+
+Manage the multi-snapshot session and session output controls.
+
+```
+Input:  { action?: "list"|"switch"|"unload", handle?: "before",
+          quiet?: bool, suppress_suggestions?: bool }
+Output: resident snapshots (active one marked), or switch/unload result
+```
+
+### `memlab_property_distribution`
+
+For a class/shape and a property, report value cardinality plus the top-K most frequent values. The key tool for diagnosing cardinality explosions (OTel metric attributes, cache keys, per-record fields).
+
+```
+Input:  { property: "http.route", class_name?: "Object", shape?: ["a","b"],
+          top_k?: 15, min_count?: 1 }
+Output: { scanned, distinct_values, top_values: [{ value, count, pct }] }
+```
+
+### `memlab_growth_signals`
+
+Single-snapshot heuristic that flags likely unbounded growth: Maps/Sets keyed by timestamps or sequential integers, and large ever-growing Arrays. Confirm with a later snapshot + `memlab_diff_snapshots`.
 
 ```
-Input:  { file_path: "/path/to/snapshot.heapsnapshot" }
-Output: { status, file_path, node_count, edge_count, total_size }
+Input:  { limit?: 15, min_entries?: 200, min_retained_size?: 262144 }
+Output: candidates with kind, entry count, retained size, sample keys
+```
+
+### `memlab_sequence_analysis`
+
+Trend analysis across an ordered sequence of 3+ snapshots. Loads each transiently (does not change the active snapshot), reports each class's count at every step, and labels "↑ every step" (leak signal) vs "grew net (noisy)". Lists classes new since baseline.
+
+```
+Input:  { paths: ["a","b","c"], limit?: 25, min_growth_count?: 50,
+          monotonic_only?: false, max_file_size_mb?: 900 }
+Output: per-step heap totals + growing classes with per-step counts and verdict
+```
+
+### `memlab_dev_artifacts`
+
+Browser snapshots: classify large retainers as production vs. dev-only (retained solely via `__REACT_DEVTOOLS_GLOBAL_HOOK__`, `__REDUX_DEVTOOLS_EXTENSION__`, `window.Debug`, …) and total the bytes to exclude from leak headlines. `memlab_detached_dom` also reports the dev-only share inline.
+
+```
+Input:  { limit?: 25, min_retained_size?: 524288, only_dev?: false }
+Output: dev-only byte total + per-object classification (production | dev-only via <global>)
+```
+
+### `memlab_event_registry`
+
+Detector for per-model event registries (Backbone/observer): objects mapping event names to arrays of `{callback, context}`. Reports top event names by listener count, listeners-per-host distribution, and a structural-vs-leak verdict.
+
+```
+Input:  { min_events?: 2, limit?: 20, timeout_ms?: 45000 }
+Output: registry stats + top events + verdict (structural O(hosts) vs re-subscription leak)
+```
+
+### `memlab_server_status`
+
+Cheap liveness/health check — returns instantly with process RSS, uptime, and resident snapshots. Use to confirm the server is responsive (vs. stuck behind a heavy scan) and to watch RSS against the snapshot-size ceiling.
+
+```
+Input:  {}
+Output: status, uptime, RSS, resident snapshots
 ```
 
 ### `memlab_snapshot_summary`
@@ -305,6 +375,21 @@ Structured map/filter/reduce over all heap nodes with code predicates.
 Input:  { filter_code: "node.type === 'closure'", map_code?: "...", reduce_code?: "...", limit?: 100 }
 ```
 
+## Investigation Skill for AI Assistants
+
+The [MCP Investigation Skill](./MCP_SKILL.md) provides a structured
+methodology for AI coding assistants to systematically investigate memory
+issues using the MCP tools. It covers:
+
+- **Step-by-step triage** — load, diagnose, and prioritize findings
+- **Investigation paths** — guided workflows for string waste, DOM leaks,
+  object accumulation, closure leaks, global bloat, listener accumulation, and
+  repeated errors, each with triggers, tool sequences, and common fixes
+- **Tool selection reference** — a quick-reference table mapping investigation
+  goals to the right MCP tool
+- **Token efficiency tips** — how to minimize token usage with compact modes
+  and parallel tool calls
+
 ## Example Workflow
 
 A typical memory investigation:

package/dist/analysis-budget.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+/**
+ * Wall-clock guardrail for heap analysis.
+ *
+ * Node.js is single-threaded, so a timer cannot interrupt a synchronous
+ * full-heap loop mid-iteration — the guardrail has to be COOPERATIVE: hot loops
+ * call `tick()` (cheap, clock checked only every few thousand iterations) and a
+ * {@link ScanTimeoutError} is thrown once the budget is exceeded. The per-call
+ * wrapper (see guardrail.ts) arms a process-global "active" budget around every
+ * tool invocation, and the shared `snapshot.nodes`/`edges.forEach` funnels feed
+ * it via {@link tickAnalysis}, so any tool that does a full-heap scan is bounded
+ * without per-tool wiring.
+ *
+ * This module imports nothing so it can be shared by utils, heap-state and the
+ * guardrail wrapper without creating an import cycle.
+ */
+/**
+ * Thrown by a budget when a heap walk exceeds its wall-clock limit. Callers
+ * either catch it locally to return partial results, or let it bubble to the
+ * per-call guardrail which turns it into a clean "analysis stopped" result.
+ */
+export declare class ScanTimeoutError extends Error {
+    iterations: number;
+    timeoutMs: number;
+    constructor(iterations: number, timeoutMs: number);
+}
+/**
+ * Wall-clock budget. Call `tick()` once per iteration; it cheaply checks
+ * elapsed time every few thousand iterations and throws {@link ScanTimeoutError}
+ * when the budget is exceeded.
+ */
+export declare function makeScanBudget(timeoutMs: number): {
+    tick: () => void;
+};
+/**
+ * Resolve the analysis timeout in ms: an explicit per-call override wins, then
+ * the MEMLAB_ANALYSIS_TIMEOUT_MS env var, then the 90s default. A value <= 0
+ * disables the guardrail (returns 0 → never trips).
+ */
+export declare function getAnalysisTimeoutMs(override?: number | null): number;
+/** Arm the global budget for one tool call. `timeoutMs <= 0` disables it. */
+export declare function beginAnalysisBudget(timeoutMs: number): void;
+/** Disarm the global budget at the end of a tool call. */
+export declare function endAnalysisBudget(): void;
+/**
+ * Cooperative checkpoint for high-iteration loops (e.g. full-heap scans). Cheap
+ * no-op when no budget is armed; the clock is only sampled every few thousand
+ * calls, so this is meant for loops that run millions of times. For loops with
+ * few iterations but expensive bodies (e.g. per-class dominator aggregation),
+ * use {@link checkAnalysisDeadline} instead.
+ */
+export declare function tickAnalysis(): void;
+/**
+ * Unconditional deadline check (samples the clock every call). Use in loops
+ * with a small iteration count but an expensive body, where the sampled
+ * {@link tickAnalysis} would not check often enough to be effective.
+ */
+export declare function checkAnalysisDeadline(): void;
+/** Wall-clock ms elapsed in the current tool call (0 if none armed). */
+export declare function activeElapsedMs(): number;
+/** The timeout the active budget was armed with (0 if disabled/none). */
+export declare function activeTimeoutMs_(): number;
+//# sourceMappingURL=analysis-budget.d.ts.map

package/dist/analysis-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-budget.d.ts","sourceRoot":"","sources":["../src/analysis-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAEhC,UAAU,EAAE,MAAM;IAClB,SAAS,EAAE,MAAM;gBADjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM;CAK3B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG;IAAC,IAAI,EAAE,MAAM,IAAI,CAAA;CAAC,CAWpE;AAYD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CASrE;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAI3D;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAED,wEAAwE;AACxE,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}

package/dist/analysis-budget.js

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+/**
+ * Wall-clock guardrail for heap analysis.
+ *
+ * Node.js is single-threaded, so a timer cannot interrupt a synchronous
+ * full-heap loop mid-iteration — the guardrail has to be COOPERATIVE: hot loops
+ * call `tick()` (cheap, clock checked only every few thousand iterations) and a
+ * {@link ScanTimeoutError} is thrown once the budget is exceeded. The per-call
+ * wrapper (see guardrail.ts) arms a process-global "active" budget around every
+ * tool invocation, and the shared `snapshot.nodes`/`edges.forEach` funnels feed
+ * it via {@link tickAnalysis}, so any tool that does a full-heap scan is bounded
+ * without per-tool wiring.
+ *
+ * This module imports nothing so it can be shared by utils, heap-state and the
+ * guardrail wrapper without creating an import cycle.
+ */
+/**
+ * Thrown by a budget when a heap walk exceeds its wall-clock limit. Callers
+ * either catch it locally to return partial results, or let it bubble to the
+ * per-call guardrail which turns it into a clean "analysis stopped" result.
+ */
+export class ScanTimeoutError extends Error {
+    iterations;
+    timeoutMs;
+    constructor(iterations, timeoutMs) {
+        super(`Scan exceeded its ${timeoutMs}ms budget after ~${iterations} nodes`);
+        this.iterations = iterations;
+        this.timeoutMs = timeoutMs;
+        this.name = 'ScanTimeoutError';
+    }
+}
+/**
+ * Wall-clock budget. Call `tick()` once per iteration; it cheaply checks
+ * elapsed time every few thousand iterations and throws {@link ScanTimeoutError}
+ * when the budget is exceeded.
+ */
+export function makeScanBudget(timeoutMs) {
+    const start = Date.now();
+    let i = 0;
+    return {
+        tick() {
+            i++;
+            if ((i & 0x3fff) === 0 && Date.now() - start > timeoutMs) {
+                throw new ScanTimeoutError(i, timeoutMs);
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Process-global "active" budget for the current tool call.
+// ---------------------------------------------------------------------------
+const DEFAULT_ANALYSIS_TIMEOUT_MS = 90_000;
+let activeBudget = null;
+let activeStart = 0;
+let activeTimeoutMs = 0;
+/**
+ * Resolve the analysis timeout in ms: an explicit per-call override wins, then
+ * the MEMLAB_ANALYSIS_TIMEOUT_MS env var, then the 90s default. A value <= 0
+ * disables the guardrail (returns 0 → never trips).
+ */
+export function getAnalysisTimeoutMs(override) {
+    if (override != null && Number.isFinite(override)) {
+        return override > 0 ? override : 0;
+    }
+    const env = Number(process.env.MEMLAB_ANALYSIS_TIMEOUT_MS);
+    if (Number.isFinite(env)) {
+        return env > 0 ? env : 0;
+    }
+    return DEFAULT_ANALYSIS_TIMEOUT_MS;
+}
+/** Arm the global budget for one tool call. `timeoutMs <= 0` disables it. */
+export function beginAnalysisBudget(timeoutMs) {
+    activeStart = Date.now();
+    activeTimeoutMs = timeoutMs;
+    activeBudget = timeoutMs > 0 ? makeScanBudget(timeoutMs) : null;
+}
+/** Disarm the global budget at the end of a tool call. */
+export function endAnalysisBudget() {
+    activeBudget = null;
+    activeTimeoutMs = 0;
+}
+/**
+ * Cooperative checkpoint for high-iteration loops (e.g. full-heap scans). Cheap
+ * no-op when no budget is armed; the clock is only sampled every few thousand
+ * calls, so this is meant for loops that run millions of times. For loops with
+ * few iterations but expensive bodies (e.g. per-class dominator aggregation),
+ * use {@link checkAnalysisDeadline} instead.
+ */
+export function tickAnalysis() {
+    activeBudget?.tick();
+}
+/**
+ * Unconditional deadline check (samples the clock every call). Use in loops
+ * with a small iteration count but an expensive body, where the sampled
+ * {@link tickAnalysis} would not check often enough to be effective.
+ */
+export function checkAnalysisDeadline() {
+    if (activeTimeoutMs > 0 && Date.now() - activeStart > activeTimeoutMs) {
+        throw new ScanTimeoutError(-1, activeTimeoutMs);
+    }
+}
+/** Wall-clock ms elapsed in the current tool call (0 if none armed). */
+export function activeElapsedMs() {
+    return activeStart ? Date.now() - activeStart : 0;
+}
+/** The timeout the active budget was armed with (0 if disabled/none). */
+export function activeTimeoutMs_() {
+    return activeTimeoutMs;
+}
+//# sourceMappingURL=analysis-budget.js.map

package/dist/analysis-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-budget.js","sourceRoot":"","sources":["../src/analysis-budget.ts"],"names":[],"mappings":"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"}

package/dist/guardrail.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Install a process-wide wall-clock guardrail around every tool call.
+ *
+ * Monkey-patches `server.tool` so each registered handler is wrapped: a budget
+ * is armed for the call (per-call `timeout_ms` arg > MEMLAB_ANALYSIS_TIMEOUT_MS
+ * env > 90s default), the heap-iteration funnels (see heap-state.ts) feed it,
+ * and if the budget trips the handler's loop throws a {@link ScanTimeoutError}
+ * which we convert into a clean "analysis stopped" result instead of letting a
+ * runaway scan wedge / OOM the server.
+ *
+ * Must be called BEFORE the tools are registered so they register wrapped.
+ */
+export declare function installAnalysisGuardrail(server: McpServer): void;
+//# sourceMappingURL=guardrail.d.ts.map

package/dist/guardrail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrail.d.ts","sourceRoot":"","sources":["../src/guardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAYvE;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2ChE"}

package/dist/guardrail.js

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import { beginAnalysisBudget, endAnalysisBudget, getAnalysisTimeoutMs, activeElapsedMs, ScanTimeoutError, } from './analysis-budget.js';
+import { toolResult } from './utils.js';
+/**
+ * Install a process-wide wall-clock guardrail around every tool call.
+ *
+ * Monkey-patches `server.tool` so each registered handler is wrapped: a budget
+ * is armed for the call (per-call `timeout_ms` arg > MEMLAB_ANALYSIS_TIMEOUT_MS
+ * env > 90s default), the heap-iteration funnels (see heap-state.ts) feed it,
+ * and if the budget trips the handler's loop throws a {@link ScanTimeoutError}
+ * which we convert into a clean "analysis stopped" result instead of letting a
+ * runaway scan wedge / OOM the server.
+ *
+ * Must be called BEFORE the tools are registered so they register wrapped.
+ */
+export function installAnalysisGuardrail(server) {
+    const origTool = server.tool.bind(server);
+    server.tool = (...toolArgs) => {
+        const name = String(toolArgs[0]);
+        const lastIdx = toolArgs.length - 1;
+        const handler = toolArgs[lastIdx];
+        if (typeof handler === 'function') {
+            const inner = handler;
+            toolArgs[lastIdx] = async (...hArgs) => {
+                // The SDK calls handler(args, extra) for schema tools, handler(extra)
+                // otherwise. Read an optional per-call timeout_ms off the params.
+                const params = hArgs[0];
+                const override = params && typeof params === 'object' && 'timeout_ms' in params
+                    ? params.timeout_ms
+                    : undefined;
+                const timeoutMs = getAnalysisTimeoutMs(typeof override === 'number' ? override : undefined);
+                beginAnalysisBudget(timeoutMs);
+                try {
+                    return await inner(...hArgs);
+                }
+                catch (e) {
+                    if (e instanceof ScanTimeoutError) {
+                        const ran = Math.round(activeElapsedMs() / 1000);
+                        const limit = Math.round(timeoutMs / 1000);
+                        return toolResult(`⚠ Analysis stopped: \`${name}\` exceeded the ${limit}s guardrail (ran ~${ran}s) and was halted to keep the MCP server responsive. No complete result was produced.\n\n` +
+                            `This usually means the heap is very large. Options:\n` +
+                            `- Narrow the query with filters (min_count / min_self_size / min_retained_size / a specific name or type).\n` +
+                            `- For memlab_class_histogram, pass include_retained_size:false for an instant count + self-size histogram.\n` +
+                            `- Prefer targeted node-id tools (memlab_object_shape, memlab_trace_dominators, memlab_retainer_trace) or memlab_auto_investigate over whole-heap scans.\n` +
+                            `- Raise the limit for this call where supported (timeout_ms) or globally via the MEMLAB_ANALYSIS_TIMEOUT_MS env var (current default ${limit}s; set 0 to disable).`);
+                    }
+                    throw e;
+                }
+                finally {
+                    endAnalysisBudget();
+                }
+            };
+        }
+        return origTool(...toolArgs);
+    };
+}
+//# sourceMappingURL=guardrail.js.map

package/dist/guardrail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrail.js","sourceRoot":"","sources":["../src/guardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAC,UAAU,EAAC,MAAM,YAAY,CAAC;AAItC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAiB;IACxD,MAAM,QAAQ,GAAI,MAAM,CAAC,IAAc,CAAC,IAAI,CAAC,MAAM,CAAU,CAAC;IAC7D,MAAmC,CAAC,IAAI,GAAG,CAAC,GAAG,QAAmB,EAAE,EAAE;QACrE,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,OAAgB,CAAC;YAC/B,QAAQ,CAAC,OAAO,CAAC,GAAG,KAAK,EAAE,GAAG,KAAgB,EAAE,EAAE;gBAChD,sEAAsE;gBACtE,kEAAkE;gBAClE,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBACxB,MAAM,QAAQ,GACZ,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,YAAY,IAAI,MAAM;oBAC5D,CAAC,CAAE,MAAiC,CAAC,UAAU;oBAC/C,CAAC,CAAC,SAAS,CAAC;gBAChB,MAAM,SAAS,GAAG,oBAAoB,CACpC,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CACpD,CAAC;gBACF,mBAAmB,CAAC,SAAS,CAAC,CAAC;gBAC/B,IAAI,CAAC;oBACH,OAAO,MAAM,KAAK,CAAC,GAAG,KAAK,CAAC,CAAC;gBAC/B,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,IAAI,CAAC,YAAY,gBAAgB,EAAE,CAAC;wBAClC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC,CAAC;wBACjD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;wBAC3C,OAAO,UAAU,CACf,yBAAyB,IAAI,mBAAmB,KAAK,qBAAqB,GAAG,2FAA2F;4BACtK,uDAAuD;4BACvD,8GAA8G;4BAC9G,8GAA8G;4BAC9G,2JAA2J;4BAC3J,wIAAwI,KAAK,uBAAuB,CACvK,CAAC;oBACJ,CAAC;oBACD,MAAM,CAAC,CAAC;gBACV,CAAC;wBAAS,CAAC;oBACT,iBAAiB,EAAE,CAAC;gBACtB,CAAC;YACH,CAAC,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC,GAAG,QAAQ,CAAC,CAAC;IAC/B,CAAC,CAAC;AACJ,CAAC"}

package/dist/heap-state.d.ts

@@ -10,6 +10,12 @@
 import type { IHeapSnapshot } from '@memlab/core';
 export type SnapshotEnv = 'browser' | 'node' | 'unknown';
 export interface SnapshotMetadata {
+    /**
+     * Stable, human-friendly handle for this snapshot within the session.
+     * Node ids are only valid relative to the snapshot they were read from;
+     * the handle identifies which loaded snapshot a given id belongs to.
+     */
+    handle: string;
     filePath: string;
     fileName: string;
     nodeCount: number;
@@ -17,9 +23,48 @@ export interface SnapshotMetadata {
     totalSize: number;
     env: SnapshotEnv;
 }
+/**
+ * Session-level output controls to trim repeated boilerplate tokens.
+ * - `quietHeader`: when true, the per-call snapshot header is printed only
+ *   once per loaded snapshot instead of on every tool result.
+ * - `suppressSuggestions`: when true, tools omit their "Suggested next steps"
+ *   trailers.
+ */
+export interface SessionConfig {
+    quietHeader: boolean;
+    suppressSuggestions: boolean;
+}
+export declare function getSessionConfig(): SessionConfig;
+export declare function setSessionConfig(patch: Partial<SessionConfig>): SessionConfig;
+/**
+ * Returns true exactly once per loaded snapshot when `quietHeader` is on,
+ * and always when it is off. Tools call this from `toolResult` to decide
+ * whether to prepend the snapshot header.
+ */
+export declare function shouldEmitHeader(): boolean;
 export declare function getSnapshot(): IHeapSnapshot;
 export declare function getFilePath(): string | null;
 export declare function getSnapshotEnv(): SnapshotEnv;
 export declare function getSnapshotMetadata(): SnapshotMetadata | null;
-export declare function setSnapshot(snapshot: IHeapSnapshot, filePath: string, metadata: Omit<SnapshotMetadata, 'filePath'>): void;
+/**
+ * Register a snapshot and make it the current one.
+ *
+ * @param snapshot parsed heap snapshot
+ * @param filePath absolute path the snapshot was loaded from
+ * @param metadata derived stats (handle is assigned here if not supplied)
+ * @param opts.alias preferred handle; falls back to the file name
+ * @param opts.replace when true (default), unload all other snapshots first,
+ *        preserving the single-resident memory profile. When false, keep
+ *        previously-loaded snapshots resident for diffing/comparison.
+ */
+export declare function setSnapshot(snapshot: IHeapSnapshot, filePath: string, metadata: Omit<SnapshotMetadata, 'filePath' | 'handle'>, opts?: {
+    alias?: string;
+    replace?: boolean;
+}): SnapshotMetadata;
+export declare function listSnapshots(): SnapshotMetadata[];
+export declare function getCurrentHandle(): string | null;
+export declare function getSnapshotByHandle(handle: string): IHeapSnapshot | null;
+export declare function getMetadataByHandle(handle: string): SnapshotMetadata | null;
+export declare function setCurrentSnapshot(handle: string): boolean;
+export declare function removeSnapshot(handle: string): boolean;
 //# sourceMappingURL=heap-state.d.ts.map

package/dist/heap-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heap-state.d.ts","sourceRoot":"","sources":["../src/heap-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAEhD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,WAAW,CAAC;CAClB;AAKD,wBAAgB,WAAW,IAAI,aAAa,CAK3C;AAED,wBAAgB,WAAW,IAAI,MAAM,GAAG,IAAI,CAE3C;AAED,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAE7D;AAED,wBAAgB,WAAW,CACzB,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,GAC3C,IAAI,CAGN"}
+{"version":3,"file":"heap-state.d.ts","sourceRoot":"","sources":["../src/heap-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAGhD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAgCzD,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,WAAW,CAAC;CAClB;AAaD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAWD,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAM7E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAK1C;AAgBD,wBAAgB,WAAW,IAAI,aAAa,CAO3C;AAED,wBAAgB,WAAW,IAAI,MAAM,GAAG,IAAI,CAG3C;AAED,wBAAgB,cAAc,IAAI,WAAW,CAG5C;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAG7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,QAAQ,CAAC,EACvD,IAAI,GAAE;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAM,GAC7C,gBAAgB,CAWlB;AAED,wBAAgB,aAAa,IAAI,gBAAgB,EAAE,CAElD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAExE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAE3E;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAK1D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOtD"}

package/dist/heap-state.js

@@ -7,25 +7,157 @@
  * @format
  * @oncall memory_lab
  */
-let currentSnapshot = null;
-let currentMetadata = null;
+import { tickAnalysis } from './analysis-budget.js';
+// Wrap the snapshot's full-collection iterators so every heap walk feeds the
+// active wall-clock guardrail (see analysis-budget.ts) without each tool having
+// to wire it in. `snapshot.nodes`/`snapshot.edges` are stable objects assigned
+// once at parse time, so patching their `forEach` once is durable; we mark the
+// collection to stay idempotent across the many getSnapshot() calls per session.
+const TICK_PATCHED = '__memlabTickPatched';
+function patchForEachMethods(collection, methods) {
+    if (!collection || typeof collection !== 'object')
+        return;
+    const c = collection;
+    if (c[TICK_PATCHED])
+        return;
+    for (const m of methods) {
+        const fn = c[m];
+        if (typeof fn !== 'function')
+            continue;
+        const orig = fn.bind(c);
+        c[m] = (cb) => orig((...args) => {
+            tickAnalysis();
+            return cb(...args);
+        });
+    }
+    Object.defineProperty(c, TICK_PATCHED, { value: true, enumerable: false });
+}
+function instrumentSnapshot(snapshot) {
+    const s = snapshot;
+    patchForEachMethods(s.nodes, ['forEach', 'forEachTraceable']);
+    patchForEachMethods(s.edges, ['forEach']);
+}
+// Multiple snapshots can be resident at once (for diffing and before/after
+// comparison). The "current" handle is the default target for tools that
+// don't take an explicit snapshot argument.
+const loaded = new Map();
+let currentHandle = null;
+const sessionConfig = {
+    quietHeader: false,
+    suppressSuggestions: false,
+};
+// Tracks whether the header has been emitted since the current snapshot was
+// loaded/activated, so `quietHeader` can print it exactly once.
+let headerEmitted = false;
+export function getSessionConfig() {
+    return sessionConfig;
+}
+export function setSessionConfig(patch) {
+    if (patch.quietHeader != null)
+        sessionConfig.quietHeader = patch.quietHeader;
+    if (patch.suppressSuggestions != null) {
+        sessionConfig.suppressSuggestions = patch.suppressSuggestions;
+    }
+    return sessionConfig;
+}
+/**
+ * Returns true exactly once per loaded snapshot when `quietHeader` is on,
+ * and always when it is off. Tools call this from `toolResult` to decide
+ * whether to prepend the snapshot header.
+ */
+export function shouldEmitHeader() {
+    if (!sessionConfig.quietHeader)
+        return true;
+    if (headerEmitted)
+        return false;
+    headerEmitted = true;
+    return true;
+}
+function uniqueHandle(base) {
+    // Sanitize to a short slug, then disambiguate against existing handles.
+    const slug = base
+        .replace(/\.heapsnapshot$/i, '')
+        .replace(/[^A-Za-z0-9._-]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 40) || 'snapshot';
+    if (!loaded.has(slug))
+        return slug;
+    let i = 2;
+    while (loaded.has(`${slug}#${i}`))
+        i++;
+    return `${slug}#${i}`;
+}
 export function getSnapshot() {
-    if (!currentSnapshot) {
+    const entry = currentHandle ? loaded.get(currentHandle) : undefined;
+    if (!entry) {
         throw new Error('No heap snapshot loaded. Use memlab_load_snapshot first.');
     }
-    return currentSnapshot;
+    instrumentSnapshot(entry.snapshot);
+    return entry.snapshot;
 }
 export function getFilePath() {
-    return currentMetadata?.filePath ?? null;
+    if (!currentHandle)
+        return null;
+    return loaded.get(currentHandle)?.metadata.filePath ?? null;
 }
 export function getSnapshotEnv() {
-    return currentMetadata?.env ?? 'unknown';
+    if (!currentHandle)
+        return 'unknown';
+    return loaded.get(currentHandle)?.metadata.env ?? 'unknown';
 }
 export function getSnapshotMetadata() {
-    return currentMetadata;
+    if (!currentHandle)
+        return null;
+    return loaded.get(currentHandle)?.metadata ?? null;
 }
-export function setSnapshot(snapshot, filePath, metadata) {
-    currentSnapshot = snapshot;
-    currentMetadata = { filePath, ...metadata };
+/**
+ * Register a snapshot and make it the current one.
+ *
+ * @param snapshot parsed heap snapshot
+ * @param filePath absolute path the snapshot was loaded from
+ * @param metadata derived stats (handle is assigned here if not supplied)
+ * @param opts.alias preferred handle; falls back to the file name
+ * @param opts.replace when true (default), unload all other snapshots first,
+ *        preserving the single-resident memory profile. When false, keep
+ *        previously-loaded snapshots resident for diffing/comparison.
+ */
+export function setSnapshot(snapshot, filePath, metadata, opts = {}) {
+    const replace = opts.replace ?? true;
+    if (replace) {
+        loaded.clear();
+    }
+    const handle = uniqueHandle(opts.alias || metadata.fileName);
+    const full = { handle, filePath, ...metadata };
+    loaded.set(handle, { snapshot, metadata: full });
+    currentHandle = handle;
+    headerEmitted = false;
+    return full;
+}
+export function listSnapshots() {
+    return [...loaded.values()].map(l => l.metadata);
+}
+export function getCurrentHandle() {
+    return currentHandle;
+}
+export function getSnapshotByHandle(handle) {
+    return loaded.get(handle)?.snapshot ?? null;
+}
+export function getMetadataByHandle(handle) {
+    return loaded.get(handle)?.metadata ?? null;
+}
+export function setCurrentSnapshot(handle) {
+    if (!loaded.has(handle))
+        return false;
+    currentHandle = handle;
+    headerEmitted = false;
+    return true;
+}
+export function removeSnapshot(handle) {
+    const existed = loaded.delete(handle);
+    if (existed && currentHandle === handle) {
+        currentHandle = loaded.size > 0 ? [...loaded.keys()][0] : null;
+        headerEmitted = false;
+    }
+    return existed;
 }
 //# sourceMappingURL=heap-state.js.map