Persistent Memory — AI's Long-Term Memory

Imagine having a brilliant assistant who forgets you the moment you leave the room. Every time you return, you have to reintroduce yourself, re-explain your coffee preferences, and recap your ongoing projects. Exhausting, right? Hermes Agent’s persistent memory is like giving your AI a personal notebook — it jots down what matters and remembers you the next time you meet.

---

Two Notebooks: MEMORY and USER

Hermes Agent uses two files to store memories, much like keeping a work journal and a personal diary:

File	Purpose	Character Limit
MEMORY.md	The AI’s own notes — environment details, project specifics, lessons learned	2,200 characters
USER.md	Your personal profile — preferences, communication style, expectations	1,375 characters

These files live in ~/.hermes/memories/ on your computer. At the start of every conversation, the AI flips open its notebook, reads the contents, and gets to work.

---

How Memories Get Written

The AI uses a tool called memory to manage what it remembers. There are three main operations:

# Add a new memory
memory add "User prefers to communicate in English"

# Replace an old memory (e.g., update project status)
memory replace "Project uses Python" → "Project migrated to Rust"

# Remove an outdated memory
memory remove "Old project info"

All of this happens automatically — you never need to edit files by hand. When the AI spots useful information, it writes it down. When memory gets full, it tidies up on its own, discarding what’s no longer important.

---

A Critical Warning: Don’t Share Notebooks

Warning: Never run two Hermes Agent processes pointing to the same folder. It’s like two people scribbling in the same diary — you’ll end up with a mess. Each AI should have its own dedicated notebook (what we call a profile). If you truly need to share information, use an external memory service instead.

---

What Happens When Memory Is Full?

The character limits are intentional — they force the AI to remember only what truly matters. When memory approaches capacity, the AI doesn’t cram things in. Instead, it consolidates: merging similar entries, deleting outdated facts, and then writing the new memory. Think of it like your phone’s storage — you clear out old files before snapping new photos.

---

A Quirky Detail: Memory Is “Frozen”

At the start of each conversation, the AI takes a “snapshot” of its memory and loads it into working memory. That snapshot stays fixed for the entire conversation — even if the AI learns something new mid-conversation, it won’t take effect until the next session. This design keeps the AI fast and stable. It’s like taking meeting notes: you don’t revise them mid-meeting; you update them afterward.

---

Summary and Practical Tips

Persistent memory transforms Hermes Agent from “meeting you for the first time, every time” to “getting to know you better with each interaction.” It remembers your projects, preferences, and environment, making every conversation smoother.

Practical tip: If you notice the AI has forgotten something important, just tell it directly: “Please remember: …” It will automatically use the memory tool to save it. Also, periodically check the ~/.hermes/memories/ folder — if you spot outdated info, feel free to edit it manually. After all, it’s your notebook!