Hermes Agent Memory and Session Storage Troubleshooting

When Hermes seems to forget a fact, mix two projects, lose the thread after compression, or recall the wrong conversation, first identify which state layer failed. Active context, durable memory, session history, external memory providers, and profiles are separate systems. Fixing the wrong layer usually makes the problem harder to diagnose. The Hermes Agent Dashboard is useful for selecting the owning profile and inspecting sessions and logs, but it cannot reconstruct state that was never written or repair storage corruption by itself.

Confirmed save, pending save or no tool call?#

Before diagnosing “forgotten memory,” separate three checkpoints: the model actually called the memory tool, any required approval completed, and a new session in the same profile loaded the entry. A spoken “I remembered” is not proof of persistence. Inspect /memory pending before repeating writes; approve only the intended change. Then finish the current task, save a handoff and use /new for a neutral recall check. A gateway restart can resume the old conversation rather than create a new memory snapshot.

The memory architecture and three-checkpoint example keeps this distinct from compression and external retrieval. Source: official memory troubleshooting, checked November 1, 2026. This is a diagnostic procedure, not a claim that we reproduced your failure. Do not delete memory files or state.db to test a missing write.

Compression failed: missing input is not revoked OAuth#

If /compress fails repeatedly, save the first concrete error, not just the later attempts_exhausted warning. A request-format failure, revoked login and overloaded provider need different repairs. Repeating the same command or buying a bigger VPS does not distinguish them.

OpenAI Responses request is missing input#

This exact error has a documented Codex auxiliary-path cause. The adapter passed chat-shaped messages to Relay while metadata selected a Responses codec expecting input. The request could fail before reaching the provider. Upstream fix #139050 normalizes the codec metadata at the synchronous, asynchronous and streaming auxiliary boundaries; it does not change your primary provider or grant more quota.

Merged is not the same as released. Checked October 20, 2026: the fix merged on October 15 after the latest published release, v0.22.2. We checked the tag's source and Git ancestry: that tag does not contain this fix. Do not assume that seeing v0.22.2 after an update proves this particular repair is installed. Use the update guide, record the actual installed build, and confirm a release includes the fix before treating an upgrade as the repair. Do not switch a production install to an unreleased branch merely to follow this article.

Our read-only source probe checks the pinned merged helper with three metadata inputs: Codex Responses, Anthropic Messages and chat completions. All three produced chat-completions metadata without mutating the input; the helper was absent from the v0.22.2 source. The raw results and source hashes are reproducible with Python 3. This is a pure-function check, not a live provider, full Relay, compression-recovery or recall benchmark.

401 or OAuth access token has been revoked#

Repair the credential used by the compression route, which may differ from the model visible in chat. Reauthorize through that provider or plugin's supported account flow, then test the same route. The Codex request-format fix above does not repair a revoked Claude OAuth token. Do not paste tokens, auth files or private transcripts into a support post. Follow provider authentication and error diagnosis rather than treating a rejected login as exhausted memory.

Preserve the conversation before changing routes#

1. Save the session ID, goal, exact artifact path, unresolved constraint and next action outside the chat. Use the session handoff checklist; do not delete state.db, its sidecars or memory files.
2. Record the installed version and owning profile. Inspect that profile's configuration rather than the laptop's default profile when the failing agent runs on a server.

hermes --version
hermes -p PROFILE config path
hermes -p PROFILE config edit

Replace PROFILE with the real profile name. Record the existing auxiliary.compression.provider, model and task-specific fallback settings before editing. Configuration may contain private values: retain the backup privately, not in a public diagnostic.

3. If an alternative summary route is needed, choose one already authorized for this conversation, with valid credentials, sufficient context and a known billing owner. Sending summaries to another provider sends conversation content there and can incur separate charges. The compression setup guide and auxiliary fallback rules explain the controls; changing the main chat model alone is not proof the summarizer changed.
4. Let the active task finish before restarting its process. Reload the affected surface safely and resume the recorded conversation rather than starting /new by default. Verify the actual summary route in logs, try /compress once, and check the four saved facts plus one bounded continuation. A smaller context meter is not a passing recall test.

Current compression failure documentation, checked October 20, distinguishes aborted compression with the transcript kept from a committed deterministic fallback. Authentication/quota failures can abort; repeated stalls or sustained overload can reach a degraded fallback under the documented policy. Read the actual warning and installed-version behavior. Do not translate every failure into either “nothing was lost” or “memory was deleted.”

If you want someone else to maintain the runtime, compare self-hosted and managed operation. Managed hosting changes operational ownership; it does not cure revoked third-party credentials, guarantee summaries or enlarge a provider's context window. Disclosure: this site promotes FlyHermes commercially.

Compression succeeded, but a detail is missing#

Treat a smaller context meter and a correct continuation as separate checks. Before /compress, save four things outside the conversation: the task goal, exact artifact path, unresolved constraint and next action. Afterward, ask Hermes to restate them and complete one bounded step. Verify against the original artifact; a confident summary is not independent evidence.

If a path or earlier decision is absent, retrieve the original session passage rather than rewriting durable memory from the summary. Current in-place compression keeps the session ID and soft-archives earlier turns. It does not guarantee that every detail remains in the active prompt. The compression configuration guide now separates the trigger, lean/legacy retention and protected messages so each can be diagnosed independently.

Do not reset a working gateway conversation merely to apply a compression change: current docs say compression.* and model.context_length edits apply on the next message. Check the installed release and owning profile first; other configuration has different reload behavior. If the failure is host RAM or a remote provider context-limit rejection, identify that explicitly before changing the hosting plan.

Source: official configuration reference, checked October 15, 2026. The four-item check is a proposed recovery acceptance test, not a hands-on reliability benchmark.

Diagnose the right memory layer first#

Hermes has four practical state layers. They solve different problems:

1. Active context is the conversation currently sent to the model. It is finite and eventually needs compression.
2. Durable memory stores compact facts and preferences in MEMORY.md and USER.md. It should not become a task diary.
3. Session history stores full conversations in SQLite and powers resume plus FTS5 session search.
4. External memory providers add semantic retrieval or user modeling alongside built-in memory. Only one external provider is active at a time.

Profiles wrap those layers in an isolation boundary. A CLI session under the default profile and a Telegram gateway under another profile can both be healthy while remembering different things. The persistent memory overview explains the architecture; the memory setup guide covers a clean first configuration.

Memory troubleshooting decision tree#

Hermes forgot something from the current conversation#

Check context pressure before editing memory. On Hermes Agent v0.20 or newer, run /context first. Its category table separates system prompt, tools, skills, memory, conversation, and free space; /context all adds per-skill and per-toolset costs. Use /usage for provider usage and cost. If Hermes Desktop no longer shows the meter after an update, right-click the bottom status bar, enable Context meter, and wait until the chat has usage data. A hidden widget is not proof of deleted memory. Then use:

/compress

For more control, /compress here 2 keeps the latest two exchanges verbatim and summarizes the earlier conversation. A focused command such as /compress deployment decisions asks the summary to preserve one topic. Current Hermes uses in-place compression by default: the active session keeps its ID while pre-compression turns are soft-archived for history. Older lineage-style continuation behavior can still appear in legacy sessions or when in-place mode is disabled, so do not diagnose a missing #2 session as compression failure.

Use /new only when you want a genuinely fresh session. If compression repeatedly fails, inspect the active provider and its context window with /provider, /model, and /usage. A provider quota or model-context failure is not a corrupt memory store. The provider rate-limit guide separates quota errors from context errors.

Hermes repeats tools or answers before context is full#

A loop at low context occupancy is not the same as context exhaustion. /context shows the active prompt breakdown and free space. /status shows session-level model, profile, token, and duration information; do not treat a cumulative session counter as the model payload for the next turn. A recent support case looped around 39K tokens on a 64K model, while the underlying causes were separated into a Hermes restart-loop bug and model-side tool-selection behavior.

Use one-variable-at-a-time checks:

/context
/context all
/status
/model
/tools list

1. Check pressure. If /context still shows substantial free space, do not keep forcing /compress.
2. Check inventory. /context all and /tools list prove which skills and tool schemas are loaded. Missing or duplicated capability is a tool configuration problem, not durable-memory corruption.
3. Update and isolate. Run hermes update, then start /new loop-test so an already-damaged session does not contaminate the test.
4. Replay one tiny action. Ask for one tool call with an observable result. If the same model repeats the call or never consumes its result, switch only the model or provider and run the identical test again.
5. Classify the result. A fresh-session fix points to old session state; an update fix points to Hermes runtime behavior; a model-only difference points to tool-use compatibility. If every route fails, inspect logs and the tool definition before changing memory.

For local models, verify the effective context length and tool-calling support rather than relying on the model's advertised maximum. The local model guide and provider fallback guide provide the next checks. Preserve the exact repeated call, error, model, provider, and Hermes version in a session handoff before resetting a long job.

Hermes forgot a stable fact between sessions#

Run:

hermes profile list
hermes profile show <name>
hermes memory status
hermes config path

Then confirm the active profile has:

memory:
  memory_enabled: true
  user_profile_enabled: true

Built-in memory is loaded as a frozen snapshot at session start. If memory was written or edited during the current session, start /new memory-check before concluding the write failed. Test with one harmless fact, not a password or API key.

Durable memory is intentionally small. Use it for stable environment facts, preferences, conventions, and lessons likely to matter again. When it is near capacity, consolidate overlapping entries instead of adding another verbose paragraph. Store secrets in the profile .env or a secret manager, never in memory.

Hermes cannot find an older task or decision#

Do not copy every transcript into durable memory. Name important sessions and search the session store:

hermes sessions list
hermes sessions browse
hermes --continue "project name"

Ask Hermes to search past sessions when you need a specific discussion. Session search returns actual stored messages from ~/.hermes/state.db; it is different from the compact facts injected into every prompt. Search is cross-session and can cross CLI, Telegram, and Discord history when those sessions belong to the active profile; the /sessions picker itself may be more narrowly scoped by origin. Use the AI agent session handoff checklist when a project must continue safely across people or long gaps.

session storage unavailable: FATAL or DeletedWalGenerationError#

This is a session-store failure, not a durable-memory failure. Hermes keeps full transcripts and resume/search data in the active profile's SQLite state.db; named profiles have separate stores. Current Hermes fails loudly when the Desktop or TUI cannot persist a turn so a normal-looking chat does not silently become unresumable.

A September 2026 Discord support thread reported the exact session storage unavailable: FATAL symptom. The linked upstream incident identified DeletedWalGenerationError: a short-lived Hermes process could drop SQLite's live WAL locks, after which another process checkpointed and unlinked state.db-wal under Desktop or the gateway. The fix landed on main; the safe first recovery is to update every Hermes surface to the same build, fully quit Desktop, restart the gateway once, and retry. Do not delete state.db-wal or state.db-shm, copy a backup over a live state.db, or run repeated restart loops.

hermes --version
hermes update
# Fully quit Hermes Desktop before restarting the gateway from a separate shell.
hermes gateway restart
hermes sessions stats

If the same error returns after the update, classify it before attempting repair:

1. WAL generation error: look for DeletedWalGenerationError in the Hermes error log. Preserve the exact version and process surface (Desktop, CLI, gateway, cron, or dashboard), then create a redacted private bundle with hermes debug share --nous.
2. Locked store: look for database is locked and the nearby lock-owner line. Close duplicate writers rather than deleting SQLite sidecars.
3. Disk or permissions: verify free space and that the active profile can write its Hermes home. Remember that a named profile uses its own state.db.
4. Malformed database: use the non-destructive recovery command below. It copies the source and sidecars before opening them, inspects canonical tables, and never replaces the active database automatically.

hermes sessions recover --source ~/.hermes/state.db --inspect-only

For a named profile, use that profile's resolved Hermes home rather than the default path. If inspection confirms damage, recover into a new output database and review the generated report before any cutover:

hermes sessions recover \
  --source /path/to/preserved/state.db \
  --output /path/to/recovered-state.db \
  --report /path/to/recovery-report.json

The backup and restore guide covers preserving profile state before recovery, while the safe update guide covers keeping Desktop, CLI, and gateway code on one version. If you want managed uptime rather than operating SQLite, process supervision, updates, and gateway recovery yourself, compare the hosted FlyHermes path.

/sessions looks empty or session search misses an older message#

Do not assume the database is corrupt from one empty picker. On messaging platforms, bare /sessions can be scoped to the current origin, shows named sessions, and excludes the active session. /sessions full includes unnamed sessions for that origin. Check the store before attempting repair:

hermes --version
hermes sessions stats
hermes sessions repair --check-only
hermes sessions list

If sessions stats still reports sessions and messages, ask Hermes to search one exact phrase with an explicit time direction, such as “search past sessions for deployment checksum, oldest first.” Session search uses FTS5 relevance by default, so a newer match may rank above an older one; that ordering is not proof the old session vanished.

An automatic session reset also does not delete the prior session. It rotates the channel to a new session ID while leaving persisted messages available to session search. A request that fails before it is appended can be absent, but that does not erase earlier stored turns. Back up before any real repair, and use the session handoff checklist to preserve the current goal, files, and verification evidence before resetting.

Hermes recalls the wrong fact or drifts#

Turn on approval before allowing more automatic writes:

/memory approval on
/memory pending
/memory approve <id>
/memory reject <id>

The equivalent config is memory.write_approval: true. With approval enabled, interactive CLI foreground writes prompt inline; gateway, script, and background-review writes stage for review. Check the actual approval result before testing recall. Reject incorrect assumptions, consolidate duplicate entries, and keep the store concise. The optional dashboard can help inspect the active profile and operational state; see the Hermes Dashboard and Web UI guide.

A June 2026 Discord support snapshot contained threads titled “Severe memory bleed, hallucination, and drift,” “Context mixing between conversations,” and “Built-in memory docs say Hermes consolidates when full.” That snapshot is historical rather than proof of current incidence, but it reinforces the same operating rule: inspect and gate writes instead of treating every wrong answer as model randomness.

Memory works in CLI but not Telegram or Discord#

This is usually a profile or process boundary, not a memory algorithm problem.

1. Confirm the active session profile with /profile; use hermes profile show <name> for profile details.
2. Inspect the gateway profile/config and run hermes gateway status.
3. Restart the gateway after config or profile changes.
4. Send one real message through the target channel.
5. Check gateway logs if the channel still behaves differently.

The gateway troubleshooting guide covers stale processes, duplicate polling, launchd/systemd state, and end-to-end delivery checks. Use distinct profiles and bot tokens when two bots need different memory, skills, or secrets.

An external memory provider caused the problem#

Return to the smallest known-good setup:

hermes memory status
hermes memory off

Start a fresh session and verify built-in MEMORY.md and USER.md first. Then re-enable one provider with hermes memory setup and test again. External providers are additive; Honcho, Mem0, Hindsight, OpenViking, and other provider failures should not be debugged as if they were built-in memory corruption.

If an Obsidian workflow is involved, remember that the vault is a human-readable note surface, not a replacement for session state or durable memory. Follow the Hermes Agent Obsidian workflow and verify the gateway can access the same filesystem path as the CLI.

Stale memory: when remembering becomes the bug#

A memory system can work perfectly and still produce the wrong answer. The dangerous case is not "Hermes forgot"; it is "Hermes confidently reused a conclusion that used to be true." Treat durable memory as a compact set of current operating facts, not an append-only archive.

Use this stale-memory repair loop:

1. Find the claim and its scope. Ask which profile supplied it, whether it came from durable memory, the current session, session search, a skill, or an external provider. Run /profile, /context, and hermes memory status before editing anything.
2. Verify the current source of truth. Check the live file, account, API, deployment, or official documentation. A remembered hostname, model route, price, project path, or team preference is evidence to verify—not authority.
3. Replace the obsolete fact explicitly. Prefer a concise current statement such as Pricing page source is src/app/pricing/page.tsx as of 2026-09-22 over preserving two contradictory instructions. If history matters, keep it in the session handoff record or project notes rather than active durable memory.
4. Review pending automatic writes. Run /memory pending when write approval is enabled. Reject summaries that turn a temporary workaround, old incident, or one-session assumption into a permanent rule.
5. Start a fresh session and test recall. Built-in memory is loaded as a session-start snapshot. Use /new, ask one neutral question that should retrieve the corrected fact, and verify that the old answer no longer appears.

Do not solve conflicting memory by importing more transcripts. Full history belongs in session search and handoff workflows; stable preferences and operating facts belong in durable memory; reusable procedures belong in skills. This separation keeps recall useful without letting yesterday's workaround become tomorrow's policy.

Stale-memory checklist#

• The active Hermes profile is the expected one.
• The remembered claim was checked against a live source of truth.
• The obsolete entry was removed or replaced, not merely contradicted later.
• Pending automatic writes were reviewed for temporary assumptions.
• External memory was disabled while built-in recall was tested.
• A fresh /new session retrieves the corrected fact.
• The full incident/history remains discoverable through session search or a handoff note.

Safe repair sequence#

Use this order so each test answers one question:

1. Record the symptom. Missing current detail, missing stable fact, wrong past session, cross-project bleed, or provider error.
2. Prove the profile. Run /profile on the surface that failed; use hermes profile show <name> when you need the profile home and details.
3. Prove built-in memory. Run hermes memory status, disable the external provider, and start a fresh session.
4. Inspect context. Run /context, use /context all when skills or tool schemas look expensive, and use /usage for provider consumption. Reduce a long thread with /compress, not the nonexistent /compact alias.
5. Search history. Resume or search sessions instead of promoting temporary task logs into memory.
6. Gate new writes. Turn on memory approval while correcting drift.
7. Test the real surface. A CLI answer does not prove Telegram, Discord, cron, or a remote gateway uses the same profile.
8. Back up before surgery. Use the Hermes memory backup guide before pruning sessions or editing state files.

When to use FlyHermes instead#

Self-hosted Hermes gives you direct control over profiles, local memory files, providers, gateway services, backups, and update timing. That control also makes you responsible for process uptime, disk state, profile boundaries, remote access, and recovery.

If the outcome you want is an agent available from browser and phone without operating that stack, compare FlyHermes managed hosting. Managed hosting does not eliminate the need for sensible memory boundaries, but it removes much of the VPS, gateway, TLS, update, and monitoring work around them. The self-hosted vs hosted AI agent guide gives the full decision framework.

Persistent state is not persistent execution#

Memory and session state can survive a restart, but they do not execute work while the runtime machine is asleep. Separate recall problems from uptime problems: inspect context and memory for the former, then run a closed-client scheduled test for the latter. See the self-hosted vs hosted AI agent guide for the runtime ownership checklist.

A missing session may be hidden by its surface, not deleted#

Before repairing memory or SQLite, identify the session source. In Web UI, select the profile that owns the conversation and change Chats to Automation or All; cron, tool, API, and ACP sessions are filtered from the default human-chat view. Bot Mode is different: each bot's canonical Bot Chat is intentionally kept out of the regular Sessions list and must be reopened from the Bots roster. The eye icon restores a hidden bot row, not its chats. A separate chat created with New chat with this agent can appear under Sessions. Use the Hermes Dashboard Sessions guide, then compare the UI with hermes sessions stats and FTS5 search before attempting storage repair.

Compression fallback is not a guarantee of a complete summary#

Current official documentation gives compression its own auxiliary.compression route. With provider: auto and a selected main provider, the task follows the main route and configured fallback policy rather than freely choosing any logged-in paid account. An explicit auxiliary provider has different capacity-error handling, so capture the exact route and error before changing settings.

Read the outcome rather than assuming one universal degradation path. Current detailed compression docs distinguish an aborted attempt that keeps the transcript from a committed deterministic fallback after specific repeated failures. Neither a fallback marker nor a smaller meter proves full recall. Preserve task state, inspect the exact warning and installed version, and verify the continuation after repair. Follow provider fallback setup and verification for routing diagnosis before deleting memory files or resetting the session database.

Source: official Hermes fallback and recovery documentation, checked October 1, 2026.

Check the auxiliary provider when compression fails#

A healthy main chat does not prove compression or session search has a funded route. Inspect auxiliary.compression and auxiliary.session_search, confirm their provider/model/wallet, and test them after any provider change. Repeated compression failures can look like memory loss while the real cause is a 402, 429, timeout, or output limit on a side lane. Follow the provider error decision tree before deleting memory or resetting sessions.

Memory is full: patch the fact, preserve the entry#

Quick answer: current Hermes memory uses add, patch and remove. There is no replace action in the current documented interface. A patch changes only the exact old_text span inside an entry; the rest of that entry stays intact. Older examples using replace can therefore fail on current builds. Check your installed version rather than treating an obsolete action as corrupted memory.

Built-in memory is bounded: MEMORY.md defaults to 2,200 characters and USER.md to 1,375. A longer patch can exceed the same limit as an add. Hermes rejects an overflowing write rather than silently evicting another fact. Do not delete state.db, reset the profile or add a semantic provider to repair a capacity error.

Make room and save in one batch#

Ask the agent to use the memory tool with one operations batch that shortens or removes a verified stale entry and adds the needed fact. The capacity check applies to the final batch result. A failed or ambiguous operation must be corrected before retrying; do not repeatedly submit a successful batch.

This illustrative tool payload changes one fact while preserving the rest of its entry. It is not a shell command, and it only applies if the exact old span exists in your store:

{
  "target": "memory",
  "operations": [
    {
      "action": "patch",
      "old_text": "Project staging host is staging-old.example",
      "content": "Project staging host is staging.example"
    }
  ]
}

Use a top-level target of memory for agent notes or user for preferences. All operations in that batch share that target; changing both stores requires separate calls. If the span occurs more than once, provide more surrounding text. To rewrite an entire entry intentionally, supply that whole entry as old_text, not a fragment that could identify unrelated facts. The current documented patch is literal substring editing, not a regex recipe.

Verify the repair without destroying useful state#

1. Confirm the owning profile and inspect the current entry. Save a private backup before manual editing; memory can contain sensitive project details.
2. Check the proposed new fact against its real source. Shorten only redundant or stale text; keep raw incident history in session search and handoff notes.
3. Request one bounded batch. If write approval is enabled, inspect /memory pending and approve only the intended change. A staged request is not yet a persisted repair.
4. Confirm both the changed fact and a neighboring fact in the saved entry. A successful patch should not wipe the rest of a multi-fact entry.
5. Finish the current task and start /new in the same profile for a neutral recall check. The running session's memory snapshot is frozen; a restart that resumes it is not this test.

This is a source-verified recovery procedure, not a claim that we executed writes against your memory or benchmarked recall. External memory providers have separate storage and retrieval behavior; the built-in repair does not prove their records changed. The memory setup guide covers layer selection before adding a provider. Managed hosting changes who maintains the runtime, not the need to verify facts or approve sensitive writes.

Source: official Persistent Memory documentation, sections Memory Tool Actions, Substring Matching and What Happens When Memory is Full; checked November 6, 2026. Current docs explicitly reject replace; older issue and pull-request examples are historical, not the current API contract.

Wrong memories keep returning: audit automatic writes#

Hermes can run a background self-improvement review after a turn. That review may save a memory or update a skill, which is useful until a weak assumption is promoted repeatedly. Turn on the write gate before deleting files:

/memory approval on
/memory pending
/memory approve <id>
/memory reject <id>

Set display.memory_notifications: verbose when you need a compact preview of each automatic change. If unwanted saves stop after memory.write_approval: true, the store is healthy; the problem was write policy. If they continue, verify the active profile and external provider, because the built-in gate and an additive provider have different write paths.

The background review also has its own cost and failure lane. Inspect auxiliary.background_review, provider credits, and session_model_usage entries where task='background_review'. To isolate a suspected review loop without disabling manual memory or /refine, set auxiliary.background_review.enabled: false, start a clean test session, and compare behavior. The provider cost and rate-limit guide covers 402/429 and auxiliary-route failures.

Fresh community signal: inspectability beats more memory layers#

Recent Hermes community discussions are converging on the same failure mode: users add a semantic provider or wiki because recall feels weak, then discover that irrelevant injection, duplicate facts, unclear identity mapping, or profile-scoping mistakes make the agent less predictable. A current Reddit discussion about irrelevant Honcho context and a local-first memory-provider discussion both emphasize visibility, provenance, and correction. Treat those threads as problem-language evidence, not official setup instructions.

The operating rule is simple: prove built-in memory in one profile, turn on write approval, inspect what is injected, and only then add one external provider for a named capability. More retention is not automatically better recall.

Verify memory with a fresh-session test#

Use the Hermes memory setup and provider decision guide to save one safe preference and one project rule, then test exact recall, contradiction handling, source awareness, and unknowns in a new session. A provider dashboard record is not proof that the active Hermes profile retrieved it.