The two files have different owners in spirit. MEMORY.md is for what the agent needs to remember about the environment, the workflows, and the lessons it has learned. USER.md is for what the agent needs to remember about the person it is helping. The distinction matters because mixing them produces a memory file that mixes personal preferences with project conventions, which makes future edits more error-prone.
The agent manages its own memory through a single tool with three actions: add, replace, and remove (https://hermes-agent.nousresearch.com/docs/user-guide/features/memory). There is no read action because the content is already in the system prompt. The replace and remove actions use substring matching rather than full-text equality, which means you do not need to know the exact current wording to update an entry; you only need a unique substring that identifies exactly one entry. If the substring matches multiple entries, the tool returns an error asking for a more specific match, which is a sane failure mode.
The frozen snapshot pattern that preserves the prefix cache
The memory injection is captured once at session start and never changes mid-session (https://hermes-agent.nousresearch.com/docs/user-guide/features/memory). The published reason is prompt cache preservation, which lines up with the prompt caching guidance published for major model providers (https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching). When the agent adds, replaces, or removes memory entries during a session, the changes are persisted to disk immediately but the system prompt does not change; the new state appears in tool responses and is visible from the next session onward.
The design implication for builders is that memory is durable, not interactive. You cannot ask the agent to "remember X and act on it this session" and expect the system prompt to update mid-conversation. The right mental model is: memory changes land for next time, and the current session sees its content as a frozen block. Planning around that property is what separates a builder who uses memory well from one who gets confused about why a freshly added entry does not seem to be in scope.
A second implication is that you should never try to grow MEMORY.md indefinitely. The documentation is explicit that memory does not auto-compact, and that a write which would exceed the limit returns an error instead of silently dropping the entry (https://hermes-agent.nousresearch.com/docs/user-guide/features/memory). The agent then has to consolidate or remove entries in the same turn to make room. That is the documented pressure to keep memory small and meaningful, and it is healthier than the alternative of unbounded growth.
Skills - the on-demand knowledge documents
Skills are on-demand knowledge documents the agent can load when needed, organized for progressive disclosure to minimize token usage (https://hermes-agent.nousresearch.com/docs/user-guide/features/skills). The catalog is compatible with the published agentskills specification (https://agentskills.io/specification), which matters for portability: a skill written against the spec loads in Hermes Agent, and a Hermes Agent skill should load in any other compliant runtime.
Every installed skill becomes a slash command, which is the surface that users actually touch (https://hermes-agent.nousresearch.com/docs/user-guide/features/skills). The published pattern is to chain up to five slash commands at the start of a message and let the rest become the instruction. Skill bundles let you collapse combinations you use repeatedly into a single short command, and the public /plan skill is the documented example of a bundle (https://hermes-agent.nousresearch.com/docs/user-guide/features/skills). The bundle pattern is what you reach for when a workflow has matured enough that the user should not have to remember the right slash-command sequence every time.
Skills live in a skills directory under the agent's home, and the primary directory is the canonical location for installed skills (https://hermes-agent.nousresearch.com/docs/user-guide/features/skills). Hub-installed and agent-created skills also land there. On a fresh install, bundled skills are copied from the repository. If you want a profile with no bundled skills and that stays empty across updates, the documented paths are --no-skills at install time, hermes profile create <name> --no-skills at profile creation, or the runtime hermes skills opt-out toggle (https://hermes-agent.nousresearch.com/docs/user-guide/features/skills). The opt-out --remove form is documented as safe: it deletes unmodified bundled skills but never touches anything you have edited or installed from the hub.
Sessions - the deep-searchable past
The session search surface, surfaced through the session_search tool and the session_search toolset, lets the agent (and the operator) reach back into past conversations by keyword or by adjacent message id (https://hermes-agent.nousresearch.com/docs/user-guide/features/tools). Sessions are different from memory in two important ways. They are not bounded to a character cap, because the storage model is a message log rather than a curated file. They are not auto-injected into the system prompt, because doing so would blow the context budget.
The right mental model is that memory is for facts you have decided are durable, skills are for procedures the agent should be able to perform on demand, and sessions are for evidence the agent (or operator) can search when the durable layers do not contain the answer. The agent's job is to write important facts from a session into memory; the operator's job is to decide when a session deserves a new skill. The sessions layer is the place both of them reach when they need to remember what actually happened.
Choosing the right layer for the right fact
The rule of thumb is straightforward. If the fact will be needed at the start of next session, write it to memory. If the fact is a procedure the agent should be able to perform on demand, write it to a skill. If the fact is evidence of what happened in a specific past conversation, leave it in the session log and reach for it through search. Conflating the layers produces a memory file full of procedures, a skill catalog full of one-off facts, and a session history full of repeated searches for the same thing.
The same rule applies to user profile content versus project conventions. A preference like "user prefers concise responses" belongs in USER.md. A convention like "project uses tabs and 120-char line width" belongs in MEMORY.md. A procedure like "the deployment checklist for staging" belongs in a skill, not in either memory file. The classification is not bureaucratic; it is what lets the agent apply each piece of knowledge in the right context.
| Fact type | Best layer | Why |
|---|
| User prefers concise responses | USER.md | Stable preference that should influence every response |
| Project uses tabs and 120-char line width | MEMORY.md | Project-scoped convention the agent should apply when editing files |
| Deployment checklist for staging | Skill | A reusable procedure the agent performs on demand |
| What was decided in last Tuesday's call | Session search | One-time event that is searchable but should not become a durable fact |
| Today's debug path for a flaky test | Session search | Ephemeral context that does not deserve a permanent slot |
Designing for capacity before overflow
Capacity design matters more for the bounded layers. The 2,200-character MEMORY.md and 1,375-character USER.md caps look small until you start measuring (https://hermes-agent.nousresearch.com/docs/user-guide/features/memory). A useful exercise is to instrument a session and count how many facts the agent would have wanted to remember by the end, then design how you would consolidate them to fit. The healthy pattern is to review memory periodically and to retire facts that no longer pay rent. A single consolidated fact is worth three narrow facts that say the same thing in different words.
Skills do not have a global character cap, but they have a different cost: each skill the agent decides to load costs tokens on every future session that touches its slash command (https://hermes-agent.nousresearch.com/docs/user-guide/features/skills). The progressive disclosure design is the mitigation; the right habit is to write skills so that only the description loads by default and the full body loads only on demand. That keeps the always-on token cost of a large skill catalog small.
Capacity metrics and review thresholds
A capacity-aware builder tracks three numbers and reviews them on a cadence. The numbers are cheap to compute and they are the early signal that a layer is about to overflow or a skill catalog is bloating. The thresholds below are starting points; tighten or loosen them based on how your team actually uses the agent.
| Metric | Layer | Review threshold | What changes when it fires |
|---|
| MEMORY.md character usage | MEMORY.md | More than 70 percent of 2,200 chars | Time to consolidate entries before the next write errors |
| USER.md character usage | USER.md | More than 70 percent of 1,375 chars | Time to merge overlapping preferences |
| Slash command skills installed | Skills directory | More than 25 active slash commands without a bundle | Time to compose related skills into a single bundle |
The limits are documented behavior, not opinions; treat them as the promotion gate for the next memory review rather than as a ceiling to push against.
FAQ
Why does my newly added memory entry not seem to take effect this session?
The memory injection is captured once at session start and never changes mid-session (https://hermes-agent.nousresearch.com/docs/user-guide/features/memory). The entry is persisted and will appear from the next session onward.
Can I remove a skill and bring it back later?
Yes. The documented opt-out toggles (hermes skills opt-out, hermes skills opt-out --remove, hermes skills opt-in --sync) are designed to be reversible, with explicit safety rules about what gets deleted (https://hermes-agent.nousresearch.com/docs/user-guide/features/skills).
What is the difference between a skill and a project context file?
A skill is an on-demand knowledge document loaded by slash command or by the agent on demand (https://hermes-agent.nousresearch.com/docs/user-guide/features/skills). A project context file is automatically discovered and injected into the system prompt when the agent works inside a project directory (https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files). Skills are for procedures; context files are for project-local instructions.
The persistence test
A knowledge architecture is healthy when each layer holds the things it is most suited to holding, when nothing important is duplicated across layers, and when the operator can explain, on demand, where a particular fact lives and why. The three-layer design in Hermes Agent is built to make those questions answerable; the builder's job is to use the layers as designed. Each implementation of the architecture is a judgment about where to draw the line between durable memory, on-demand skills, and searchable sessions; the right implementation names the boundary in writing and lets future reviews challenge it.
A memory review most teams postpone is the one where they instrument how often each MEMORY entry actually changes the next session. The entries that do not pay rent in the implementation review are the entries to retire, and the practical test for whether an entry belongs in MEMORY or in USER is the question "does this change how I act or how I describe the person?"