SOUL.md Governance Framework

What SOUL.md Governance Framework does

The README argues that the native MEMORY.md, limited to 2,200 characters, and USER.md, limited to 1,375, trigger an automatic compression cycle that merges and discards entries without categories, priorities or write-time rules. The framework instead turns native memory off and keeps preferences, profile and other data in categorized files under ~/.hermes/user-memory/, guarded by a read-only SOUL.md.

It also adds a skill registry under ~/.hermes/user-registry/ for capability discovery, and a skill-maintenance script, maintain.py, that syncs the registry. The README says Hermes's built-in guidance to save skills after complex tasks provides no expiry, quality validation or duplicate detection, and the framework adds maintenance for that. Setup copies the framework files into ~/.hermes, edits Section 1 of SOUL.md for your role and language, turns off native memory with two hermes config set commands, and runs the maintenance script.

Key features

• Read-only SOUL.md governance anchor
• Categorized memory files under ~/.hermes/user-memory/
• Skill registry for capability discovery
• maintain.py script that syncs the skill registry
• Setup that disables native memory through hermes config set

When to use it

• Stop automatic compression from discarding preferences and rules
• Keep memory files organized by category rather than in one file
• Audit and clean up skills the agent has created over time

Who it is for: Hermes Agent users who want stricter, file-based control over memory and skills than the built-in MEMORY.md and USER.md provide.

How it fits with Hermes Agent

Built for Hermes Agent: it assumes the default ~/.hermes layout and replaces the built-in memory files with its own structure.

How to install SOUL.md Governance Framework

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

cp framework/SOUL.md ~/.hermes/SOUL.md
cp -r framework/user-memory ~/.hermes/
cp -r framework/user-registry ~/.hermes/
cp -r framework/skills/user-created ~/.hermes/skills/

Requirements: A working Hermes Agent installation in the default ~/.hermes location.

Note: Setup turns off Hermes's built-in memory by setting memory.memory_enabled and memory.user_profile_enabled to false.

FAQ