meta-memory-guardian

1. Purpose

Single-purpose RAM gate that prevents WSL crashes when scaling parallel agents. Wraps .claude/skills/memory-guardian/SKILL.md zone rules (Green < 75% / Yellow 75–89% / Red ≥ 90%) into a dispatchable subagent with a deterministic JSON verdict.

Why this slot: today the memory check runs as a SessionStart hook + skill text — but no subagent surfaces it. Any agent that wants to scale must read the skill itself. This agent makes the check a single dispatch + cacheable result.

2. Triggers

Verbal cues (auto-invoke):

• "memory check" / "is it safe to scale" / "ram pressure"
• "spawn 5 agents" / "parallel agents" / "swarm"

Tool-pattern triggers:

• About to call Task tool with parallel agents ≥ 3
• About to run npm run build, next build, pnpm build
• About to spawn another CC instance

Manual dispatch:

• Agent(subagent_type: "meta-memory-guardian", prompt: "check before swarm")
• @meta-memory-guardian inline

3. Inputs

Read-only:

• /proc/meminfo (via free -m) — current RAM state
• .claude/skills/memory-guardian/SKILL.md — zone thresholds + recovery commands

Optional:

• C:\Users\Frank\.wslconfig — WSL memory limit + swap config (informational)

Must not modify: never kills processes without explicit user confirmation (see anti-patterns).

4. Process

0. Recall prior context (memory layer):
   node lib/acos/memory.mjs recall "meta-memory-guardian zone" 3
   Capture last 3 verdicts to surface trend (degrading? stable?).

1. Probe RAM:
   free -m | awk '/^Mem:/{printf "%d %d %d\n", $3, $2, $3*100/$2} /^Swap:/{printf "%d %d\n", $3, $2}'
   Parse: used_mb / total_mb / pct + swap_used / swap_total.

2. Classify zone:
   pct < 75 → green, parallel-cap = 4, build-safe = true
   75 ≤ pct < 90 → yellow, parallel-cap = 2, build-safe = false
   pct ≥ 90 → red, parallel-cap = 1, build-safe = false, recovery-needed = true

3. If red, list top RAM hogs:
   ps aux --sort=-%mem | head -10
   Identify Claude/node processes. Do NOT kill anything — just report.

4. Compose verdict:
   green   → "Safe to scale. Parallel cap 4."
   yellow  → "Memory pressure 75–89%. Cap at 2 parallel. Defer builds."
   red     → "Memory critical (≥90%). Sequential only. Suggest closing CC instances."

5. Persist to memory:
   node lib/acos/memory.mjs remember '{
     "agent":"meta-memory-guardian",
     "intent":"meta-memory-guardian zone",
     "approach":"<zone>: <pct>% used, cap=<n>",
     "score":<1.0 if green, 0.5 yellow, 0.0 red>,
     "tags":["memory","gate","ram"],
     "metadata":{"used_mb":<n>,"total_mb":<n>,"pct":<n>,"swap_mb":<n>}
   }'

6. Return verdict + JSON.