pi-hermes-memory-cleanup

A utility project for cleaning up and optimizing Hermes persistent memory storage used by the Pi coding agent.

Why

Hermes stores persistent memory as markdown files plus SQLite databases. Over time this accumulates:

• Duplicate memory entries
• Outdated recovery/retired backup files
• Bloated failures.md and MEMORY.md files
• Sessions database growth

This project provides scripts, tests, and guidance to safely audit and clean Hermes memory.

Reference Source

The canonical Hermes source is cloned at:

/projects/cloned/pi-hermes-memory

Use this as the source of truth for how Hermes stores, consolidates, and loads memory.

Project Structure

Path	Purpose
.pi/agents.md	Development guidelines for this agent
.pi/locations.md	Where files, source, and docs live
src/	Implementation (analyze.ts storage stats, parse.ts entry parser, dupes.ts duplicate detection, superseded.ts supersession detection, prune.ts recovery pruning, dedupe.ts entry removal, limits.ts injection caps, trim.ts entry picker planning, cli.ts report)
test/	Vitest tests
planning/	Notes and task lists

Development

# Read-only report against ~/.pi/agent/pi-hermes-memory
npm start

# Configured injection caps vs actual usage
npx tsx src/cli.ts limits

# Pick specific entries to stop injecting (dry-run default)
npx tsx src/cli.ts trim --confirm --remove MEMORY.md#3 --remove USER.md#1

# Preview recovery-file pruning (keeps newest 10 per file)
npm run prune

# Actually prune (dry-run is the default; --confirm mutates)
npx tsx src/cli.ts prune --confirm --keep 5

# Preview duplicate/superseded entry removal
npm run dedupe

# Apply removal (backs up affected files first)
npx tsx src/cli.ts dedupe --confirm

# Run tests
npm test

# Type check
npm run typecheck

Safety

All mutating commands are dry-run by default and require --confirm. dedupe --confirm copies affected markdown files to ~/.pi/agent/pi-hermes-memory/.cleanup-backups/<timestamp>/ before rewriting, and never empties a file entirely. prune only touches .recovery-* files and always keeps the newest N per base file. Every command prints a before/after summary with bytes freed.

Report Output

npm start (read-only) prints:

• Storage stats — sizes of MEMORY.md, USER.md, failures.md, recovery/retired backup files, and the SQLite databases
• Per-request injection — what the model actually receives every request, computed from your Hermes mode: policy-only injects just the policy prompt + standing instructions (markdown files are tool-searchable, zero per-request cost); legacy-inject injects full file contents
• Memory files on disk — per-file entry counts, bytes, and estimated tokens, labeled injected vs. tool-searchable per your mode
• Stalest entries — the five entries with the oldest last= activity dates
• Largest entries — the five entries with the highest estimated token cost
• Duplicates — exact duplicates (identical normalized text) and near-duplicates (Jaccard/overlap similarity ≥ 0.6 with ≥ 5 shared tokens)
• Superseded entries — older entries whose content is largely contained (overlap ≥ 0.7) in a strictly newer, larger entry; candidates for retirement

limits shows Hermes injection configuration (~/.pi/agent/hermes-memory-config.json): memoryMode, memoryPolicyStyle, per-file char caps vs actual usage with near-cap warnings, and the failures.md injection filters (max age / max entries).

Entries are parsed from the standard Hermes markdown format: text blocks separated by § lines, with optional <!-- created=YYYY-MM-DD, last=YYYY-MM-DD --> metadata trailers.

Pi Extension

Install the package (or keep the local path in settings.json) and use inside pi:

The menu tags each operation by blast radius: ⚡ affects injected context (trim, dedupe), 💽 disk only (prune), untagged entries are read-only views.

/memory-cleanup                        interactive menu (report / limits / trim / dedupe / prune)
/memory-cleanup report                 show the full report in the TUI
/memory-cleanup limits                 injection caps vs usage
/memory-cleanup trim --confirm --remove MEMORY.md#3
                                       remove specific entries (backs up first)
/memory-cleanup dedupe --confirm       back up + remove duplicate/superseded entries
/memory-cleanup prune --confirm        delete old recovery files

License

MIT