Hermes memory is not a single “remember this” field. It is a layered system for making future agent runs require less repeated context and fewer corrections. Run /context before blaming memory: live conversation pressure and durable recall are different layers, and /context all exposes skill and tool-schema costs.
Quick answer#
Hermes Agent memory has three practical layers: durable memory for stable facts and preferences, skills for reusable procedures, and session search for recalling past conversations. Use durable memory for facts that should shape future behavior, use skills for workflows with commands and verification steps, and use session search when a user references something from a previous conversation. The memory decision guide explains where this design helps and what still needs verification.
A saved fact has three separate checkpoints#
A confirmation in chat, a durable write and a fresh-session recall are not the same event. The official persistent-memory guide, checked November 1, 2026, describes a specific failure: the model says it remembered a path without calling the memory tool. Check the write before changing your hosting plan or installing another memory plugin.
- Write: ask Hermes to use the memory tool to save one non-sensitive, stable fact. For example: “Use the memory tool to remember that my demo project uses metric units.” Confirm the tool ran and the intended store contains that entry. A sentence saying “saved” is not a receipt.
- Approval: if write approval is enabled, inspect
/memory pendingand approve only the intended entry. A staged write has not yet reached the durable store. Do not approve unrelated pending changes merely to make this test pass. - Read: finish the current task, preserve any handoff, then start
/newin the same profile. Ask neutrally which units the demo project uses, without supplying the answer. Compare the response with the saved entry.
hermes profile list
hermes memory status
hermes journey list
These commands inspect the default selected environment; for a named profile use its explicit selector, such as hermes -p work memory status. Do not compare a local CLI save with a gateway on a different profile and call the difference data loss. The memory setup guide covers configuration; the troubleshooting runbook handles failed writes and recall.
This is a proposed acceptance check, not a measured recall benchmark. It tests one approved fact in one profile; it does not establish accuracy across all tasks or providers. Never use a password, API key or private client detail as the test fact.
Restarting a gateway is not a new memory snapshot#
Built-in MEMORY.md and USER.md are loaded as a frozen system-prompt snapshot at session start. Tool responses can show live changes during a conversation, but the injected snapshot does not change with every write. This distinction preserves prefix caching; it also explains why another already-running session may still see old facts.
A messaging conversation can survive a gateway restart or machine reboot. Restarting the service therefore does not prove a new session began. Use /new at a completed-task or topic boundary when you want a genuinely fresh thread and the updated memory snapshot. Save the goal, artifact path and next action first with the session handoff checklist. Use /compress when you want to shorten the active context instead: compression is not evidence that an absent durable write occurred.
Source: official memory session-boundary documentation, checked November 1, 2026. Existing stored session history and a new active context are separate things; do not delete the session database to refresh memory.
External memory is a separate data and operations decision#
Start with built-in files when you need a few stable facts, skills when you need repeatable procedures, and session search when you need a past conversation. An external provider is useful only when you can name the additional job: semantic retrieval, a knowledge graph or deliberately shared knowledge across isolated agents. It adds setup, credentials, storage policy and potentially provider charges; it is not a prerequisite for persistent memory.
Current memory-provider documentation says an active provider can receive conversation turns, transcript/tool output and mirrored memory writes. Secret scrubbing is a safeguard, not proof that every arbitrary password or opaque token will be detected. Review the destination and retention policy before enabling it. Built-in-file storage also does not mean the selected chat model runs locally: prompt content still goes to that model's configured endpoint.
There is an important configuration boundary: the built-in memory configuration reference explicitly allows both built-in stores to be disabled while an external provider remains active. Read that control alongside the provider guide's general “additive” description; do not assume a provider repairs disabled local stores. hermes memory off disables the external provider, not the built-in memory files. Verify the active configuration and test one layer at a time.
For concurrent agents, use separate Hermes profiles rather than pointing independent writers at the same Hermes home. The official memory guide warns that shared-home writers can compound each other's entries. A shared external knowledge service needs deliberate identity and access design; it is not permission to merge private project histories.
If maintaining runtime updates, backups and gateways is the obstacle, compare self-hosted and managed operation. Managed hosting changes who maintains the service, not whether a model called the memory tool or whether a third-party memory service retained data. This site promotes FlyHermes commercially. Start with the installation guide if you want direct runtime control.
Layer 1: durable facts#
Durable memory is for compact facts that stay useful. Examples include preferred communication style, stable project paths, deployment conventions, environment quirks, and user corrections that should not need to be repeated.
Good memory is declarative:
- The project deploys through GitHub pushes.
- The user prefers concise plain-English status updates.
- The local config file is in a specific path.
Bad memory is a task log:
- Fixed bug X today.
- Opened PR Y.
- Need to finish step three tomorrow.
Those details expire quickly and belong elsewhere.
Layer 2: procedural skills#
Skills are the procedure layer. They tell Hermes when to load a workflow, which commands to run, which pitfalls to avoid, and how to verify success. A skill can be more detailed than memory because it is loaded only when relevant.
For example, a Hermes skill for browser QA might include viewport checks, console inspection, screenshot rules, and known renderer issues. That should not be crammed into a single memory entry.
Layer 3: session search#
Session search is for recall. When a user says “we fixed this before” or “use the approach from last time,” Hermes can search prior sessions instead of asking the user to repeat the whole story.
This keeps permanent memory small while still making old work discoverable. It also reduces the temptation to store raw transcripts as permanent facts.
A document index is not built-in memory#
A technical manual, a research archive and a conversation history are different sources. Reading a PDF once does not guarantee that Hermes will retrieve its exact contents in a later session. Keep the original file and a searchable derivative outside the bounded memory files; let a skill describe how to locate and cite the relevant passage.
For example, the technical-PDF retrieval guide keeps document sections in a separate SQLite index. That third-party database is not Hermes's session database and is not automatically queried by built-in memory. The agent needs an explicit retrieval procedure and access to the index from its current runtime.
A useful handoff records the document's filename, revision, approved location and the procedure for retrieving evidence. Do not save the full manual, a temporary search result or a guessed register definition as a permanent user fact. If the source changes, rebuild and verify the derivative deliberately; an old conversational answer is not a substitute for checking the new revision.
Test these stores separately in a fresh session:
- Confirm an approved stable fact was actually written to memory.
- Confirm the document exists at the path the active runtime can access.
- Run the retrieval procedure and verify a source locator against the original.
- Ask for an absent fact and inspect whether the agent acknowledges the missing evidence.
The official memory documentation, checked October 7, 2026, describes a frozen memory snapshot loaded at session start. A spoken confirmation is not a write, and a write does not retroactively refresh another running session. If a fact disappears, check the actual save, pending approval, active profile and memory enablement before changing compression settings.
How SOUL.md fits#
SOUL.md is personality and operating guidance. It is not a replacement for memory. Think of it as the stable character and behavior layer: tone, boundaries, identity, and high-level style. Memory adds facts. Skills add procedures.
For deeper customization, read the system prompt guide.
Profiles prevent context collisions#
If the same Hermes install handles personal tasks, work tasks, and public bots, profiles matter. A work deployment preference should not affect a personal assistant. A Telegram bot's public response style should not affect private research.
Use Hermes profiles to separate these contexts cleanly.
Privacy model#
Memory is powerful because it is persistent. Treat it like configuration, not casual chat. Never store raw secrets, tokens, or personal data that the agent does not need. For sensitive projects, combine memory with privacy controls, security hardening, and local model routes where appropriate.
Practical memory hygiene checklist#
Review memory periodically:
- Remove stale paths and obsolete conventions.
- Replace imperative notes with declarative facts.
- Move procedures into skills.
- Keep client or tenant facts separated.
- Avoid storing anything that expires within a week.
This keeps the agent sharper over time.
Example workflow#
A user corrects Hermes: “Do not use direct Vercel deploys for this project; push to GitHub.” Hermes should save the durable project convention as memory. If the deploy process has multiple commands and checks, Hermes should create or update a deploy skill. Later, when asked to ship a page, Hermes can act correctly without another reminder.
Next step#
Read why Hermes wins on memory, then set up your first profile and one reusable skill. If privacy is your main concern, pair this with the Hermes privacy guide and Ollama setup.
Install path#
To evaluate the memory system, install Hermes Agent and create a controlled test. Tell Hermes one stable project convention, ask it to complete a related task, then return later and ask for a similar task. Pair that with persistent memory and a skill when the procedure repeats.
The important test is behavioral. Hermes should not merely recite that it remembers something; it should choose the right default action because of that memory. For example, it should use the preferred deploy path, avoid a tool the user rejected, or load the project-specific checklist before editing files.
Recent community troubleshooting note#
Recent Discord threads around how to fix Hermes memory, Local hindsight memory installation broke Hermes, and auxiliary timeout failures show that memory architecture is only half the story. If recall or compaction fails in practice, use the Hermes memory troubleshooting checklist before changing providers or deleting state. Pair it with profiles when testing Hindsight, Recall, Obsidian, or another local memory layer.
Memory is bounded, reviewable, and auditable#
Built-in memory is not an unbounded transcript bucket. MEMORY.md is capped at 2,200 characters and USER.md at 1,375; over-capacity writes fail visibly so the agent can consolidate instead of silently evicting a fact. Use hermes journey list, edit, and delete to inspect learned nodes. Enable /memory approval on when automatic or foreground saves need review, and use the memory troubleshooting runbook when wrong facts, full stores, or background-review spend appear.
Choose a memory provider only after built-in memory passes#
Start with the built-in versus external provider decision tree. Built-in files handle concise durable facts; SQLite preserves session history; project files hold repository rules. Add an external provider only for a named retrieval, graph, fact, or sharing requirement, then measure token overhead and fresh-session recall.