Every Session Starts in Darkness. Your Documents Shouldn't. — A Copy-Paste Setup So AI Agents Stop Losing Context Between Sessions (Dead Light Framework, Part 2)
Two files, four rules, ten minutes. Skip the theory; the templates are below and you can paste them into a repo right now.
Dead Light Framework — Part 2 of an ongoing series. Series so far: 1 · The Emperor Is All But Dead · 2 · Every Session Starts in Darkness · next: when two files aren't enough — the paperwork-vs-runtime decision.
By a developer running AI agents as daily teammates — a peer, not an authority (full framing in #1). · ~7 min · the Dead Light Framework repository (MIT)
The tax you're paying (and want gone)
If you hand real work to AI agents, you pay this every day: each new session starts from zero. You re-explain the project, what you decided last time, what's in flight, which files matter. Fifteen, twenty minutes of re-priming a human teammate would never need — and worse, the agent cheerfully re-litigates Monday's decision on Wednesday because nothing told it the decision was settled.
My least favourite version of it: I once left a comment explaining why an ugly branch of code had to stay. Two days later a fresh session, sent in to tidy up TODOs, read the comment as a TODO and deleted the branch by morning. The reasoning died with the session that wrote it. That's the tax — and it compounds.
It isn't a model problem. Each session is stateless by design; the last session's reasoning is gone unless something on disk carries it. So put it on disk — deliberately, in a shape the next session can consume in one read. Here's the smallest setup that does it.
The setup: two files, four rules (≈10 min)
Drop two files at your repo root. That's the whole mechanism.
HANDOFF.md — the snapshot a fresh session reads first
Your project's current state on one screen: what's true now, what's mid-task, what's decided, what to do next. It's the first thing an agent reads each session — the thing that replaces fifteen minutes of you re-explaining. Rewrite it freely; it always describes "now" (running history lives in LOG.md, below). Think of it as the project's working memory, externalised so a memoryless teammate can borrow it.
---
doc_kind: state
status: working # draft | working | sealed
updated: 2026-05-22
---
# HANDOFF — <project>
## Now # what is true today
- Frontend v2 rename is done; auth is on the new schema.
## In flight # mid-task work + who owns it
- Migrating `users` table — session-12, half done; next step is the backfill.
## Decided # do NOT re-litigate these
- Auth must not import billing. Why: layering; billing changes shouldn't ripple into auth.
## Start here next
- Run the `users` backfill, then delete the legacy column.
Copy the full, commented template: handoff-template.md
LOG.md — the append-only history
If HANDOFF.md is "now", LOG.md is "everything that happened" — one line per event, append-only; you never edit a past line (a correction is a new line). Why keep it when the snapshot already shows the current state? Because the snapshot overwrites itself: the moment you need to know why something was decided, replay how you got here, or recover after a session left a mess, you need the history the snapshot threw away. The snapshot is derived from this log — not the other way round.
---
doc_kind: log
---
# LOG — <project> (append-only; a correction is a NEW line, never an edit)
- 2026-05-22 · session-12 · decided · auth must not import billing (layering) <!-- sealed -->
- 2026-05-22 · session-12 · created · users-table migration draft [candidate]
- 2026-05-22 · session-12 · note · backfill must run before dropping legacy column
Copy the full, commented template: log-template.md
The four rules
-
Two kinds, never mixed.
HANDOFF.mdis current state — overwrite it freely.LOG.mdis history — append only; never edit a past line (a correction is a new line). This one split is what makes the whole thing trustworthy. -
First thing every session: read
HANDOFF.md, then the new lines inLOG.mdsince you last looked. That's your re-prime — under a minute, no human needed. -
Last thing every session: append what you did to
LOG.md, then updateHANDOFF.mdto match. (An agent can do both as part of "wrap up.") -
Tag what isn't settled.
[candidate]= produced by an agent, not human-confirmed.<!-- sealed -->= a decision that must not be "cleaned up" away. Agents read these.
That's it. No tool to install, no service to run — git plus two markdown files. Want it as one copy-paste page (both templates + the rules + the agent instruction)? The Agent Context Quickstart.
Tell your agent once (system prompt /
CLAUDE.md/.cursorrules): "At the start of every session read HANDOFF.md and the recent LOG.md lines before doing anything. At the end, append your actions to LOG.md and update HANDOFF.md. Never edit past LOG lines; never touch a<!-- sealed -->decision without asking." Now the discipline is the agent's job, not yours.
What you actually get
- Re-prime drops from ~15 min to ~1 min. The agent reads two files and is current — you stop being a human context-cache.
-
Decisions stop silently reverting. A
sealedline inDecidedis a wall the next session sees; the Wednesday-undoes-Monday failure mostly stops. -
You can stop mid-task and resume clean.
In flight+ the LOG tail tell the next session exactly where to pick up — even a different agent, even weeks later.
Honest cost: ~2 minutes of discipline per session (append + update), and it pays off only once you're past a handful of sessions or running more than one agent. Below that, a plain README is fine — don't over-build.
Why it works (the 30-second version)
Documentation is your team's shared memory. When some teammates wipe their memory every session, the documents have to carry state — and the reliable way to carry state across actors that can't sync live is exactly this: one append-only history plus a derived current-state view. That's the eventually-consistent coordination pattern distributed systems have used for decades; I just borrowed it. The full standard — including the multi-repo and multi-agent versions, and the failure modes — is framework/paperwork-standard.md.
This covers one repo and one session at a time. The moment you have two agents writing at the same instant, or an invariant that must never break even for a second, two markdown files can't promise it — and that's a real, provable limit, not a gap you patch with better notes. Knowing which side of that line you're on is the next post.
The story below the setup (optional — skip if you came for the templates)
You can stop here with a working setup. If you want the why behind the why, here it is.
Back in late 2024 / early 2025, when I first started handing agents real work — audit this service, draft this migration, pick up where the last session left off — this was a dumb, recurring tax. Every new session opened with me re-explaining the same context, and by the third I was burning fifteen or twenty minutes re-establishing state a human teammate would simply have had. So I wrote a better HANDOFF.md. Then a better one. The overhead kept climbing, and a voice in the back of my head kept saying: you're carving this at the wrong joint.
So I made the mistake of following the problem — and it turned out not to be the problem I thought it was. Strip the word "documentation" and it's stark: I had actors that start cold, run briefly, and can't talk to each other in real time, and they had to act coherently anyway. That's not a docs question — it's distributed systems, a field that's been proving theorems about exactly this since the 1970s. I'd been hand-rolling a worse version of it in markdown without noticing.
That's also why this framework wears Warhammer 40,000 names, in case the "darkness" felt like an affectation. The Imperium of Man runs a galaxy with no real-time communication — its ships cross the warp, where they're simply unreachable. So it governs on three things: frozen edicts (decided once, not renegotiable by whoever's nearest), the Adeptus Administratum (literally galactic paperwork), and the Astronomican — a beacon of light a ship lost in the dark steers by. Strip the gothic paint and that's the entire engineering of this post: frozen authority, durable records, and a signal that survives. The darkness in the title is the warp between your sessions; your two files are the Astronomican.
And there's a catch I'll be honest about, because it shapes the whole series: that "real, provable limit" two paragraphs up isn't hand-waving — coordinating actors with no live channel runs into a genuine theorem (CAP), and it caps what any pile of documents can promise. So after I'd borrowed all this and wired it together, I spent more effort trying to break it than to build it — cold, hostile reviewers; an independent pass over every borrowed citation; benchmarks designed to make it fail. Some of it failed. That story is the rest of the series — but your setup above doesn't wait on any of it.
New here? I'm a developer who runs AI agents daily — a peer, not an authority; full framing in #1. Standing caveat: one developer, essentially one case study — useful, not proven. Tell me where it breaks for you.
"Every session starts in darkness" is Warhammer-flavoured naming, nothing more. Independent practitioner exploration; no affiliation with Games Workshop. Repository MIT-licensed.
Top comments (0)