Hermes Agent Memory Setup: Choose and Verify the Right Memory Layer

Steps

1. 1

   Check the active profile and memory status

   Run hermes profile show and hermes 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. 2

   Enable built-in memory in config

   Run hermes config edit and confirm memory.memory_enabled: true and memory.user_profile_enabled: true. Built-in memory uses ~/.hermes/memories/MEMORY.md for durable environment facts and USER.md for stable user preferences.

3. 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. 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-check or restart the relevant gateway session, then ask Hermes to recall one non-sensitive test preference.

5. 5

   Choose whether writes need approval

   For reviewed environments, set memory.write_approval: true or run /memory approval on. Review staged writes with /memory pending, /memory approve <id>, and /memory reject <id> before they become durable.

6. 6

   Add an external provider only if you need one

   Run hermes memory setup to 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. 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. 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. 9

   Audit the background review lane

   Use memory.write_approval: true plus /memory pending to review automatic saves. If post-turn reviews create noise or unexpected spend, inspect auxiliary.background_review and usage rows tagged background_review; temporarily set enabled: false to isolate that fork without disabling manual memory.

10. 10

    Choose the smallest memory layer that solves the problem

    Use built-in memory for a small set of durable facts and preferences; SQLite session history for past conversations and task provenance; project files such as AGENTS.md for repository rules; and an external provider only for larger semantic retrieval, structured fact extraction, graphs, or shared memory. More layers are not automatically better because every retrieved item can consume context and introduce stale facts.

11. 11

    Pick an external provider by operating constraint

    Choose local-first when data residency and offline operation matter; choose a hosted provider when managed indexing and team access matter; choose a graph/fact-oriented system only when relationships and entity history are the job. Before committing, verify export/migration, deletion, pricing, API limits, health checks, and whether the provider is scoped per Hermes profile. Do not infer quality from a dashboard screenshot or a creator benchmark alone.

12. 12

    Run the five-prompt recall test

    In a disposable profile, save one non-sensitive preference and one project convention. Start a new session, then ask: (1) recall the preference, (2) recall the convention, (3) distinguish it from a contradictory temporary instruction, (4) cite or identify the memory source when possible, and (5) say what is unknown. Repeat after /compress and after a gateway/CLI reconnection. Pass means correct recall without inventing a third fact.

13. 13

    Separate memory recall from session-store health

    Built-in memory files can be healthy while SQLite session history is unavailable. If Desktop shows session storage unavailable: FATAL, follow the memory and session-storage troubleshooting guide: update first, preserve state.db and its WAL/SHM sidecars, check the active profile, and use non-destructive inspection before repair.

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 /compress to 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 /sessions looks empty in a messaging chat, run hermes sessions stats before changing memory. The picker and FTS5 session search have different scopes and purposes.
• 💡Use display.memory_notifications: verbose when 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.
• 💡Measure memory by correct retrieval and restraint, not by how much text it stores.
• 💡A provider dashboard proves records exist; a fresh-session prompt proves Hermes can retrieve and use the right record.
• 💡For team use, isolate profiles and secrets first. Shared memory is not a substitute for access control.
• 💡If retrieval increases prompt cost, compare one fresh-session call with and without the external provider before expanding the corpus.

Troubleshooting

FAQ

Related setup and cost guides