Working across multiple sessions

Real work does not fit in one session. You stop for the day, or the context fills, or you switch tasks and come back. Each new session starts with no memory at all.

The fix is not a better memory feature. It is writing things down in the repository.

The state file

Keep a short file, in version control, that answers four questions:

# Current work

## Goal
Migrate the billing service from Stripe Charges to PaymentIntents.

## Done
- Added PaymentIntent creation in `src/billing/intents.ts`
- Tests passing for the happy path

## Open
- Refunds still use the old API
- Webhook signature check needs updating for the new event shape

## Decided against
- Running both APIs in parallel. Too much reconciliation work.
- Upgrading the whole SDK at once. Do it after this lands.

Start a session by pointing at it. End a session by asking the agent to update it.

Why "decided against" earns its place

It is the section that saves the most time and the one everybody omits.

Without it, every new session cheerfully proposes the approach you already rejected, and you spend the first ten minutes re-explaining why it does not work. Written down once, it is settled permanently.

Why a file beats the conversation

A file is re-read fresh every session, survives compaction, is reviewable in a pull request, and is visible to your colleagues.

Conversation history has none of those properties. It is also the thing most likely to be silently trimmed at exactly the wrong moment.

Keep it small

This is a state file, not a design document. Twenty to forty lines. If it grows past that, the extra belongs in a proper document that the state file points to.

A long state file has the same problem as a long rules file: it fills the context you were trying to protect.

Ending a session well

Two minutes at the end saves twenty at the start of the next one:

> Update the state file. Add what we finished, what is still open, and anything we ruled out and why. Keep it under forty lines.

Read what it writes. A state file with a wrong claim in it is worse than no state file, because you will trust it tomorrow.

Starting a session well

> Read the state file, then continue with the refund path.

That is enough. The agent picks up from a written record rather than reconstructing from fragments.

The general principle

Anything that must outlive the context window belongs in a file. Everything else is disposable, and treating it as disposable is what keeps sessions fast.