Hermes Agent memory: a hard cap, not an archive

10 min readSimon BudziakBy Simon Budziak

On this page8 sections
Title card reading Agent memory is a budget, not an archive, with the Hermes Agent logo and name in the top-left corner. A navy background with a stylized terminal window outlined in thin gold, holding one small brightly lit gauge at the top and a much larger field of faint dim records below it, joined by a single gold thread.

Personal AI agents were sold on a simple promise: the agent remembers, so you stop re-explaining yourself. That promise is now table stakes, and the interesting engineering sits one layer down. Hermes Agent caps what it may hold in context at roughly 1,300 tokens, according to its persistent memory documentation, refuses any write that would exceed the cap, and runs a background curator that ages self-written skills out after 30 and 90 days. The design question is no longer whether an agent remembers, it is what it is allowed to keep and who prunes it. This post walks through the two memory lanes Hermes runs, the curator that stops its self-written skills from rotting, and the two claims from our original version that did not survive checking.

The comparison that stopped being true

When we first wrote about Hermes in April 2026, the argument was that it remembers and everything else starts fresh. That framing is dead, and it is worth saying so plainly rather than quietly editing around it.

OpenClaw now ships a built-in memory engine whose own documentation says its default backend is a per-agent SQLite database with FTS5 full-text indexing, plus vector search through any supported embedding provider and a hybrid mode combining both. It has memory tiers, provenance, recall lanes, a user model, and a background consolidation pass it calls dreaming. That is the same architecture the original post treated as Hermes’ distinguishing bet, with more retrieval modes layered on top.

The scoreboard moved too. OpenClaw sits at roughly 387,000 GitHub stars and 81,000 forks, against 236,000 stars and 47,000 forks for hermes-agent as of August 2026. Nvidia’s Jensen Huang told CNBC’s Mad Money from the GTC stage on 17 March 2026 that “This is definitely the next ChatGPT.” None of that settles which design is better, and citing star counts as evidence of quality is how you end up writing a press release.

The useful question is not which agent has memory. Both do. It is what each one refuses to remember, because an agent that keeps everything is an agent whose context window is the real constraint.

What Hermes actually keeps in context

Hermes’ always-loaded memory is two files in ~/.hermes/memories/, and both are hard-capped. Per the persistent memory documentation, MEMORY.md holds the agent’s own notes about your environment and conventions at 2,200 characters, about 800 tokens, and USER.md holds your profile and communication preferences at 1,375 characters, about 500 tokens. That is the entire always-on budget: roughly 1,300 tokens, typically 8 to 15 entries plus 5 to 10.

Two design choices follow from the cap, and both are more interesting than the cap itself.

Memory does not auto-compact. A write that would breach the limit returns an error rather than silently dropping the oldest entry. The agent has to consolidate or remove something in the same turn and retry. Silent eviction is the easy implementation and it is the one that loses the fact you needed six weeks later, with nothing in any log to tell you it happened.

The injection is a frozen snapshot. Memory is rendered into the system prompt once at session start and never changes mid-session, deliberately, to preserve the model’s prefix cache. Writes land on disk immediately but do not appear in the prompt until the next session. That is a real trade of freshness for cost, and it is the kind of thing you want stated in the docs rather than discovered in a bill.

Diagram titled Two lanes, one budget. The upper lane, Always in context, shows MEMORY.md at 2,200 characters and USER.md at 1,375 characters totalling about 1,300 tokens, marked capped and frozen at session start. The lower lane, Searched on demand, shows the SQLite session database with FTS5, marked unlimited, about 20 milliseconds, and no LLM call.
The cap only works because a second, unbounded lane sits behind it. Neither lane on its own would be usable.

The second lane: unlimited search, no summarization

A 1,300 token ceiling would be crippling on its own. It works because everything else is searchable rather than resident. Every CLI and messaging session is stored in SQLite at ~/.hermes/state.db with FTS5 full-text search, and the agent queries it with a session_search tool.

The documented performance is about 20ms for an FTS5 query and about 1ms to scroll within a result, at no token cost in the system prompt and no LLM call. Our original version put this at under 10ms and added that a fast model summarizes the results before injecting them. Both were wrong. The docs are explicit that search returns actual messages from the database with no LLM summarization and no truncation.

That correction matters beyond a stray number. A retrieval lane that hands back the real messages is a different tool from one that hands back a model’s precis of them, and we have written before about why a summary is not a source. Summaries drop reversals and negative findings. When the agent is answering “did we decide against this in March”, the raw turn is the answer and a paraphrase of it is a liability.

One more detail worth borrowing regardless of which agent you run: memory entries are scanned before they are accepted, because anything written into memory is by definition injected into a future system prompt. Content matching prompt injection or credential-exfiltration patterns, or carrying invisible Unicode, is rejected. A memory store is an untrusted input channel with a delay fuse, and most implementations do not treat it as one.

Skills the agent writes for itself

The second half of the loop is skills, stored in ~/.hermes/skills/ and compatible with the agentskills.io open standard. The skills system loads them by progressive disclosure across three levels: a list of names and descriptions costs about 3,000 tokens, the full skill body loads only when the agent decides it needs it, and reference files load only when a specific question reaches for one.

The concrete mechanism is /learn, which turns a directory, a documentation URL, a pasted procedure, or the workflow you just walked the agent through into an authored skill. Point it at something large, a book or a docs corpus, and it writes a lean entry file carrying the mental models plus one distilled file per topic under references/, indexed rather than inlined. Re-running /learn on the same topic folds new material into the existing skill instead of creating a second one.

This is the part of the original post that has held up, and it is the genuine architectural difference. Skills that come from your own failures encode your systems: the staging box that wants SSH on port 2222, the migration that always breaks the same way. A registry skill cannot know any of that.

Why a curator exists

Here is the honest counterweight, and it comes from Hermes’ own documentation rather than from us. Agent-written skills accumulate, and the curator exists because of what happens if they do not get pruned: “Without maintenance, you end up with dozens of narrow near-duplicates that pollute the catalog and waste tokens.”

The curator runs as a background pass, gated on an inactivity check rather than a cron daemon: every 168 hours by default, and only after the agent has been idle 2 hours. It has two phases with very different risk profiles.

The deterministic phase is always on and uses no model at all. Skills unused for 30 days are marked stale, and skills unused for 90 days are moved to an archive directory. Never-used skills get a grace floor rather than immediate archival, on the reasoning that zero uses is absence of evidence rather than proof a skill is disposable. Pinned skills and skills referenced by any cron job, including paused ones, are skipped. Nothing is ever auto-deleted; the worst outcome is a recoverable archive.

The LLM consolidation phase, which merges overlapping skills into umbrellas, is off by default and costs 50 to 100 API calls in a full sweep. Turning it on is opt-in precisely because it makes broad structural changes to a library you did not write.

That shape is worth stealing whether or not you run Hermes: cheap deterministic pruning always on, expensive model-driven restructuring opt-in and dry-runnable first. It is the same instinct behind treating a context window as a set of separate levers rather than one dial.

Two claims we could not verify

The original version of this post carried two assertions that do not survive a source check, and both came from the same secondary article rather than from either project’s documentation.

The first was that Hermes recovered from errors 22% more effectively than OpenClaw in long-horizon task evaluations. The figure traces to a single vendor blog post that names no benchmark, no dataset, no evaluation harness, and cites no primary source. There is no measurement behind it that we can find, so it is gone rather than softened.

The second was that OpenClaw requires a manual reset of a persistent state file called SOUL after a logic break. OpenClaw’s own documentation describes SOUL.md as a personality guide, the file that sets tone, opinions, brevity and humour, and explicitly warns against turning it into a changelog or state dump. It is not a memory store, so resetting it is not an error-recovery step.

Both errors have the same shape. A comparison article asserted a number, the number flattered the conclusion we already liked, and it travelled. It is the argument for reading the docs of the tool you are criticising, not only the docs of the one you are recommending.

Choosing between them, honestly

The breadth-versus-depth framing survives, stripped of the invented evidence. OpenClaw optimises for reach: a published registry with security audits, a skills CLI, and a community catalogue that a third-party index puts at over 5,400 skills. Hermes optimises for a library that is small, personal, and actively pruned, on the bet that a skill written from your own failure beats a generic one.

If you want to try it, installation is one command on Linux, macOS, WSL2 or Termux:

curl -fsSL https://raw.githubusercontent.com/\
NousResearch/hermes-agent/main/scripts/install.sh | bash

We have set up agents on both for teams doing repetitive engineering work, and the pattern we would defend is narrower than the one we originally claimed. What compounds is not the agent’s memory in the abstract. It is having an explicit budget for what stays in context, a cheap way to reach everything else, and something that throws away what stopped being true. Any agent memory design without all three eventually costs more than it returns.

Sources

Last updated:

See this working in a system we built