Memory & context

Built-in memory is two small files in ~/.hermes/memories/: MEMORY.md for the agent's own notes about your environment and lessons learned, and USER.md for your preferences and communication style. The agent edits them with its memory tool. Every session also lands in a searchable history the agent can look back through.

Both files are loaded into the system prompt as a frozen snapshot when a session starts, so something saved mid-session shows up in the next session, not the current one. Starting a new session at natural breaks (a finished task, a new topic) is what lets memory pay off.

Memory belongs to a profile, not to an app. The CLI, Desktop and your messaging chats on the same profile share the same memory and session history; a different profile (or Bot Mode bot) has its own.

Yes, built-in memory is deliberately small. MEMORY.md is capped at 2,200 characters (about 800 tokens) and USER.md at 1,375 characters (about 500 tokens). The limits are memory.memory_char_limit and memory.user_char_limit in config.yaml.

Memory doesn't silently drop old entries when full. The write fails and the agent has to consolidate or remove entries to make room. For longer history, it relies on session search.

The memory files are plain text, so you can open and edit them directly: ~/.hermes/memories/MEMORY.md and USER.md (inside the profile's folder for other profiles). You can also ask the agent to add, patch or remove an entry, or use /journey (Desktop's Star Map) to browse, edit or delete learned memories and skills.

Deleting an entry removes it from what is loaded into future sessions, but not from everywhere. Past conversations stay in the session history the agent can search (hermes sessions delete or hermes sessions prune removes them), and an external memory provider may hold its own copy, so check it there too.

To stop memory entirely, set memory.memory_enabled and memory.user_profile_enabled to false in config.yaml. To review writes before they land, set memory.write_approval: true and use /memory pending, /memory approve and /memory reject.

First check the file. Memory only saves when the model actually calls the memory tool, and weaker or small local models sometimes say "saved" without doing it. Other common causes: writes are staged because write_approval is on, you're on a different profile, memory is disabled, or the session that needs it started before the save.

Start a fresh session with /new after saving so the updated snapshot loads.

Yes. External memory providers run alongside the built-in files, never replacing them. RetainDB and ByteRover ship with Hermes; Honcho, Hindsight, Supermemory, Mem0, OpenViking and Holographic install from the plugin catalog with hermes plugins install <name>.

Run hermes memory setup to choose and configure one, hermes memory status to check what's active, and hermes memory off to disable it.

Yes. Every CLI and messaging session is stored in a SQLite database at ~/.hermes/state.db with full-text search, and the agent has a session_search tool to find and scroll through past conversations. Searching costs no extra LLM calls.

You can browse sessions yourself with hermes sessions list, and filter it with options such as --source telegram.

Use hermes --continue (or -c) to resume the most recent CLI session; in each terminal it prefers that terminal's own last session. Use hermes --resume <id or title> for a specific one, or --resume latest.

Session IDs are shown when you exit and in hermes sessions list. Inside a session, /resume <title> works too.

Context files are project instructions Hermes loads automatically. It looks for .hermes.md or HERMES.md, AGENTS.override.md, AGENTS.md, CLAUDE.md and .cursorrules, and loads only the first type it finds. Inside a git repo, AGENTS.md files from the repo root down to your working directory are combined.

SOUL.md is separate. It sets the agent's global personality and lives in your Hermes home folder.

SOUL.md in your Hermes home is who the agent is (tone, style, personality, standing instructions), and you edit it yourself. USER.md (who you are) and MEMORY.md (what the agent has learned) live in ~/.hermes/memories/ and are maintained by the agent through its memory tool. AGENTS.md or .hermes.md in a project holds that project's rules.

Keep each one short and on topic. The memory files are capped (about 2,200 characters for MEMORY.md and 1,375 for USER.md), so they suit durable facts, not long procedures; put step-by-step workflows in a skill, which only loads when needed. Project details belong in that project's AGENTS.md, not in SOUL.md.

A common mix-up: facts about yourself written into SOUL.md never feed USER.md. To have them remembered, just tell the agent. For a temporary change of tone, use /personality instead of editing files, and start a new session after editing SOUL.md so it loads cleanly.

Long conversations fill the model's context window, so Hermes compresses older history automatically, by default at 50% of the context limit (compression.threshold). Run /context (or click the context meter in Desktop) to see what is filling the window: system prompt, tool schemas, skills, MCP, memory and the conversation itself. /context all adds per-skill and per-toolset costs.

The warning “Context is over the compression threshold … but compression is currently blocked” means Hermes wanted to compress but couldn't at that moment, so the session will keep growing until the provider refuses it. Do what it says: /compress to retry now, or /new to start fresh. Memory and the session history stay searchable after a reset.

To prevent it, start a new session when you switch tasks, use /compress here to keep the latest exchanges verbatim, and trim MCP servers or toolsets that take a big share. If limits hit surprisingly early, check the context length Hermes detected at startup.

Use an @ reference. @file:path/to/file.py injects a file (append :10-25 for a line range), @folder: a directory listing, @diff and @staged your git changes, @git:5 the last five commits with patches, and @url: a fetched web page. In the interactive CLI, typing @ offers tab completion.

References are capped to protect the context window: a warning at 25% of the context length and a refusal at 50%. Sensitive paths are always blocked from @file: to avoid exposing credentials.

No, not by default. Each profile has its own memory, sessions and skills, and the docs warn against running two agents on one profile or Hermes home: both write memory automatically and load each other's writes at session start, so the stored state degrades with every session. There's no conflict resolution between profiles because they never write to the same store.

Run one agent per profile. For genuinely shared memory, connect the profiles to one external memory provider. Honcho, for example, keeps one shared user across all profiles in a workspace while each profile keeps its own view. To seed a new profile with existing memories and sessions, hermes profile create accepts --clone-all.

Start with built-in memory. It's always on, costs nothing extra, and together with session search covers most personal use. An external provider is additive: it runs alongside MEMORY.md and USER.md, never replacing them, and only one can be active at a time.

Add one when you want richer recall across many sessions or memory shared between profiles. The docs cover Honcho, Hindsight, Supermemory, Mem0, OpenViking and Holographic (from the plugin catalog) plus bundled RetainDB and ByteRover, with a comparison table. Run hermes memory setup to pick and configure one, hermes memory status to check it, and hermes memory off to go back.

For a knowledge base you can read and edit yourself, an Obsidian vault works well alongside memory: the bundled Obsidian skill lets the agent read, search and write notes there. Keep durable facts in memory and long notes in the vault.

Start a new one (/new) whenever you switch tasks or topics. Shorter sessions are cheaper and faster, and a fresh session is when updated memory loads. Nothing useful is lost: past sessions stay searchable by the agent. Continue a session (hermes --continue, /resume) when you're picking up the same piece of work.

Messaging chats are one long-running session that survives restarts, so on Telegram or Discord the reset is up to you; send /new at natural breaks. In a Bot Mode bot's own chat, /new compacts the conversation instead of forking it.

To tidy up, hermes sessions prune deletes sessions by filters such as --older-than 30d or --source telegram (default: older than 90 days; try --dry-run first), hermes sessions archive hides matching sessions without deleting, and hermes sessions optimize reclaims disk space.

Not through Hermes' built-in memory files, which belong to one profile. The route is a memory service that both agents connect to. Hermes supports several external memory providers, including Honcho, Supermemory and Hindsight; if the other agent has an integration for the same service, point both at the same account or workspace.

The Nous team has said on X that Honcho, Supermemory and Hindsight each offer a Claude Code plugin as well as a Hermes provider. Check each service's own docs for the current integrations.

A simpler shared store is a folder of notes both agents can read, such as an Obsidian vault, or project rules in AGENTS.md, which Hermes and many coding agents read automatically.