COORDINATION.md: Cross-Session Memory for Claude

Introduction

You've been working with Claude Code for two hours. You've built the authentication flow, set up the database schema, and started implementing the dashboard. You close your laptop, get some coffee, and when you return and start a new conversation, Claude has no idea what you were working on.

Every session with Claude starts fresh. There's no persistent memory, no automatic context from previous conversations. Claude doesn't know you spent the morning refactoring the user service or that you're halfway through a three-phase feature implementation. You either re-explain everything, hope Claude figures it out from the codebase, or accept fragmented work.

COORDINATION.md is your solution. It's a structured file that tracks active work, blocked tasks, phase progress, and session handoffs. When Claude reads COORDINATION.md at the start of each session, it immediately knows what's in progress, what's blocked, and what needs to happen next.

The Problem: Claude Forgets

Claude Code has no persistent memory between sessions. Every new conversation starts with a blank slate. This creates several problems that compound over time.

Lost Context

You spent an hour discussing architecture decisions with Claude. You agreed on patterns, naming conventions, and implementation order. Next session, Claude has no memory of those decisions. You either repeat the conversation or watch Claude make different choices.

Incomplete Work

Complex features don't finish in one session. If you're implementing a three-phase feature and complete phase one, Claude doesn't know phase two exists. It might consider the work "done" when you've barely started.

Blocked Tasks Forgotten

You hit a blocker waiting for an API key, a design decision, or external input. You note it mentally and move on. Next session, you've forgotten the blocker, Claude never knew about it, and you waste time rediscovering the same issue.

Handoff Failures

In multi-agent systems or team environments, handoffs between sessions break down. One session's progress doesn't transfer to the next. Each new conversation is an island, disconnected from what came before.

What COORDINATION.md Does

COORDINATION.md serves as Claude's external memory between sessions. It tracks everything Claude needs to know to continue work seamlessly.

Tracks Active Work

What's currently being implemented? What phase is it in? Who's working on it? COORDINATION.md maintains a real-time snapshot of work in progress, so Claude can pick up exactly where the last session left off.

Records Blocked Tasks

Tasks get blocked by missing information, pending decisions, or external dependencies. COORDINATION.md captures these blockers explicitly, including what's needed to unblock them, so nothing falls through the cracks.

Manages Phase Progress

Complex features get broken into phases. COORDINATION.md tracks which phases are complete, which is current, and which are pending. Claude knows exactly where you are in multi-phase implementations.

Enables Session Handoffs

When you end a session, COORDINATION.md captures the state. When you start a new session, Claude reads it and continues seamlessly. The handoff is explicit and reliable.

What to Include

A well-structured COORDINATION.md contains several key sections. Each serves a specific purpose in maintaining continuity.

Active Collaborations

Document work currently in progress. Include the task name, current status, assigned agent (if using multi-agent), and a brief description of the current state.

## Active Work

### User Authentication - IN PROGRESS
**Agent:** web-developer
**Phase:** 2 of 3
**Status:** Implementing password reset flow

Notes:
- Login/signup complete and tested
- Session management working
- Password reset UI built, needs backend connection

Blocked Work

Capture tasks that can't proceed and why. Include what's needed to unblock them, who can resolve it, and when it was blocked.

## Blocked

### Payment Integration - BLOCKED
**Blocked Since:** 2025-01-15
**Reason:** Waiting for Stripe API keys from client
**Unblock:** Receive API keys and add to environment
**Can Continue:** Frontend payment form (doesn't need live keys)

Pending Validation

Track work that's complete but needs review or testing. This prevents completed work from being forgotten before validation.

## Pending Validation

### Dashboard Charts - NEEDS REVIEW
**Completed:** 2025-01-16
**Validate:**
- [ ] Charts render correctly on mobile
- [ ] Data updates in real-time
- [ ] Loading states show properly
- [ ] Error handling works

Session Checkpoints

Record the state at session end. This is what Claude reads at the next session start to understand where things left off.

## Last Session

**Date:** 2025-01-16
**Duration:** 2 hours
**Focus:** Dashboard implementation

**Completed:**
- Chart component structure
- Data fetching service
- Basic responsive layout

**Next Session Should:**
1. Add chart animations
2. Implement filter controls
3. Connect to live data source

**Open Questions:**
- Should filters persist across page refreshes?

Example COORDINATION.md

Here's a realistic example for a project with multiple active workstreams. Use this as a template for your own projects.

# Project Coordination

> Last updated: 2025-01-16 14:30

## Active Work

### Landing Page Redesign - IN PROGRESS
**Phase:** 2 of 3 (CSS Styling)
**Agent:** frontend-designer
**Status:** Mobile styles complete, working on tablet breakpoints

| Phase | Description | Status |
|-------|-------------|--------|
| 1 | HTML structure | COMPLETE |
| 2 | CSS styling | IN PROGRESS |
| 3 | JavaScript interactions | PENDING |

**Next:** Complete tablet styles, then hand off to web-developer for Phase 3.

---

### API Rate Limiting - IN PROGRESS
**Agent:** firebase-developer
**Status:** Implementing token bucket algorithm

Notes:
- Basic rate limiting working
- Need to add per-user limits
- Redis integration pending decision

---

## Blocked

### Email Notifications - BLOCKED
**Since:** 2025-01-14
**Reason:** SendGrid account pending approval
**Unblock:** Account approval (ETA: 1-2 business days)
**Workaround:** Can test with console logging

---

## Pending Validation

### User Profile Page
**Completed:** 2025-01-15
**Checklist:**
- [ ] Avatar upload works
- [ ] Form validation correct
- [ ] Changes persist after refresh
- [ ] Works on iOS Safari

---

## Recently Completed

- 2025-01-16: Authentication flow (all 3 phases)
- 2025-01-15: Database schema setup
- 2025-01-14: Project initialization

---

## Session Notes

### 2025-01-16 Afternoon Session
**Focus:** Landing page Phase 2
**Completed:** Mobile responsive styles
**Blocked by:** Nothing
**Next session:** Finish tablet/desktop styles

### 2025-01-16 Morning Session
**Focus:** API rate limiting
**Completed:** Basic implementation
**Blocked by:** Redis decision
**Next session:** Continue once Redis decision made

How to Use It

COORDINATION.md works best when it becomes part of your workflow rhythm. Here's how to integrate it effectively.

PM Reads at Session Start

In a multi-agent setup, the Project Manager reads COORDINATION.md before doing anything else. This gives immediate context on what's active, blocked, and needed. No guessing, no re-explaining.

User: "Continue"

PM (internally):
1. Read COORDINATION.md
2. See "Landing Page Phase 2 - IN PROGRESS"
3. Delegate: "frontend-designer: Complete tablet styles for landing page"

No context re-establishment needed.

Update During Work

As tasks complete, blockers emerge, or phases progress, update COORDINATION.md. Keep it current. Stale information is worse than no information because it actively misleads.

Session Handoff Protocol

At the end of each session, update the "Session Notes" section. Document what was accomplished, what's next, and any open questions. This becomes the starting context for the next session.

Before closing:

1. Update task statuses (IN PROGRESS, BLOCKED, COMPLETE)
2. Add session note with summary
3. List "Next session should" items
4. Note any blockers discovered

This takes 2 minutes and saves 15 minutes next session.

Use "Continue" Command

Train yourself to start sessions with "continue" or "what's next". The PM reads COORDINATION.md and immediately picks up active work. No need to explain what you were doing.

Benefits

Teams and individuals who adopt COORDINATION.md report significant improvements in their Claude Code workflow.

Session Continuity

No more "where were we?" conversations. Every session starts with full context. Claude knows what's active, blocked, and needed without you explaining it.

Accountability

Work doesn't disappear into the void. Blocked tasks stay visible until unblocked. Pending validation stays tracked until validated. Nothing falls through the cracks.

Progress Tracking

See exactly where you are in complex implementations. Phase progress is explicit. You can answer "how far along is feature X?" instantly by checking COORDINATION.md.

Team Alignment

In multi-agent or team environments, everyone reads the same status file. No conflicting understandings of what's in progress. Single source of truth for work state.

Reduced Cognitive Load

You don't have to remember everything. COORDINATION.md remembers for you. Focus on the work itself, not on tracking the work.

Integration with Phases

COORDINATION.md is particularly powerful for tracking multi-phase tasks. Complex features often span multiple sessions and multiple agents. Without explicit tracking, phase progress gets lost.

Phase Tables

Use tables to show phase progress at a glance. Mark each phase as PENDING, IN PROGRESS, or COMPLETE.

### Feature: User Dashboard
**Total Phases:** 4
**Current Phase:** 2

| Phase | Description | Agent | Status |
|-------|-------------|-------|--------|
| 1 | Data models & API | firebase-developer | COMPLETE |
| 2 | UI components | frontend-designer | IN PROGRESS |
| 3 | Interactivity | web-developer | PENDING |
| 4 | Polish & testing | frontend-designer | PENDING |

Phase Handoffs

When one phase completes, the next begins. COORDINATION.md makes these handoffs explicit. The completing agent marks their phase done; the PM delegates the next phase.

Phase 1 completes:
1. firebase-developer marks Phase 1 COMPLETE
2. PM updates COORDINATION.md
3. PM delegates Phase 2 to frontend-designer
4. frontend-designer sees Phase 1 complete, begins Phase 2

No confusion about readiness. No duplicate work.

Cross-Session Phases

Phases often span multiple sessions. COORDINATION.md preserves phase state across session boundaries. When you return tomorrow, you know exactly which phase is active and what's been done.

Conclusion

COORDINATION.md transforms Claude Code from a stateless assistant into a team member with persistent memory. Instead of re-explaining context every session, you simply say "continue" and work resumes exactly where it left off.

The file itself is simple: markdown with structured sections for active work, blocked tasks, pending validation, and session notes. The power comes from consistent use. Update it during work, not just at session end. Read it at session start, not after you've already asked Claude what's happening.

Start with the basics: one section for active work and one for session notes. Add blocked tasks and pending validation as your workflow demands. The template in this guide works for most projects, but adapt it to your needs.

Your future sessions will thank you. Instead of spending the first ten minutes reconstructing context, you'll spend them making progress. That's the power of explicit, persistent coordination.