The Agent That Writes Its Own Manual

Every developer has had the same conversation with an AI assistant. You explain how your project is organized. It fixes the thing. Then, next week, you explain it all over again, because the model has no idea it ever helped you.

Most agents are built that way on purpose. Throw the context away between sessions, and you avoid the mess that comes from models remembering too much. But Nous Research's Hermes Agent is trying the opposite bet: give an agent a real memory, and let it learn on the job.

The result is a small, self-contained machine for turning experience into reusable knowledge. Here's how it works.

Four kinds of memory, in four places

Hermes doesn't jam everything it knows into one long context window. It splits memory into four layers, each with its own trigger and job:

• Facts about you live in two small Markdown files. USER.md holds your preferences and communication style — capped at 1,375 characters, around 500 tokens. MEMORY.md holds the agent's own notes about your environment and conventions, at 2,200 characters. Both live in ~/.hermes/memories/ and are injected into the prompt as a frozen snapshot at the start of every session.
• What happened lives in a searchable history. Every session is logged to a SQLite database (~/.hermes/state.db) with FTS5 full-text search. When the agent needs to recall something from weeks ago, it queries its own past messages — no summarization, no truncation.
• How to do things lives in skills.
• Who you are, over time lives in a user-modeling layer.

Splitting memory this way keeps the context window small, which keeps responses fast and grounded.

The part that's genuinely new: skills

Skills are Markdown files stored under ~/.hermes/skills/, in the agentskills.io open format. Each one holds a name, a description, and the concrete steps and tool calls that worked last time. The clever part is how they get written.

When a session ends, a background review agent inspects what happened. If the work crossed a bar — a task more than a few tool calls, a fix for an error, an explicit correction from you — it writes or patches a skill on its own, with no human approval. The next time a similar task appears, the skill is loaded and the agent jumps straight to the answer it already worked out.

Progressive disclosure keeps this cheap. Only skill names and one-line summaries sit in the system prompt; the full file loads on demand. So you can accumulate hundreds of skills without re-reading all of them every turn.

What this means in practice

It adds up to a genuine learning loop. The agent doesn't just execute a task — it extracts the lesson, keeps it around, and applies it later. Details like "this database uses a custom port" or "the build fails unless you set this flag" get captured once, instead of rediscovered every session.

It's not perfect. Memory is bounded and curated, and a misremembered skill can steer a session wrong. But the direction is meaningful: the fix for the "explain it again" problem isn't a longer context window. It's an agent that writes down what it learned, and remembers to read it.

The full source is MIT-licensed on GitHub, and the docs walk through the architecture. It's worth a look if you're tired of repeating yourself to a machine with amnesia.