Hermes Session Maintenance Setup¶
Monthly cleanup script for Hermes Agent's state.db. Closes zombie sessions, prunes old data, backs up the database, and reclaims disk space -- all with zero tokens consumed by the agent.
The Problem It Solves¶
Hermes Agent stores all sessions and messages in state.db (SQLite). Over time:
- Zombie sessions (never closed) leak memory and confuse the gateway
- FTS5 indexes grow with every message sent
- SQLite never releases pages without
VACUUM - RAM usage climbs as the gateway loads accumulated session data
Without maintenance, a production Hermes instance degrades silently.
Quick Install¶
# Copy the script
mkdir -p ~/.hermes/scripts
curl -L https://raw.githubusercontent.com/salt-vrn/hermes-session-maintenance/main/scripts/session-maintenance.sh \
-o ~/.hermes/scripts/session-maintenance.sh
chmod +x ~/.hermes/scripts/session-maintenance.sh
# Preview what would happen (safe, no changes)
bash ~/.hermes/scripts/session-maintenance.sh --dry-run
# Run for real
bash ~/.hermes/scripts/session-maintenance.sh
What It Does¶
| Step | Action | Threshold |
|---|---|---|
| 1 | Sanity check | Verify started_at is unix seconds |
| 2 | Close zombie sessions | ended_at IS NULL and older than 1 day |
| 3 | Prune ended sessions | Older than 7 days (messages + FTS cascade) |
| 4 | Backup state.db | Timestamped copy in ~/.hermes/backups/ (30-day retention) |
| 5 | VACUUM state.db | Reclaim disk space |
Scheduling¶
Hermes Cron¶
Ask the agent:
"Create a monthly cron job to run session-maintenance.sh on the 1st at 04:00"
Or use /cron create with:
- Schedule: 0 4 1 * *
- Script: session-maintenance.sh
- no_agent: true (no tokens consumed)
- deliver: origin
Manual crontab¶
0 4 1 * * /bin/bash ~/.hermes/scripts/session-maintenance.sh
Configuration¶
Edit the top of session-maintenance.sh:
DAYS_ZOMBIE=1 # Close sessions older than N days with no ended_at
DAYS_PRUNE=7 # Delete ended sessions older than N days
Output Example¶
=== Session Maintenance Start ===
10:00:01 default: zombies=3 pruned=12 freed=45MB remaining=150 sessions, 8420 messages
10:00:05 frame: zombies=0 pruned=2 freed=8MB remaining=45 sessions, 2100 messages
=== Session Maintenance Done ===
Safety Design¶
- Active sessions (< 1 day old) are never touched
started_atformat is verified before modifications (rejects ms timestamps, ISO dates)ended_at = started_atfor zombies -- no fabricated durations- Backup before VACUUM with 30-day retention
flockprevents parallel execution- Each profile processed independently -- one failure doesn't affect others
- Reports before/after stats for audit trail
⚠️ VACUUM and the Gateway¶
VACUUM requires an exclusive lock on the database. If the Hermes gateway is writing to state.db, VACUUM fails with database is locked.
Safe approaches:
- Schedule at 04:00 (low activity)
- Use --dry-run first
- If VACUUM fails -- backup is safe, retry next month
Requirements¶
- Linux (GNU grep with PCRE,
flock,du -b) - Hermes Agent installed
- Bash 4+
- Python 3 (for SQLite operations -- comes with Hermes)
← Advanced Memory Setup | Skill Cleaner Setup → Powered by CorpusIQ
Integration with CorpusIQ¶
CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.
This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.