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. - 8
Set a memory-capacity policy
Built-in MEMORY.md is capped at 2,200 characters and USER.md at 1,375. When a write is rejected, use
hermes journey list, edit or delete stale memory nodes, consolidate overlapping entries, and retry. Do not turn durable memory into a transcript store. - 9
Audit the background review lane
Use
memory.write_approval: trueplus/memory pendingto review automatic saves. If post-turn reviews create noise or unexpected spend, inspectauxiliary.background_reviewand usage rows taggedbackground_review; temporarily setenabled: falseto isolate that fork without disabling manual 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. - 💡Use
display.memory_notifications: verbosewhen auditing automatic saves; it shows a compact preview without changing whether the review runs. - 💡A rejected over-capacity write is expected safety behavior. Consolidate first rather than increasing unrelated model context limits.
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.
❌ Hermes repeats actions before the context window is full
✅ Treat this as a loop diagnosis before editing memory. Check /context, /model, and /tools list; update Hermes; replay one small task in a fresh session; and compare one alternate model/provider.
❌ A memory add or replace says the store is full
✅ Review the returned entries, merge overlapping facts, and remove stale details with the memory tool or hermes journey. MEMORY.md and USER.md reject over-limit writes instead of silently evicting old facts.
❌ Automatic memory saves are noisy or cost more than expected
✅ Enable write approval, set memory notifications to verbose, and inspect auxiliary.background_review plus usage records tagged background_review. Disable only that automatic fork while testing.
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.
Does a repeated tool call mean Hermes memory is corrupt?
Usually not. At low context pressure, repeated calls are more likely to involve session state, runtime behavior, tool configuration, or model tool-use compatibility. Test those layers before changing durable memory.
How large is Hermes Agent built-in memory?
MEMORY.md is capped at 2,200 characters and USER.md at 1,375. The limits keep the frozen system-prompt block focused; detailed history belongs in SQLite session search or project files.
Can I disable automatic background memory review?
Yes. Set auxiliary.background_review.enabled: false. This stops automatic post-turn review forks but does not disable the built-in memory tool or manual /refine.
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.