hermes - 💡(How to fix) Fix Architecture: State Persistence Precedence (Memory vs Skills vs Hooks) [1 pull requests]

Problem or Use Case

Hermes currently has multiple state sources that can all influence behavior in a single run (session context, persistent memory, skills, hooks/plugins, profile config, and runtime flags). The precedence between these sources is not documented in one canonical place.

This creates avoidable triage noise:

• contributors cannot quickly tell whether behavior is a bug vs expected override behavior
• debugging gets slower because "which layer won" is unclear
• user-facing guidance can conflict across docs because precedence is implicit

Proposed Solution

Add a canonical, test-backed precedence model for runtime state resolution, then document it once and reference it everywhere.

Suggested deliverables:

1. Single source-of-truth spec

   • Add a docs page (or architecture ADR) defining precedence and conflict rules across:
     • CLI/runtime flags
     • profile config
     • session context
     • persistent memory
     • loaded skills
     • hooks/plugins
   • Include tie-breakers and deterministic ordering when multiple sources set the same key.

2. Implementation alignment

   • Centralize merge/override logic in one resolver path (instead of scattered ad-hoc precedence checks).
   • Emit optional debug trace (e.g., hermes debug or verbose mode) that shows why a value was selected and from which source.

3. Regression tests

   • Add table-driven tests for conflict scenarios (same key set in multiple layers).
   • Cover at least one integration test proving docs + runtime behavior match.

Alternatives Considered

• Keep current behavior and add scattered doc notes. This reduces immediate effort but does not prevent future drift.
• Only add debug output without a canonical precedence contract. Helpful, but still leaves ambiguity about intended behavior.

Feature Type

Developer experience (tests, docs, CI)

Scope

Medium (few files, < 300 lines)

Additional Context

This is primarily an architecture/docs consistency request intended to reduce bug-report ambiguity and speed up maintainer triage. It can be split into:

• docs-first issue (contract)
• implementation parity issue (resolver + tests) if maintainers prefer smaller slices.