Claude Code forgets everything when you close the terminal. Every session starts from zero. No memory of what was decided, what failed, what to do next. You re-explain the same context every single time.
I have been running Claude Code daily for months across 9 projects. 1,300+ sessions, 69,000+ messages. At that scale, re-explaining context is not a minor annoyance. It is a productivity killer.
MEMORY.md does not solve this. It is a flat file with a 200-line cap and a 25KB size limit where the AI decides what to remember. There is no handoff protocol. No structured way to end one session and start the next one with full context. So I built one.
This article is about the session protocol I use to give Claude Code continuity across sessions. It is part of claude-brain, my open source persistent memory system. But the protocol pattern works even if you never install the brain.
The Problem: No Handoff
Here is what happens without a protocol:
- You work with Claude for 3 hours on a complex feature
- Context window fills up or you close the terminal
- You open a new session
- Claude has no idea what happened
- You spend 15 minutes re-explaining where you left off
- Claude makes the same wrong suggestions you already rejected last session
- Repeat
The core issue is that there is no structured handoff between sessions. No checklist. No verification. No continuity. Every session is an island.
The Fix: Start and End Protocols
I built two protocols that run at the beginning and end of every session. They live in three places that work together:
CLAUDE.md is a project-level instruction file that Claude reads automatically when it opens a session. This is where the protocol rules are defined. Claude follows these instructions the same way a new employee follows an onboarding document. The start checklist, end checklist, verification steps, and "no coding without GO" rules are all in here.
SESSION_PROTOCOLS.md is a human-readable reference copy of the same protocols. It exists so I can review and update the rules without digging through CLAUDE.md's other project instructions.
Six Python hook scripts in the hooks/ folder handle the automation. Claude Code has a hook system that fires scripts at specific points in a session. These are real Python scripts that run automatically, not manual steps:
session-start.py reads NEXT_SESSION.md + injects last session's notes,
unfinished items, and the verification checklist
user-prompt-submit.py searches the brain database on every prompt,
injects relevant matches into context
stop.py captures the conversation to the database
on every Claude response
session-end.py triggers sync and backup when the session closes
pre-compact.py saves full context before the context window resets
post-compact.py re-injects brain context after compaction
The hooks enforce the protocol even when I forget to ask for it. The session-start hook injects the checklist requirements automatically. Claude cannot skip them.
NEXT_SESSION.md is the bridge file. At the end of every session, Claude writes a summary and my forward instructions into this file. At the start of the next session, session-start.py reads it and injects the contents into context. This is how past-me communicates with future-Claude.
End-Session Protocol: Capture Everything Before Closing
When I say "end session" (or "wrap up" or "done for today"), Claude must complete all of these steps and show me the checklist:
1. Write session notes to the database.
A structured summary: what was done, what decisions were made, what files were changed, what is unfinished. These notes are written directly to a local SQLite database using a script. They include tags for categorization (coding, debugging, research, etc.).
2. Update the project summary.
Not a patch. A full rewrite of the project's current state. This summary powers the next session's context injection and also feeds into daily email digests.
3. Update MEMORY.md as a backup.
The "last session" section gets overwritten with the current session's summary. This is a fallback in case the database is unavailable.
4. Update governance files.
The project tracker, feature plan, and any other files that track progress. If a step was completed, it gets marked done. If a new decision was made, it gets logged.
5. Ask me one question: "Anything you want Claude to know next session?"
This is the most important step. Whatever I answer gets written into a file called NEXT_SESSION.md. The session-start hook reads this file automatically and injects it into the next session's context. This is how I pass instructions forward to a future Claude that has no memory of the current conversation.
6. Write NEXT_SESSION.md.
The full session summary plus my answer from step 5. This file is the bridge between sessions.
7. Git commit and push.
All changes are committed. Nothing is left in a dirty state.
8. Output the verified checklist.
Every step must show DONE:
+-----------------------------+----------+
| End-Session Checklist | Status |
+-----------------------------+----------+
| Session notes + tags written | DONE |
+-----------------------------+----------+
| Project summary updated | DONE |
+-----------------------------+----------+
| MEMORY.md updated | DONE |
+-----------------------------+----------+
| Governance files updated | DONE |
+-----------------------------+----------+
| NEXT_SESSION.md written | DONE |
+-----------------------------+----------+
| Git committed + pushed | DONE |
+-----------------------------+----------+
If any row shows MISSING, we stop and fix it before closing.
Start-Session Protocol: Verify Before Acting
When a new session starts, Claude must complete all of these steps before doing anything else. Before answering questions. Before writing code. Before proposing a plan. The checklist comes first.
1. Search the brain.
The brain is a local database of every conversation I have ever had with Claude. On session start, Claude searches it for recent context: what was discussed, what is unfinished, what decisions are locked.
2. Read the project tracker.
This is the source of truth for where things stand. What steps are done, what is in progress, what is next. Claude reads this so it does not suggest work that is already completed.
3. Review the session-start hook output.
The hook automatically injects: last session's notes, flagged unfinished items, a verification checklist, and recent session topics. Claude must actually review this, not just acknowledge it.
4. Verify before acting.
If picking up unfinished work, Claude must verify the premise independently. Do not trust the notes blindly. Re-read the file. Check the current state. Confirm the problem still exists. This rule exists because prior sessions sometimes left notes with wrong assumptions that led to hours of wasted work.
5. Present unfinished items and next-session notes to me.
This is critical. I need to SEE the unfinished items and the notes I left for this session. Not a checkmark. Not "I reviewed them." The actual content, presented prominently so I can react to it. Sometimes what I said at the end of a long session at midnight is not what I want to work on the next morning.
6. Output the verified checklist.
+-------------------------------------+----------+
| Start-Session Checklist | Status |
+-------------------------------------+----------+
| Brain searched | DONE |
+-------------------------------------+----------+
| PROJECT_TRACKER.md read | DONE |
+-------------------------------------+----------+
| Session-start hook output reviewed | DONE |
+-------------------------------------+----------+
| Unfinished items SHOWN to user | DONE |
+-------------------------------------+----------+
| Next-session notes SHOWN to user | DONE |
+-------------------------------------+----------+
7. Confirm ready.
Claude states what it knows: "Brain searched. Last session: [summary]. Tracker read. Current step: [step]. Ready."
Only then do we start working.
Why Checklists Matter
AI will skip steps. Not maliciously. It just prioritizes answering your question over following a protocol. Without a checklist, Claude will jump straight into whatever you asked and skip the context loading. This happened to me in sessions 35, 38, and 39 before I enforced the checklist.
The checklist is not optional. The hooks inject the requirements automatically. CLAUDE.md reinforces them as explicit rules. The combination makes it reliable. Not perfect, but close enough that I catch failures immediately when they happen.
The Bridge: NEXT_SESSION.md
This file is the single most valuable piece of the protocol. Here is why.
At the end of every session, I tell Claude what the next session should know. Real examples:
- "Priority tomorrow is pushing dev to main. Do not start anything else."
- "The authentication bug is NOT in the middleware. Do not go down that path again. Check the token validation."
- "I changed my mind on the database schema. Ignore everything from session 42 about the users table."
These are instructions from past-me to future-Claude. They prevent re-litigating decisions, repeating mistakes, and going down paths I already rejected.
The session-start hook reads NEXT_SESSION.md and injects it into context. But the protocol also requires Claude to SHOW me the contents so I can override them. Sometimes what I said last night is not what I want today.
The Safety Net: Frustration Circuit Breaker
One more thing the protocol handles. When my message indicates frustration (all caps, repeated punctuation, anger keywords), the user-prompt-submit hook automatically searches the brain for the current topic and injects a STOP directive. This forces Claude to reassess instead of continuing down a wrong path.
This exists because the worst sessions happen when Claude keeps iterating on a broken approach while I get increasingly frustrated. The circuit breaker catches that pattern and breaks the loop.
What This Looks Like in Practice
End of Monday's session:
Me: "end session"
Claude: [writes notes, updates tracker, updates summaries]
Claude: "Anything you want Claude to know next session?"
Me: "The FTS5 bug is fixed. Do not touch fuzzy search again.
Priority is pushing dev to main and outreach."
Claude: [writes NEXT_SESSION.md, commits, shows checklist, all DONE]
Start of Tuesday's session:
Claude: [searches brain, reads tracker, reads hook output]
Claude: "Session 48 summary: FTS5 fuzzy bug fixed, hook improvements
on dev, outreach across 5 platforms.
Your notes for this session:
- FTS5 bug is fixed. Do not touch fuzzy search.
- Priority: push dev to main and outreach.
Unfinished: dev branch 3 commits ahead of main.
Tracker: step 51/52 complete.
[checklist table, all DONE]
Ready."
No re-explaining. No context loss. Claude knows exactly where we left off and what I want to do today.
The Pattern Without claude-brain
You do not need the full brain system to use this pattern. Here is the minimum viable version:
1. Create a NEXT_SESSION.md in your project root.
At the end of every session, tell Claude to write a summary and your next-session instructions to this file.
2. Add this to your CLAUDE.md:
When starting a session, read NEXT_SESSION.md first.
Show me the contents before doing anything else.
3. Add an end-session instruction to CLAUDE.md:
When I say "end session", write a summary of what was done,
what is unfinished, and ask me what the next session should know.
Save to NEXT_SESSION.md.
That is it. Three steps. You get 80% of the value with zero infrastructure.
The full brain system adds automated hooks (so you cannot forget), database-backed search (so Claude can find anything from any session), and enforcement mechanisms (so the protocol actually runs every time). But the core idea is just structured handoffs between sessions.
Real Numbers
This protocol has been running across 1,300+ sessions and 9 projects:
- Zero sessions where Claude started without context (since enforcing the checklist)
- Average re-explanation time dropped from 15 minutes to under 1 minute
- Session quality scores improved because Claude stops repeating rejected approaches
- NEXT_SESSION.md has caught 4 cases where the prior session left wrong assumptions
Try It
The minimum version (NEXT_SESSION.md + CLAUDE.md instructions) takes 2 minutes to set up. Start there.
If you want the full system with automated hooks, database, search, email digests, and MCP tools:
curl -fsSL https://raw.githubusercontent.com/mikeadolan/claude-brain/main/install.sh | bash
Free, open source, works on macOS, Linux, and Windows.
GitHub: github.com/mikeadolan/claude-brain
Video: claude-brain in 85 seconds
Article 1: How I Built Persistent Memory for Claude Code
Article 2: Why I Use Claude Code for Everything
Top comments (0)