Persistent Memory: How Hermes Remembers Across Sessions

Hermes Agent has bounded, curated memory that persists across sessions. This lets it remember your preferences, your projects, your environment, and things it has learned — without carrying the entire history of every conversation around in its context window. Instead of a sprawling transcript, the agent keeps compact, structured entries that are always available.

How the Memory Is Stored

Two files make up the agent's memory, both held in ~/.hermes/memories/:

• MEMORY.md — the agent's personal notes: environment facts, conventions, and things it has learned. It works within a 2,200 character limit (~800 tokens).
• USER.md — the user profile: your preferences, communication style, and expectations. This fits within 1,375 characters (~500 tokens).

Both files are injected into the system prompt as a frozen snapshot at session start. The snapshot pattern is intentional: it preserves the LLM's prefix cache for performance. When the agent adds or removes memory entries mid-session, the changes are written to disk immediately but only appear in the system prompt when the next session begins.

Managed Through the memory Tool

The agent manages its own memory with the memory tool, which supports three actions:

• add — add a new entry.
• replace — update an existing entry, using short unique substring matching via old_text.
• remove — delete an entry that's no longer relevant, also using substring matching.

There is no read action, because the content is automatically injected into the system prompt at session start. The two targets are memory (the agent's personal notes about the environment, workflows, and lessons) and user (your identity, preferences, and communication style).

What the Agent Saves — and Skips

The agent saves proactively, without being asked, when it learns something durable:

• User preferences ("I prefer TypeScript over JavaScript") → saved to user.
• Environment facts ("This server runs Debian 12 with PostgreSQL 16") → saved to memory.
• Corrections ("Don't use sudo for Docker commands, user is in the docker group").
• Project conventions and config, completed-task diary entries, and skills or techniques that worked.

It deliberately skips trivial or re-discoverable facts, raw data dumps like large code blocks and log files, and session-specific ephemera such as temporary file paths. Because the character limits are strict, the memory does not auto-compact — when a write would overflow, the tool returns an error and the agent consolidates or removes entries itself before retrying. When memory is above 80% capacity, best practice is to merge related entries before adding new ones.

Duplicate Prevention and Security

The memory system rejects exact duplicate entries automatically, returning a "no duplicate added" message. Because memory is injected into the system prompt, every entry is scanned for injection and exfiltration patterns before it is accepted — content matching threat patterns such as prompt injection, credential exfiltration, or SSH backdoors, or containing invisible Unicode characters, is blocked.

Beyond Short-Term Memory: Session Search

Separate from the persistent files, the agent can search its past conversations with the session_search tool. All CLI and messaging sessions are stored in SQLite (~/.hermes/state.db) with FTS5 full-text search. Queries return actual messages from the database — no LLM summarization, no truncation — so the agent can find things it discussed weeks ago, even if they are no longer in its active memory. The rule of thumb: memory is for critical facts that should always be in context, while session search answers "did we discuss X last week?"

The Learning Journey and Configuration

The learning journey (hermes journey, or /journey in the TUI and desktop app) is a timeline of everything Hermes has learned — saved skills and memory entries plotted over time — and it's also where you prune and correct that learning with list, delete, and edit subcommands. The whole system is configurable in config.yaml under memory: with settings such as memory_char_limit, user_char_limit, and write_approval. Set write_approval: true to require approval before any save, and use /memory pending, /memory approve, and /memory reject to review staged writes. Disabling both memory_enabled and user_profile_enabled turns the built-in stores off entirely, and external memory providers can be added for knowledge graphs and semantic search.

Key Takeaways

• Hermes keeps a bounded, curated memory — MEMORY.md and USER.md — injected into the system prompt as a frozen snapshot each session.
• The manager tool supports add, replace, and remove, with substring matching and automatic duplicate rejection.
• Character limits force high-quality, dense entries, and every entry is security-scanned before it's accepted.
• The session_search tool lets the agent recall specific past conversations from all sessions.
• write_approval and the learning journey give you control over what Hermes remembers.