Give Hermes Agent a Long-Term Memory on Upstash Redis

We built upstash-hermes-memory, a Hermes memory provider that stores your agent’s memories and chat history in Upstash Redis. It is now in the Hermes plugin catalog so you can install it with a simple command.

Hermes Agent keeps memories in two small Markdown files: MEMORY.md for the agent's notes and USER.md for your profile. Together, they hold about 3,500 characters. This works great for simple preferences like "prefers short answers" or "the API is located in ~/code/myapi", but is too short to store everything about months of projects, people, and decisions.

Why you would want it

There are several benefits of enabling it:

• Built-in memory files have a size limit. An error is returned from the memory tool if the files are full. The agent has to delete or merge entries to make space. This doesn't happen with the memory stored in Redis; only the 3 most related memories are included in the prompt when those are being recalled.
• Built-in memories are only loaded at the beginning of a session. With Upstash Redis as the memory provider, Hermes searches your memories in Redis on each incoming message, meaning that if you have a long chat on Telegram or Discord, Hermes gets memories related to the latest message.
• Each session is stored as a transcript in Redis. The agent can search those transcripts using a tool if you ask questions like "what did we decide about the deploy last week?".
• Built-in memory is per profile. You can configure multiple Hermes profiles (or even run Hermes on multiple machines) with the same database and user id to have them share the same memory.
• Memories and chats are stored in a single Redis Search index. This lets the Upstash integration run on the Upstash Free plan (which allows one index per database).

What's cool about this integration is that Hermes will use both its built-in memory storage and the external provider you configure, so it's a net benefit to turn this on.

How it works

Hermes calls its memory provider at fixed points in every turn. Before each turn, Hermes searches your memories in Upstash Redis with your message and adds the top 3 to the prompt. After the turn, it saves the new messages to the session's transcript. Here is one turn:

Around that loop:

• Memory isolation: Subagents, cron jobs and context flushes can read memories, but your main agent is the only one who writes. No background job cluttering up your agent's memory.
• Single-turn persistence: After each turn, we append any new messages to the session's chat transcript in Redis. This is one small write the size of that turn, which means weeks-long chats have the exact same overhead as brand-new ones.
• Synced built-in memory: Whenever Hermes's built-in memory tool decides to persist a fact, the Upstash integration saves a copy to Redis. When Hermes later corrects or removes it, we update the Redis copy too, so it won't sneak back in.
• Model tools: The Upstash integration gives the model four tools during any turn: upstash_memory_save, upstash_memory_search, upstash_memory_forget, upstash_chat_search.
• Search: Memory recall uses hybrid search on Upstash Redis Search, which combines fuzzy full-text matching with search by meaning. A question like "where is the assistant hosted" can find "Hermes runs on the ops Box" even though the two share no words. Redis Search creates the embeddings itself, so you don't need an embeddings model or separate vector database. Chat search uses fuzzy full-text matching. All you need is a single Redis database.

Set it up

First, create a Redis database on Upstash console and get its REST URL and token.

Then install the plugin and pick it as the memory provider:

hermes plugins install upstash
hermes memory setup

hermes memory setup asks for the URL and token and writes them to ~/.hermes/.env. If you prefer to do it by hand, install the package into the Python environment Hermes runs in with pip install upstash-hermes-memory, then set the provider in ~/.hermes/config.yaml:

memory:
  provider: upstash

These are the settings it reads:

To check it, tell your agent something about yourself, start a new session with /new, and ask about it. You can also open the Data Browser in the Upstash console and see the memories under agentkit:memory:.

Share memory with your other apps

The Upstash integration writes the same keys and documents as AgentMemory and ChatHistory in @upstash/agentkit-sdk. A fact your Hermes agent saves can be recalled by a TypeScript agent built with the Vercel AI SDK on the same database, and the other way round. Using both on one database needs a plan with more than one search index, since the TypeScript side creates its own memory index.

The Python classes work outside Hermes too, so you can import AgentMemory from upstash_hermes_memory in any Python app.

The code is open source in the AgentKit repo. If you try it, we'd love to hear how your agent's memory holds up.