Hermes Agent Memory vs Skills: Where Things Belong

Hermes Agent gives you four surfaces to put things in, and the wrong choice turns into silent rot. Memory fills with stale notes. Skills duplicate. Handoff grows into a graveyard of “where did I leave that.” The cost of getting the decision wrong is not visible on day one; it is visible three months later when the agent confidently recycles a hallucinated preference.

This guide gives you one sentence per surface, one rule for what belongs where, and a worked example that walks the decision out loud. Read it once, then refer back when you are about to write to memory at the end of a long session and are tempted to dump everything in.

The four surfaces in one sentence

Surface	One-sentence job
Memory (MEMORY.md / USER.md)	Durable preferences and environment facts you want present in every session, indefinitely.
Skills (/opt/data/skills/<category>/<name>/SKILL.md)	Reusable procedures that load on demand when a task matches.
fact_store	Entity-tagged, queryable rows about specific things — hostnames, dates, owners, URLs.
Session handoff (/opt/data/notes/session_handoff_<date>.md)	Short notes for the next time this specific conversation thread picks up.

The mistake is treating them as interchangeable. They are not.

What goes in memory

Stable preferences. Durable environment facts. High-signal lessons with date markers.

The current first line of USER.md states the rule plainly:

Memory hygiene (durable preference): Memory is for operational state I need every day, NOT for history/versioning records. Before writing to memory, ask: “is this needed verbatim on the next turn?” If no, it goes to a file. Rule enforced by skill memory-hygiene.

Examples that belong in memory: “Alastair prefers surgical execution,” “release preference: run regression coverage before an explicitly authorized GitHub push,” “Amazon Associates tracking ID agenticbotsit-20.” Each of these is needed verbatim on most future turns, and does not rot.

What does NOT go in memory

Temporary TODOs. One-off article drafts. Version-progression histories. Yesterday’s deploy path. Anything that names a specific date, hour, or session.

Memory fills with stale notes if you do not enforce the rule. The litmus test is simple: if the answer to “is this needed verbatim on the next turn?” is no, or only this session, or only for a week, it goes to a file — not memory. The memory-hygiene skill is the gatekeeper: it exists because this rule is easy to forget at the end of a long session, when the path of least resistance is to dump it all into MEMORY.md and call it done.

A useful sub-rule: if the line starts with “yesterday,” “today I,” “we just,” or names a commit SHA, it is not a memory candidate.

What goes in skills

Reusable procedures. Things that recur and have a known shape: “how to publish an ABS guide,” “how to write a Cloudflare tunnel-cleanup script,” “how to gate memory writes,” “how to deploy an Astro static site end-to-end.”

Skills live as one directory per skill under /opt/data/skills/<category>/<name>/, with SKILL.md as the entry point and optional references/, templates/, scripts/, assets/. The categories are themselves subdirectories — devops/, creative/, web/, data-science/, ecommerce/, and so on. A live enumeration of /opt/data/skills/ on this VPS shows 68 entries, with example names like abs-character-art, ats-rd-full-audit, bfl-api, bug-history-miner, cf-edge-cache-user-sees-stale, codename-brand-separation, computer-use, delegate-task-chunking, devops/cloudflare-tunnel-deploy, and devops/cron-health-monitor. That is what a healthy skills directory looks like — each entry is a procedure someone was tired of re-deriving.

Skills are loaded with skill_view when the trigger conditions match. They do not auto-load on every turn.

What goes in fact_store

Entity-tagged facts about specific things. Hostnames. Dates. Owner names. URLs that you need to query, not narrate.

fact_store is a queryable rows surface. It is the right home for “the production tunnel ID is a1b2c3d4-…” or “the Shopify product gid://shopify/Product/12345 last synced 2026-07-12.” If you find yourself writing the same hostname into three different session handoffs, promote it to fact_store and let it be queried.

Never put secrets in fact_store. No API keys, no tokens, no OAuth client secrets. Secrets go in the environment, in .env files, or in a secrets manager — not in any surface the agent reads as part of normal context.

What goes in session handoff

One file per session under /opt/data/notes/session_handoff_<date>.md, capturing the short next-action list and the open questions for next time.

Handoff is not memory. Handoff is not a skill. Handoff is the parking lot for this conversation thread: what was in flight, what blocked, what to try first next time. It is read by the next session that resumes the same work, and it can be deleted once that thread closes. If a handoff note keeps being referenced across unrelated sessions, that is a signal it actually belongs in memory or in a skill.

A worked example

A tool call hallucinated a memory of “I always run npm run build --foo.” The agent now wants to write that to MEMORY.md.

Walk the decision out loud:

1. Durable across sessions? Yes — the user wants this flag remembered next time. Pass.
2. Stable environment fact? Sort of. It is a launch flag, not a fixed property of the host. Borderline.
3. Changes frequently? Yes. Build flags evolve with the project. Likely to go stale.

Verdict: this is not a memory candidate. It belongs in one of two places:

• If the flag is the result of a procedure (“how I build this project”), it is a skill — write a SKILL.md that captures the build command and the reason for the flag, so a future agent can re-derive it.
• If the flag is a one-line project preference, it goes in a project file (package.json scripts, a Makefile, or a project README), not in Hermes memory.

The reason this matters: writing the flag to MEMORY.md makes it look load-bearing to every future session, including sessions on unrelated projects. That is how memory fills with stale notes that are confident and wrong.

Commands, briefly

Command	Job
hermes memory status	Show the active memory provider config (built-in is always active).
hermes memory setup [provider]	Interactive provider selection, or skip the picker with a positional name (honcho, openviking, mem0, hindsight, holographic, retaindb, byterover).
hermes memory off	Disable the external provider and fall back to built-in MEMORY.md / USER.md.
hermes memory reset	Erase the built-in memory. Use deliberately.
hermes skills browse	Browse all available skills (paginated).
hermes skills search <query>	Search skill registries.
hermes skills install <name>	Install a skill from a registry.
hermes skills list [--source {all,hub,builtin,local}] [--enabled-only]	List installed skills; filter by source or show only enabled.
hermes skills config	Interactive skill configuration — enable/disable individual skills.

The four memory subcommands are setup, status, off, reset. There is no graph subcommand; do not look for one.

Verification checklist

Five commands to confirm memory and skills are in the state you expect:

hermes memory status
hermes skills list --source all
hermes skills list --source local --enabled-only
ls /opt/data/memories/
ls /opt/data/skills/

If hermes memory status shows a provider you did not intend, run hermes memory off and confirm the built-in path is what is in use. If hermes skills list --source local --enabled-only is empty but ls /opt/data/skills/ is full, a skill has been disabled at the config layer rather than removed from disk; hermes skills config is the place to re-enable it.

Sources

• Hermes memory docs
• Hermes skills docs
• ABS companion: ABS Regression Failure Modes and Their Cheap-First Check
• Setup companion: Hermes Agent Setup Without Turning Everything On at Once

Last verified: 2026-07-14 against Hermes v0.18.2 (2026.7.7.2) and the live /opt/data/skills/ directory on this VPS (68 entries).