@memlab/mcp-server 2.18.1 → 2.86.0

package/dist/tools/map-entries.js

@@ -0,0 +1,139 @@
+/**
+ * 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 { z } from 'zod';
+import { getSnapshot } from '../heap-state.js';
+import { formatBytes, formatNumber, markdownTable, truncateNodeName, errorResult, toolResult, enumerateMapEntries, enumerateSetElements, } from '../utils.js';
+// Render a node as a short label, inlining the string value for string nodes so
+// cache keys are visible verbatim (the whole point of enumerating a cache Map).
+function describeNode(node, maxLen) {
+    if (node.isString) {
+        const strNode = node.toStringNode();
+        if (strNode) {
+            const val = strNode.stringValue;
+            const shown = val.length > maxLen ? val.slice(0, maxLen) + '...' : val;
+            return `"${shown}"`;
+        }
+    }
+    return `${truncateNodeName(node.name, node.type, node.self_size, maxLen)} (${node.type})`;
+}
+export function registerMapEntries(server) {
+    server.tool('memlab_map_entries', '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.', {
+        node_id: z
+            .number()
+            .describe('REQUIRED. The numeric ID of a single Map or Set node. Find candidates with memlab_find_nodes_by_class("Map") or ("Set"); there is no scan-all mode. For WeakMaps use memlab_weakmap_entries.'),
+        limit: z
+            .number()
+            .optional()
+            .default(20)
+            .describe('Maximum number of entries to return (default 20)'),
+        sort_by: z
+            .enum(['retained_size', 'retained', 'key_name', 'insertion'])
+            .optional()
+            .default('retained_size')
+            .describe('Sort by entry retained size ("retained_size", alias "retained"), key name ("key_name"), or backing-store order ("insertion"). Default: retained_size.'),
+    }, async ({ node_id, limit, sort_by }) => {
+        try {
+            const snapshot = getSnapshot();
+            const node = snapshot.getNodeById(node_id);
+            if (!node) {
+                return errorResult(`Node with id ${node_id} not found`);
+            }
+            const isMap = node.name === 'Map';
+            const isSet = node.name === 'Set';
+            if (!isMap && !isSet) {
+                return errorResult(`@${node_id} is a ${node.name} (${node.type}), not a Map or Set. ` +
+                    `Use \`memlab_find_nodes_by_class("Map")\` or \`("Set")\` to find ` +
+                    `instances. For WeakMaps use \`memlab_weakmap_entries\`.`);
+            }
+            // Enumerate via the shared, index-aware backing-store walk
+            // (`src/utils.ts`). It pairs each key with the value in the immediately
+            // following FixedArray slot INDEX, so a Map with SMI values (whose value
+            // slots emit no edge) reports value:null instead of mispairing the key
+            // with the next entry's key. Set elements come back one-per-slot.
+            const entries = (isSet
+                ? enumerateSetElements(node).map(k => ({ key: k, value: null }))
+                : enumerateMapEntries(node)).map(e => ({
+                key: e.key,
+                value: e.value,
+                keyRetained: e.key.retainedSize,
+                valueRetained: e.value ? e.value.retainedSize : 0,
+            }));
+            if (entries.length === 0) {
+                return toolResult(`${node.name} @${node_id} has no enumerable entries.\n\n` +
+                    `**Note:** the backing store may hold primitive (SMI/number/bool) ` +
+                    `values inline rather than as heap objects, or V8's layout may not ` +
+                    `expose them in this snapshot. Try \`memlab_get_references(${node_id})\` ` +
+                    `to inspect the raw structure.`);
+            }
+            if (sort_by === 'retained_size' || sort_by === 'retained') {
+                entries.sort((a, b) => b.keyRetained +
+                    b.valueRetained -
+                    (a.keyRetained + a.valueRetained));
+            }
+            else if (sort_by === 'key_name') {
+                entries.sort((a, b) => a.key.name.localeCompare(b.key.name));
+            } // 'insertion' keeps backing-store order
+            const shown = entries.slice(0, limit);
+            const totalEntries = entries.length;
+            const totalKeyRetained = entries.reduce((s, e) => s + e.keyRetained, 0);
+            const totalValueRetained = entries.reduce((s, e) => s + e.valueRetained, 0);
+            let entryTable;
+            if (isSet) {
+                const headers = ['Value ID', 'Value', 'Retained'];
+                const rightCols = new Set([2]);
+                const rows = shown.map(e => [
+                    `@${e.key.id}`,
+                    describeNode(e.key, 60),
+                    formatBytes(e.keyRetained),
+                ]);
+                entryTable = markdownTable(headers, rows, rightCols);
+            }
+            else {
+                const headers = [
+                    'Key ID',
+                    'Key',
+                    'Value ID',
+                    'Value',
+                    'Value Retained',
+                ];
+                const rightCols = new Set([4]);
+                const rows = shown.map(e => [
+                    `@${e.key.id}`,
+                    describeNode(e.key, 60),
+                    e.value ? `@${e.value.id}` : '—',
+                    e.value ? describeNode(e.value, 40) : '—',
+                    formatBytes(e.valueRetained),
+                ]);
+                entryTable = markdownTable(headers, rows, rightCols);
+            }
+            const lines = [
+                `${node.name} @${node_id}: ${formatNumber(totalEntries)} entries` +
+                    (totalEntries > limit ? ` (showing top ${limit})` : ''),
+                isSet
+                    ? `Total retained: ${formatBytes(totalKeyRetained)}`
+                    : `Total key retained: ${formatBytes(totalKeyRetained)}, ` +
+                        `total value retained: ${formatBytes(totalValueRetained)}`,
+                '',
+                entryTable,
+            ];
+            if (isMap) {
+                lines.push('', '_Keys are paired with the value in the immediately-following backing-' +
+                    'store slot INDEX. Entries whose value is an inline SMI (small int) ' +
+                    'emit no heap edge, so their value shows as "—" (primitive, not ' +
+                    'captured) rather than being mispaired with the next entry._');
+            }
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=map-entries.js.map

package/dist/tools/map-entries.js.map

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

package/dist/tools/match-object.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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';
+export declare function registerMatchObject(server: McpServer): void;
+//# sourceMappingURL=match-object.d.ts.map

package/dist/tools/match-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match-object.d.ts","sourceRoot":"","sources":["../../src/tools/match-object.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAmEvE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAoJ3D"}

package/dist/tools/match-object.js

@@ -0,0 +1,165 @@
+/**
+ * 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 { z } from 'zod';
+import { getSnapshot, getSnapshotByHandle, getMetadataByHandle, listSnapshots, } from '../heap-state.js';
+import { formatBytes, formatNumber, markdownTable, truncateNodeName, errorResult, toolResult, } from '../utils.js';
+import { getFirstNonFrameworkRetainer } from './detached-dom.js';
+// Property names sampled to fingerprint an object's shape. Matches the cap the
+// other shape-based tools use, so a fingerprint is comparable across them.
+const SHAPE_PROP_CAP = 12;
+// Cap on candidates scored per match. A class with a million instances would
+// otherwise turn an identity lookup into a full-heap ranking problem.
+const MAX_CANDIDATES = 5000;
+/**
+ * Property-name fingerprint, or null when the node is too wide to fingerprint.
+ *
+ * Returning an empty array for a wide node was wrong in a way that inverted the
+ * result: `jaccard(empty, empty)` is 1, so two wide objects of the same class
+ * scored a PERFECT shape match without a single property having been compared.
+ * "Not computed" and "genuinely has no properties" have to be distinguishable.
+ */
+function shapeOf(node) {
+    const props = [];
+    if (node.edge_count > 1024)
+        return null;
+    node.forEachReference(edge => {
+        if (edge.type === 'property') {
+            props.push(String(edge.name_or_index));
+            if (props.length >= SHAPE_PROP_CAP)
+                return { stop: true };
+        }
+    });
+    props.sort();
+    return props;
+}
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter++;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+export function registerMatchObject(server) {
+    server.tool('memlab_match_object', '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.', {
+        node_id: z
+            .number()
+            .describe('Node id in the CURRENT snapshot to find a match for.'),
+        target_handle: z
+            .string()
+            .describe('Handle of the other resident snapshot to search (memlab_snapshots lists them).'),
+        limit: z
+            .number()
+            .optional()
+            .default(5)
+            .describe('Maximum candidates to return (default 5).'),
+        min_score: z
+            .number()
+            .optional()
+            .default(0.5)
+            .describe('Minimum match score, 0-1 (default 0.5). Score is 0.7×shape overlap + 0.3×retainer-path agreement; name and type must match exactly regardless.'),
+    }, async ({ node_id, target_handle, limit, min_score }) => {
+        try {
+            const source = getSnapshot();
+            const target = getSnapshotByHandle(target_handle);
+            if (target == null) {
+                const available = listSnapshots()
+                    .map(m => m.handle)
+                    .join(', ');
+                return errorResult(`No resident snapshot with handle "${target_handle}". Resident: ${available || '(none)'}. Load the other snapshot with memlab_load_snapshot({file_path, keep_previous: true}).`);
+            }
+            const targetMeta = getMetadataByHandle(target_handle);
+            if (targetMeta?.light) {
+                return errorResult(`Snapshot "${target_handle}" was loaded in LIGHT mode; matching compares retained sizes and retainer paths, which it does not have. Reload it without light.`);
+            }
+            const src = source.getNodeById(node_id);
+            if (!src)
+                return errorResult(`Node @${node_id} not found.`);
+            const srcShapeProps = shapeOf(src);
+            const srcShape = srcShapeProps == null ? null : new Set(srcShapeProps);
+            const srcRetainer = getFirstNonFrameworkRetainer(src);
+            const candidates = [];
+            let sameClass = 0;
+            let truncated = false;
+            target.nodes.forEach(node => {
+                if (node.id <= 3)
+                    return;
+                if (node.name !== src.name || node.type !== src.type)
+                    return;
+                sameClass++;
+                if (candidates.length >= MAX_CANDIDATES) {
+                    truncated = true;
+                    return;
+                }
+                const candProps = shapeOf(node);
+                // Either side being unfingerprintable means the shape term carries no
+                // evidence; score it 0 rather than 1 so a wide object cannot reach a
+                // perfect score on class and retainer alone.
+                const shapeKnown = srcShape != null && candProps != null;
+                const shapeScore = shapeKnown
+                    ? jaccard(srcShape, new Set(candProps))
+                    : 0;
+                const retainerMatch = srcRetainer !== '(unknown)' &&
+                    getFirstNonFrameworkRetainer(node) === srcRetainer;
+                const score = 0.7 * shapeScore + 0.3 * (retainerMatch ? 1 : 0);
+                candidates.push({ node, score, shapeScore, shapeKnown, retainerMatch });
+            });
+            if (sameClass === 0) {
+                return toolResult(`No node named \`${src.name}\` (${src.type}) exists in "${target_handle}". ` +
+                    'The class is absent from that snapshot entirely — which is itself the answer if you were asking whether these objects survive.');
+            }
+            candidates.sort((a, b) => b.score - a.score);
+            const shown = candidates
+                .filter(c => c.score >= min_score)
+                .slice(0, limit);
+            const lines = [
+                `## Cross-snapshot match for @${src.id} \`${truncateNodeName(src.name, src.type, src.self_size, 50)}\` (${src.type})`,
+                '',
+                `Source retains ${formatBytes(src.retainedSize)}; searched **${formatNumber(sameClass)}** same-class node(s) in "${target_handle}".`,
+                '',
+            ];
+            if (shown.length === 0) {
+                lines.push(`No candidate scored at or above ${min_score}. The class exists there but no instance resembles this one in shape or retainer path — lower \`min_score\` to see the closest anyway.`);
+                return toolResult(lines.join('\n'));
+            }
+            lines.push(markdownTable([
+                'Candidate',
+                'Score',
+                'Shape',
+                'Same retainer',
+                'Retained',
+                'Δ vs source',
+            ], shown.map(c => {
+                const delta = c.node.retainedSize - src.retainedSize;
+                return [
+                    `@${c.node.id}`,
+                    c.score.toFixed(2),
+                    c.shapeKnown ? `${Math.round(c.shapeScore * 100)}%` : 'n/a',
+                    c.retainerMatch ? 'yes' : 'no',
+                    formatBytes(c.node.retainedSize),
+                    `${delta >= 0 ? '+' : '−'}${formatBytes(Math.abs(delta))}`,
+                ];
+            }), new Set([1, 2, 4, 5])), '', `_Source retainer: \`${srcRetainer}\`._`);
+            if (truncated) {
+                lines.push('', `_⚠ Scoring stopped after ${formatNumber(MAX_CANDIDATES)} same-class candidates; ${formatNumber(sameClass)} exist. With this many instances a per-object identity match is weak evidence — compare counts and shapes instead._`);
+            }
+            lines.push('', '_Identity across captures is INFERRED from class, shape and retainer path — node ids are per-capture and cannot confirm it. A high score means "indistinguishable by the available evidence", not "the same object". Confirm with `memlab_retainer_trace` on both sides before drawing a conclusion._');
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=match-object.js.map

package/dist/tools/match-object.js.map

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

package/dist/tools/metric.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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';
+export declare function metricStorePath(): string;
+export declare function registerMetric(server: McpServer): void;
+//# sourceMappingURL=metric.d.ts.map

package/dist/tools/metric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric.d.ts","sourceRoot":"","sources":["../../src/tools/metric.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAuCvE,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAuCD,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA4KtD"}

package/dist/tools/metric.js

@@ -0,0 +1,185 @@
+/**
+ * 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 fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { z } from 'zod';
+import { getSnapshotMetadata } from '../heap-state.js';
+import { errorResult, formatNumber, markdownTable, toolResult, } from '../utils.js';
+const MAX_POINTS_PER_METRIC = 200;
+export function metricStorePath() {
+    const dir = process.env.MEMLAB_STATE_DIR ?? path.join(os.homedir(), '.memlab');
+    return path.join(dir, 'metrics.json');
+}
+function readStore() {
+    const file = metricStorePath();
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed?.version === 1 && parsed.metrics != null)
+            return parsed;
+    }
+    catch {
+        // A missing or corrupt store is not an error worth failing a measurement
+        // over — start a fresh one rather than losing the number being recorded.
+    }
+    return { version: 1, metrics: {} };
+}
+function writeStore(store) {
+    const file = metricStorePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(store, null, 2));
+}
+function formatValue(p) {
+    return `${formatNumber(Math.round(p.value * 100) / 100)}${p.unit === '' ? '' : ` ${p.unit}`}`;
+}
+function trendLine(points) {
+    if (points.length < 2) {
+        return '_One point so far — record the same metric again after the next capture to get a trend._';
+    }
+    const first = points[0];
+    const last = points[points.length - 1];
+    if (first.unit !== last.unit) {
+        return `⚠ Units changed across points (\`${first.unit}\` → \`${last.unit}\`); the delta below is arithmetic only and may be meaningless.`;
+    }
+    const delta = last.value - first.value;
+    const pct = first.value !== 0 ? (delta / Math.abs(first.value)) * 100 : 0;
+    const dir = delta > 0 ? 'up' : delta < 0 ? 'down' : 'unchanged';
+    return `**${dir}** ${formatNumber(Math.abs(Math.round(delta * 100) / 100))} ${last.unit} across ${points.length} points (${first.label} → ${last.label})${first.value !== 0 ? `, ${pct >= 0 ? '+' : ''}${pct.toFixed(1)}%` : ''}.`;
+}
+export function registerMetric(server) {
+    server.tool('memlab_metric', 'Record a measurement under a name and keep it across sessions, so a number measured today can be compared with one measured next week.\n\n' +
+        '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.\n\n' +
+        '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`).', {
+        mode: z
+            .enum(['record', 'history', 'list', 'forget'])
+            .optional()
+            .default('record')
+            .describe('What to do (default "record").'),
+        name: z
+            .string()
+            .optional()
+            .describe('Metric name — reuse the SAME name across sessions for anything you want to compare, e.g. "wa.listener_records" or "wa.heap_after_100_msgs".'),
+        value: z.number().optional().describe('The measured value to record.'),
+        unit: z
+            .string()
+            .optional()
+            .default('')
+            .describe('Unit for the value, e.g. "bytes", "MB", "objects", "per cycle". Recorded verbatim and compared on read, so keep it consistent for one metric.'),
+        label: z
+            .string()
+            .optional()
+            .describe('What this point describes — the build, gate state or rung, e.g. "gate off, 100 msgs". Defaults to the active snapshot\'s name.'),
+        note: z
+            .string()
+            .optional()
+            .describe('Optional free text: how it was measured, which tool call produced it, what to be careful about.'),
+        limit: z
+            .number()
+            .optional()
+            .default(20)
+            .describe('Rows to show in history/list (default 20).'),
+    }, async ({ mode, name, value, unit, label, note, limit }) => {
+        try {
+            const store = readStore();
+            if (mode === 'list') {
+                const names = Object.keys(store.metrics).sort();
+                if (names.length === 0) {
+                    return toolResult(`No metrics recorded yet (store: \`${metricStorePath()}\`).\n\nRecord one with \`memlab_metric({name: "...", value: 123, unit: "objects"})\` — the point of it is the comparison you will want in a later session.`);
+                }
+                const rows = names.slice(0, limit).map(n => {
+                    const points = store.metrics[n];
+                    const last = points[points.length - 1];
+                    return [
+                        n,
+                        formatNumber(points.length),
+                        formatValue(last),
+                        last.label,
+                    ];
+                });
+                return toolResult([
+                    '## Recorded metrics',
+                    '',
+                    markdownTable(['Metric', 'Points', 'Latest', 'Latest label'], rows, new Set([1, 2])),
+                    '',
+                    `Store: \`${metricStorePath()}\`. Use \`memlab_metric({mode: "history", name})\` for the full series.`,
+                ].join('\n'));
+            }
+            if (name == null || name === '') {
+                return errorResult(new Error('Pass `name` — every metric is identified by its name.'));
+            }
+            if (mode === 'forget') {
+                if (store.metrics[name] == null) {
+                    return toolResult(`No metric named \`${name}\`; nothing to drop.`);
+                }
+                delete store.metrics[name];
+                writeStore(store);
+                return toolResult(`Dropped \`${name}\`.`);
+            }
+            if (mode === 'history') {
+                const points = store.metrics[name];
+                if (points == null || points.length === 0) {
+                    return toolResult(`No points recorded for \`${name}\`. \`memlab_metric({mode: "list"})\` shows what is recorded.`);
+                }
+                const shown = points.slice(-limit);
+                const rows = shown.map(p => [
+                    String(p.seq),
+                    p.label,
+                    formatValue(p),
+                    p.note ?? '',
+                ]);
+                return toolResult([
+                    `## \`${name}\``,
+                    '',
+                    trendLine(points),
+                    '',
+                    markdownTable(['#', 'Label', 'Value', 'Note'], rows, new Set([2])),
+                    points.length > shown.length
+                        ? `\n_Showing the last ${shown.length} of ${points.length} points._`
+                        : '',
+                    '',
+                    '_Points are compared in the order they were recorded, which is not necessarily chronological order of the captures they describe — the label is the only thing that says what a point is._',
+                ].join('\n'));
+            }
+            if (value == null) {
+                return errorResult(new Error('Pass `value` — the number to record under this name.'));
+            }
+            const meta = getSnapshotMetadata();
+            const points = store.metrics[name] ?? [];
+            const point = {
+                value,
+                unit: unit ?? '',
+                label: label ?? meta?.fileName ?? meta?.handle ?? 'unlabelled',
+                note,
+                seq: points.length + 1,
+            };
+            points.push(point);
+            // Bounded: a metric recorded in a loop should not grow the store
+            // without limit, and the oldest points are the least useful.
+            store.metrics[name] = points.slice(-MAX_POINTS_PER_METRIC);
+            writeStore(store);
+            const prev = points.length >= 2 ? points[points.length - 2] : null;
+            const lines = [
+                `Recorded \`${name}\` = **${formatValue(point)}** (${point.label}), point ${point.seq}.`,
+            ];
+            if (prev != null && prev.unit === point.unit) {
+                const delta = point.value - prev.value;
+                lines.push('', `Previous point (${prev.label}): ${formatValue(prev)} — ${delta === 0 ? 'no change' : `${delta > 0 ? '+' : ''}${formatNumber(Math.round(delta * 100) / 100)} ${point.unit}`}.`);
+            }
+            if (point.label === 'unlabelled') {
+                lines.push('', '⚠ No label and no active snapshot, so this point records a number with nothing saying what it describes. Pass `label` — in a later session that is all there is to go on.');
+            }
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=metric.js.map

package/dist/tools/metric.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric.js","sourceRoot":"","sources":["../../src/tools/metric.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,mBAAmB,EAAC,MAAM,kBAAkB,CAAC;AACrD,OAAO,EACL,WAAW,EACX,YAAY,EACZ,aAAa,EACb,UAAU,GACX,MAAM,aAAa,CAAC;AA0BrB,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GACP,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACrE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,IAAI,GAAG,eAAe,EAAE,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;QACxE,IAAI,MAAM,EAAE,OAAO,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,IAAI,IAAI;YAAE,OAAO,MAAM,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;QACzE,yEAAyE;IAC3E,CAAC;IACD,OAAO,EAAC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAC,CAAC;AACnC,CAAC;AAED,SAAS,UAAU,CAAC,KAAkB;IACpC,MAAM,IAAI,GAAG,eAAe,EAAE,CAAC;IAC/B,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAC,SAAS,EAAE,IAAI,EAAC,CAAC,CAAC;IACpD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,WAAW,CAAC,CAAc;IACjC,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;AAChG,CAAC;AAED,SAAS,SAAS,CAAC,MAAqB;IACtC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,0FAA0F,CAAC;IACpG,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvC,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QAC7B,OAAO,oCAAoC,KAAK,CAAC,IAAI,UAAU,IAAI,CAAC,IAAI,iEAAiE,CAAC;IAC5I,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACvC,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1E,MAAM,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;IAChE,OAAO,KAAK,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,WAAW,MAAM,CAAC,MAAM,YAAY,KAAK,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;AACrO,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAiB;IAC9C,MAAM,CAAC,IAAI,CACT,eAAe,EACf,4IAA4I;QAC1I,0WAA0W;QAC1W,4NAA4N,EAC9N;QACE,IAAI,EAAE,CAAC;aACJ,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;aAC7C,QAAQ,EAAE;aACV,OAAO,CAAC,QAAQ,CAAC;aACjB,QAAQ,CAAC,gCAAgC,CAAC;QAC7C,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,6IAA6I,CAC9I;QACH,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;QACtE,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CACP,+IAA+I,CAChJ;QACH,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,gIAAgI,CACjI;QACH,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,iGAAiG,CAClG;QACH,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CAAC,4CAA4C,CAAC;KAC1D,EACD,KAAK,EAAE,EAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAC,EAAE,EAAE;QACtD,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;YAE1B,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBACpB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;gBAChD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACvB,OAAO,UAAU,CACf,qCAAqC,eAAe,EAAE,6JAA6J,CACpN,CAAC;gBACJ,CAAC;gBACD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;oBACzC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;oBAChC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;oBACvC,OAAO;wBACL,CAAC;wBACD,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC;wBAC3B,WAAW,CAAC,IAAI,CAAC;wBACjB,IAAI,CAAC,KAAK;qBACX,CAAC;gBACJ,CAAC,CAAC,CAAC;gBACH,OAAO,UAAU,CACf;oBACE,qBAAqB;oBACrB,EAAE;oBACF,aAAa,CACX,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,CAAC,EAC9C,IAAI,EACJ,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAChB;oBACD,EAAE;oBACF,YAAY,eAAe,EAAE,yEAAyE;iBACvG,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;YACJ,CAAC;YAED,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;gBAChC,OAAO,WAAW,CAChB,IAAI,KAAK,CAAC,uDAAuD,CAAC,CACnE,CAAC;YACJ,CAAC;YAED,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACtB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;oBAChC,OAAO,UAAU,CAAC,qBAAqB,IAAI,sBAAsB,CAAC,CAAC;gBACrE,CAAC;gBACD,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC3B,UAAU,CAAC,KAAK,CAAC,CAAC;gBAClB,OAAO,UAAU,CAAC,aAAa,IAAI,KAAK,CAAC,CAAC;YAC5C,CAAC;YAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACnC,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC1C,OAAO,UAAU,CACf,4BAA4B,IAAI,+DAA+D,CAChG,CAAC;gBACJ,CAAC;gBACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;gBACnC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC1B,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;oBACb,CAAC,CAAC,KAAK;oBACP,WAAW,CAAC,CAAC,CAAC;oBACd,CAAC,CAAC,IAAI,IAAI,EAAE;iBACb,CAAC,CAAC;gBACH,OAAO,UAAU,CACf;oBACE,QAAQ,IAAI,IAAI;oBAChB,EAAE;oBACF,SAAS,CAAC,MAAM,CAAC;oBACjB,EAAE;oBACF,aAAa,CACX,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAC/B,IAAI,EACJ,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CACb;oBACD,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM;wBAC1B,CAAC,CAAC,uBAAuB,KAAK,CAAC,MAAM,OAAO,MAAM,CAAC,MAAM,WAAW;wBACpE,CAAC,CAAC,EAAE;oBACN,EAAE;oBACF,4LAA4L;iBAC7L,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;YACJ,CAAC;YAED,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;gBAClB,OAAO,WAAW,CAChB,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAClE,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,GAAG,mBAAmB,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACzC,MAAM,KAAK,GAAgB;gBACzB,KAAK;gBACL,IAAI,EAAE,IAAI,IAAI,EAAE;gBAChB,KAAK,EAAE,KAAK,IAAI,IAAI,EAAE,QAAQ,IAAI,IAAI,EAAE,MAAM,IAAI,YAAY;gBAC9D,IAAI;gBACJ,GAAG,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC;aACvB,CAAC;YACF,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,iEAAiE;YACjE,6DAA6D;YAC7D,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC;YAC3D,UAAU,CAAC,KAAK,CAAC,CAAC;YAElB,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YACnE,MAAM,KAAK,GAAG;gBACZ,cAAc,IAAI,UAAU,WAAW,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,GAAG,GAAG;aACzF,CAAC;YACF,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;gBAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;gBACvC,KAAK,CAAC,IAAI,CACR,EAAE,EACF,mBAAmB,IAAI,CAAC,KAAK,MAAM,WAAW,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,EAAE,GAAG,CAC/K,CAAC;YACJ,CAAC;YACD,IAAI,KAAK,CAAC,KAAK,KAAK,YAAY,EAAE,CAAC;gBACjC,KAAK,CAAC,IAAI,CACR,EAAE,EACF,2KAA2K,CAC5K,CAAC;YACJ,CAAC;YACD,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/module-attribution.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { IHeapNode, IHeapSnapshot } from '@memlab/core';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+interface Registry {
+    node: IHeapNode;
+    edgeName: string;
+    /** module-export node id -> module id/name */
+    moduleByNodeId: Map<number, string>;
+}
+export declare function findModuleRegistries(snapshot: IHeapSnapshot): Registry[];
+interface ModuleStat {
+    module: string;
+    selfBytes: number;
+    nodes: number;
+}
+/**
+ * One pass with a memo indexed by `nodeIndex`: each node inherits its immediate
+ * dominator's module unless it IS a module export, so the whole heap is
+ * attributed in O(N) rather than one bounded walk per node.
+ */
+export declare function attributeByModule(snapshot: IHeapSnapshot, registries: Registry[]): {
+    stats: ModuleStat[];
+    attributed: number;
+    unattributed: number;
+};
+export declare function registerModuleAttribution(server: McpServer): void;
+export {};
+//# sourceMappingURL=module-attribution.d.ts.map

package/dist/tools/module-attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-attribution.d.ts","sourceRoot":"","sources":["../../src/tools/module-attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAgDvE,UAAU,QAAQ;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,aAAa,GAAG,QAAQ,EAAE,CA0BxE;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,aAAa,EACvB,UAAU,EAAE,QAAQ,EAAE,GACrB;IAAC,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAC,CA+DjE;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6GjE"}