How-To Guide
How to Set Up Hermes Agent Memory
Configure Hermes Agent built-in memory, review MEMORY.md and USER.md, choose an optional external memory provider, and separate durable facts from session history.
Quick answer
Hermes Agent has built-in persistent memory: ~/.hermes/memories/MEMORY.md stores durable environment facts and USER.md stores stable user preferences. Enable memory.memory_enabled and memory.user_profile_enabled, start a new session after writes, and use the SQLite session store for historical task recall. hermes memory setup is only for adding one optional external provider alongside built-in memory.
Hermes Agent memory setup has two distinct layers. Built-in memory keeps concise durable facts in MEMORY.md and USER.md, while the SQLite session store preserves conversations for resume and FTS5 session search. Optional external providers add semantic search, knowledge graphs, fact extraction, or cross-session user modeling. Start with built-in memory, verify the correct profile, and add a provider only when you can name the capability you need.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed
- ☑Access to the intended Hermes profile
- ☑No external database or memory provider is required for built-in memory
Steps
- 1
Check the active profile and memory status
Run
hermes profile showandhermes memory status. Hermes profiles isolate memory, sessions, skills, and config, so first prove you are changing the profile that your CLI or gateway actually uses. - 2
Enable built-in memory in config
Run
hermes config editand confirmmemory.memory_enabled: trueandmemory.user_profile_enabled: true. Built-in memory uses~/.hermes/memories/MEMORY.mdfor durable environment facts andUSER.mdfor stable user preferences. - 3
Add only durable context
Tell Hermes stable facts worth carrying into future sessions: your timezone, preferred output style, project conventions, recurring infrastructure, or long-lived constraints. Do not turn memory into a task log; use named sessions and session search for past work.
- 4
Start a new session and verify recall
Built-in memory is injected as a frozen snapshot at session start. After a write, use
/new memory-checkor restart the relevant gateway session, then ask Hermes to recall one non-sensitive test preference. - 5
Choose whether writes need approval
For reviewed environments, set
memory.write_approval: trueor run/memory approval on. Review staged writes with/memory pending,/memory approve <id>, and/memory reject <id>before they become durable. - 6
Add an external provider only if you need one
Run
hermes memory setupto choose Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, or Supermemory. One external provider can be active at a time, and it runs alongside built-in MEMORY.md and USER.md rather than replacing them. - 7
Verify the final setup
Run
hermes memory status, start a fresh session, and test one safe fact. For long conversations, use/compress; for historical task recall, ask Hermes to search sessions instead of stuffing temporary progress into durable memory.
Pro Tips
- 💡Keep MEMORY.md concise: environment facts, durable conventions, and lessons likely to matter again.
- 💡Keep USER.md focused on stable user preferences and profile details rather than project status.
- 💡Use
/compressto reduce a long active context; compression does not delete stored sessions or durable memory. - 💡Use named sessions,
hermes --continue, and session search for task continuity; those are different from durable memory. - 💡Enable memory write approval when several people or unattended agents share a profile.
- 💡Use a separate profile when projects need isolated memories, skills, secrets, sessions, or gateway bots.
- 💡If
/sessionslooks empty in a messaging chat, runhermes sessions statsbefore changing memory. The picker and FTS5 session search have different scopes and purposes.
Troubleshooting
❌ Hermes forgets things between sessions
✅ Run hermes memory status, confirm memory.memory_enabled and memory.user_profile_enabled, verify the active profile, and start a new session so the latest MEMORY.md and USER.md snapshot is loaded.
❌ A past task does not appear in durable memory
✅ That is often correct: task transcripts belong in the SQLite session store. Resume the named session or use session search; save only reusable facts and lessons to durable memory.
❌ MEMORY.md changes not reflected in responses
✅ Hermes loads a frozen memory snapshot at session start. Use /new, resume a fresh continuation, or restart the affected gateway process after editing memory.
❌ An external memory provider broke normal behavior
✅ Run hermes memory status, then hermes memory off to disable the external provider and retest built-in memory. External providers are additive, so built-in MEMORY.md and USER.md should continue working.
❌ CLI memory works but Telegram or Discord does not
✅ Check which profile and service environment the gateway uses. A gateway may be running under a different profile or stale process even when the local CLI reads the expected memory.
❌ Session search finds some platforms but not the phrase you remember
✅ Confirm the active profile, run hermes sessions stats, search an exact phrase with oldest/newest direction, and remember that BM25 relevance can rank newer matches first. Do not promote the whole transcript into MEMORY.md.
FAQ
Does Hermes Agent memory work without an external provider?
Yes. Built-in MEMORY.md and USER.md remain available without Honcho, Mem0, Hindsight, or another provider. External providers are optional and additive.
What is the difference between memory and session history?
Memory stores concise durable facts and preferences. Session history stores the full conversation, tool calls, titles, compression lineage, and FTS5 index used for resume and session search.
Where does Hermes Agent store memory?
Built-in persistent memory lives under ~/.hermes/memories/, primarily in MEMORY.md and USER.md. Profiles use their own profile-scoped Hermes home and therefore their own memory files.
What does hermes memory setup do?
It opens the provider picker for optional external memory systems. It is not required to turn on built-in MEMORY.md and USER.md. Use hermes memory status to see what is active.
Should I put API keys or passwords in Hermes memory?
No. Put secrets in the profile .env or an approved secret store. Durable memory is for non-secret facts, preferences, conventions, and reusable lessons.
Related setup and cost guides
How Hermes persistent memory works
Understand built-in durable memory, session history, profiles, and optional provider layers.
Fix Hermes memory and context problems
Diagnose profile, session, compression, provider, and gateway failures without guessing.
Use separate Hermes Agent profiles
Isolate memories, sessions, skills, config, secrets, and gateway bots by project.
Back up Hermes memory safely
Preserve durable state without committing secrets, browser data, logs, or raw transcripts.
Inspect memory in the Hermes dashboard
Review the active profile, memory state, sessions, logs, providers, and gateway health.