/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`).