kaaskoek232-ComfyUI-MemoryManagement/AGENTS.md

AGENTS.md

Cursor Cloud specific instructions

Overview

This is a ComfyUI Memory Management Custom Nodes plugin (v1.1.0) — a pure-Python package providing 7 custom nodes for memory monitoring, cleanup, and VRAM optimization. It runs in standalone mode (no ComfyUI host required) for development and testing.

Development Environment

• Python 3.12 with a virtual environment at .venv/
• Dependencies: psutil, torch (CPU build), plus dev tools (pytest, black, flake8, mypy)
• Activate the venv: source /workspace/.venv/bin/activate

Running Tests

The built-in test_memory_nodes.py has a relative import issue (nodes use from ..utils relative imports). To test correctly, import through the package:

source /workspace/.venv/bin/activate
python -c "
import sys; sys.path.insert(0, '/')
import workspace  # loads all 7 nodes in standalone mode
"

Or exercise individual nodes:

python -c "
import sys; sys.path.insert(0, '/')
from workspace.nodes.memory_monitor import MemoryMonitorNode
node = MemoryMonitorNode()
print(node.monitor_memory(refresh_trigger=1, show_detailed=True, show_gpu_info=True, memory_threshold_warning=80.0))
"

Lint / Format Commands

source /workspace/.venv/bin/activate
flake8 . --max-line-length=100 --exclude=.venv
black --check --line-length 100 --exclude '.venv' .
mypy . --exclude '.venv' --ignore-missing-imports

Key Gotchas

1. No CUDA GPU in Cloud VM — VRAM optimizer/unload nodes degrade gracefully (return success=False, 0 bytes freed). This is expected.
2. Standalone mode — Without ComfyUI installed, the package logs "ComfyUI not detected - using standalone mode" and uses fallback memory management methods. All node functionality still works.
3. torch numpy warning — PyTorch emits a harmless UserWarning: Failed to initialize NumPy when numpy is not installed. This does not affect functionality.
4. Package import path — The workspace root directory must be importable as a package (add / to sys.path and import workspace). Direct from nodes.X import Y fails due to relative imports in node files.