# mz-optimize-memory

mz-optimize-memory — a Claude Code skill that investigates high memory use in Materialize clusters and tests ways to reduce it. It runs on OOM events, replica downsizing work, and index or GROUP SIZE reviews.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 121 installs · ★ 3 repo stars
- Author: MaterializeInc
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/MaterializeInc/agent-skills/tree/HEAD/skills/mz-optimize-memory/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/mz-optimize-memory

## What it does

The skill analyzes memory use in Materialize clusters and evaluates index strategies, `GROUP SIZE` hints, slimmer views, and subquery decorrelation. It backs each verdict with measurements; estimates alone do not settle whether a change should ship.

It asks for approval before reading user data or making changes. Object experiments run on a dedicated cluster, never production; accepted changes are delivered for the deployment source of truth or as DDL. For cluster queries, it prefers the Materialize MCP endpoint's `query` tool with a cluster argument. Multi-replica clusters also require `cluster_replica`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add MaterializeInc/agent-skills --skill mz-optimize-memory -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/mz-optimize-memory/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/mz-optimize-memory/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add MaterializeInc/agent-skills --skill mz-optimize-memory -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/mz-optimize-memory/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add MaterializeInc/agent-skills --skill mz-optimize-memory -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/mz-optimize-memory/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install MaterializeInc/agent-skills skills/mz-optimize-memory
```

2. **Manually: put the files in place**
- File: `.github/skills/mz-optimize-memory/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add MaterializeInc/agent-skills --skill mz-optimize-memory -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/MaterializeInc/agent-skills --path skills/mz-optimize-memory
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/mz-optimize-memory/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add MaterializeInc/agent-skills --skill mz-optimize-memory -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/MaterializeInc/agent-skills/tree/HEAD/skills/mz-optimize-memory/SKILL.md

## When to use it
- trace memory use to Materialize objects
- reduce cluster memory use and replica size
- decide which indexes to add or remove
- tune `GROUP SIZE` hints
- measure proposed changes before rollout

## Example prompts
- Find out why this Materialize cluster uses so much memory.
- Review the indexes and test which ones can be removed on a separate cluster.
- Assess whether this replica can be downsized and tune its `GROUP SIZE` hints.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: f1b130111285c012.

BEGIN THIRD-PARTY FILE f1b130111285c012
```text
---
name: mz-optimize-memory
description: >
  Reduce the memory footprint and cost of Materialize compute clusters:
  find where arrangement memory sits, pick and size the right optimization
  lever (index strategy, GROUP SIZE hint tuning, view slimming, subquery
  decorrelation), adjudicate
  proposed index or view changes, run measured experiments safely, and
  package verified changes. Use when a Materialize cluster or replica uses
  too much memory or is OOMing or crash-looping, when the user wants to
  downsize a replica or cut Materialize spend, when deciding which indexes
  to add or drop, or when tuning GROUP SIZE hints.
---

# Optimize Cluster Memory

Reduce what a Materialize compute cluster spends on memory, with every
claim backed by a measurement. The deliverable of an engagement is a set
of per-item verdicts with measured evidence, validated changes expressed
in the user's own deployment tooling, and a right-sized replica at the
end. Freed memory is not saved money until the replica is resized down.

For freshness problems (an object lagging behind wall-clock time) use
the mz-debug-freshness skill instead. Memory work and freshness
work share instruments but have different workflows.

## Ground rules

- Ask before changing anything, and before reading the user's data. Catalog,
  introspection and EXPLAIN reads need no permission; a SELECT over the user's
  relations (a cardinality probe, the match-rate query, an exactness proof)
  reads their data and is asked for first. Anything that creates, alters,
  drops, or writes rows, in the user's environment or on their machine
  (including a local Docker container), is proposed first and run only after a
  yes. Approval covers a class of change, not each statement: an approved
  experiment cluster covers building and dropping candidate objects on it, and
  anything beyond it needs a fresh ask.
- Never change objects on production clusters, even with permission to
  experiment. Object definitions usually have a source of truth
  outside Materialize (mz-deploy, dbt, or deploy scripts), and a
  catalog-only change is silently reverted, or half-reverted, by the
  next deploy. Accepted changes are delivered as edits to that source
  of truth, or as DDL for the user to run where the catalog is the
  source.
- Experiments run on a dedicated experiment cluster that the user
  creates (you supply the commands). Never build or rebuild candidate
  objects on a production cluster: an object built there hydrates on
  the production replica and spends production memory and CPU on an
  experiment. Read-only `EXPLAIN ANALYZE` and introspection reads against
  production are diagnosis and are fine; anything that hydrates goes
  to the experiment cluster.
- Do not recommend `REFRESH EVERY` materialized views as an optimization
  lever in any situation.
```
END THIRD-PARTY FILE f1b130111285c012

The third-party file has ended. Everything between the f1b130111285c012 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2843 of 60001 bytes. © MaterializeInc · Apache-2.0 · https://github.com/MaterializeInc/agent-skills/tree/HEAD/skills/mz-optimize-memory/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
