When the Harness Changes, the Tool Adapts
Todo-MCP has always evolved through friction. The original version existed because auto-compaction destroyed session state and there was no way to persist it. Each subsequent version addressed real pain discovered through production use — position-vs-ID confusion, missing uncomplete operations, context cleanup needs.
v2.5 follows the same pattern. Claude Code shipped auto-memory — file-based markdown memories that auto-load into every session — and the existing framing stopped fitting. Not because anything broke, but because stable knowledge was living in the wrong place.
The Problem v2.5 Solves
Under the previous framing, todo-mcp and the CLI's built-in task tool were "the two systems." Cross-session knowledge — lessons learned, workarounds discovered, project preferences — lived in todo-mcp context as lesson_* and workaround_* keys.
Those keys persisted reliably. But they did not auto-load. A workaround discovered in session A was invisible in session B unless someone explicitly called context_get. The most valuable cross-session knowledge was silently unused.
Auto-memory changed this. It gave Claude a place to store knowledge that loads automatically every session. The question became: if auto-memory handles stable knowledge, what is todo-mcp context actually best at?
The answer: crash protection.
What Changed
v2.5 is a conceptual reframe, not a feature release. The MCP server behavior is essentially unchanged. What is different is the operational model — how the tools get used together.
Four Systems Instead of Two
The new framing recognizes four state systems with non-overlapping roles:
- Auto-memory — stable knowledge that auto-loads every session (preferences, lessons, sprint context)
- Todo-MCP tasks — strategic work units with permanent IDs, dependencies, and archival
- Todo-MCP context — the write-ahead log for in-flight work, crash-protected via breadcrumbs
- TaskCreate (formerly TodoWrite) — in-session subtask checklist visible to the user in real time
Cross-Session Knowledge Moves to Auto-Memory
Lessons and workarounds now live in auto-memory feedback files that load every session automatically. No more invisible knowledge. The lesson_* and workaround_* context key patterns are deprecated — their replacements auto-load without anyone calling context_get.
Context Becomes the Crash-Protection Layer
With stable knowledge handled by auto-memory, todo-mcp context can focus on what it does uniquely well: cheap, frequent, durable writes. The primary pattern is a task_#N_progress breadcrumb updated after every meaningful step, recording what is done, what is in progress, and what comes next.
The breadcrumb costs less than 100 milliseconds per write. After a crash, it tells the next session exactly where to resume — no codebase re-derivation, no guessing.
TodoWrite Is Now TaskCreate
The CLI's built-in task tool was renamed by the harness. The mental model is identical — an in-session subtask checklist for the current task. If you search for TodoWrite in documentation, you will find it referenced as TaskCreate with a note about the rename.
What You Get from v2.5
- Lessons that auto-load. A workaround discovered in one session is visible in the next without anyone calling
context_get. This was the leak that v2.5 closes. - Crash-resilience at the subtask level. Mid-task crashes resume on a clean breadcrumb instead of forcing a full state re-derivation. Recovery is precise — you pick up at the exact subtask, not the beginning of the session.
- A cleaner mental model. Each system has a non-overlapping purpose. There is a clear right answer for where any piece of information belongs.
- Lower friction onboarding. New installations seed starter auto-memory files automatically. The protocol survives every subsequent session without manual setup.
What Did Not Change
The MCP tool surface is the same. Existing installations keep working. The upgrade is in-place — the install script handles both old and new configurations. Your existing context data persists; your existing tasks are untouched.
This is not a breaking change. It is the next chapter in todo-mcp's friction-driven evolution. Claude Code's harness changed, friction emerged, and todo-mcp adapted.
The Pattern Continues
Every version of todo-mcp has followed the same arc: real usage reveals friction, friction reveals requirements, requirements become features. v2.5 is no different. Auto-memory arrived, the old framing leaked knowledge, and the four-system architecture is the fix.
If you are already using todo-mcp, the updated mastery documentation included with your installation covers the full protocol. If you are new, the four-system architecture is the starting point — it tells you exactly where each piece of information belongs and why.
The friction log continues. If you find something that does not work the way it should, that is not a bug report — it is the next version. Update: The next chapter is here — skills emerged from the four-system architecture, turning the persistent store into a self-maintaining workflow.