name: memory-gc

description: Inspect or rotate hunt-memory JSONL files (audit.jsonl, patterns.jsonl, journal.jsonl). Caps file size and keeps N rotated backups so memory does not grow unbounded.

/memory-gc

Garbage-collect the hunt-memory directory. Reports current sizes, rotates oversized files past a configurable cap, or purges old backups.

Why This Exists

Append-only logs grow without bound. On active hunters:

• audit.jsonl can reach 100 MB+ in months (every outbound request)
• patterns.jsonl and journal.jsonl accumulate forever

This command surfaces that growth and gives you a one-shot fix.

Usage

/memory-gc                       # report only
/memory-gc --rotate              # rotate files above 10 MB (default cap)
/memory-gc --rotate --max-mb 5   # custom cap
/memory-gc --purge-backups       # delete all .1/.2/.3 backups
/memory-gc --dir <path>          # scan a non-default hunt-memory dir

What It Does

1. Walks the hunt-memory directory recursively.
2. Finds audit.jsonl, patterns.jsonl, and journal.jsonl files at any depth.
3. Prints a per-file table: live size, total (live + backups), backup count, status.
4. With --rotate: renames oversize files to <file>.1, shifting older backups up to <file>.{keep}. The oldest is dropped.
5. With --purge-backups: removes every .1/.2/.3 backup, keeping only live files.

Implementation

The agent shells out to:

python -m tools.memory_gc [args]

from the repo root.

Defaults

• Rotation cap: 10 MB per file
• Backups kept: 3 (so <file>.1 newest → <file>.3 oldest)
• Scope: hunt-memory/ and any nested target dirs

Auto-rotation fires automatically in two places:

1. On every write — inside AuditLog.log() and PatternDB.save() when the next append would exceed the cap.
2. On session end — a Stop hook in .claude/settings.json runs python3 -m tools.memory_gc --rotate so long sessions that wrote a lot but never crossed the cap mid-session still get cleaned up.

So this slash command is mainly for ad-hoc reporting (/memory-gc with no args) and manual cleanup of accumulated backups (/memory-gc --purge-backups).