Persona and Memory: How They Shape Each Other

+15 Mana ✨
Persona and Memory Composition(DOCUMENTATION)

Introduction

SOUL.md and the persistent memory files (USER.md, MEMORY.md) work together inside the same system prompt. SOUL.md is who the agent is. USER.md is who you are. MEMORY.md is what the agent has learned about your environment. The three files are read at session start, sit near each other in the prompt stack, and shape each other's effect in subtle ways.

Key Concepts

  • Identity layer: SOUL.md, slot #1. The agent's voice.
  • User profile: USER.md, included with the persistent memory snapshot. Your role, preferences, communication style.
  • Environment facts: MEMORY.md. Tools, paths, conventions discovered or declared.
  • Composition: The model reads all three together and produces responses that try to honor every layer.

Real World Context

A developer's USER.md says "Olivier prefers terse, technical responses." Their SOUL.md says "You are a patient, enthusiastic teacher." The two are in tension. The next response under this setup tries to be brief but pedagogical, often with awkward results: a short paragraph that still tries to explain a term. The agent is not broken; the files are inconsistent. The fix is to make them agree ("You are a patient, enthusiastic teacher who keeps responses short") or to pick the one that should dominate in this context.

Deep Dive

The three layers compose like CSS rules: each contributes constraints, and the agent tries to satisfy all of them. When they agree, the effect is reinforcing. When they disagree, the agent improvises a middle ground that may not be what you want.

Reinforcement (good). SOUL.md says "be direct." USER.md says "Olivier prefers short answers." MEMORY.md says "This user works in Go and Postgres; assume technical fluency." All three reinforce a terse, technical voice. The agent has clean signals and produces consistent output.

Tension (mixed). SOUL.md says "be a patient teacher." USER.md says "prefers short answers." The agent tries to be both, producing short pedagogy. Sometimes this works. Often it feels stuck between two styles.

Conflict (bad). SOUL.md says "never use emoji." USER.md says "loves emoji and casual chat." The agent picks one and feels wrong to whoever wrote the other.

The practical move: when you craft SOUL.md, glance at your USER.md (and MEMORY.md, if it has voice-relevant entries) and make sure they agree. They are co-authored, in effect. A new persona should not contradict your profile, and a profile update should not silently contradict your SOUL.md.

There is also a user profiling dimension worth knowing about. Hermes can build USER.md over time from observed preferences ("prefers terse responses," "uses fish shell," "works in Europe/Paris timezone"). Those auto-discovered preferences become part of the prompt the agent reads. If your SOUL.md fights the profile, you will feel the friction even if you do not see USER.md directly.

Finally: SOUL.md is agent identity; USER.md is user identity. The clearest setups keep them on opposite sides of that line. SOUL.md says nothing about you. USER.md says nothing about the agent's voice. When you respect that separation, the two compose cleanly.

Common Pitfalls

  1. Cross-contamination: Putting user preferences in SOUL.md or persona traits in USER.md. The files exist precisely to keep these separate.
  2. Silent conflicts: SOUL.md and USER.md drift apart over weeks because they were edited at different times. Re-read both quarterly.

Best Practices

  1. Co-author SOUL.md and USER.md: When you create or update one, glance at the other to check for agreement.
  2. Keep agent identity and user identity on opposite sides of the line: SOUL.md about the agent. USER.md about you. No cross-contamination.

Summary

  • SOUL.md, USER.md, and MEMORY.md compose like layered constraints. The agent tries to honor all of them.
  • Reinforcement is good; tension is mixed; conflict produces inconsistent output.
  • Auto-discovered user profiling lives in USER.md; SOUL.md must not contradict it without intent.
  • Keep agent identity and user identity strictly separated.

Code Examples

markdown
# Two files that COMPOSE well

# ~/.hermes/SOUL.md (agent identity)
You are a direct, dry technical assistant. Lead with the conclusion.
No emoji. Admit uncertainty rather than fabricate.

# ~/.hermes/memories/USER.md (user profile)
Olivier, senior backend engineer in Europe/Paris.
Prefers short, technical answers. Comfortable with Go, TypeScript, Postgres.
Reads code faster than prose; show snippets when relevant.

These reinforce: terse, technical, code-forward. The agent's output is
consistent because both files point the same direction.
✓ Completed