matlab-optimize-memory - SKILL.md Agent Skill

name: matlab-optimize-memory description: "Guides the 7-step MATLAB memory optimization workflow: baseline, profile, identify, optimize, measure, verify, report. Use when asked to reduce MATLAB memory usage, find memory bottlenecks, fix out-of-memory errors, or optimize memory-intensive code." license: MathWorks BSD-3-Clause metadata: author: MathWorks version: "1.1"

MATLAB Memory Optimization Workflow

Systematic 7-step workflow for finding and fixing memory bottlenecks in MATLAB code.

When to Use

User gets out-of-memory errors running MATLAB code
User wants to reduce memory usage of their MATLAB program
User wants to process larger datasets without running out of memory
User asks to profile or measure memory allocations

When NOT to Use

The bottleneck is execution speed, not memory (use matlab-optimize-performance)
The memory issue is in compiled C/MEX code that can't be changed at the M-code level
Memory usage is dominated by I/O buffers (memory-mapped files, database connections)

The 7-Step Workflow

Step 1: Establish Memory Baseline

Measure current memory usage before making changes.

m0 = memory;
targetFunction(inputs);
m1 = memory;
deltaBytes = m1.MemUsedMATLAB - m0.MemUsedMATLAB;
fprintf('Memory delta: %.2f MB\n', deltaBytes / 1e6);

When memory errors (Linux/macOS), use whos for variable sizes or Java runtime for heap:

info = whos('result');
fprintf('Variable size: %.2f MB\n', info.bytes / 1e6);

Step 2: Profile Memory Allocations

Find where memory is being allocated.

profile('-memory', 'on');
for iter = 1:5
    targetFunction(inputs);
end
profile off;
p = profile('info');
ft = p.FunctionTable;
[~, idx] = sort([ft.TotalMemAllocated], 'descend');
for i = 1:min(15, numel(idx))
    f = ft(idx(i));
    fprintf('%-40s %10.2f MB\n', f.FunctionName, f.TotalMemAllocated/1e6);
end

If TotalMemAllocated fields are zero, fall back to whos snapshots before/after each function call.

Key things to look for:

Functions with high "Allocated" but low "Freed" — memory is retained
Functions called many times with moderate allocations — total adds up
Large gaps between Allocated and Freed — temporaries accumulating

Step 3: Identify Optimization Opportunities

Based on profiling, identify which patterns apply. See references/memory-patterns.md for code examples.

Pattern	Typical Reduction	Look For
Cell collection + `vertcat`	O(N²) → O(N)	`[arr; newRow]` inside loops
Implicit expansion over `repmat`	Eliminates full copy	`repmat(A, [1 1 K])` for broadcasting
Clear variables when done	Immediate reclamation	Large arrays used only in early steps
Break chained expressions	1 fewer peak temporary	`a.b.c./d` all alive at once
Reuse variables (overwrite in-place)	Avoids output allocation	Separate variables for each step
`max`/`min` instead of masking	Eliminates logical temporary	`x .* (x > 0)` pattern
`zeros(...,'like',x)`	Eliminates temporaries	`0 * x` to create zeros
Copy-on-write sharing	Shares backing memory	Same array assigned to multiple places
Dense → sparse	O(N²) → O(N·bw)	`zeros(N,N)` where N > 10000

Step 4: Implement Optimizations

Apply the identified patterns. Focus only on the hotspots identified in Step 2 — do not apply patterns everywhere.

Step 5: Measure Optimized Memory

Re-measure using the same method as Step 1:

m0 = memory;
optimizedFunction(inputs);
m1 = memory;
deltaOpt = m1.MemUsedMATLAB - m0.MemUsedMATLAB;
reduction = 1 - deltaOpt / deltaBytes;
fprintf('Optimized: %.2f MB (%.0f%% reduction)\n', deltaOpt/1e6, reduction*100);

Step 6: Verify Correctness

Every optimization must produce the same results:

original = originalFunction(inputs);
optimized = optimizedFunction(inputs);
maxErr = max(abs(original(:) - optimized(:)));
fprintf('Max error: %.2e\n', maxErr);
assert(maxErr < 1e-10, 'Results differ!');

Step 7: Report Results

Summarize the memory optimization with baseline, optimized, reduction percentage, correctness check, and patterns applied.

Key Rules

Never propose optimizations based solely on reading source code — always measure and profile first
Verify correctness — memory optimizations must produce identical results
Clear variables early — free memory as soon as data is no longer needed
Avoid growing arrays — preallocate or use cell collection
Break chains — sequential assignment reduces peak memory vs chained expressions
Watch for copies — MATLAB copies on write; reuse variables to avoid duplicates

Platform Notes

Windows: memory command returns full statistics (MemUsedMATLAB, etc.)
Linux/macOS: memory errors ("not supported on this platform"). Use whos for variable sizes, Java Runtime.getRuntime for heap usage, or OS-level RSS via system('ps ...')
profile -memory: Works on all platforms but is undocumented since R2016a. When unavailable, use whos snapshots before/after function calls.