mac-mem-guard

Mac Mini M4 (16GB) 全局記憶體保護套件。

針對以 Claude Code (SSH) 為主要開發方式的環境設計，解決 macOS 記憶體壓力、swap 碎片化、進程殘留等問題。

問題背景

在 16GB Mac Mini 上同時跑 Claude Code (多 session) + OrbStack (Docker containers) + Nuxt dev server + VS Code 時，常見：

• Swap 爆滿 — macOS swap 碎片化後不會自動回收
• 重複 dev server — 多個 Claude Code session 各自啟動 nuxt dev，同專案跑 7+ 個實例
• 孤兒進程 — Claude Code session 結束後，子進程 (node, esbuild, playwright) 殘留
• 閒置 session 堆積 — SSH 斷線後 Claude Code session 不會自動關閉
• 瀏覽器 localhost tab — dev server 已死但 tab 還開著佔資源

架構

mac-mem-guard-setup.sh          # 一鍵部署（環境變數 + daemon + Git/OrbStack 限制）
├── mem-guard.sh                # 常駐 daemon（15s 輪詢，記錄趨勢 + purge + 孤兒清理）
├── claude-mem-cleanup.sh       # 定時清理（30min，launchd 觸發）
│   ├── close-dead-localhost-tabs.sh    # 關閉死掉的 localhost tab
│   └── cleanup-idle-claude-sessions.sh # 清理閒置 Claude Code session
└── .zshrc 追加
    ├── 環境變數（NODE_OPTIONS, ulimit, GOMEMLIMIT...）
    ├── prompt 記憶體壓力提示（SSH 可見）
    └── 便利指令（mem, mem-log, mem-trend...）

防護層

層	機制	頻率	做什麼
預防	.zshrc 環境變數	每個 shell	NODE_OPTIONS 2GB、ulimit 8GB、並行數限制
預防	Git/OrbStack 限制	永久	pack memory、VM 4GB 上限
監控	mem-guard daemon	15 秒	記錄趨勢 CSV、warn/critical 時清孤兒 + 重複 dev server
清理	claude-mem-cleanup	30 分鐘	重複 dev server、孤兒進程、zombie、閒置 session、死 tab
提示	shell prompt	30 秒	SSH 可見的 free% + swap 提示（低於 25% 時顯示）

清理規則

重複 Dev Server

同一專案目錄存在多個 nuxt dev → 只保留最新的 PID

孤兒進程

ppid=1 且符合以下 pattern 的自動清理：

• .local/share/claude/versions/*（Claude Code 殘留）
• esbuild
• .output/server/index.mjs（Nuxt build 殘留）
• playwright-mcp

Claude Code Session

• >6h 且 CPU <2% → 閒置，清理
• >24h 且 CPU <5% → 放寬門檻但仍看活動
• Session 歷史自動保存在 ~/.claude/，可用 claude -r 找回

瀏覽器 Localhost Tab

支援 Microsoft Edge、Google Chrome、Safari。curl 檢查 port 是否存活，死了就關 tab。

安裝

git clone https://github.com/YuDefine/mac-mem-guard.git
cd mac-mem-guard
bash mac-mem-guard-setup.sh
source ~/.zshrc

常用指令

mem          # 記憶體狀態 + swap + top 10 進程
mem-log      # mem-guard daemon 最近日誌
mem-trend    # 最近 5 分鐘趨勢
mem-worst    # 歷史記憶體最差的時刻
mem-purge    # 手動清 disk cache
orb-flush    # 重啟 OrbStack 回收殘留記憶體

管理 Daemon

# 停止
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.memguard.daemon.plist

# 啟動
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.memguard.daemon.plist

# 日誌
tail -f /tmp/mem-guard.log

日後分析

# 歷史數據（15 秒間隔，保留 36 小時）
cat /tmp/mem-guard-history.csv

# 系統日誌
log show --predicate 'senderImagePath contains "mem-guard"' --last 1d

# Jetsam 報告（macOS 殺了誰）
ls /Library/Logs/DiagnosticReports/JetsamEvent*

設計原則

• 不自動殺用戶進程 — 只殺已知安全的孤兒和重複實例
• SSH 友善 — 不依賴桌面通知，靠 prompt + log
• 冪等部署 — 重複執行不會重複寫入 .zshrc
• 互補不衝突 — mem-guard (15s 輪詢) 和 claude-mem-cleanup (30min 定時) 各司其職

License

MIT