Memorydetective

memorydetective

English · Português brasileiro

Diagnose iOS retain cycles and performance regressions from your chat window. No Xcode required.

Highlights

• CLI-driven leak hunting. Read .memgraph files captured by Xcode (or by memorydetective itself on simulators), find ROOT CYCLEs, classify them against known SwiftUI/Combine patterns, and get a one-liner fix hint. All from a script or a chat.
• MCP-native. Plugs into Claude Code, Claude Desktop, Cursor, Cline, and any other MCP client. The agent drives the full investigate → classify → suggest-fix loop without you opening Instruments.
• Honest about its limits. No mocked outputs, no over-promises. Hangs analysis works clean from xctrace; sample-level Time Profile is parsed when xctrace symbolicates the trace and returns a structured workaround notice when it can't (the underlying xctrace SIGSEGV on heavy unsymbolicated traces is an Apple-side limitation we surface explicitly). Memory Graph capture works on Mac apps and iOS simulator; physical iOS devices still need Xcode.

What's new in v1.18 (2026-05-17): MetricKit + audit-close. `analyzeMetricKitPayload` is the 42nd MCP tool: ingests Apple MetricKit .mxdiagnostic JSON payloads from real-device TestFlight / App Store builds (post-mortem production diagnostics, no MCP competitor covers this lane today). Three actionable outputs: crash clusters by exception type / binary / top frame, hang hotspots with localized-duration parsing ("5.4 sec" / "20秒"), CPU + disk exceptions. Cross-tool chain hints (e.g. objc_release-style top frame surfaces a findCycles suggestion). Plus three audit-close items: open-enum SupportStatusKind (downstream consumers add kinds without a breaking type bump), invocation-scoped schemaDiscovery cache (summarizeTrace end-to-end shaved from ~28s to ~15s on real Apple traces via single up-front TOC fetch), and local-only integration tests against real Apple .trace bundles (closes the v1.14 P+O drift class for good). 701 → 757 tests. 41 → 42 MCP tools.

Also recent (v1.17): reliability pass. 14 bug fixes across three tiers. Headlines: strtobool env truthy parsing, verifyFix whitelist match modes (exact / substring / regex), recordViaInstrumentsApp catches traces saved outside watchDir, inspectTrace fault-tolerant fallback, configurable countAlive framework-noise filter, variable-size class min/max/median.

And v1.16: macOS 26.x recording-unblock release. New recordViaInstrumentsApp MCP tool wraps the Instruments.app GUI flow: opens the app, surfaces step-by-step instructions, watches a directory for the saved .trace, and chains into inspectTrace on success. Until Apple fixes the xcrun xctrace record regression on macOS 26.x sims, this is the automated path.

And v1.15: schema coverage + verify-fix UX. Three new MCP trace tools filled the remaining schema gap: analyzeMemoryFootprint (38th, VM resident / dirty / virtual + jetsam diagnosis), analyzeEnergyImpact (39th, battery drain investigation), analyzeLeakTimeline (40th, xctrace's leaks instrument as a time series). summarizeTrace now chains analyzeNetworkActivity. replayScenario captures simulator screenshots per step.

Earlier: v1.14 trace-side reliability, analyzeNetworkActivity, unified supportStatus[], FLEX-inspired countAlive size view, MLeaksFinder + DebugSwift-inspired verifyFix whitelist. v1.13 shipped summarizeTrace + /summarize-trace MCP prompt. v1.12 completed reference-tree propagation. v1.11 added inspectTrace, diffMemgraphs reference-tree. v1.9 shipped analyzeAbandonedMemory, detectLeaksInXCTest, cleanupTraces, mainThreadViolations. Full notes in CHANGELOG.

Heads up for macOS 26.x users: Apple shipped a task_for_pid kernel regression on macOS 26.x that blocks leaks --outputGraph, heap, AND xctrace --template Allocations against iOS simulator processes regardless of MallocStackLogging. Even Xcode's "View Memory Graph Hierarchy" hits it unless Malloc Stack Logging is enabled in the scheme's Diagnostics tab. memorydetective surfaces this as a proactive platformAdvisory on the first capture-class tool call, plus a workaroundNotice with issue: "macos-26-task-for-pid-broken" if leaks is invoked. The most reliable workaround today is to target an iOS 18 simulator runtime (install via Xcode > Settings > Platforms > +iOS 18.x). Empirically validated in the notelet investigation 2026-05-12 where three independent CLI memory-introspection paths all failed before iOS 18 was identified as the working escape hatch. Set MEMORYDETECTIVE_SUPPRESS_PLATFORM_ADVISORY=1 to silence the notice once you have settled on a workaround.

Also on macOS 26.x: `xctrace record` is broken for simulator targets. Independent from the task_for_pid regression above, xcrun xctrace record --time-limit Ns against iOS simulator processes wedges past the time limit, eventually exits when killed, and the resulting .trace bundle is missing template metadata. xctrace export --toc then fails with Document Missing Template Error. Re-validated against Xcode 26.5 (build 17F42, xctrace 16.0) 2026-05-15: regression survives the update. This hits the entire xctrace-based ecosystem the same way (memorydetective.recordTimeProfile, XcodeTraceMCP, and naked xcrun xctrace record calls all fail identically). Workarounds: (1) use `recordViaInstrumentsApp` (v1.16, hardened in v1.17), which opens Instruments.app for you, prompts you to record + save the .trace, then chains into inspectTrace automatically once the bundle appears. v1.17 also catches saves outside the watch directory via an Instruments.app AppleScript document query, returning savedOutsideWatchDir: true plus the actual path; (2) record from an older macOS host with Xcode 26.0 if you have one; (3) record against a physical device (the regression appears to be simulator-specific). v1.17 added a viability probe on recordTimeProfile (bundleStatus: "wedged" when the on-disk bundle is the 52K stub) and on inspectTrace (returns ok: true with diagnosis text instead of throwing). USAGE.md > Troubleshooting has a step-by-step.

Quickstart

npm install -g memorydetective

Add to your MCP client config (Claude Code shown):

// ~/.claude/settings.json

{ "mcpServers": { "memorydetective": { "command": "memorydetective" } } }

Or use it directly from the command line:

memorydetective analyze   ~/Desktop/myapp.memgraph

memorydetective classify ~/Desktop/myapp.memgraph

→ See Examples for chat-driven flows · API for the full tool reference · Configure for Claude Desktop / Cursor / Cline · USAGE.md for the full walkthrough including how fixes flow from diagnosis to your codebase.

---

Examples

Realistic chat snippets. The agent calls the MCP tools listed in API.

Diagnose a leak from a memgraph

You: I just exported a memory graph at ~/Desktop/example.memgraph. Something's leaking after I close a detail screen. What is it?

Claude: *(calls analyzeMemgraph → classifyCycle)*

Found 4 ROOT CYCLE blocks across 60,436 leaks. The dominant one matches swiftui.tag-index-projection with high confidence. A closure attached via .tag() on a photo carousel ForEach is capturing self strongly through _viewModel.wrappedValue, which keeps DetailViewModel and the navigation coordinator alive after dismissal.

Suggested fix: replace [weak self] capture in the tap handler with a static helper, or weak-capture the view-model via [weak coord = self.coordinator]. Want me to find the exact file?

Verify a fix actually worked

You: I shipped the fix. Compare ~/Desktop/before.memgraph to ~/Desktop/after.memgraph and tell me whether DetailViewModel count dropped.

Claude: *(calls diffMemgraphs → countAlive)*

DetailViewModel: 12 → 0 (delta -12). The swiftui.tag-index-projection cycle is gone. Total leak count fell from 60,436 to 55,576 (−4,860). Three other ROOT CYCLEs persist. They're SwiftUI internals, not your code.

Self-contained verify-fix loop (v1.8)

When leaks --outputGraph fails on macOS 26.x (Failed to get DYLD info for task), the cause is usually that the app was not launched with MallocStackLogging=1. The new orchestration tools handle this end to end without you wiring up xcodebuild + simctl + axe yourself.

You: Reproduce the leak in MyApp for me. Build, launch with the right env vars, repeat the photo carousel flow 5 times to amplify it, capture before, then I'll ship the fix and you capture after.

Claude: *(calls bootAndLaunchForLeakInvestigation)*

Built + booted iPhone 15 (UDID ABCD-...). Launched MyApp (PID 49581) with MallocStackLogging=1. Bundle id com.example.MyApp.

*(calls replayScenario with 5 taps on the carousel + back-button cycle, repeat 5)*

Executed 25 actions in 12.3s. No failures.

*(calls captureScenarioState({label:"before"}))*

Wrote before.memgraph (63,201 leaks), before.png, before.ui.json. MallocStackLogging active, no workaroundNotice.

*(you ship the fix and rebuild)*

*(calls bootAndLaunchForLeakInvestigation + replay + captureScenarioState({label:"after"}))*

*(calls diffMemgraphs → verifyFix)*

DetailViewModel: 15 → 0. swiftui.tag-index-projection PASS. Bytes freed: 28.4 MB.

Find the slow path on a real device

You: Profile DemoApp on my iPhone for 90 seconds and tell me where the hangs are.

Claude: *(calls listTraceDevices → recordTimeProfile → analyzeHangs)*

Recorded ~/Desktop/run.trace (90s, attached to DemoApp on iPhone 17 Pro Max). Found 23 user-visible hangs (>500 ms each), longest 1.16 s, average 769 ms. Severe load. All on the main thread. Sample-level hotspots aren't symbolicated yet; open the trace in Instruments for that step (analyzeTimeProfile returns a structured workaround notice when xctrace can't symbolicate. See CHANGELOG known limits).

Analyze MetricKit payloads from real-user crashes (v1.18)

You: I have a folder of .mxdiagnostic files from the last 30 days of TestFlight at ~/Downloads/metrickit-may/. What's catching real users?

Claude: *(calls analyzeMetricKitPayload({ payloadDir: "~/Downloads/metrickit-may/" }))*

47 payloads, 2026-04-15 → 2026-05-15. Top: 18 crashes EXC_BAD_ACCESS clustered on the same top frame, all in builds 456 and 457 (clean on 458 + earlier). Pattern matches retain-cycle release; chain hint surfaces findCycles next.

Second: 5.4s hang on libsqlite3.dylib (3 samples). Pattern db-lock. If you reproduce locally, chain into analyzeHangs with includeStackClassification: true for the mainThreadViolations[] classifier.

No symbolicated frames in v1.18 (raw binaryUUID + offset shipped; dSYM lookup is a separate tool, future release). Localized hang strings handled: input was "5.4 sec", normalized to 5400ms; one diagnostic carrie