The Three-System Architecture: Why Your AI Coding Assistant Needs Three Types of Memory

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 whose index loads 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 nothing pointed a new session at them. 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 Three Systems

1. Auto-Memory: Stable Knowledge, Indexed Every Session

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. The index is what loads — one line per memory — and Claude opens an individual memory file when its index line says it is relevant.

This is the only system that reaches a session 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.

The Checklist You See Is a Render, Not a Fourth System

Earlier versions of this architecture named a fourth system: the CLI's built-in task tool (TaskCreate, formerly TodoWrite), described as the live subtask checklist. When we probed the harness directly, that tool was not there. The lesson was uncomfortable but useful — a claim about the harness, remembered rather than re-checked, had outlived the harness version it was true of.

The interesting part is what did not go missing. Every piece of state that checklist was supposed to show already lived somewhere durable:

• Todo-MCP tasks supplies the roster and each item's status.
• Todo-MCP context supplies the in-flight subtask narrative, through the task_#N_progress breadcrumb.
• Auto-memory supplies anything that must outlive the current task — sprint framing, prior decisions.

So the user-visible checklist is now drawn from those three systems whenever it is shown — at session start and at each task boundary. Nothing is written to it. It is composed fresh from data that already lives in the three systems, which is why it is always right: it was never a copy.

A roster render looks like this:

5 of 12 outstanding · 2 blocked

- «#4» ○ Derive the tool inventory from one table — est 2h
- «#5» ◐ Audit the todo_* tools against actual behaviour — est 2h
- «#6» ⊘ Port the cross-environment rules — est 1h 30m
- «#7» ⛔ Wire the CLI export path — est 45m
- «#8» ○ Write the migration note — est 1h

For the current task's own steps, the render reads one line of the breadcrumb — SUBTASKS: — and copies it as written:

SUBTASKS: ✓ Login form · ✓ Validation · ▸ Connect auth API · Handle response · Store token

✓ marks each step done, ▸ the one in progress, and pending steps carry no mark. The breadcrumb is written first; the checklist is drawn from it. Never the reverse.

Two rules keep the render from quietly turning back into a fourth place where state is stored:

• Counts come from project_status — and the outstanding count includes blocked tasks. The task list header counts completed tasks too, so it reads most wrongly late in a sprint, exactly when you most want an accurate number.
• Each line's gist is the task's own first line, copied verbatim. Re-wording it on every draw is how a display becomes a second source of truth.

Why Each System Is Irreplaceable

The key insight is that these three systems have non-overlapping strengths:

• Auto-memory is the only system that reaches a session without a call: its index loads, and Claude opens the files it points to. Anything you need to be pointed to at session start 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.

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, nothing points the next session to it. When in-flight state lives in auto-memory instead of context, the writes are too slow and heavy. And when the progress display is treated as a place to store state, that state has no durable home at all.

The Division of Labor

Here is how concerns map to systems in practice:

• User preferences and project rules — auto-memory (rare writes, indexed every session)
• Lessons and workarounds discovered during work — auto-memory (long-lived, reasoning included)
• Sprint-boundary resume state — auto-memory (its index line 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)
• User-visible progress checklist — a render, drawn fresh from the three systems above

How They Work Together

A typical task lifecycle touches all three systems:

1. Plan — Create todo-mcp tasks with estimates. Set dependencies and sequence afterwards with todo_update. Strategic, session-spanning.
2. Start — Begin a task with todo_start, then check for an existing breadcrumb: resume from it if there is one, write a starter breadcrumb only if there is not.
3. Work — Update the breadcrumb after every meaningful subtask, before long operations, and after every build or test result. The progress you see is drawn from that breadcrumb — there is no second list to keep in sync.
4. Complete — Mark the task done and delete its breadcrumb keys in the same step.
5. Reflect — At sprint boundaries or session end, write an auto-memory file capturing what was learned. Its index line 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. And the next render reflects all three correctly, because nothing it shows was ever stored anywhere else.

The Evolution

Keeping these three 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 next reframe added auto-memory as a peer system. The one after that removed a system that turned out not to exist — and found that nothing important had been lost, because the durable state was always in the other three.

This is how todo-mcp has always evolved. When the harness changes, friction emerges, and the tool adapts. The three-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 three systems catch each one — see the companion article.