# Multi-Session Continuity

> Maintaining context and momentum across multiple AI coding conversations, even across days or weeks.

## When to Use

- Long-running projects spanning multiple sessions
- Picking up work after a break
- Handing off work between different AI tools
- When conversation context windows are exhausted

## The Pattern

AI agents lose context between conversations. Continuity comes from three layers:

```
Layer 1: Agent Memory          (auto-retrieved, editor-specific)
Layer 2: Committed Docs        (AGENTS.md, progress files, session summaries)
Layer 3: Code Itself           (well-named commits, self-documenting code)
```

The best developers use all three layers.

## Continuity Strategies

### 1. Progress Files (for multi-day work)

When a task spans multiple sessions, create a lightweight progress tracker:

```markdown
# progress.md (in project root, gitignored or committed)

## Current Task: Add notifications module

### Done

- [x] types.ts — NotificationDoc, schemas (commit abc123)
- [x] repository.ts — CRUD + batch operations (commit def456)
- [x] routes.ts — 6 endpoints (commit ghi789)

### In Progress

- [ ] Notification delivery (email + push)

### Pending

- [ ] Tests (target: 20+)
- [ ] Register in server.ts
- [ ] Add container to cosmos-init.ts

### Notes

- Using existing email provider pattern from invitations module
- Push notifications need APNs cert (not set up yet)
```

**Key:** Keep it terse. Under 30 lines. Update at end of each session.

### 2. Session Summaries (for knowledge transfer)

After completing a significant piece of work, write a summary in `docs/`:

```markdown
# Session Summary: Telemetry Implementation

## What was built

- Platform-service telemetry module (34 tests)
- iOS keyboard instrumentation (10 event points)
- Desktop Python client (threading flush, persistent install_id)
- Browser client (sendBeacon, localStorage install_id)

## Architecture decisions

- Batch ingestion (POST /api/telemetry/events)
- PII scanning on ingest (regex blockers)
- 30-day TTL on event docs, 90-day on clusters
- FNV-1a hash for deterministic policy rollout

## What's pending

- Phase 3: Error clustering alerts, geo enrichment, policy builder UI
```

### 3. Commit Messages as Context

Well-structured commit messages are the most durable form of context:

```
feat(telemetry): add platform-service telemetry module

- types.ts: TelemetryEvent, ErrorCluster, CollectionPolicy schemas
- repository.ts: batch ingest, query, GDPR erasure
- routes.ts: POST /events, GET /query, GET /config, policy CRUD
- 34 tests passing

Cosmos containers: telemetry_events, telemetry_error_clusters,
telemetry_collection_policies
```

An agent can `git log --oneline -20` to understand recent work.

### 4. Starting a New Session

When resuming work, give the agent a quick bootstrap:

```
I'm continuing work on the notifications module for platform-service.
Last session I completed types.ts and repository.ts.
Today I need to:
1. Create routes.ts with 6 endpoints
2. Write tests
3. Register in server.ts

See docs/progress.md for detailed status.
Follow the pattern in src/modules/auth/ for the routes.
```

### 5. Handoff Between Editors

When switching from Windsurf to Claude Code (or vice versa):

1. **Commit all work** — The code is the universal context
2. **Update AGENTS.md** if architecture changed
3. **Leave a progress.md** with current state
4. **In the new editor:** "Read AGENTS.md and docs/progress.md. I'm continuing the notifications module."

## The Memory Hierarchy

| Durability        | Source                         | Survives Editor Switch? |
| ----------------- | ------------------------------ | ----------------------- |
| **Permanent**     | Git commits, AGENTS.md         | Yes                     |
| **Long-lived**    | Agent memories (Windsurf)      | No (editor-specific)    |
| **Session-lived** | Conversation context           | No                      |
| **Ephemeral**     | IDE state (open files, cursor) | No                      |

**Lesson:** Never rely solely on agent memory. The most important context should be committed.

## Anti-Patterns

- **Starting fresh every session** — "Build me a notifications module" when half is already built
- **Relying on agent memory alone** — Memories can be stale or irrelevant
- **Progress files with 200 lines** — Keep them under 30 lines; prune completed items
- **Not committing before ending a session** — Uncommitted work is invisible to the next session
- **Over-documenting** — A progress.md for a 10-minute task is overkill

## Real-World Example

A telemetry system was built across 3 sessions:

**Session 1:** Platform-service module (types, repo, routes, tests)
→ Committed + memory saved with module details + test count

**Session 2:** iOS + Desktop clients
→ Agent retrieved Session 1 memory, understood the API contract
→ Built clients that matched the existing schema exactly
→ Updated memory with new completion status

**Session 3:** Browser client + admin dashboard UI
→ Agent retrieved both memories, built the remaining pieces
→ Wrote final session summary in docs/

Total: 3 sessions, zero rework, zero context loss.

## Editor-Specific Notes

| Editor          | Continuity Features                                                  |
| --------------- | -------------------------------------------------------------------- |
| **Windsurf**    | Persistent memories, conversation history, implicit context tracking |
| **Claude Code** | CLAUDE.md auto-read, conversation history within projects            |
| **Cursor**      | Conversation history per workspace, .cursorrules per project         |
| **Aider**       | Git-aware, auto-reads recent commits, .aider.conf.yml                |
| **Copilot**     | Limited — relies on open files and .github/copilot-instructions.md   |

## Related Skills

- [03 — Memory Management](./03-memory-management.md)
- [05 — Effective Agent Prompting](./05-effective-agent-prompting.md)
- [19 — Session Summaries & Playbooks](./19-session-playbooks.md)
