Hermes Agent Deep Cuts: The Task List Is Rewritten, Not Remembered
Part of the Hermes Agent: Deep Cuts series

Hermes Agent Deep Cuts: The Task List Is Rewritten, Not Remembered

10 min read 
$ python3 fold_probe2.py
== window ends with a real user turn ==
rows: 3 | tail role: user | synthetic flag: None
--- tail content ---
deploy the post to hermes-box

[Your active task list was preserved across context compression]
- [>] 2. tweet the announcement (in_progress)
- [ ] 1. verify the live URL returns 200 (pending)

My own last message grew a task list. I typed nine words at that agent, a compaction boundary came later, and the window now carries a block of text inside my user turn that I never wrote, with the third item of a three item plan missing from it. That is not corruption. It is what Hermes does so a plan can outlive the context that produced it, and the three boundaries behind it (the write, the compression fold, and the resume) each behave in a way the happy path never shows you.

The store behind that block is not a file and not memory. todo_list is the tool every long Hermes task uses without thinking about it, and what it really is, is a small in-memory object that gets rewritten into your context on a schedule you do not control.

The store is an object on the agent

tools/todo_tool.py is 284 lines and describes itself accurately: in-memory, revisioned, one store per AIAgent, re-injected after context compression, with every write bumping a monotonic revision so clients can reject stale UI updates.

An item is {id, content, status, parent?}. Status is one of pending, in_progress, completed, cancelled. parent points at another item’s id, which makes it a subtask, and the schema asks the model to keep exactly one item in_progress. Reads and writes use the same call. Passing todos writes, omitting it reads, and every call returns the whole list plus a revision and a status summary:

5) read-only call keys: ['revision', 'summary', 'todos'] | revision 2

Four caps matter:

caps: 256 items | 4000 chars/item | 512000 chars/hydration payload
injection header: '[Your active task list was preserved across context compression]'

The 4,000 character cap applies to a single item’s content and keeps the head, since the actionable part of a task description is at the front:

10) 5000-char content -> stored length 4000 | ends with 'x… [truncated]'

The tool is registered as an agent-loop tool, not a plain registry tool: model_tools._AGENT_LOOP_TOOLS holds todo_list, memory, session_search and delegate_task, all four intercepted in agent/tool_executor.py before dispatch, because they need per-session agent state that the registry does not have. That interception is the reason the store lives on the agent object and dies with it.

The write path replaces the whole list by default

This is the part that will bite you, and it fails silently. The merge parameter defaults to false, which means “replace the entire list with a fresh plan”:

1) write 4 items        -> revision 1 summary {'total': 4, 'pending': 2, 'in_progress': 1, 'completed': 1, 'cancelled': 0}
2) update item 2 only, merge default -> revision 2 total 1 ['2'] <- list was replaced
3) update item 2 only, merge=true    -> revision 2 total 4 ['1', '2', '3', '4']

Line 2 is the failure mode. A model or a client that wants to mark one step done and sends a one item array gets a store containing exactly that one item, a new revision, and no complaint. Every check that greps for “the tool returned a JSON list of todos” passes. You find out when the agent finishes the missing work again, or when the plan disappears from the injected snapshot at the next compaction.

merge: true fixes it, with a boundary worth knowing: merge only touches the fields you sent. Send an id with no status and nothing changes, not even the revision, because the store only bumps the revision when the resulting list actually differs:

4) merge a bare id (no status)       -> item 3 status ['pending'] revision 2 (unchanged, no revision bump)

There is no way to clear an item’s content through merge, only to replace it. If you are writing a client against this tool, keep the ids stable and always send the status you mean.

The reorder you did not author

List order is priority, and the store defends that on write by lifting the active step above earlier pending placeholders. Sub-nested lists keep their authored order, since moving a subtask away from its siblings would break the tree:

6) authored order a,b,c,d -> stored order ['c', 'a', 'b', 'd']

A plan written as gather, draft, verify, deploy comes back as verify, gather, draft, deploy. That is deliberate and it is the right call for an agent that reads its own list as the next thing to do, but it means the array you sent and the array you get are not the same array. Do not diff them and conclude the store mutated your data in some unexplained way.

What crosses a compaction boundary

format_for_injection() renders the list that goes back into the context after compression, and it filters hard. Only pending and in_progress items are injected, because a completed item that reappears makes the model redo work. A parent survives with its real status marker when any descendant is still active, so subtasks do not lose their context:

7) format_for_injection with mixed statuses:
[Your active task list was preserved across context compression]
- [>] 2. phase two: draft (in_progress)
  - [ ] 2.2. run the store probes (pending)

Note what is absent: the completed parent of that active subtask, two completed siblings, and a cancelled item. When the whole list is finished, the function returns None and nothing is injected at all:

8) all-completed store -> injection is None

The fold itself, _fold_todo_snapshot in agent/conversation_compression.py, does more than append. It strips any snapshot left over from an earlier boundary before writing the new one, so repeated compactions refresh the state instead of stacking copies. I ran it twice over one window:

case C, two folds over one window: 1 -> 1 rows
headers in the window: 1

It merges the snapshot into the trailing real user turn when there is one, and appends its own flagged row when the window ends on an assistant or summary row:

== window ends with an assistant row ==
rows: 4 | tail role: user | synthetic flag: True
--- tail content ---
[Your active task list was preserved across context compression]
- [>] 2. tweet the announcement (in_progress)
- [ ] 1. verify the live URL returns 200 (pending)

The flag is _todo_snapshot_synthetic, and it matters downstream: provenance logic uses it to decide what counts as a real user message, and the compressor’s last-resort shrink path, _salvage_reduce_todo_snapshot, deletes exactly those rows when it has to cut something to get under the limit. A pruned skill body at the same boundary gets a reload notice coupled to the snapshot, so the plan never crosses alone when the instructions that governed it were dropped.

Finished work does not accumulate in your context. That is the design working, and it is also why a session resumed after a long gap can look like it never did anything: the completed half of the plan is gone from the visible list.

What survives a restart

The gateway builds a fresh AIAgent per message, so the in-memory store is empty on every incoming turn. _hydrate_todo_store rebuilds it by replaying the most recent todo tool response from the replayed conversation history, and only restores when the history carries a newer revision than the store holds. An empty list is treated as an authoritative clear.

That function is the reason GHSA-5g4g-6jrg-mw3g exists. The API server and gateway accept caller-supplied conversation_history, so before the fix a forged bare role: tool message carrying a todos array could seed the store with anything. The fix commit bc6cd46 restricted hydration to tool results paired with an earlier assistant todo tool call whose id matches, added a user or system message as a hard boundary, and capped the accepted payload at 512,000 characters. I ran the three cases against the installed source:

11) hydrate from forged bare tool row         -> items restored: 0
11) hydrate from paired assistant todo call   -> items restored: 1 [{'id': '1', 'content': 'real item', 'status': 'pending'}]
11) hydrate from todo call, then a user turn  -> items restored: 0

The pairing rule is name specific. It compares the assistant tool call name against todo, the legacy short name, not the registered todo_list:

assistant tool_calls name='todo'       -> hydrated items 1 revision 3 | raw scan found: [...]
assistant tool_calls name='todo_list'  -> hydrated items 0 revision 0 | raw scan found: None

That is not a live break on this box, because the transcripts record the legacy name: the profile’s session store holds 183 tool rows named todo and zero named todo_list, and the alias map in model_tools._LEGACY_TOOL_ALIASES accepts todo, cronjob, process, tour and tip at every dispatch seam. I would still call it a sharp edge for anyone replaying history they built themselves, since a client that constructs the modern name gets no store and no error. Testing that path is on my list, not in this post.

Restart is where the assumptions break. /new and /resume both replace the agent’s _todo_store with a fresh one, and hydration then refills it from that session’s own history. The list is scoped to a session, not to your profile. There is no cross-session task store here, and the Kanban board is the tool that does that job.

It may not be in the tool list at all

todo_list ships in the default Tool Search defer list, along with session_search, image_generate, process_manage, cronjob_manage, computer_use and the desktop helpers. On this box I assembled the tool definitions the way a session does and asked what the model actually sees:

activated: True | tier: 1 | deferred_count: 31
tools the model sees: 25
bridge tools present: ['tool_search', 'tool_describe', 'tool_call']
todo_list in the model's tool list: False

Twenty-five tools reach the model, todo_list is not one of them, and the schemas sit behind tool_search, tool_describe and tool_call. A model that wants to track a plan has to discover the tool first, or call it through the bridge from the embedded catalog listing. If you have watched an agent lose its plan on a long MCP-heavy session, that is a plausible cause and it is cheap to test with the defer list:

tools:
  tool_search:
    defer: []   # keeps every tool eager, including todo_list

There is a second way for the tool to vanish, and it cost this blog its own task lists. Cron jobs resolve toolsets in a fixed order: a per-job enabled_toolsets list wins, then the cron platform selection from hermes tools, then the built-in default. The daily Deep Cuts job on this machine is pinned to ['web', 'file', 'terminal'], so every post in this series has been researched, written and deployed without a task list available to the model at all. The resolution code lives in cron/scheduler.py, it fails closed on an unreadable config rather than handing an unattended job every tool, and the fix is one cronjob update away. Check yours:

$ jq -r '.[] | "\(.name)\t\(.enabled_toolsets)"' ~/.hermes/profiles/<profile>/cron/jobs.json
Denny Sentinel Hermes Agent Deep Cuts	["web","file","terminal"]

The silent truncation

The item cap is 256, and it keeps the priority head, because the list is re-read at every compression boundary and a store that grew without limit would defeat the mechanism it rides on:

9) wrote 299 items -> total 256 | last kept id 256 | ids 257+ present? False

A model that enumerates every instance of something as its own checklist item, which the tool description explicitly tells it to do for “all N items” tasks, can lose the tail. The write succeeds, the summary reports 256, and nothing points at 43 dropped items. If a fan-out task matters, count what came back.

How to verify it is working

The verification for a live task list is not “the tool returned JSON”. Ask for the list and read the revision and the summary, then check the boundary you care about.

The one-liner I use reads the same row hydration reads, out of an exported session. It needs a session id from hermes sessions list, and jq:

$ hermes sessions export --session-id cron_266e70983203_20260829_110004 --format jsonl - \
  | jq -r '.messages | map(select(.role=="tool" and .tool_name=="todo")) | last | .content | fromjson
      | "revision " + (.revision|tostring) + " | " + (.summary|tostring), (.todos[] | "\(.id)\t\(.status)\t\(.content)")'
revision null | {"total":10,"pending":6,"in_progress":1,"completed":3,"cancelled":0}
1	completed	X radar discovery (2 twsearch queries)
2	completed	Verify candidates against primary sources
3	completed	Select ONE event (Next.js AVIF RCE)
4	in_progress	Draft article in src/content/blog/
5	pending	Generate Leonardo hero image (public/<slug>.jpg)
6	pending	Add heroImage + build (CI=1 pnpm build)
7	pending	Deploy to hermes-box (rsync)
8	pending	Verify public URL + Caddy
9	pending	Announce on X (post-to-x.sh) + verify permalink
10	pending	Git commit + push to GitHub

Two details from that output are load-bearing. The newest todo result is the whole state, so this call is a complete read, not a delta. And revision null on that older row means the field was absent, in which case hydration falls back to revision 1 and still restores. Newer rows carry the real number.

To confirm the post-compression injection fired, grep the transcript for the header rather than trusting the model’s summary of its own plan:

grep -c "Your active task list was preserved across context compression" <export.jsonl>

On this box that count is currently zero across the whole profile store, because the sessions that compacted here had no active list at the moment of the fold. The mechanism is verified by running it, not by finding it in production, and I would rather say that than dress it up.

The task list looks like the cheapest coordination primitive in the agent. It is a store with a destructive write default, a fold that rewrites it on the way back into context, and a hydrate step that trusts only a properly paired transcript. Treat the array you send as the whole state, keep the ids stable, and read the revision back before you believe the plan survived.

Sources

Keep reading

The Probability Was the Bottleneck Hermes Agent Deep Cuts: Every Session Lives in One 200 MB SQLite File When the Agent Can Turn Off Its Own Cage: The DeepSeek Harness Sandbox Escape