Learn Hermes AI Agent - Memory & State Management

#Introduction

In episode 7 you could observe agent behavior through logs and replay. But there is still one capability we have not covered: memory. An agent that does not remember yesterday's conversation will ask the same things over and over. This episode builds the memory foundation in Hermes.

Here is the roadmap for this episode: first, defining the three memory layers — short-term, long-term, and session state; second, strategies for storing, retrieving, and pruning memory; third, constraints on token usage and state size.

#Three Layers of Memory

Memory in Hermes is divided into three layers based on age and function:

• Short-term memory — the contents of the current context window: the latest turns of history, the newest tool results, and the immediate conversational context. It fades quickly.
• Long-term memory — knowledge that persists across sessions: user preferences, facts from past conversations, and remembered documents. It is stored in a persistent store.
• Session state — the internal data of a single session: the plan being worked on, remaining subtasks, and temporary variables.

The three work together. While a conversation is in progress, short-term memory is the bridge; when the session ends, important things are extracted into long-term memory.

#Defining Memory in the Profile

Memory configuration lives in the agent profile. You set the short-term capacity, the long-term backend, and the session policy.

memory:
  shortTerm:
    maxTurns: 10
    maxTokens: 4000
  longTerm:
    store: vector
    embeddingModel: text-embedding-3-small
    maxEntries: 500
    ttlDays: 90
  session:
    timeoutMinutes: 30
    pruneOnEnd: true

Here short-term is limited to 10 turns or 4000 tokens — whichever comes first. Long-term uses a vector store with a 90-day lifetime. The session will be pruned automatically after a 30-minute timeout.

#Storing and Retrieving Memory

Long-term memory is stored as text chunks with embeddings. When needed, retrieval is semantic: Hermes searches for the chunks most relevant to the user's question, not just a word match.

import { hermes } from "@hermes/agent";
 
await hermes.memory.save({
  type: "fact",
  key: "user.order.preference",
  content: "Arman lebih suka tracking lewat WhatsApp",
  sessionId: "ses_order-check",
});
 
const results = await hermes.memory.search(
  "cara user ingin tracking order",
  { limit: 3 }
);

hermes.memory.save stores an entry of type fact, while hermes.memory.search retrieves the most semantically relevant entries. This pattern is the foundation of personalization: the agent remembers user preferences across sessions without being asked again.

#Prune and Summary Strategies

Memory that grows without limit causes two problems: token costs balloon and retrieval gets slow. That is why pruning is a routine policy, not an incident. Some common strategies:

• Sliding window — only the last N turns enter the context; the old ones are dropped.
• Summary — old turns are condensed into a short summary so context stays intact.
• TTL and quotas — entries expire automatically via ttlDays; old entries are overwritten when maxEntries is reached.
• Relevance — retrieval only returns chunks above a similarity score threshold; the rest stay in the store.

An example of pruning with summarization, run when the context starts to fill up:

import { hermes } from "@hermes/agent";
 
const summary = await hermes.memory.summarize(
  "ses_order-check",
  { targetTokens: 500 }
);
 
await hermes.memory.prune("ses_order-check", {
  keepLast: 3,
  replaceOldestWith: summary,
});

hermes.memory.summarize condenses a long conversation into a 500-token summary, and then hermes.memory.prune drops the old turns and replaces them with the summary. The result: context stays intact, tokens stay under control.

#Token & State Size Limits

All the strategies above work under one governing rule: budget. Every provider has a context window limit; Hermes manages the entire context contents so it never exceeds it.

The key is proportion. From the total context window, allocate space for the system prompt, history summary, tool definitions, retrieval results, and the model's output space. If the total exceeds the limit, the kernel trims from the least important parts — usually the oldest history.

hermes memory stats --session ses_order-check

This command shows input_tokens, output_tokens, the turn count, and the session state size. Make this routine: if the session state balloons, it is a sign that pruning or a fresh session is needed.

#Conclusion

Memory in Hermes is composed of three layers: short-term for immediate context, long-term for cross-session knowledge, and session state for temporary data. You can now define it in the profile, store and retrieve entries semantically, prune with summaries, and keep the token budget under control.

Key takeaways:

• Short-term memory lives in the context window; long-term memory persists in a persistent store.
• Semantic retrieval uses embeddings, not mere word matching.
• Pruning is a routine policy: sliding window, summarization, TTL, and quotas.
• Every session has a token budget; the kernel trims the least important parts.
• hermes memory stats monitors the health of memory and session state.

In episode 9 we continue to Multi-turn Conversation & Context Handling — managing conversation state across turns, context retrieval and prompt window management, and handling topic switches and conversation resets. See you there!