Teach Hermes Agent a task once: memory, skills and /learn

This is for people who keep giving their agent the same corrections: "use our template", "skip vendor blogs", "prices in EUR". After this guide, Hermes Agent stores those corrections in places it reads in every later session, turns a task you walked it through into a skill it can reuse (also from a scheduled job), and you can review what it saves before it sticks.

It all works from the dashboard and the chat. Details are from Hermes Agent v0.22.7 and its memory and skills docs.

How Hermes remembers

There are three stores, and knowing which one holds what explains most surprises.

Memory (MEMORY.md and USER.md). Two small text files. MEMORY.md holds the agent's notes about your environment and conventions (2,200 characters, roughly 800 tokens). USER.md holds your profile and preferences (1,375 characters, roughly 500 tokens). Both are inserted into the system prompt at the start of a session and stay frozen for that session. The agent edits them with its memory tool (add, patch, remove). There is no auto-compaction: when a write would overflow, the tool returns an error and the agent has to merge or drop entries first.

Session search. Every conversation is stored in a SQLite database with full-text search. The agent can look up "what did we decide about X last week" with its session_search tool. This costs no LLM calls and has no size limit, but the agent only looks when it thinks it should.

Skills. Markdown procedures (SKILL.md plus optional reference files) in the skills folder. Only a short index (name and description) is in the prompt; the full text loads when the agent decides a skill is relevant, or when you call it as /skill-name. The agent writes and patches these itself with the skill_manage tool, typically after a multi-step task, after it hit errors and found the working path, or after you corrected its approach.

A background review ties these together. After turns, Hermes forks a short review of the conversation that can save memory entries or patch skills. The default trigger is every 10 turns for memory (memory.nudge_interval: 10). By default you see a short "Memory updated" or "Skill 'x' patched" line in chat when it does.

Step 1: Give it facts it should always have

Facts that matter in every session belong in memory. Be explicit, because a sentence like "I'll remember that" is just text unless the model actually calls the tool:

Use the memory tool to save these to the user profile:
- I work in Europe/Berlin time and write in British English.
- Reports for me: bullet points, no more than 200 words, sources as links.
- Currency in EUR. Round to whole euros.

Start a new session (/new in Telegram or the Chat tab) and ask "What do you know about my report preferences?" The answer should come from the new snapshot. If it doesn't, the save didn't happen; see "What goes wrong" below.

Keep memory for small, durable facts. A procedure with steps is a skill, not a memory entry.

Step 2: Walk it through the task once

Do the task in a normal chat and correct it until the output is what you want. For example, a weekly competitor summary:

Check the pricing pages and changelogs of these three products:
https://example-a.com/pricing, https://example-b.com/pricing,
https://example-c.com/changelog
Summarize what changed this week.

Then correct it the way you would a colleague:

Don't include the blog posts, only the changelog entries.
Put the table first: product | change | date | link. Then two lines of commentary.
Example-B hides prices behind a "monthly/annual" toggle. Always report monthly.

Corrections like the last one, a quirk of a specific site, are the most valuable thing a skill can carry. They're exactly what you'd otherwise repeat every week.

Step 3: Turn it into a skill with /learn

The background review may save a skill on its own. Don't rely on that for something you care about; ask:

/learn how we just built the weekly competitor summary, including the
Example-B monthly-price rule and the table format

/learn builds a prompt that follows Hermes's skill-writing standards and hands it to the agent as a normal turn. The agent writes the skill with skill_manage. It works the same in Telegram, the dashboard Chat tab, and the TUI. The dashboard's Skills page also has a Learn a skill button with fields for a directory, a URL, and free text; it composes the same /learn request.

/learn takes other sources too:

/learn https://docs.example.com/api/quickstart
/learn filing an expense: open the portal, New > Expense, attach the receipt, submit

A good skill reads like a checklist: when to use it, the procedure in order, pitfalls with a one-line reason each, how to verify the result. Hermes's linter warns when a skill turns into an incident log (dates, issue numbers, quoted chat) or a SKILL.md grows past about 24,000 characters.

Check it on the Skills page: search for the name, open it, read the procedure. If something is wrong, tell the agent ("patch the competitor-summary skill: the table needs a 'source' column") rather than starting over. Targeted patches cost fewer tokens than full rewrites.

Step 4: Use it

Every installed skill is a slash command:

/weekly-competitor-summary

Or attach it to a scheduled job. On the Cron page, create a job, choose the skill under Skills (optional), and keep the prompt short, since the skill carries the how:

Run the weekly competitor summary for this week.

A skill named by any cron job is protected from the curator's automatic archiving (more on that below), even when the job is paused.

Step 5: Decide how much you want to review

The default is that the agent writes memory and skills freely, including from the background review. That's convenient until it saves a wrong assumption about you. There are two gates. Set them in Config (search write_approval) or in YAML mode:

memory:
  write_approval: true
skills:
  write_approval: true

Or turn them on from chat with /memory approval on and /skills approval on. Use the dashboard Chat tab for the /skills one: in Telegram, /skills only becomes available once the skills gate is on.

With the gates on, writes outside the interactive terminal are staged. Review them in chat:

/memory pending
/memory approve all
/skills pending
/skills diff <id>
/skills approve <id>
/skills reject <id>

/skills diff output is cut short in chat bubbles; read long diffs in the dashboard Chat tab.

To see what changed without approving every write, keep the gates off and make notifications more detailed:

display:
  memory_notifications: verbose   # off | on (default) | verbose

With verbose, the chat line includes a short preview of the new memory entry or the skill diff.

Step 6: Keep the skill library from rotting

Agent-written skills pile up. Hermes runs a curator for agent-created skills only, never for bundled or hub-installed ones. Its defaults:

curator:
  enabled: true
  interval_hours: 168        # at most once a week
  min_idle_hours: 2
  stale_after_days: 14
  archive_after_days: 30
  consolidate: false

A skill unused for 14 days is marked stale; at 30 days it moves to an archive folder. Nothing is deleted, and archived skills can be restored. The LLM pass that merges overlapping skills is off unless you set consolidate: true. The first curator run is deferred by a full interval after install, so you get a week to look before it touches anything.

To keep a skill you use rarely (a quarterly report, say), pin it:

/curator pin quarterly-board-report

Pinned skills are skipped by the curator, and the agent can't delete them (it can still patch them). The System page shows curator status with pause, resume, and run-now controls.

Costs

Memory costs about 1,300 tokens on every request: the two files at full size are injected into every system prompt. Session search is free. A skill costs nothing until it is loaded; the index line per skill is small but adds up with hundreds of skills.

The background review is the cost people miss. By default it runs on your main model and replays the conversation, which is mostly prompt-cache reads. If your main model is expensive, route the review to a cheaper one. This setting isn't in the Models page slots in v0.22.7; set it in Config (YAML mode):

auxiliary:
  background_review:
    provider: openrouter
    model: anthropic/claude-haiku-5.5
    max_input_tokens: 48000

On a different model the review replays a compact digest instead of the full transcript; Hermes's docs report this as 3 to 5 times cheaper. max_input_tokens caps the total input a single review may replay.

Some numbers, at list prices as of November 2026 (Claude pricing): a review that replays 48,000 input tokens and writes 1,000 output tokens costs 0.048 × $2 + 0.001 × $10 = $0.106 on Claude Sonnet 5.5 without caching, and 0.048 × $0.10 + 0.001 × $0.50 = $0.0053 on Claude Haiku 5.5. At 10 reviews a day that's about $32 versus $1.60 a month, as an upper bound. Use Analytics to see your real numbers. Each finished review also writes a "Background review complete" line with its call count and input/output tokens to the agent log, which you can read on the Logs page.

To stop automatic reviews entirely while keeping manual ones (/refine):

auxiliary:
  background_review:
    enabled: false

What goes wrong

"I told it to remember, and the next session it forgot." Hermes's own docs list the causes in order: the model said it saved but never called the tool (common with small models, roughly under 30B parameters, and weak tool-callers); the write was staged because write_approval is on; you're on a different profile; memory is disabled; or you're still in the session where it was saved, which uses the old snapshot. Ask the agent to print the current contents of its memory files to check. If saves keep failing, use a stronger model while you set things up. Once the entries exist, a smaller model reads them fine.

Telegram never seems to learn. A Telegram chat is one continuous session that survives restarts. It can run for weeks, so the memory snapshot never refreshes and compaction keeps re-summarizing a growing history. Send /new at natural breaks: a finished task, a new topic, a new day.

Memory is full. The tool returns an error with the current entries and how many characters to free; the agent should merge entries in one batch. If it keeps happening, move procedures out of memory into skills.

A skill disappeared. Check the curator: it archives agent-created skills after 30 days without use. Restore it with /curator restore <name> and pin it if it's seasonal. There are open issues where the curator archives skills that are only used indirectly, for example by script-only cron jobs that never record skill usage (#136030). Pin anything those jobs depend on.

The agent "improved" a skill in a way you didn't want. Turn on skills.write_approval, or ask it to undo the change with a targeted patch. The curator keeps snapshots of the skills folder before its runs.

It learned something wrong about you. Ask it to remove the entry ("remove the memory entry about EUR"), or reset the stores from System → Memory. Then turn on memory.write_approval if the background review keeps re-adding it.

On ranx.cloud there are no backups, and memory, skills, and session history live only on the instance's disk. Before deleting an instance or making big changes, use System → Operations → create a backup, then download the archive when the page says it's ready.