feat(skills): add disk-guardian — auto ephemeral session file cleanup with persistent memory by LVT382009 · Pull Request #12212 · NousResearch/hermes-agent

LVT382009 · 2026-04-18T16:26:05Z

Summary

Adds disk-guardian, an optional skill that tracks ephemeral files created
by Hermes during sessions and removes them automatically. Test files are
deleted at the end of every task with no confirmation. Runs silently in the
background — only interrupts the user for risky items (research folders,
large files >500 MB).

Scoped strictly to HERMES_HOME — never touches ~/.hermes/logs/ or
system directories.

Why It's Better Than Manual Cleanup

Yes, MUCH better. Here's why:

What Hermes Normally Does ❌

Create test files randomly
Forget about them
Leave them cluttering the filesystem
Clean up only when you explicitly ask
No tracking, no rules, no safety
Manual, ad-hoc, inconsistent

What Disk Guardian Does ✅

Systematic tracking - Every file Hermes creates gets tracked by category
Automatic cleanup - Test files deleted immediately, temp files after 7 days
Safety rules - Won't delete large files (>500MB) without confirmation
Path protection - Rejects files outside HERMES_HOME, protects Windows mounts
Audit logging - Every operation logged for transparency
Persistent rules - Rules saved to MEMORY.md, work across sessions
Auto-run - Runs in background (v1.2.0), no manual intervention needed
Dry-run preview - Shows what will be deleted before doing it
Forget command - Remove tracking without deleting files

The Key Difference

Hermes normally: Leave mess, clean when asked, forget about it
Disk Guardian: Prevents mess, cleans automatically, remembers everything

It's the difference between "I'll clean my room when my mom tells me to" vs "I have a robot that keeps my room clean 24/7."

You prefer systematic, automated tools over manual approaches - this is exactly that. It runs silently in background with persistent memory, just like you want.

What's included

optional-skills/devops/disk-guardian/SKILL.md — skill document
optional-skills/devops/disk-guardian/scripts/disk_guardian.py — Python helper

Cleanup rules (deterministic)

Category	Threshold	Confirmation
`test`	>0 days — deleted at task end	Never
`temp`	>7 days since tracked	Never
`cron-output`	>14 days since tracked	Never
empty dirs	always	Never
`research`	>30 days, beyond 10 newest	Always
`chrome-profile`	>14 days since tracked	Always
files >500 MB	never auto	Always (deep only)

Persistent memory (new in v1.2.0)

Running disk_guardian.py install-memory writes rules to MEMORY.md so
the agent auto-tracks and auto-cleans across all future sessions without
any user prompt.

Usage

Quick Start

# Set the script path
SCRIPT=~/.hermes/optional-skills/devops/disk-guardian/scripts/disk_guardian.py

# Install persistent memory (run once)
python3 $SCRIPT install-memory

# Check what's tracked
python3 $SCRIPT status

# Preview what would be deleted
python3 $SCRIPT dry-run

# Auto-delete safe files
python3 $SCRIPT quick

# Full cleanup with prompts
python3 $SCRIPT deep

All Commands

Command	What It Does
`install-memory`	Write persistent rules to MEMORY.md (run once)
`status`	Show tracked files by category + top 10 largest
`dry-run`	Preview deletions without touching anything
`quick`	Auto-delete safe files (no prompts)
`deep`	Full cleanup, prompt for risky items
`track <path> <category>`	Register a file for tracking
`forget <path>`	Stop tracking a path

Tracking Files

# Track a test script
python3 $SCRIPT track "/home/user/.hermes/test_output.py" "test"

# Track temp output
python3 $SCRIPT track "/home/user/.hermes/cache/run_abc.json" "temp"

# Track cron output
python3 $SCRIPT track "/home/user/.hermes/cron/report_2026.md" "cron-output"

# Track research folder
python3 $SCRIPT track "/home/user/.hermes/research/project" "research"

Auto-Run Behavior

Disk Guardian runs silently in background:

Auto-tracks files created during tasks
Auto-runs quick cleanup at end of tasks with test files
Auto-runs if HERMES_HOME exceeds 5 GB
Never asks for safe categories (temp, test, empty dirs)
Only surfaces when confirmation needed (research, large files)

Path Safety

✅ Allowed:

Files under HERMES_HOME (usually ~/.hermes)
/tmp/hermes-* files

❌ Rejected:

Files outside HERMES_HOME
/tmp/ files without hermes- prefix
Windows mounts (/mnt/c/, /mnt/d/, etc.)

When It Triggers

Auto-trigger (no user prompt):

End of task that created test files
Session context window exceeds 60%
Any file matching test_*, *.test.*, tmp_* created
User says "done", "finished", "task complete"

User-triggered:

"disk is full", "clean up", "free space"
"what temp files exist", "show disk usage"
"run cleanup"

Verification

# Check cleanup log
tail -5 ~/.hermes/disk-guardian/cleanup.log

# Ask Hermes about memory
"what do you remember about disk cleanup?"

Notes

_is_safe_path() enforced in code — rejects anything outside HERMES_HOME
Backup/restore scoped to tracked.json only, never ~/.hermes/logs/
WSL2-aware: rejects /mnt/c/ and other Windows mounts
Atomic writes: .tmp → backup → replace
Optional skill, not bundled

…iles and disk optimization

@LVT382009

Rewires @LVT382009's disk-guardian (PR #12212) from a skill-plus-script into a plugin that runs entirely via hooks — no agent compliance needed. - post_tool_call hook auto-tracks files created by write_file / terminal / patch when they match test_/tmp_/*.test.* patterns under HERMES_HOME - on_session_end hook runs cmd_quick cleanup when test files were auto-tracked during the turn; stays quiet otherwise - /disk-guardian slash command keeps status / dry-run / quick / deep / track / forget for manual use - Deterministic cleanup rules, path safety, atomic writes, and audit logging preserved from the original contribution - Protect well-known top-level state dirs (logs/, memories/, sessions/, cron/, cache/, etc.) from empty-dir removal so fresh installs don't get gutted on first session end The plugin system gains a bundled-plugin discovery path (<repo>/plugins/ <name>/) alongside user/project/entry-point sources. Memory and context_engine subdirs are skipped — they keep their own discovery paths. HERMES_DISABLE_BUNDLED_PLUGINS=1 suppresses the scan; the test conftest sets it by default so existing plugin tests stay clean. Co-authored-by: LVT382009 <levantam.98.2324@gmail.com>

@LVT382009

Rewires @LVT382009's disk-guardian (PR #12212) from a skill-plus-script into a plugin that runs entirely via hooks — no agent compliance needed. - post_tool_call hook auto-tracks files created by write_file / terminal / patch when they match test_/tmp_/*.test.* patterns under HERMES_HOME - on_session_end hook runs cmd_quick cleanup when test files were auto-tracked during the turn; stays quiet otherwise - /disk-guardian slash command keeps status / dry-run / quick / deep / track / forget for manual use - Deterministic cleanup rules, path safety, atomic writes, and audit logging preserved from the original contribution - Protect well-known top-level state dirs (logs/, memories/, sessions/, cron/, cache/, etc.) from empty-dir removal so fresh installs don't get gutted on first session end The plugin system gains a bundled-plugin discovery path (<repo>/plugins/ <name>/) alongside user/project/entry-point sources. Memory and context_engine subdirs are skipped — they keep their own discovery paths. HERMES_DISABLE_BUNDLED_PLUGINS=1 suppresses the scan; the test conftest sets it by default so existing plugin tests stay clean. Co-authored-by: LVT382009 <levantam.98.2324@gmail.com>

teknium1 · 2026-04-20T11:47:10Z

Merged via PR #12944 — #12944

Your commits (068b224, aeecf06, 32e6bae) were cherry-picked onto current main with your authorship preserved in git log. The skill was ported to a bundled plugin that runs the same deterministic cleanup rules automatically via post_tool_call + on_session_end hooks — the agent no longer needs to remember to call a script.

We also took the opportunity to flip all plugins (bundled and user-installed) to opt-in by default, so disk-cleanup ships discovered but disabled; users activate it with hermes plugins enable disk-cleanup. Thanks for the contribution — the safety logic and deterministic rules you wrote carry over intact.

@LVT382009

Rewires @LVT382009's disk-guardian (PR NousResearch#12212) from a skill-plus-script into a plugin that runs entirely via hooks — no agent compliance needed. - post_tool_call hook auto-tracks files created by write_file / terminal / patch when they match test_/tmp_/*.test.* patterns under HERMES_HOME - on_session_end hook runs cmd_quick cleanup when test files were auto-tracked during the turn; stays quiet otherwise - /disk-guardian slash command keeps status / dry-run / quick / deep / track / forget for manual use - Deterministic cleanup rules, path safety, atomic writes, and audit logging preserved from the original contribution - Protect well-known top-level state dirs (logs/, memories/, sessions/, cron/, cache/, etc.) from empty-dir removal so fresh installs don't get gutted on first session end The plugin system gains a bundled-plugin discovery path (<repo>/plugins/ <name>/) alongside user/project/entry-point sources. Memory and context_engine subdirs are skipped — they keep their own discovery paths. HERMES_DISABLE_BUNDLED_PLUGINS=1 suppresses the scan; the test conftest sets it by default so existing plugin tests stay clean. Co-authored-by: LVT382009 <levantam.98.2324@gmail.com>

@LVT382009

Rewires @LVT382009's disk-guardian (PR NousResearch#12212) from a skill-plus-script into a plugin that runs entirely via hooks — no agent compliance needed. - post_tool_call hook auto-tracks files created by write_file / terminal / patch when they match test_/tmp_/*.test.* patterns under HERMES_HOME - on_session_end hook runs cmd_quick cleanup when test files were auto-tracked during the turn; stays quiet otherwise - /disk-guardian slash command keeps status / dry-run / quick / deep / track / forget for manual use - Deterministic cleanup rules, path safety, atomic writes, and audit logging preserved from the original contribution - Protect well-known top-level state dirs (logs/, memories/, sessions/, cron/, cache/, etc.) from empty-dir removal so fresh installs don't get gutted on first session end The plugin system gains a bundled-plugin discovery path (<repo>/plugins/ <name>/) alongside user/project/entry-point sources. Memory and context_engine subdirs are skipped — they keep their own discovery paths. HERMES_DISABLE_BUNDLED_PLUGINS=1 suppresses the scan; the test conftest sets it by default so existing plugin tests stay clean. Co-authored-by: LVT382009 <levantam.98.2324@gmail.com>

@LVT382009

Rewires @LVT382009's disk-guardian (PR NousResearch#12212) from a skill-plus-script into a plugin that runs entirely via hooks — no agent compliance needed. - post_tool_call hook auto-tracks files created by write_file / terminal / patch when they match test_/tmp_/*.test.* patterns under HERMES_HOME - on_session_end hook runs cmd_quick cleanup when test files were auto-tracked during the turn; stays quiet otherwise - /disk-guardian slash command keeps status / dry-run / quick / deep / track / forget for manual use - Deterministic cleanup rules, path safety, atomic writes, and audit logging preserved from the original contribution - Protect well-known top-level state dirs (logs/, memories/, sessions/, cron/, cache/, etc.) from empty-dir removal so fresh installs don't get gutted on first session end The plugin system gains a bundled-plugin discovery path (<repo>/plugins/ <name>/) alongside user/project/entry-point sources. Memory and context_engine subdirs are skipped — they keep their own discovery paths. HERMES_DISABLE_BUNDLED_PLUGINS=1 suppresses the scan; the test conftest sets it by default so existing plugin tests stay clean. Co-authored-by: LVT382009 <levantam.98.2324@gmail.com>

@LVT382009

Rewires @LVT382009's disk-guardian (PR NousResearch#12212) from a skill-plus-script into a plugin that runs entirely via hooks — no agent compliance needed. - post_tool_call hook auto-tracks files created by write_file / terminal / patch when they match test_/tmp_/*.test.* patterns under HERMES_HOME - on_session_end hook runs cmd_quick cleanup when test files were auto-tracked during the turn; stays quiet otherwise - /disk-guardian slash command keeps status / dry-run / quick / deep / track / forget for manual use - Deterministic cleanup rules, path safety, atomic writes, and audit logging preserved from the original contribution - Protect well-known top-level state dirs (logs/, memories/, sessions/, cron/, cache/, etc.) from empty-dir removal so fresh installs don't get gutted on first session end The plugin system gains a bundled-plugin discovery path (<repo>/plugins/ <name>/) alongside user/project/entry-point sources. Memory and context_engine subdirs are skipped — they keep their own discovery paths. HERMES_DISABLE_BUNDLED_PLUGINS=1 suppresses the scan; the test conftest sets it by default so existing plugin tests stay clean. Co-authored-by: LVT382009 <levantam.98.2324@gmail.com>

@LVT382009

Rewires @LVT382009's disk-guardian (PR NousResearch#12212) from a skill-plus-script into a plugin that runs entirely via hooks — no agent compliance needed. - post_tool_call hook auto-tracks files created by write_file / terminal / patch when they match test_/tmp_/*.test.* patterns under HERMES_HOME - on_session_end hook runs cmd_quick cleanup when test files were auto-tracked during the turn; stays quiet otherwise - /disk-guardian slash command keeps status / dry-run / quick / deep / track / forget for manual use - Deterministic cleanup rules, path safety, atomic writes, and audit logging preserved from the original contribution - Protect well-known top-level state dirs (logs/, memories/, sessions/, cron/, cache/, etc.) from empty-dir removal so fresh installs don't get gutted on first session end The plugin system gains a bundled-plugin discovery path (<repo>/plugins/ <name>/) alongside user/project/entry-point sources. Memory and context_engine subdirs are skipped — they keep their own discovery paths. HERMES_DISABLE_BUNDLED_PLUGINS=1 suppresses the scan; the test conftest sets it by default so existing plugin tests stay clean. Co-authored-by: LVT382009 <levantam.98.2324@gmail.com>

@LVT382009

Rewires @LVT382009's disk-guardian (PR NousResearch#12212) from a skill-plus-script into a plugin that runs entirely via hooks — no agent compliance needed. - post_tool_call hook auto-tracks files created by write_file / terminal / patch when they match test_/tmp_/*.test.* patterns under HERMES_HOME - on_session_end hook runs cmd_quick cleanup when test files were auto-tracked during the turn; stays quiet otherwise - /disk-guardian slash command keeps status / dry-run / quick / deep / track / forget for manual use - Deterministic cleanup rules, path safety, atomic writes, and audit logging preserved from the original contribution - Protect well-known top-level state dirs (logs/, memories/, sessions/, cron/, cache/, etc.) from empty-dir removal so fresh installs don't get gutted on first session end The plugin system gains a bundled-plugin discovery path (<repo>/plugins/ <name>/) alongside user/project/entry-point sources. Memory and context_engine subdirs are skipped — they keep their own discovery paths. HERMES_DISABLE_BUNDLED_PLUGINS=1 suppresses the scan; the test conftest sets it by default so existing plugin tests stay clean. Co-authored-by: LVT382009 <levantam.98.2324@gmail.com>

feat(skills): add disk-guardian — autonomous cleanup of Hermes temp f…

4ed0aaf

…iles and disk optimization

LVT382009 changed the title ~~feat(skills): add disk-guardian — autonomous cleanup of Hermes temp files & test file and disk optimization~~ feat(skills): add disk-guardian — autonomous cleanup of Hermes temp files and disk optimization Apr 18, 2026

LVT382009 added 2 commits April 19, 2026 05:20

Update SKILL.md

989fb11

Update disk_guardian.py

3128386

LVT382009 changed the title ~~feat(skills): add disk-guardian — autonomous cleanup of Hermes temp files and disk optimization~~ feat(skills): add disk-guardian — auto ephemeral session file cleanup with persistent memory Apr 18, 2026

teknium1 mentioned this pull request Apr 20, 2026

feat(plugins): opt-in-by-default + bundled disk-cleanup plugin (salvage #12212) #12944

Merged

teknium1 closed this in #12944 Apr 20, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(skills): add disk-guardian — auto ephemeral session file cleanup with persistent memory#12212

feat(skills): add disk-guardian — auto ephemeral session file cleanup with persistent memory#12212
LVT382009 wants to merge 3 commits into
NousResearch:mainfrom
LVT382009:feat/disk-guardian-v2

LVT382009 commented Apr 18, 2026 •

edited

Loading

Uh oh!

teknium1 commented Apr 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

LVT382009 commented Apr 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why It's Better Than Manual Cleanup

What Hermes Normally Does ❌

What Disk Guardian Does ✅

The Key Difference

What's included

Cleanup rules (deterministic)

Persistent memory (new in v1.2.0)

Usage

Quick Start

All Commands

Tracking Files

Auto-Run Behavior

Path Safety

When It Triggers

Verification

Notes

Uh oh!

teknium1 commented Apr 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

LVT382009 commented Apr 18, 2026 •

edited

Loading