Memory Debugging

Overview

Memory issues manifest as crashes after prolonged use. Core principle 90% of memory leaks follow 3 patterns (retain cycles, timer/observer leaks, collection growth). Diagnose systematically with Instruments, never guess.

Example Prompts

• "My app crashes after 10-15 minutes with no error messages"
• "Memory jumps from 50MB to 200MB+ on a specific action — leak or cache?"
• "View controllers don't deallocate after dismiss"
• "Timers/observers causing memory leaks — how to verify?"
• "App uses 200MB and I don't know if that's normal"

---

Red Flags — Memory Leak Likely

• Progressive memory growth: 50MB → 100MB → 200MB (not plateauing)
• App crashes after 10-15 minutes with no error in Xcode console
• Memory warnings appear repeatedly in device logs
• View controllers don't deallocate after dismiss (visible in Memory Graph Debugger)
• Same operation run multiple times causes linear memory growth

Leak vs normal: Normal = stays at 100MB. Leak = 50MB → 100MB → 150MB → 200MB → CRASH.

Mandatory First Steps

ALWAYS diagnose FIRST (before reading code):

1. Check device logs for "Memory pressure critical", "Jetsam killed", "Low Memory"
2. Use Memory Graph Debugger (below) — shows object count growth
3. Xcode → Product → Profile → Memory. Perform action 5 times, note if memory keeps growing

What this tells you: Flat = not a leak. Linear growth = classic leak. Spike then flat = normal cache. Spikes stacking = compound leak.

Why diagnostics first: Finding leak with Instruments: 5-15 min. Guessing: 45+ min.

Detecting Leaks — Step by Step

Step 1: Memory Graph Debugger (Fastest)

1. Open app in simulator
2. Debug → Memory Graph Debugger (or toolbar icon)
3. Look for PURPLE/RED circles with "⚠" badge
4. Click them → Xcode shows retain cycle chain

Step 2: Instruments (Detailed Analysis)

1. Product → Profile (Cmd+I) → "Memory" template
2. Perform action 5-10 times
3. Memory line goes UP for each action? = Leak confirmed

Key instruments: Heap Allocations (object count), Leaked Objects (direct detection), VM Tracker (by type).

Step 3: Deallocation Check

// Add deinit logging to suspect classes
class MyViewController: UIViewController {
    deinit { print("✅ MyViewController deallocated") }
}

@MainActor
class ViewModel: ObservableObject {
    deinit { print("✅ ViewModel deallocated") }
}

Navigate to view, navigate away. See "✅ deallocated"? Yes = no leak. No = retained somewhere.

Jetsam (Memory Pressure Termination)

Jetsam is not a bug — iOS terminates background apps to free memory. Not a crash (no crash log), but frequent kills hurt UX.

Termination	Cause	Solution
Memory Limit Exceeded	Your app used too much memory	Reduce peak footprint
Jetsam	System needed memory for other apps	Reduce background memory to <50MB

Reducing Jetsam Rate

Clear caches on backgrounding:

// SwiftUI
.onChange(of: scenePhase) { _, newPhase in
    if newPhase == .background {
        imageCache.clearAll()
        URLCache.shared.removeAllCachedResponses()
    }
}

State Restoration

Users shouldn't notice jetsam. Use @SceneStorage (SwiftUI) or stateRestorationActivity (UIKit) to restore navigation position, drafts, and scroll position.

Monitoring with MetricKit

class JetsamMonitor: NSObject, MXMetricManagerSubscriber {
    func didReceive(_ payloads: [MXMetricPayload]) {
        for payload in payloads {
            guard let exitData = payload.applicationExitMetrics else { continue }
            let bgData = exitData.backgroundExitData
            if bgData.cumulativeMemoryPressureExitCount > 0 {
                // Send to analytics
            }
        }
    }
}

App memory grows while in USE? → Memory leak (fix retention)
App killed in BACKGROUND? → Jetsam (reduce bg memory)

Common Memory Leak Patterns (With Fixes)

Pattern 1: Timer Leaks (Most Common — 50% of leaks)

Why [weak self] alone doesn't fix timer leaks: The RunLoop retains scheduled timers. [weak self] only prevents the closure from retaining self — the Timer object itself continues to exist and fire. You must explicitly invalidate() to break the RunLoop's retention.

❌ Leak — Timer never invalidated

progressTimer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
    self?.updateProgress()
}
// Timer never stopped → RunLoop keeps it alive and firing forever

✅ Best fix: Combine (auto-cleanup)

cancellable = Timer.publish(every: 1.0, tolerance: 0.1, on: .main, in: .default)
    .autoconnect()
    .sink { [weak self] _ in self?.updateProgress() }
// No deinit needed — cancellable auto-cleans when released

Alternative: Call timer?.invalidate(); timer = nil in both the appropriate teardown method (viewWillDisappear, stop method, etc.) AND deinit.

For timer crash patterns (EXC_BAD_INSTRUCTION) and RunLoop mode issues, see axiom-timer-patterns.

Pattern 2: Observer/Notification Leaks (25% of leaks)

❌ Leak — No removeObserver

NotificationCenter.default.addObserver(self, selector: #selector(handle),
    name: AVAudioSession.routeChangeNotification, object: nil)
// No matching removeObserver → accumulates listeners

✅ Best fix: Combine publisher

NotificationCenter.default.publisher(for: AVAudioSession.routeChangeNotification)
    .sink { [weak self] _ in self?.handleChange() }
    .store(in: &cancellables)  // Auto-cleanup with viewModel

Alternative: NotificationCenter.default.removeObserver(self) in deinit.

Pattern 3: Closure Capture Leaks (15% of leaks)

❌ Leak — Closure in array captures self

updateCallbacks.append { [self] track in
    self.refreshUI(with: track)  // Strong capture → cycle
}

✅ Fix: Use [weak self]

updateCallbacks.append { [weak self] track in
    self?.refreshUI(with: track)
}

Clear callback arrays in deinit. Use [unowned self] only when certain self outlives the closure.

Pattern 4: Strong Reference Cycles

❌ Leak — Mutual strong references

player?.onPlaybackEnd = { [self] in self.playNextTrack() }
// self → player → closure → self (cycle)

✅ Fix: [weak self] in closure

player?.onPlaybackEnd = { [weak self] in self?.playNextTrack() }

Pattern 5: View/Layout Callback Leaks

Use the delegation pattern with AnyObject protocol (enables weak references) instead of closures that capture view controllers.

Pattern 6: PhotoKit Image Request Leaks

PHImageManager.requestImage() returns a PHImageRequestID that must be cancelled. Without cancellation, pending requests queue up and hold memory when scrolling.

class PhotoCell: UICollectionViewCell {
    private var imageRequestID: PHImageRequestID = PHInvalidImageRequestID

    func configure(with asset: PHAsset, imageManager: PHImageManager) {
        if imageRequestID != PHInvalidImageRequestID {
            imageManager.cancelImageRequest(imageRequestID)
        }
        imageRequestID = imageManager.requestImage(for: asset, targetSize: PHImageManagerMaximumSize,
            contentMode: .aspectFill, options: nil) { [weak self] image, _ in
            self?.imageView.image = image
        }
    }
how to use axiom-memory-debugging
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use axiom-memory-debugging on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add axiom-memory-debugging
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/charleswiltgen/axiom --skill axiom-memory-debuggingcopy
The skills CLI fetches axiom-memory-debugging from GitHub repository charleswiltgen/axiom and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/axiom-memory-debugging
Reload or restart Cursor to activate axiom-memory-debugging. Access the skill through slash commands (e.g., /axiom-memory-debugging) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?