Hermes Memory Suite

A collection of optional skills for Hermes Agent that enforce rigorous memory discipline, periodic audit, and self-improvement loop understanding.

Why this exists

Hermes Agent has a powerful but nuanced memory system — memory, fact_store (holographic), skill_manage, and session logs each serve different purposes with different lifetimes, visibility rules, and trade-offs. Without strict routing, it's easy to:

• Bloat MEMORY.md with technical project details that belong in fact_store
• Store debugging output or task progress that pollutes the system prompt every turn
• Hit the ~2.2K char limit on MEMORY.md without progressive warnings
• Lose critical insight during context compression (the holographic plugin doesn't implement on_pre_compress)
• Have the background self-improvement loop make writes it can't verify (fork has no shell access)

These skills encode hard-won lessons from real use — backed by source code analysis of Hermes Agent internals (memory_tool.py, memory_manager.py, background_review.py, context_compressor.py, conversation_loop.py, holographic plugin).

Skills included

memory-discipline (critical)

A decision tree and absolute rules for where to save what. Every time you're about to call memory, fact_store, or skill_manage, run this checklist:

Serve every turn, auto-injected?
├── YES → Stable user preference? → MEMORY (target='memory'|'user')
├── NO  → Project/technical detail? → FACT_STORE
├── NO  → Procedure with 3+ steps?  → SKILL
└── NO  → Temporary/task progress?  → Don't save (use session_search)

Documents the frozen snapshot bug (mid-session writes update the file but the system prompt stays frozen until restart), the background fork blind spot (self-improvement loop can write but can't verify), and the holographic on_pre_compress gap.

memory-audit (high)

Periodic audit procedure that checks:

• Memory saturation (yellow >80%, red >95% of char limits)
• Stale facts in fact_store (trust < 0.4)
• Semantic duplicates in memory (same concept, different wording)
• Cross-sync issues (same fact in both memory and fact_store)

Runnable on demand or triggered automatically when memory is near capacity.

self-improvement-loop (medium)

Deep documentation of how the background review system actually works — based on the real source code:

• Trigger timing: Memory nudge pre-turn (every 10 turns), skill nudge post-turn (every 10 tool iters)
• Counter resets: Calling memory() or skill_manage() resets the respective counters
• Fork architecture: Background review spawns a child AIAgent with strict tool whitelist (only memory + skill_manage), auto-deny on shell commands, max_iterations=16
• 3 known pitfalls: nudge timing blindness, no rate-limit on review writes, holographic missing on_pre_compress
• Gateway cold-start workaround: Hydrates counters from conversation_history so nudges work after gateway eviction

Installation

Each skill is a standard Hermes Agent optional skill. Copy the skill directory to your Hermes skills path:

# Copy individual skills
cp -r optional-skills/memory-discipline ~/.hermes/skills/
cp -r optional-skills/memory-audit ~/.hermes/skills/
cp -r optional-skills/self-improvement-loop ~/.hermes/skills/

Or symlink to keep them in sync:

ln -s $(pwd)/optional-skills/memory-discipline ~/.hermes/skills/
ln -s $(pwd)/optional-skills/memory-audit ~/.hermes/skills/
ln -s $(pwd)/optional-skills/self-improvement-loop ~/.hermes/skills/

Once loaded, the skills are available via skill_view(name) and follow their trigger conditions automatically.

File structure

hermes-memory-suite/
├── README.md
├── LICENSE                     (MIT)
├── optional-skills/
│   ├── memory-discipline/
│   │   ├── SKILL.md            (decision tree + absolute rules)
│   │   └── references/
│   │       └── memory-tool-limits.md  (limits table, frozen snapshot bug, fork blind spot)
│   ├── memory-audit/
│   │   └── SKILL.md            (6-phase audit procedure)
│   └── self-improvement-loop/
│       └── SKILL.md            (architecture docs, 3 pitfalls, workarounds)
└── docs/
    └── index.md                (diagram and overview — coming soon)

Requirements

• Hermes Agent (any version)
• Skills must be placed under ~/.hermes/skills/ to be loadable
• No external dependencies, no plugins required

License

MIT — do whatever you want with it. If you find these skills useful, a star on the repo is appreciated.