.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Hermes Agent's built-in memory works fine for most setups. SOUL.md, USER.md, MEMORY.md and state.db cover persona, user facts, learned memory and session history. Four files and a database. Greppable. Version-controllable. For people who want more (semantic retrieval, shared memory across multiple agents, vector search at scale), Hermes can plug in external memory providers.
This article covers when external memory is worth the setup and how to configure two common options: Honcho (hosted) and self-hosted Postgres with pgvector.
What "external memory" means in Hermes
Hermes delegates part of its memory layer to a separate service. The service decides what to remember, what to forget, what to surface back to the agent each turn. Local files (SOUL.md, USER.md) stay as persona and base context. External memory adds richer retrieval-augmented context on top.
Three common patterns:
- Honcho: hosted memory service with per-user contexts and session retrieval
- Mem: similar hosted approach, different API surface
- Self-hosted SQLite or Postgres with vector extension where you control everything
When external memory is worth the setup
The built-in MEMORY.md grows monotonically. The agent adds facts. The model reads them all on every prompt. That works up to a few hundred KB. Beyond that, the context window fills with old facts and you're paying tokens to reload history the agent rarely needs.
External memory does semantic retrieval. Instead of loading the whole file, the layer looks at your prompt, picks the most relevant facts, sends only those into context. Token cost stays low. Memory size can scale to gigabytes without affecting per-prompt latency.
My rule of thumb
- MEMORY.md under 200 KB: built-in memory is fine, don't bother with external
- MEMORY.md over 200 KB and still growing: external pays for itself
- Multiple agents sharing memory: external is the only practical answer
Most people don't need it. If you do, here's how to set it up"
Option 1: Honcho setup
Honcho is the most commonly recommended hosted external memory layer for Hermes. Free tier available. Straightforward integration.
Configuration steps
hermes memory provider list
hermes memory provider add honcho --api-key "your-honcho-key"
hermes memory provider set-default honcho
hermes memory provider showGet the API key from your Honcho account at honcho.dev.
What changes after enabling?
The agent routes memory writes through Honcho automatically. Reads happen on every prompt: Hermes asks Honcho for relevant memory, gets a curated set back, includes only those facts in context.
First thing I noticed after enabling Honcho: the agent stopped repeating itself across sessions. Before, MEMORY.md was getting cluttered with near-duplicates. Honcho deduplicates as it stores. Smaller surface area, less noise.
Option 2: Self-hosted Postgres with pgvector
If you don't want a hosted dependency, self-host with Postgres and pgvector.
Install dependencies
sudo apt install postgresql-16 postgresql-16-pgvectorCreate the database
sudo -u postgres psql -c "CREATE DATABASE hermes_memory;"
sudo -u postgres psql -d hermes_memory -c "CREATE EXTENSION vector;"
sudo -u postgres psql -d hermes_memory -c "CREATE USER hermes WITH PASSWORD 'change-me';"
sudo -u postgres psql -d hermes_memory -c "GRANT ALL ON DATABASE hermes_memory TO hermes;"Configure Hermes to use it
hermes memory provider add local-pgvector \
--connection "postgres://hermes:change-me@localhost:5432/hermes_memory"
hermes memory provider set-default local-pgvectorWhat you trade off..
No external service dependency. You own the data. You also own the backups: hermes_memory database is now critical state, treat it like state.db in our Hermes backups guide.
RAM requirements go up. Postgres plus vector embeddings on the same box as the agent. 2GB tier I usually recommend isn't enough; 4GB minimum for self-hosted external memory.
Per-profile memory spaces
The genuine win of external memory: separate context spaces per profile sharing a backing store.
Built-in MEMORY.md gives you one file per persona. Switching personas swaps the file. Each persona starts cold the first time you switch.
External memory keeps separate context spaces per profile. Agent under Work persona writes to one space. Under Personal persona, a different space. Optionally read-only access from one to the other.
Configure separate spaces
hermes memory space create work
hermes memory space create personal
hermes persona set work --memory-space work
hermes persona set personal --memory-space personalSame backing store, completely isolated contexts. Agent under Work has no view of what Personal remembers.
Inspecting what the agent has stored
One trick: just ask the agent. "Read me your memory file" or "summarise what you know about me". The agent dumps current memory back in human-readable form. Useful debugging tool when the agent does something I didn't expect.
Remove a wrong fact
hermes memory list | grep -i "wrong fact"
hermes memory remove <memory-id>For hosted Honcho, use its dashboard. For self-hosted pgvector, plain SQL through psql.
Skills don't go in external memory
Skills are how-to procedures the agent generates. They live in ~/.hermes/skills/ and don't go through the memory provider. Skills need to be loaded explicitly by name or by tool invocation, not surfaced by semantic similarity.
Editing skills is a different flow, covered in our edit Hermes skills without breaking the loop tutorial.
Diagnosing when agent stops remembering
If the agent suddenly forgets something you told it last week, isolate which layer dropped it:
hermes memory provider status
hermes memory query "what did Andrei say about his work address"Interpret the results
- Query returns the fact: memory has it. The agent's prompt construction isn't surfacing it (often a SOUL.md or AGENTS.md instruction telling the agent not to reference certain things).
- Query returns nothing: memory never stored it or has since dropped it.
Backup story changes with external memory
Now you have state in three places:
- Local files (SOUL.md, USER.md, AGENTS.md per project, skills)
- Local state.db
- External memory provider's data
If you were only backing up ~/.hermes, that's not enough. External provider needs its own backup. For Honcho: API export endpoint. For self-hosted pgvector: regular pg_dump on a schedule.
Add the new step to whatever cron is running your existing backups. Our Hermes backups guide covers the script patterns.
When the built-in memory is enough
Most users. Honestly. Don't add complexity you don't need just because external memory sounds cool. The built-in markdown approach is debuggable in ways that vector stores aren't.
If you're using Hermes for an hour a day, you definitely don't need this. If your agent has been running 24/7 for months with multiple concurrent users, external memory starts to make sense.
Hosting on LumaDock
If you go self-hosted (pgvector), 4GB minimum tier on LumaDock fits Hermes plus Postgres plus pgvector without contention. Unmetered bandwidth and no setup fees. If you go with Honcho, smaller VPS is fine. Either way the agent itself runs the same. Full setup in our Hermes Agent complete guide.
