Skip to main content
Hermes maintains persistent memory across sessions. Rather than relying on you to re-explain your preferences and context every time, it remembers what matters and builds on it.

​
How memory works

There are two memory files, both stored in ~/.hermes/memories/:
FilePurpose
MEMORY.mdThe agent’s personal notes — environment facts, project conventions, tool quirks, things learned
USER.mdYour profile — name, role, preferences, communication style, workflow habits
Both files are loaded once at session start and injected into the system prompt as a frozen snapshot. Mid-session writes update the files on disk immediately but do not change the active system prompt — this preserves Anthropic prompt caching for the entire session. The snapshot refreshes on the next session start. Entries are separated by § (section sign) and have character limits to keep the system prompt compact.

​
Memory locations

~/.hermes/
├── memories/
│   ├── MEMORY.md    # agent notes
│   └── USER.md      # user profile
├── SOUL.md          # agent persona
└── config.yaml

​
Periodic memory nudges

Hermes proactively notices when important information should be saved. After a conversation where you share preferences or the agent discovers something worth keeping, it will offer to write a memory entry. You can also trigger this manually: 
Remember that I prefer TypeScript over JavaScript
Or use the memory tool directly: 
Save this to memory: project uses pnpm, not npm
Past conversations are stored in a SQLite database with FTS5 full-text search. The session_search tool lets the agent search across all past sessions by keyword, summarize results with an LLM, and surface relevant context from previous work. You can trigger a search from a slash command or by asking the agent: 
What did we work on last week regarding the auth system?
The agent will search past sessions, retrieve relevant excerpts, and synthesize a summary.

​
Honcho dialectic user modeling

Honcho is an AI-native memory system that builds a persistent model of who you are across sessions using dialectic reasoning — it asks clarifying questions and refines its understanding of your preferences, goals, and context over time. To enable Honcho:
  1. Set the HONCHO_API_KEY environment variable in ~/.hermes/.env
  2. Honcho tools (honcho_context, honcho_profile, honcho_search, honcho_conclude) activate automatically
Honcho memory complements the built-in MEMORY.md/USER.md system — they can be used together.

​
SOUL.md

~/.hermes/SOUL.md is the agent’s persona file. It defines Hermes’s character, communication style, and behavioral defaults. Edit it to adjust how the agent presents itself: 
hermes config edit  # opens your editor
# or edit directly:
nano ~/.hermes/SOUL.md
A default SOUL.md is seeded on first run. If you’re migrating from OpenClaw, hermes claw migrate can import your existing SOUL.md.

​
Memory best practices

Keep memory entries compact and factual. The memory store has a character limit (2200 chars for MEMORY.md, 1375 chars for USER.md). Long entries crowd out other useful facts.
  • Do save: preferences, environment facts, project conventions, corrections, tool quirks
  • Don’t save: session outcomes, completed-work logs, temporary task state (use session_search to recall those)
  • For procedures: use skills instead of memory
  • For user identity: prefer USER.md over MEMORY.md

​
/insights command

Run /insights (or /insights --days 30) to see usage analytics for your sessions — turn counts, tool usage frequency, session lengths, and more. This helps you understand how you’re using the agent and identify patterns.
All memory data is stored locally in ~/.hermes/. Nothing is sent to external servers unless you explicitly enable Honcho, which uses the Honcho API. The HERMES_HOME environment variable lets you relocate the storage directory.

Build docs developers (and LLMs) love

Get started for freeTalk to us