Diagnosing Memory

Goal: reduce any "it forgot what I told it" / "my memories are gone" / memory-provider failure to one concrete fix — a config field, an env var, a plugin install, or a session restart.

Disambiguation: if a model provider is configured but silently unavailable (not a memory issue), see diagnosing-providers.

[!WARNING] Hermes memory has two independent layers, and the external one fails silently. Built-in memory (MEMORY.md / USER.md) is always active. At most one external provider can be active; if it is unavailable, external memory is disabled for that session and built-in memory answers instead — the agent does not announce this. "My mem0 memories are gone" usually means "mem0 was unavailable; built-in answered."

1. How memory resolves

The provider: comment in config.yaml lists the one-at-a-time set — but since 2026-10 only retaindb and byterover still ship bundled; openviking, mem0, holographic, honcho, and supermemory all moved to catalog plugins (install first: hermes plugins install <name>, e.g. hindsight made the same bundled → catalog move in 2026-09) — and that list is not exhaustive. Providers also arrive as catalog plugins or optional skills (e.g. honcho: catalog entry honcho, Plastic Labs, pip honcho-ai — upstream dropped the optional skill that shipped it on 2026-11-03); they install the same way (hermes plugins install honcho) and show up in the installed-plugins list of hermes memory status. Trust that list over any comment.

A provider is available only when all four hold: plugin installed, its pip dependencies importable in the install's dependency environment (PM-era: $HERMES_HOME/installs; older checkouts: the in-tree venv), its env vars set, and its is_available() check passing. Any one missing → silent fallback to built-in (see the warning above).

[!IMPORTANT] Built-in memory is a frozen snapshot. MEMORY.md/USER.md are injected into the system prompt once at session start. Mid-session saves hit disk immediately but do not update the current session's prompt — this is by design (it keeps the prompt cache stable). "It forgot what I just told it" is usually this, not a bug: the write landed and appears next session. Verify with a file read before diagnosing further.

2. How to inspect

Probe in this order — the first two are built-in helpers and answer most cases:

1. hermes memory status — the authoritative check. Real example (a machine with honcho selected but no API key):

   Memory status
   ────────────────────────────────────────
     Built-in (MEMORY.md / USER.md):
       Memory injection:   enabled ✓
       User profile:       enabled ✓
       Memory tool:        enabled ✓
     Provider:  honcho
     Plugin:    installed ✓
     Status:    not available ✗
     Missing:
       ✗ HONCHO_API_KEY  → https://app.honcho.dev

   A trailing Note: line (quoted verbatim in the tool's output) explains that systemd/gateway services do not inherit the profile .env secrets file — set any listed variables in the service environment itself (see the gateway/systemd row in §3).

   Read it line by line: the three built-in lines confirm the stores and the memory tool are on; Provider: shows what memory.provider is set to; Plugin: / Status: / Missing: are the three failure points in order (plugin file → pip deps → env vars). The installed-plugins list at the bottom is the ground truth for provider names — the hermes memory --help string is not kept in sync with it.

2. hermes doctor — its "Memory Provider" section probes the active provider deeper (config file, API key, live connect, ImportError on the provider package). Run it after memory status points at a layer.
3. Config + files — read the memory: block of $HERMES_HOME/config.yaml (or hermes config show), and ls "$HERMES_HOME/memories/". On native Windows $HERMES_HOME is %LOCALAPPDATA%\hermes — confirm with hermes config path, never assume.
4. Session log — a provider selected but unavailable logs a one-shot warning at agent start (wording varies by version; look for a line naming the provider and saying external memory is disabled for the session): hermes logs --follow while starting a session. The gate that produces it is the external-provider block in agent/system_prompt.py.
5. hermes guide memories (or /hermes-doctor memories in-session) — this plugin's read-only hygiene audit of the built-in stores: over-limit files, exact/near-duplicate entries, user-profile facts mis-targeted into MEMORY.md, and undated dynamic entries. It reports content-level findings that hermes memory status does not look at.

3. Pitfalls (symptom → cause → fix)

Two name traps that are not this surface:

• context.memory_trim is process-heap release for long-lived gateway processes (Linux/glibc only) — nothing to do with MEMORY.md.
• hermes memory-graph is an alias of hermes journey (learned-skills/memory timeline viewer), not a memory provider.

4. The memory: config block

Hermes configuration is YAML — edit config.yaml, never JSON syntax.

Apply and verify

There is no /reload-memory: built-in memory is snapshotted at session start, so restart the session after any config/.env/plugin fix. Then confirm with hermes memory status (all lines ✓, or provider lines as intended) and, for built-in, ask the agent to remember something and check the file changed on disk.

[!CAUTION] hermes memory reset erases $HERMES_HOME/memories/MEMORY.md and/or USER.md irreversibly (--target all|memory|user, confirmation prompt, --yes skips it). It resets built-in memory only — it does not touch external providers.

6. The session database (state.db) — size and compaction

The session log ($HERMES_HOME/state.db, SQLite) grows independently of both memory stores — a 900+ MB database or a large WAL is not a memory problem. Full procedure (table map, compaction canary, integrity queries, prune/archive/ optimize sequence): references/state_db.md.

Verification

hermes memory status

Pass: all built-in lines show ✓; if an external provider is configured, Status: available ✓ with no Missing: entries. Fail: Status: not available ✗ or missing env var listed — follow §3 for the matching symptom row.

hermes doctor

Pass: "Memory Provider" section reports no errors. Fail: ImportError or API key error — run hermes memory setup <provider> to reinstall deps, then add the missing key to $HERMES_HOME/.env.

hermes guide memories

Pass: check exits with no ~ or ✗ markers (notes/warnings with ~ are acceptable only if they describe non-critical items like approaching limits). Fail: ~ or ✗ markers present — address the flagged over-limit, duplicate, or unreadable entries per §3; for unreadable files, check file permissions (POSIX: chmod 600 $HERMES_HOME/memories/*.md; Windows: icacls $HERMES_HOME\memories\*.md /grant:r %USERNAME%:F) and verify the file is valid UTF-8 — permission fixes do not resolve encoding errors.

Report

This skill diagnoses memory problems — the agent forgot something, an external memory provider configured but silently unavailable, missing provider plugins or API keys, and built-in MEMORY.md/USER.md errors. When you run the diagnostic workflow, present findings in the standard format below.

Summary

Your external memory provider (honcho) is not available because the API key is missing from .env. The provider is selected in config but silently falls back to built-in memory, so your honcho memories appear "gone."

Findings

Recommended Fix

Add HONCHO_API_KEY=<your-key> to $HERMES_HOME/.env, then restart the session. Verify with hermes memory status — the provider should show Status: available ✓. If the provider plugin is also missing, install it first (hermes plugins install honcho), then run hermes memory setup honcho to install its dependencies and record the key — memory setup prints the catalog install command but cannot install the plugin itself.

References

• $HERMES_HOME/.env — the missing API key
• $HERMES_HOME/config.yaml — memory.provider: honcho
• agent/system_prompt.py — external-provider gate
• tools/memory_tool_store.py — memory store limits

Facts re-verified 2026-09-14 against upstream source at commit 46a0daee58abbc1b07f84f505a5ba90f1958295c: tools/memory_tool_store.py (limits + rejection text), hermes_cli/config_defaults.py (the memory: block and its provider comment), agent/memory_provider.py (plugin path), agent/system_prompt.py (the external-provider gate), hermes_cli/mem_trim.py (context.memory_trim), hermes_cli/subcommands/journey.py (memory-graph alias), plus optional-skills/autonomous-ai-agents/honcho/ for the provider-list note; provider comment re-verified 2026-09-29 at 5000e2993 (hindsight is now catalog-installed). Re-checked 2026-10-12 against upstream main (53bc70c5): only retaindb + byterover remain bundled under plugins/memory/ — openviking, mem0, holographic, honcho, supermemory are catalog plugins. Re-verified 2026-11-04 against upstream main 07274ac65438a0b62bb9fd64bf284e58b2fd8fc6 (drift re-baseline): plugins/memory/ still holds only retaindb + byterover, and honcho now arrives solely as the catalog entry honcho (plugin-catalog/honcho.yaml, Plastic Labs, hermes-plugin-honcho subdir) — upstream dropped optional-skills/autonomous-ai-agents/honcho/ on 2026-11-03, so the 2026-09-14 citation for the provider-list note no longer resolves. Re-verify before reuse.