Teach it to remember you

Most chatbots forget you the moment you close the tab. Hermes doesn't — but the way it remembers is unusual, and worth understanding before you start relying on it.

Three places things get stored

Hermes keeps three distinct things on your disk. Each has a different purpose.

MEMORY.md is the agent's notebook about your environment. Things like "the user's main project lives at ~/code/frontend" or "uses pnpm, not npm" or "prefers TypeScript over JavaScript." Stuff Hermes learns while working with you that it wants to remember next time. Hard capped at 2,200 characters by default — deliberately small. Memory is meant to be lean.

USER.md is a short profile of you. Your name, your role, how you like to be addressed, your communication style, recurring preferences. Capped at 1,375 characters. Even smaller than MEMORY.md, because it's meant to be stable signal about you, not a history of everything you've ever said.

Session history is everything else. Every conversation you have gets saved to a local SQLite database at ~/.hermes/state.db. You can search it, resume old sessions, or browse them later with hermes sessions list. No character limit — it's the full record.

The two Markdown files get injected into every conversation. The session database doesn't — it's archival, there when you want to look things up.

How it "remembers" the right thing

You might worry: as conversations pile up, does Hermes get slower? It doesn't.

Hermes doesn't stuff your entire history into the context window. It uses SQLite's FTS5 full-text search engine to retrieve memories on demand — ask a database question and it searches for database-related memories; ask a frontend question and it pulls up frontend-related ones. Only the relevant fragments get loaded, not everything.

This means three months of use feels about as fast as three days. The memory database grows, but retrieval stays precise and local. It's also why a local SQLite file is all you need — no cloud vector database, no extra infrastructure.

Where to find them

ls ~/.hermes/memories/
cat ~/.hermes/memories/MEMORY.md
cat ~/.hermes/memories/USER.md

The files might be empty or not exist yet, depending on how much you've used Hermes. That's fine.

How things get written

You don't usually edit these files by hand. Hermes writes to them automatically when it decides something is worth remembering. There's an internal tool the agent can call to add, replace, or remove entries. The idea is: you work with Hermes, it notices patterns, it updates its own notes, and next time it already knows.

You can still edit the files directly if you want to — they're just Markdown. But try working with Hermes first and see what it chooses to remember. You might be surprised.

Try it out

Start a new session and tell Hermes a few things about yourself:

My main project lives at ~/code/my-app. It's a Next.js app with pnpm. I prefer concise answers. When I say "fix this" I usually want you to show me the diff first before touching the file.

Then ask it to save that:

Remember those preferences for next time.

Quit, start a new session, and ask:

Where does my main project live, and what package manager do I use?

If memory is working, it'll tell you without needing to be reminded.

Checkpoint — After the second session, cat ~/.hermes/memories/MEMORY.md. You should see entries reflecting the things you told it.

Browsing past sessions

hermes sessions list

This prints your session history. You can resume any of them with hermes --resume <session_id>, or just get back to the most recent one with hermes --continue.

A word on keeping memory tidy

Because MEMORY.md is small on purpose, it gets noisy over time. Old, irrelevant entries will hang around. Every few weeks, it's worth opening the file and deleting stuff that no longer applies. Hermes will thank you in the form of cleaner responses.

You can also tell Hermes directly: "Forget my preferences about the old project." It'll update the file for you.

What memory is not

Memory isn't a knowledge base. It isn't a place to store your documentation. It isn't a substitute for context files (we haven't covered those, but they're a different system). Memory is deliberately tiny because its job is to keep a small amount of high-signal context about you that should be in every conversation. If you need Hermes to know a whole codebase, you feed it the codebase in the session — you don't shove it into memory.

Next: hook Hermes up to Telegram so you can talk to it from your phone.