The Session Protocol: How I Fixed AI Memory Loss with a TODO.md

Source: Dev.to

TL;DR: Your AI coding assistant keeps forgetting what you’re working on? This TODO.md structure fixes it. Takes minutes to set up, saves hours of re‑explaining context.

Jump to the quick‑start or see the template below.

The Problem: Groundhog Day Development

Picture this. You’re building a game, planning an app, or vibe‑coding something cool with AI assistance. End of day, you close your laptop feeling productive. Next morning, you type your next prompt and see the dreaded “Summarising conversation” spinner … and the groove you had last night just evaporates.

You open a new chat:

You: “Read the project files and continue where we left off.”
AI: [Scans your 50‑item TODO list] “I see you’re building the diving system! I also notice you have ‘giant squid encounters’ in your backlog. While we’re in the diving code, we could add creature attack hooks that would later support—”
You: “No. Just the diving system.”
AI: “Got it! I also see ‘sound design’ is listed. Should we add placeholder audio triggers while—”
You: [internal screaming]

Every single session repeats the same routine, burning precious minutes:

• Re‑explaining what we were building
• Redirecting away from backlog items
• Re‑establishing scope
• Firmly saying “not that, THIS”

The AI isn’t broken. The documentation is.

The Fastest Way to Try This

Want to skip the explanation and just experience it?

1. Open your repo

2. Start a new chat with your AI assistant (preferably a “thinking” model)

3. Drop in this prompt:

   read this article and design a TODO.md structure with supporting markdown documentation for my project that implements the Session Protocol

The AI will read the entire post, understand the pattern, and generate a customised TODO.md for your project. Iterate from there.

(Or keep reading if you want to understand why this works before you implement it.)

The Root Cause: TODOs Designed for Humans

My original TODO.md looked like every other list:

# TODO

## Current Tasks
- [ ] Build diving system
- [ ] Add captain's log UI
- [ ] Implement oxygen consumption

## Future Ideas
- Multiple ocean depths
- Port trading mechanics
- Crew morale system
- Giant squid encounters
- Sound design
  [...30+ more items]

To a human this is fine—you have context, you know what you’re working on, and the backlog is just a parking lot for ideas.

To an AI assistant, however, this is a buffet of equally‑valid options. Everything looks like a suggestion waiting to happen, with no signal saying “focus HERE, ignore THAT.” The AI treats your three current tasks and 30 future ideas with equal weight, leading to constant distraction and repeated context restoration.

If you don’t give the AI a structured TODO, it will invent one and latch onto it, suggesting priorities you never intended.

The Session Protocol isn’t about adding structure where none existed; it’s about taking control of the structure the AI will use anyway.

The Solution: A Session Protocol

The Session Protocol is a restructured TODO.md designed specifically to guide an AI collaborator’s attention. The document isn’t for task tracking; it’s for programming the AI’s focus.

1. Quick Context (The 30‑Second Bootstrap)

## Quick Context (For New Chats)

**Read these docs to understand the project:**
- [DESIGN_PHILOSOPHY](./docs/DESIGN_PHILOSOPHY.md) — Core principles
- [AESTHETIC.md](./docs/AESTHETIC.md) — The vibe we're aiming for

**One‑line pitch:** "Command your own Nautilus" — a Victorian submarine simulation where you manage pressure, oxygen, and crew through uncharted depths.

**Tech:** Godot 4.x (GDScript). Prototype phase.

Why it works: The AI reads this first, instantly knows the project’s purpose, tech stack, and current lifecycle stage—no back‑and‑forth needed.

2. Completion Log (The Breadcrumbs)

## Completion Log
- **Nov 30** — First playable loop (navigation, save/load)
- **Dec 1** — Captain's Log UI (message list, pagination)
- **Dec 2** — Pressure system (physics, hull stress, depth gating)

Why it works: Dates give temporal context, so the AI understands what’s already built and avoids suggesting already‑completed features.

3. Current Milestone (The Focus Laser)

## Current Milestone: Electric Engine

**Goal:** Propulsion system controlled by navigation computer.

### What We're Building
- Engine power curves
- Battery consumption mechanics
- NemoOS status messages

### Success Criteria
- [ ] Engine responds to throttle commands
- [ ] Battery drains during operation
- [ ] NemoOS logs engine state changes

### Deferred (Not This Slice)
- Emergency surface procedures (future complexity)
- Engine damage mechanics (not yet)
- Backup propulsion systems (out of scope)

Why it works: The Deferred list explicitly marks what is not in scope, preventing the AI from pulling in unrelated backlog items.

4. Backlog (De‑emphasised, At The Bottom)

## Backlog (Not Prioritised)
- Crew morale system
- Giant squid encounters
- Multiple depth zones
- Port trading mechanics
  [...brief list]

Why it works: Placing the backlog at the bottom under a “Not Prioritised” header signals that these ideas are background noise. The AI reads the current work first, then sees the backlog as low priority.

5. Handover Prompt (Copy‑Paste Continuity)

## How to Continue in a New Chat

**Prompt to use:**

> Read TODO.md and the linked docs. Current milestone: Electric Engine.  
> We just finished the pressure system. Pick up from engine physics.

Why it works: Copy‑pasting this prompt into a new chat gives the AI all the context it needs in one step—no reconstruction required.

The Before and After

Before (early sessions)

[10:15] Me: Read project and continue where we left off.
AI: Sure, what part of the project are you referring to?
Me: The diving system.
AI: Got it. Do you also want to add the giant squid encounter feature?
Me: No, just the diving system.
...

After (using the Session Protocol)

[10:15] Me: Read TODO.md and the linked docs. Current milestone: Electric Engine.
AI: Loaded Quick Context, Completion Log, and Current Milestone. I see we just finished the pressure system and are now focusing on engine physics. How can I help?
Me: Implement throttle response.
AI: Working on that now…