---
title: "How Hermes Agent's memory works"
description: "Hermes agent memory, from the official docs: two bounded files with hard caps, capacity errors, SQLite session search, and external providers."
canonical: https://past.dev/blog/hermes-agent-memory
date: 2026-09-03
category: Research
authors: The past.dev team
---
# How Hermes Agent's memory works

Hermes Agent is Nous Research's open-source agent for the command line and messaging channels ([repo](https://github.com/NousResearch/hermes-agent)). Hermes agent memory is deliberately bounded: two files with hard character caps, `MEMORY.md` for the agent's own notes and `USER.md` for your profile, injected into the system prompt at session start ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)). The agent edits those files itself through a `memory` tool, a SQLite full-text index covers every past conversation, and optional external providers add larger stores. When a file is full, writes fail loudly instead of trimming silently.

This post documents that design as of September 2026, from the official documentation, with each claim linked to the page that states it. For the general problem space, see [what agent memory is](/what-is-agent-memory).

## The two files behind Hermes Agent memory

The built-in store is two Markdown files in `~/.hermes/memories/` ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)):

- `MEMORY.md`: 2,200 characters, which the docs describe as roughly 800 tokens. The agent's personal notes: environment facts, conventions, things it has learned.
- `USER.md`: 1,375 characters, roughly 500 tokens. Your profile: preferences, communication style, expectations.
- Both are injected as a frozen snapshot at session start, so the copy in the system prompt stays constant for the whole session; the files on disk are what change ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)).
- Combined, that is about 1,300 tokens of always-present context per the docs' own accounting ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)).
- Memory is scoped per profile: each profile keeps its own memory store, session database, and skills directory, and the docs warn against pointing two agent processes at the same Hermes home directory ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)).

## How writes happen

The agent manages its own [long-term memory](/glossary/long-term-memory) through one tool, with several documented guardrails ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)):

- The `memory` tool has three actions: `add` creates entries, `replace` updates them by matching a substring passed as `old_text`, and `remove` deletes by substring. A `target` parameter selects `memory` or `user`.
- Entries are scanned for injection and exfiltration patterns before being accepted, because accepted entries land in the system prompt.
- `display.memory_notifications` controls how visible writes are: `off`, `on`, or `verbose`.
- A background self-improvement review runs after each turn (`auxiliary.background_review.enabled`, default true). It can run on a cheaper model via `auxiliary.background_review.provider` and `model`, and `defer: auto` queues reviews until idle for local models.
- `memory.write_approval` (default false) gates saves behind a human. Foreground writes prompt inline, background writes are staged, and `/memory pending`, `/memory approve <id>`, and `/memory reject <id>` manage the queue.

## Caps, capacity errors, and consolidation

The character limits are enforced at write time ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)):

- When a file is at capacity, the tool returns an error instead of silently dropping entries. The agent has to consolidate related entries or remove stale ones, then retry.
- Memory does not auto-compact. The docs instruct the agent to consolidate as the files approach their caps, so pruning is an explicit act.
- The caps are configuration: `memory.memory_char_limit` (2200) and `memory.user_char_limit` (1375) in `~/.hermes/config.yaml`.
- Setting `memory.memory_enabled` and `memory.user_profile_enabled` to false turns the built-in stores off and removes the `memory` tool from the agent's schema entirely.

This is a forgetting policy enforced by the write path itself; the tradeoffs of that approach are covered in our guide to [forgetting policy](/guides/forgetting-policy).

## Session search: unbounded history, raw messages

What the two files cannot hold, the session database can ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)):

- Every CLI and messaging session is stored in SQLite at `~/.hermes/state.db` with FTS5 full-text indexing.
- The `session_search` tool queries it and returns the actual stored messages rather than an LLM's summary of them.
- `hermes sessions list` browses the same history from the shell ([memory docs on GitHub](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/memory.md)).

The division of labor is explicit: the files hold what every session needs at start, and session search answers questions about specific past conversations. In glossary terms, Hermes keeps a tiny curated store plus searchable [episodic memory](/glossary/episodic-memory) of everything said.

## Hermes agent long term memory via external providers

For memory beyond the built-in caps, Hermes supports external provider plugins, one active at a time ([memory providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers)):

- The documented plugins include Mem0, Supermemory, Honcho, Hindsight, Holographic, OpenViking, RetainDB, ByteRover, and Memori.
- Providers inject relevant context into the system prompt before each turn, add their own tools to the agent (names like `mem0_search`, `supermemory_store`, `honcho_search`), and sync conversation turns in the background.
- The built-in files keep working unchanged, and Hermes mirrors built-in memory writes to the active external provider.
- Setup is CLI-driven: `hermes memory setup` (interactive picker), `hermes memory status`, and `hermes memory off`. The active provider is the `memory.provider` key in `~/.hermes/config.yaml`.

Picking among provider architectures (fact extraction, knowledge graphs, local SQLite stores, cloud APIs) is its own decision; our guide to [choosing a memory system](/guides/choose-memory-system) maps the categories.

## The journey timeline

Hermes also renders what it has learned as a timeline ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)):

- `hermes journey` in the terminal (aliases `hermes learning` and `hermes memory-graph`), `/journey` in chat, and a Star Map panel in the desktop app.
- `hermes journey list` shows node IDs, `hermes journey delete <node>` removes a node (skills are archived, memory entries removed), and `hermes journey edit <node>` opens the content in `$EDITOR`.

## What Hermes agent memory does not do

- No unbounded accumulation. Nothing above the caps gets stored until the agent makes room; that is the documented behavior rather than a failure mode ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)).
- No mid-session refresh of the prompt copy. The snapshot is frozen at session start, so an entry written mid-session lives in the file and reaches the prompt at the next session ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)).
- No summarized recall from history. Session search returns stored messages verbatim; summarization is left to the agent in the moment ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)).
- No documented sync or cloud backup for the built-in files. The docs describe them as local files under the Hermes home directory, scoped per profile ([memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)).

## For builders: when two files are the ceiling

Hermes shows how far a bounded, auditable store can go for a single user on a single machine. If you are building your own assistant and need what that model cannot give your product (memory across many users, many sources, and years of history), past.dev is the infrastructure layer for it: `POST /api/v1/ingest` takes raw text with its original timestamp, entity resolution links references to the same person across sources, and facts carry event time, validity windows, and supersession links. `POST /api/v1/recall` returns ranked, dated evidence with sources and one of four status values (Supported, Conflicted, NoKnownSupport, UnknownBecauseDegraded), deployed managed or self-hosted in your own Postgres. Start with the [quickstart](/docs/memory-api/quickstart) and the [benchmarks](/benchmarks).