Cross-Session Project State
Keep long-horizon work coherent across many sessions: externalized project state that any session can load, advance, and hand off.
The route
4 steps to Done
- 01
Design the project-state document
The document a stranger could continue from is the standard.
Preview prompt + verify gate ▾ Hide ▴
Design PROJECT_STATE.md. Sections: GOAL (the outcome, verbatim from the owner), MILESTONES (ordered, with status: done/active/pending and completion evidence for done ones), CURRENT POSITION (exactly where work stands: active milestone, last completed step, the very next action), DECISIONS (dated: decision, reason, alternatives rejected), BLOCKERS & RISKS (open issues with owner), WORKSPACE MAP (key files/dirs this project touches, one line each), CHANGELOG (dated deltas per session). Write the initial document for my actual project now, populating every section honestly - especially the next action, which must be executable as written.
- ✓ All seven sections populated
- ✓ Done milestones cite evidence
- ✓ Next action passes the stranger test
- 02
Implement the session-start protocol
Orientation before action, every single time.
Preview prompt + verify gate ▾ Hide ▴
Build the session-start protocol. On starting a session in the project: (1) load PROJECT_STATE.md into context under an orientation header; (2) run drift checks - verify done-milestone evidence still holds (files exist, tests still pass if cheap to run) and the workspace map matches reality; (3) render an orientation summary: goal, position, next action, open blockers, plus any drift warnings; (4) the agent's first output confirms its understanding of the position and proposes to proceed with the recorded next action (or flags why not). Test by starting a session and checking the orientation against the document by hand.
- ✓ State loaded before any task work
- ✓ Drift checks run with warnings surfaced
- ✓ First output confirms position and next action
- 03
Implement the session-end advance
A session that does not advance the state never happened.
Preview prompt + verify gate ▾ Hide ▴
Build the session-end protocol. On completion, cancellation, or escalation: (1) compute the session delta - milestones advanced (with evidence), position moved (new next action), decisions made, blockers opened/closed, workspace map changes; (2) apply the delta to PROJECT_STATE.md additively: statuses update, but DECISIONS and CHANGELOG only append; (3) write the changelog entry (date, session id, one-paragraph delta); (4) validate the updated document (next action present and executable, no milestone marked done without evidence). Make this protocol crash-resistant: a mid-session checkpoint updates CURRENT POSITION after each milestone-relevant step. Verify by diffing the document across a real working session.
- ✓ Delta computed and applied additively
- ✓ Done requires evidence
- ✓ Checkpoint updates survive a crash
- 04
Run the multi-session and handoff tests
Continuity is the claim - test it like one.
Preview prompt + verify gate ▾ Hide ▴
Prove the system. TEST A (continuity): run a real 5-session task (sessions deliberately short); verify each session starts at the previous end point, no analysis is redone, and early decisions hold in late sessions - audit via the changelog. TEST B (cold handoff): after session 3, start a completely fresh session (or different agent) with nothing but the state document; verify it continues correctly without human re-explanation - this is the handoff quality bar. TEST C (drift): between sessions, manually change the code to invalidate a done milestone; verify the next session-start flags the drift instead of proceeding blind. Fix whatever failed and re-run that test.
- ✓ 5-session audit shows no redone work
- ✓ Cold handoff continues correctly
- ✓ Injected drift is caught at start
Research-backed
Sources behind this flow
Tier 3 · memory
Dual-Memory Complete
A production-oriented dual-store agent memory system: separate tables for memories, core files, and skills in a multi-table vector store, with configurable confidence thresholds and trigger-word driven self-evolution.
Tier 3 · memory
KAS Memory
An agent memory system that auto-extracts insights from coding sessions, recalls relevant memories in future conversations, and builds a growing reusable knowledge base - aimed squarely at not repeating the same mistakes across sessions.
Tier 6 · agent-research
L2MAC
The LLM Automatic Computer framework (ICLR 2024): treats the LLM as a CPU with an external memory unit, generating large, consistent codebases far beyond a single context window.