Memory Has Three Timescales
Hermes Agent has several ways to preserve continuity, and they solve different problems. This chapter distinguishes what stays in the live prompt, what remains searchable in a session record, what is compressed when a conversation grows, and what is promoted into durable memory. The practical goal is not to make the agent remember everything; it is to help an operator choose the least expensive and most reliable form of continuity for a fact, a past decision, a long task, or a future session.
The distinction matters because “memory” can mean at least four different things in an agent system. The current turn needs immediate context. A user may later ask what was decided in an earlier conversation. A long-running task may outgrow the model's context window. And a stable preference or reusable fact may need to be present when a completely new session begins. Treating all four needs as one growing prompt would make Hermes slower, more expensive, and harder to correct.
What must be present now, later, or always
The first timescale is live context. It is the message history and system prompt that the AIAgent sends as it works. This is where the current task's instructions, recent tool results, and immediate decisions have the strongest influence. Live context is precise but bounded by the active model's context window. It is not a good place to store every fact that might ever matter, because each additional token competes with the task at hand.
The second is episodic recall. Hermes stores session transcripts in SQLite, with full-text search indexes that cover message content and tool-related fields. The session_search capability can find a conversation from the past and return actual messages, rather than requiring the agent to keep the entire history in every prompt. The record can also be browsed around a match, so a found line can be interpreted in its surrounding exchange.
The third is compressed continuity within a long session. When a conversation becomes too large, Hermes can replace older middle turns with a structured summary while preserving a recent tail and keeping tool-call groups intact. The summary is meant to preserve goals, constraints, progress, decisions, relevant files, and next steps. It is a working representation of an ongoing task, not a new permanent belief about the user.
The fourth is cross-session state. Built-in memory and the user profile are compact stores that are loaded when a new session begins. They are intended for facts that should apply broadly: a stable environment convention, a durable preference, or a user expectation. A procedure that should be loaded only for a particular class of task belongs in a skill rather than in this always-present layer.
These timescales overlap, but they are not interchangeable. A decision can be in the live transcript and later remain searchable without ever becoming a memory entry. A compressed summary can help finish today's task without being treated as a permanent fact. A memory entry can be available at the start of tomorrow's session while the detailed conversation that justified it is still recoverable through search.
Built-in memory is deliberately small
Hermes's built-in stores are simple files with a strict purpose. MEMORY.md holds the agent's personal notes about environments, conventions, lessons, and other durable facts. USER.md holds a profile of the person using it: preferences, communication style, role, and other information that should shape interactions. Both are injected into the system prompt at session start.
The limits are part of the design. The memory tool refuses a write that would exceed its configured capacity instead of silently deleting older entries. It supports adding, replacing, and removing entries, and can apply a batch atomically so that stale material can be consolidated before a new fact is added. Exact duplicates are rejected. Content is scanned for prompt-injection and exfiltration patterns because anything accepted into these files will later be placed inside the system prompt.
This makes the right unit of memory a high-signal fact, not a transcript excerpt. “The project uses a particular database and tests are run with a particular command” may be useful if it applies to every future session in that environment. “The user asked about a deployment on Tuesday” is normally not. The latter belongs in the session record, where the agent can retrieve it if the user asks, without spending prompt space on it forever.
The distinction between the two built-in targets also prevents a subtle category error. An operator's communication preference is not the same as an agent's environment note. Hermes gives each a separate place because the consequences differ: one describes how to work with the person, while the other describes how the agent should operate in the world. That separation makes later editing more intelligible and reduces the chance that a temporary project fact is mistaken for a personal identity claim.
Memory is also not live shared state inside a turn. Hermes captures a frozen snapshot when the session starts. If the agent writes a new entry midway through the conversation, the file changes immediately, but the already-built system prompt does not mutate simply because the write succeeded. The tool result can show the live state, yet the model's current prompt remains stable. This can feel surprising until the underlying objective is clear: changing the cached prefix after every memory operation would make the prompt harder to reason about and would sacrifice provider-side caching.
The delay is therefore intentional. A new entry becomes durable now and normally becomes prompt context at a later session or a controlled rebuild. That is safer than pretending that a current turn has instantly rewritten the rules under which it was already operating.
Session search is recall, not permanent identity
Searchable history fills the gap between a tiny always-on memory and an enormous archive. Hermes stores full messages and metadata in a state database, with FTS5 indexes designed for ordinary word search as well as substring or CJK-oriented retrieval. A query can be filtered by source or role, and results include a match snippet and nearby context. The agent can use this when a user says, “We discussed this last week,” or when an old technical decision is relevant to a new task.
Search has a different cost profile from prompt injection. A memory entry consumes space in every future prompt, even when irrelevant. A session search consumes effort only when invoked. That makes search appropriate for episodic detail, completed work, old error messages, and decisions whose importance is conditional. It also means search results must be interpreted: a matching sentence is evidence of what was said, not automatically proof that the decision remains correct.
The database preserves session boundaries and lineage rather than flattening every conversation into one universal memory. Platform and profile information help keep sessions separated. Compression can create archived generations or, in the default in-place mode, rewrite the active message list while retaining archived rows. Those rows remain useful to search, but they do not necessarily belong in the live prompt. The system is preserving access without claiming that all historical content deserves equal authority.
That is an important property for a learning agent. If every retrieved sentence were silently promoted to a standing instruction, search would become a back door into uncontrolled memory. Hermes instead treats search as a way to recover context for a current decision. Promotion into durable memory or a skill is a separate action with its own tool semantics and, where configured, approval.
Compression keeps a long task moving
Search is not enough when the current conversation itself has grown beyond a useful context window. Hermes has a context compressor for that transition. Before compression, it can prune old verbose tool results outside the protected tail. It then identifies a head that should remain intact, a middle that can be summarized, and a recent tail that is valuable for immediate continuity. Boundaries are aligned so a tool call is not separated from the results that explain it.
The summary is structured around the work: goal, constraints and preferences, completed progress, work in progress, blockers, key decisions, relevant files, next steps, and critical context. On later compressions, the previous summary can be updated rather than discarded and rewritten from scratch. That gives a long debugging or implementation task a way to carry forward its current state without repeating every terminal output.
Compression has an explicit loss boundary. A summary is not a byte-for-byte transcript. Details may be omitted, and the project warns that a summary model with an insufficient context window can degrade the result. Search and preserved anchors provide recovery paths, but they do not make the compression lossless. The correct mental model is a change in representation: detailed history becomes a smaller working account plus a searchable archive.
In-place compaction keeps one stable session identity while old rows are marked inactive or archived and the retained context remains active. This avoids making a user follow a chain of newly named sessions just because a long conversation crossed a boundary. It also means that apparent duplicate content in the database can be legitimate: a protected message may exist in an archived generation and the active generation at the same time.
The lifecycle shows why no single state store can do every job. Live context is where the next model call operates. Compression changes the representation of that context when pressure rises. Archived history preserves a route back to detail. A reviewed promotion changes the future starting point. Each arrow has a different trigger and a different risk of loss or delay.
Stability has a price
The frozen memory snapshot is one instance of a broader prompt-assembly decision. Hermes separates a stable system prompt from ephemeral API-call additions so the provider can reuse a prefix across turns. Identity, tool guidance, project context, skills, memory and profile snapshots, and runtime information are arranged in tiers. A later-turn overlay can carry transient context without turning that context into a permanent prompt mutation.
The benefit is cost and predictability. If the prefix remains byte-stable, a provider can cache it. If a memory write changed the system prompt in the middle of every turn, the cache would be invalidated and the model would receive a different operating frame after an internal tool call. The cost is temporal: a newly learned fact may not affect the current session immediately. Hermes chooses a delayed, explicit update over a constantly shifting instruction surface.
This also explains why compression and memory should not be conflated. Compression is a response to pressure in an active conversation; memory is a promotion of selected facts into future sessions. A summary can say what remains unfinished today without declaring that the unfinished state is a durable user preference. Conversely, an environment convention may be worth preserving even after the original task has ended, but it should not force the next session to carry the entire debugging transcript.
Choosing the right continuity mechanism
An operator can use a simple question: who needs this information, and for how long? If the next model call needs it to decide, keep it in live context. If a future question may need the detail but most sessions will not, keep it in the searchable transcript. If the current session is too long, compress it into a structured working summary and retain a recovery path. If the fact should shape every future session, put a concise, correct version in built-in memory or the user profile. If the knowledge describes how to perform a recurring class of task, encode it as a skill.
That last distinction will matter for the learning loop. Memory answers “what should be known by default?” Search answers “what did we say or do?” Compression answers “how can this task continue within a bounded context?” Skills answer “how should this class of work be performed next time?” Hermes becomes more than a transcript only when those questions remain separate enough for the system and the operator to correct them independently.
The next synthesis can now connect the execution turn to these three timescales. A completed interaction produces evidence, but evidence does not become future behavior by itself. The important question is which transition turns a useful experience into a reviewed, bounded, and reusable change—and where that transition can be delayed, rejected, or made unsafe.