One System Is Not Enough
When I first started building Todo-MCP, the framing was simple: there were two systems — Todo-MCP for persistent tasks, and the CLI's built-in task tool for in-session subtasks. That worked for a while.
Then Claude Code shipped auto-memory — file-based markdown memories that auto-load into every session. This was a genuine architectural shift in how the harness worked, not a cosmetic feature. Suddenly there were capabilities that did not exist before, and the two-system framing no longer fit.
The problem was not that anything broke. It was that stable knowledge — lessons learned, workarounds discovered, project preferences — was living in the wrong place. Under the old framing, those lived as todo-mcp context keys with prefixes like lesson_* and workaround_*. They persisted, but they did not auto-load. A lesson discovered in one session was invisible in the next unless someone explicitly called context_get. Cross-session knowledge was quietly going unused.
The reframe was not about adding features to todo-mcp. It was about recognizing what each system is actually good at and dividing the work accordingly.
The Four Systems
1. Auto-Memory: Stable Knowledge That Auto-Loads
Auto-memory is Claude's own file-based memory system. Markdown files with frontmatter, stored at a project-specific path, indexed by a MEMORY.md file that loads into every session automatically.
This is the only system where information appears without anyone asking for it. That makes it the right home for anything you want Claude to know at the start of every session: user preferences, cross-task lessons, sprint context, project rules.
The trade-off: writes are multi-step (read the file, edit or create it, update the index). Not suitable for high-frequency updates.
2. Todo-MCP Tasks: Strategic Work Units
Tasks with permanent IDs — «#42» — that never change. Dependencies, sequence numbers, status tracking, time estimates, archival. When you reference a task in a commit message or a conversation, that reference resolves cleanly months or years later.
This is the only system with structured work management. No other system gives you dependency graphs, ordered execution, or archival with export. Tasks are the backbone of any multi-session project.
3. Todo-MCP Context: The Crash-Protection Layer
Key-value pairs stored in the same SQLite database as tasks. A single context_set call is one durable write — fast, atomic, less than 100 milliseconds.
This is the only system with cheap, frequent, durable writes. That makes it uniquely suited to be the write-ahead log for in-flight work. The primary use case is the breadcrumb pattern: a task_#N_progress key that gets updated after every meaningful step, recording what is done, what is in progress, and what comes next.
When a crash happens, the breadcrumb tells the next session exactly where to resume. No codebase re-derivation, no guessing.
4. TaskCreate: Live Subtask Visibility
The CLI's built-in task tool (formerly called TodoWrite). An in-session subtask checklist that the user sees updating live as work progresses.
This is the only system the user watches in real time. That is the collaboration affordance — you see each step completing as Claude works through a task. It does not survive a crash (it lives in the session), but that is fine because its purpose is communication, not persistence.
Why Each System Is Irreplaceable
The key insight is that these four systems have non-overlapping strengths:
- Auto-memory is the only system that auto-loads. Anything you need at session start without asking lives here.
- Todo-MCP tasks is the only system with permanent IDs, dependency graphs, and archival. Tasks referenced across commits and conversations resolve cleanly.
- Todo-MCP context is the only system with cheap, frequent, durable writes. It is the only crash-protection mechanism for in-flight work.
- TaskCreate is the only system the user sees update live. Real-time collaboration visibility.
Choosing the wrong system for a job either leaks context or loses crash-resilience. When stable knowledge lives in todo-mcp context instead of auto-memory, it does not auto-load. When in-flight state lives in auto-memory instead of context, the writes are too slow and heavy. When tasks live in TaskCreate instead of todo-mcp, they do not survive a session restart.
The Division of Labor
Here is how concerns map to systems in practice:
- User preferences and project rules — auto-memory (rare writes, auto-loads every session)
- Lessons and workarounds discovered during work — auto-memory (long-lived, reasoning included)
- Sprint-boundary resume state — auto-memory (auto-loads next session)
- Strategic tasks with estimates and dependencies — todo-mcp tasks (permanent IDs, archival)
- In-flight breadcrumbs for crash protection — todo-mcp context (fast durable writes, updated per meaningful step)
- In-session subtask checklist — TaskCreate (user-visible during conversation)
How They Work Together
A typical task lifecycle touches all four systems:
- Plan — Create todo-mcp tasks with estimates and dependencies. Strategic, session-spanning.
- Start — Begin a task with
todo_start. Create the in-session subtask checklist with TaskCreate. Write an initial breadcrumb to context. - Work — Update the breadcrumb after every meaningful subtask. Update TaskCreate statuses so the user sees progress live. Both happen naturally during work.
- Complete — Mark the task done. Delete the breadcrumb keys. Clear the subtask checklist.
- Reflect — At sprint boundaries or session end, write an auto-memory file capturing what was learned. This auto-loads next session.
This pattern is crash-resilient at every step. A CLI crash mid-task lands you at a clean recovery point: the breadcrumb tells you where you were, todo-mcp tasks tell you what is in progress, auto-memory tells you the broader context. TaskCreate state is lost, but that is just the visual checklist — the durable state in context and tasks is intact.
The Evolution
Keeping these four systems consistent requires discipline — and that discipline is what skills provide. Skills are the versioned procedures that ensure state moves into the right system, in the right shape, every time.
This architecture was not designed upfront. It emerged through friction.
The original framing treated todo-mcp context as a session-scoped helper and stable knowledge landed there by default. When auto-memory arrived, the friction became obvious: lessons that should have informed every session were silently invisible. The four-system reframe was the fix — recognizing what each system does best and putting knowledge where it belongs.
This is how todo-mcp has always evolved. When the harness changes, friction emerges, and the tool adapts. The four-system architecture is the next chapter in that pattern, not a reset. For a closer look at the six specific ways continuity breaks — and how these four systems catch each one — see the companion article.