#Hermes Agent Memory System

Memory is what makes Hermes "remember you." Instead of forgetting after every chat, it carries preferences, projects, and experience across sessions. This chapter breaks down its three-layer design.

#Why Memory?

An ordinary chatbot starts from zero each session, forcing you to repeat context. Hermes solves this with persistent memory:

Memoryless assistant: asks "who are you, what project?" every time
Hermes:               "Let's continue the notes project from last week —
                       you said you prefer bullet lists."

#The Three-Layer Memory Model

Cognitively, Hermes's memory has three kinds:

To avoid stuffing everything into every prompt, Hermes uses RAG (retrieval-augmented generation): it dynamically retrieves relevant memories into context as needed.

#Mapped to Three Files

At the storage layer, memory and persona live in three clearly separated files under ~/.hermes/:

SOUL.md   →  "who I am" (the agent's personality)
MEMORY.md →  "what I've learned" (experience)
USER.md   →  "what I know about you" (about you)

This separation means you can tune any layer independently: swap personas without losing memory; prune memory without touching the persona.

#Retrieval & Recall

• FTS5 full-text search: fast search across all sessions
• LLM summarization: summarize long histories for cross-session recall
• Periodic nudges: prompts that encourage saving important knowledge
• Honcho dialectic user modeling: a richer user profile

new message → retrieve relevant memory (FTS5/RAG) → inject context → model answers → (as needed) write back to MEMORY/USER

#SOUL.md: Defining the "Soul"

SOUL is a structured document defining the agent's:

• Name, persona, communication style
• Core values and priorities
• How to handle ambiguity and disagreement
• Behavioral restrictions (what not to do)
• Context-specific behavior (professional vs. casual)

By editing SOUL.md (or switching with /personality), you can shape an assistant that truly matches your habits.

#Self-Improvement & Memory Curation

Memory isn't a write-only junk drawer. Hermes continuously optimizes at four levels:

• User level: recognize patterns from feedback, adapt to your habits
• Skill level: refine more reliable execution paths
• Memory curation: raise signal-to-noise, keep the useful, drop the noise
• Soul calibration: update SOUL config when warranted

#Practical Tips

• Proactively tell Hermes your long-term preferences; it writes them to USER/MEMORY
• Periodically review MEMORY.md and prune stale or wrong memories by hand
• Use ~/.hermes/ for versioned backups — copy it to migrate to a new machine
• To adjust the persona, edit SOUL.md — don't mix persona into MEMORY

#Next Steps

• Skills — memory + skills = stronger over time
• Architecture & Features — where memory sits in the loop
• Hands-on Practice — make the assistant remember your workflow