Memory Cat 🐱

메모리 뚱냥이 — an OpenAI Build Week project

Your memory pressure, visualized as a cat that gets chonkier as your Mac fills up.

Memory Cat is a desktop pet for macOS, with a lightweight Windows version. It turns an invisible system metric into something you can understand at a glance: the fuller your Mac's memory gets, the rounder your cat becomes.

The killer demo feature makes that cat personal. Give Memory Cat one photo of your pet, and gpt-image-2 creates a six-stage chonk progression that the app automatically converts into a custom desktop theme with six chonk stages.

The default cat gets rounder as memory fills up	Built-in themes give each chonk a different style
The chonk stage, disk, RAM, swap, top memory apps, the diagnosis, themes, personality, and language — all on right-click

• One pet photo → one custom animated theme: gpt-image-2 preserves your pet's distinctive colors, markings, face, and ears while generating a six-stage horizontal sprite sheet. Memory Cat segments it and builds the theme automatically.
• The complete chonk chart: A fine boi → He chomnk → A heckin' chonker → HEFTYCHONK → MEGACHONKER → OH LAWD HE COMIN. Everyday use keeps him in the middle of the chart; the last two names are for a Mac that is genuinely out of room, so seeing one means something. Korean has its own six — see Where he changes shape.
• “🐾 What did you eat?” diagnosis: GPT-5.6 (gpt-5.6-luna) explains why the computer feels slow, recommends safe cleanup targets, estimates reclaimable space, and gives one concise piece of advice. The Korean menu label is “🐾 뭘 먹은 거야?”.
• Safety-first cleanup: only allowlisted browser caches, Trash contents, downloads older than 30 days, and Xcode DerivedData can be suggested. Every item requires confirmation and is moved through macOS Trash—never permanently deleted.
• A cat with a personality: choose a sassy, warm, or stoic voice, or describe a custom personality in natural language. The selected voice shapes the diagnosis.
• English and Korean: macOS language is detected automatically, with a manual language override in the context menu.
• Useful at a glance: disk, RAM, swap, and top memory-consuming apps appear in the right-click menu. The cat can be dragged, resized, and rethemed.

The AI-powered items above are macOS only. See Install on Windows for what the Windows build covers.

By default the cat follows memory — close a few apps and he slims down within seconds. Right-click → What makes him chonky to switch:

Memory is the default because that is usually what makes a Mac feel slow — when RAM runs out, macOS pushes pages to swap and pulls them back, and you feel the wait. Storage matters too: a full drive leaves swap no room to grow.

Swap usage is deliberately not part of the score. macOS creates and removes swap files on demand, so used / total mostly measures how big the kernel decided to make the file — the denominator moves with the numerator, and the ratio swings without your Mac's pressure changing. It can even move the wrong way: when pressure rises and the kernel grows the swap file, the ratio falls. Counting it made the cat slim down after a reboot while the Mac was actually more pressured than before. The diagnosis still reports swap; it just does not decide his size.

He changes shape at the same points his name changes, in both languages, so the picture and the label never disagree.

A running Mac never empties its memory — mine sits between 61% and 80% — so mapping 0–100% straight onto the six pictures would have used only two of them. Each band gets its own picture instead. Inside a band the movement is linear, so themes that really are forty separate drawings, like Wake-up call, still animate smoothly.

The Windows build follows storage only.

Memory Cat does not phone home. Disk, RAM, and swap numbers are measured and drawn entirely on your machine, and nothing is collected or sent anywhere in the background. There is no analytics, telemetry, or crash reporting in the codebase. (The macOS installer does route the app's own stdout and stderr to a local cat.log under ~/Library/Logs/Memory Cat/, which never leaves your machine.)

Two features reach the network, and only when you click them yourself:

• 🐾 What did you eat? diagnosis sends the usage numbers, the names of the apps using the most memory, and per-category cleanup totals. If you wrote your own personality description, that text is sent as well, since it shapes the reply. File names and paths are never sent — the payload is assembled without them, and a test enforces it. The request also sets store=False.
• Make a theme from my pet… uploads the photo you pick. A consent dialog naming OpenAI appears first, and nothing is uploaded until you approve it.

Both features need your own OPENAI_API_KEY. Without a key the app still works: the diagnosis falls back to a local, rules-based explanation and only custom theme generation is unavailable.

Cleanup can only ever touch four allowlisted locations — browser caches, the Trash, downloads older than 30 days, and Xcode DerivedData. That list is fixed in code and the model cannot extend it. Every item is confirmed individually with its full path shown, and items are moved to the macOS Trash rather than deleted.

• Performance diagnosis: GPT-5.6 (gpt-5.6-luna)
• Custom pet theme generation: gpt-image-2

Prebuilt builds live on the releases page. Nothing to install — unzip it, drag Memory Cat.app into your Applications folder, and open it.

Prefer to build it yourself, or want it to start automatically at login? Use Install on macOS below instead.

These builds are not code-signed — I have no Apple Developer certificate. macOS therefore cannot verify them and blocks the first launch. The app is fine; macOS just has no way to know that. Verify the SHA-256 in the release notes if you want to be sure you got the file I published.

On macOS 15 (Sequoia) and later, the dialog offers only Done and Move to Trash — right-clicking and choosing Open no longer works. Do this instead:

1. Double-click the app once and press Done on the warning.
2. Open System Settings → Privacy & Security, scroll to the bottom.
3. Next to "Memory Cat" was blocked, press Open Anyway.

That entry only appears right after a blocked launch, so do step 1 first.

On macOS 11–14, right-click the app and choose Open, then Open again in the dialog.

You only have to do this once.

A downloaded build does not register a login item by itself. Open Memory Cat once, then switch it on in System Settings → General → Login Items & Extensions. (Install on macOS below sets this up for you instead.)

Move the app to the Trash. Your settings and any themes you made stay in ~/Library/Application Support/Memory Cat/ — delete that folder too if you want them gone. (If you switched the login item on in System Settings, switch it off there as well. The uninstall_mac.command mentioned below is only for installs made by install_mac.command.)

This path builds the app from source on your own machine and sets it to start at login. It also works on Intel Macs and does not trip the warning above.

git clone https://github.com/hyeonheebee/memory-cat.git
cd memory-cat
./install_mac.command        # You can also double-click this file

The installer requires Python 3.9 or later. It builds a real application bundle at ~/Applications/Memory Cat.app, installs the dependencies into a virtual environment inside that bundle, launches Memory Cat, and configures it to start at login.

Because everything the app needs lives in the bundle, you can delete the cloned repository afterwards and Memory Cat keeps working.

On a Mac that has never had developer tools installed, python3 is only a stub that prompts you to install them. Run xcode-select --install first, then run the installer again. The installer checks for this and tells you what to do.

The four built-in themes ship inside the bundle and are replaced on every install. Anything you made stays in Application Support and is never overwritten.

Upgrading from an older install? The installer copies your existing config.json, .env, and any custom frames/<name>/ folders out of the repository and into Application Support on first run. It copies rather than moves, so the originals in your clone are left untouched, and it never overwrites a file that is already there.

./uninstall_mac.command

If you already deleted the repository, the same script is kept inside the app:

"$HOME/Applications/Memory Cat.app/Contents/Resources/uninstall_mac.command"

Either way it stops the app, removes the login item and the bundle, and leaves your settings and custom themes alone. It prints the one command that deletes those too, if that is what you want.

Pull, then run ./install_mac.command again. It stops the running app, rebuilds the bundle, and restarts it.

Store OPENAI_API_KEY in ~/Library/Application Support/Memory Cat/.env to enable GPT-5.6 diagnosis and custom pet theme generation. When you run from a clone for development, a .env in the project root still works.

What the Windows build includes. The disk-driven cat, RAM and swap readouts, top memory consumers, theme and size switching, and the Korean / English language toggle. The AI features are macOS only: the 🐾 What did you eat? diagnosis, custom pet themes, safe cleanup, and personalities. In exchange the Windows build has no OpenAI dependency and makes no network requests at all.

See windows/README.txt for the full instructions. In short:

pip install -r windows\requirements.txt
pythonw windows\windows_cat.pyw

To build a standalone executable, install PyInstaller and run build_exe.bat. It works from any working directory — the script switches to its own folder before building, so windows\build_exe.bat from the repository root is fine:

pip install -r windows\requirements.txt
pip install pyinstaller
windows\build_exe.bat

In PowerShell, prefix the script with .\ — PowerShell does not run commands from the current directory otherwise, and reports the script as an unrecognized term:

.\windows\build_exe.bat

The executable it produces is unsigned — expect security warnings. This is a personal project with no code-signing certificate, so the first launch of MemoryCat.exe triggers a Windows SmartScreen "unknown publisher" prompt, and antivirus engines sometimes flag PyInstaller --onefile builds as a false positive (a --onefile binary unpacks itself into a temp folder at startup, which resembles malware behaviour). That is expected here, but please do not learn to click through unsigned-binary warnings in general — it is a genuinely dangerous habit. Do not run a MemoryCat.exe that reached you by any other route — a forwarded file, a mirror, a chat attachment — because there is no way to tell it was built from this repository.

The build on this repository's releases page is the one exception, and only if you check it: each release note publishes the SHA-256 of the file, so compare it before running.

Get-FileHash .\MemoryCat.exe -Algorithm SHA256

If you would rather not trust any binary, skip the executable and run the Python script directly: windows/windows_cat.pyw is a single readable file you can inspect before running it. Building the .exe yourself, on your own machine, is always the safest option.

On macOS, right-click the cat and choose Make a theme from my pet…. After you select a photo and approve sending it to OpenAI, the app generates, imports, and immediately applies the new theme in a background thread.

The same pipeline is available from the command line:

# install_mac.command builds its virtual environment inside the app bundle.
# For a development environment in the clone, make your own:
python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip   # stock pip cannot resolve pyobjc-core
./.venv/bin/python -m pip install -r requirements.txt

# Keep OPENAI_API_KEY in the project root .env file
./.venv/bin/python vision_theme.py my-pet.jpg my-pet --quality medium

vision_theme.py asks gpt-image-2 for six clearly separated versions of the same pet, from slim to extremely round. It then reuses the existing import pipeline to write those six stages out as cat_00.png through cat_39.png under ~/Library/Application Support/Memory Cat/frames/my-pet/, plus preview and raw debug images. Set MEMORY_CAT_HOME to write somewhere else.

If you already have a horizontal image with multiple stages from slim to round, import it directly:

./.venv/bin/python import_theme.py my-sprite-sheet.png my-theme

Themes are discovered automatically from two places: the four built-in themes inside the app bundle, and your own themes in ~/Library/Application Support/Memory Cat/frames/<name>/. Newly generated themes always go to the second one, so reinstalling the app never deletes them. Reopen the right-click Theme menu to select a newly imported theme. Code-generated built-in themes can be rebuilt with python generate_frames.py.

desktop_cat.py      macOS desktop app and menus (PyObjC)
apppaths.py         where bundled assets end and user data begins
macos/build_app.py  assembles Memory Cat.app and the LaunchAgent plist
                    (local install; the bundle it makes needs the Python it
                    was built with)
macos/memorycat.spec  PyInstaller spec for the release zips (self-contained:
                    Python and every dependency live inside the bundle)
brain.py            GPT-5.6 performance diagnosis and safe Trash workflow
personality.py      personality presets and custom prompt compiler
i18n.py             English/Korean UI strings and chonk-stage names
metrics.py          shared disk and memory measurements
vision_theme.py     one pet photo -> gpt-image-2 custom theme
import_theme.py     sprite sheet segmentation and frame generation
generate_frames.py  built-in theme generator
windows/            lightweight Windows app (PySide6)
frames/<theme>/     generated PNG frames for each theme
tests/              mocked, regression, and optional live API tests

• MEMORY_CAT_CONFIG=demo_config.json: use a separate config file for demos or tests so personal settings are not read or modified.
• MEMORY_CAT_DEMO_DISK_PERCENT=92: replace measured disk usage with a demo or test value, clamped to 0–100; displayed and diagnostic values stay consistent.
• MEMORY_CAT_HOME=/tmp/cat-home: relocate everything under ~/Library/Application Support/Memory Cat/ — settings, custom themes, and .env — so a test run cannot touch your real data.
• MEMORY_CAT_APPS_DIR=/tmp/apps: install the bundle somewhere other than ~/Applications. Used by install_mac.command and uninstall_mac.command.

Example:

MEMORY_CAT_CONFIG=demo_config.json \
MEMORY_CAT_DEMO_DISK_PERCENT=92 \
.venv/bin/python desktop_cat.py

All application code in this project was written by Codex (GPT-5.6-Codex) in a single continuous session in the ChatGPT desktop app, working directly on this repository. My workflow for every feature:

1. Spec first — I wrote a detailed spec for each module (goals, design decisions, safety constraints, test requirements, done criteria) and handed it to Codex as one prompt.
2. Codex implements — Codex wrote the code, tests, and commits: the GPT-5.6 diagnosis engine (brain.py), the safety-first trash pipeline (safe_trash with an allowlist + macOS Trash only), i18n, the personality system, and the killer feature — vision_theme.py, which turns one photo of your pet into a six-stage chonk-progression theme via gpt-image-2.
3. Verify against the real API — mocked tests all passed, but my review partner (Claude, which I used for planning, code review, and demo prep — never for the code itself) ran a live API call and caught a real bug: gpt-image-2 rejects the response_format parameter. I reported it back to Codex with the error, Codex verified it against the API reference and shipped the fix with a regression test (assertNotIn("response_format", kwargs)).

Models used at runtime: GPT-5.6 (gpt-5.6-luna) powers the cat's personality-driven performance diagnosis; gpt-image-2 generates the custom pet sprite sheets.

Built by Hyeonhee Shim (@hyeonheebee). Code by Codex; planning, review, and demo by Claude. MIT License.

The MIT License covers the code. The name "Memory Cat" / "메모리 뚱냥이" and the cat artwork are not part of that grant — if you redistribute a modified version, please give it a different name.

The Windows build bundles PySide6, which is licensed under the LGPL. Its source and build script are in windows/, and the release executable is built from them by GitHub Actions, so you can rebuild it yourself with a modified PySide6 if you wish.