Sessions, context files and rollback
What the agent "knows" comes from four different sources, and it pays not to mix them up:
- The session — the current conversation; written to disk when it ends and searchable afterwards
- Context files — rules auto-discovered in the project (
AGENTS.md,.hermes.md,SOUL.mdand others) - Context references — a file, folder, diff or URL you pull into a message by hand with
@ - Memory — the short list of facts that survives between sessions (the next topic)
The first three belong to this topic.
| Source | When it loads | Token cost | Typical use |
|---|---|---|---|
| Session history | In full, every turn | High and growing | The flow of the current task |
| Context files | Automatically at session start | Fixed, on every request | Project rules, style, team conventions |
| `@` references | Only when you write them | One-off | "Look at this file", "read this diff" |
| Session search | Via a tool call | Very low (a database query) | "How did we solve this last week?" |
Checkpoints and rollback. The agent snapshots the working directory before changing files. So if a bad patch or a sweeping refactor wrecks something, it can be undone. This is the most important safety net for running an agent in a repo — but it does not replace git; keep committing.
Context files are powerful but double-edged: they carry project rules to the agent automatically, and they also mean outside content enters the system prompt. That is why these files are scanned for prompt injection — a subject we return to in the Security stage.
The practical rule: a recurring rule → a context file; one-off material → an `@` reference; a past decision → session search. The most common mistake is to pile everything into a context file — that file is paid for on every request and, as it grows, it also breaks the cache.
Practice. In a project create AGENTS.md with three rules (for example: "run tests with npm test", "commit messages are imperative", "never touch dist/"). Then open a session and check the agent follows them. Done means: you can confirm in hermes prompt-size that the file shows up in the prompt.
📚 Sources and documentation
- Context filesofficialhermes-agent.nousresearch.com
Which filenames are auto-discovered and how they are merged.
- Context references (@ syntax)officialhermes-agent.nousresearch.com
- Checkpoints and rollbackofficialhermes-agent.nousresearch.com
- Sessionsofficialhermes-agent.nousresearch.com