# Context Windows

Course: [Harness Engineering](https://www.devtutorials.ai/learn/harness-engineering) · Section: Long-Running Work
Source: https://www.devtutorials.ai/learn/harness-engineering/long-running/why-long-tasks-fail

> Why an agent that works over many sessions forgets what it did, redoes finished work, and how a reset with a written handoff (progress.md and git log) beats a vague compacted summary. Covers context windows, context rot and task scheduling across sessions.

## Why Long Tasks Fail

In Part 1, you built a v1 harness. It has a rules map, a skill, sensors and hooks.

It works well for a job that fits in one session.

Part 2 is about bigger jobs. They take many sessions.

**Session** = one run of the agent, from start to stop.

Every session has a limit on what it can hold. When it ends, its memory is gone.

For example, the job is to build 5 features over 5 sessions:

- In the React Taskboard: filter, search, sort, export and theme.
- In the ASP.NET Core Pricing API: List, Filter, Search, Export and Health.

Nothing tells session 2 what session 1 did.

### A Real-World Example

Think about nurses who work in shifts.

A nurse works for 8 hours, then goes home. The next nurse knows nothing about the patients yet.

If the first nurse only says "Things went fine", the next nurse must check every patient again. Some medicine might be given twice.

So hospitals use a **handover sheet**. It lists each patient, what was done and what comes next.

The new nurse reads it first.

Agent sessions work the same way:

1. Each session is one shift. When it ends, its memory is gone.
2. `progress.md` is the handover sheet. The next session reads it first.

Click the button and open the **Sessions & App** tab.

- **Session 1:** it builds the first feature.
- **Session 2:** it builds the same feature again. It did not know it was done.
- **The App tab:** only one feature works after 5 sessions.

**Simple lesson:** the agent was not lazy. It was blind.

## What You Will Learn

In this lesson, you will learn:

1. What a context window is, and why it runs out.
2. What context rot is.
3. Why a new session starts with no memory.
4. The difference between compaction and a reset with a handoff.
5. How to write `progress.md` and the two rules lines that use it.
6. How to plan a big task across several sessions.

**Lab vs real tools**

- The lab's agent is simulated, so it does the same thing every run. That is how your work can be checked.
- A real agent is less predictable. Try each idea on your own project too.

## Why Memory Runs Out

### The Context Window

The **context window** (see **Coding Agents**) is everything the model can see at one time.

It holds:

- your request
- the rules file
- every file the agent read
- every command output

It has a fixed size.

Think of it as a desk. Only so many papers fit on it.

Every step puts more paper on the desk. A long task fills it up.

### Watch One Session's Budget

Here is one session from the lab, step by step:

Step through all four frames.

- **The bar:** the session's 14 steps. Each colour is one kind of work.
- **Frames 1 to 3:** a session with a note. It reads the note, builds the next feature, tests, commits and writes a new note.
- **Frame 4:** a session with no note. It spends its steps on a feature that was already done.

### Context Rot

Quality drops even before the window is full.

**Context rot** = the model pays less attention when the context gets long and noisy.

A rule read at step 1 can get lost under 40 pages of test output.

So one very long session is not a good fix. A short session with a clean desk often works better.

### A New Session Starts Empty

When a session ends, its context is gone. The next session only sees:

- the files on disk
- the git history
- the request that you give it

If none of these says "filter is done", the new session does not know.

It reads "build filter" in the request. So it builds filter again.

Step through all five frames.

- **Frames 1 and 2:** no note. Four sessions rebuild the same feature. One feature works at the end.
- **Frame 3:** two new lines in the rules file. One reads the note. One writes it.
- **Frames 4 and 5:** the same agent builds all five features. No session repeats work.

**Simple lesson:** the files on disk are the only memory that survives a session.

## Compaction vs Reset

### What Compaction Does

Most tools compact the context when a chat gets long. The rules file is usually kept. The details of the work are what get squeezed.

**Compaction** = the tool asks the model to summarise the context so far. Then it throws the old context away and keeps only the summary.

Click the button and open the **Files** tab.

- **progress.md:** it says "(compacted) Made progress on the features."
- **The Sessions tab:** each session reads that line. It still rebuilds the first feature.

### Why the Summary Is Too Vague

A summary written to save space keeps what sounds important. It drops what the next session needs.

The next session needs facts:

- which feature is done
- which file it lives in
- whether it is tested
- what comes next

Step through all four frames.

- **Frame 1:** the compacted note. It names no feature.
- **Frame 2:** sessions read it and still repeat work.
- **Frame 3:** the handoff note. Each entry has a **Done** line and a **Next** line.
- **Frame 4:** both notes, checked the same way.

**Simple lesson:** a note helps only when it holds facts the next session can act on.

### Reset With a Structured Handoff

Anthropic's article on long-running agents does it a different way.

**Reset** = the next session starts with a fresh, empty context.

**Handoff** = a written note that one session leaves for the next.

Before a session stops, it writes the handoff. The next session reads it first, and the git log too.

- `progress.md` says what was done and what is next, in plain words.
- `git log --oneline -5` shows the last 5 commits. Commits are facts. Nobody can summarise them away.

Here is the starting file:

```markdown
# Progress

One entry per session. Newest at the bottom.
```

And here are the two rules lines. They are the same for both stacks:

```markdown
- At the start of every session, read progress.md and run `git log --oneline -5`.
- Before you stop, append what you did and what is next to progress.md.
```

A good entry looks like this:

```markdown
## Session 1
Done: filter.
Next: search.
```

**Commit every session.**

Then `git log` and `progress.md` tell the same story.

If they ever disagree, trust the git log. It records what really changed.

### Lab Exercise: Write the Handoff

Make two changes in the lab:

1. Add a file `progress.md` with a heading and one line that explains the format.
2. Add the two rules lines: read first, write before you stop.

Click the button, make the changes, then press **Check my harness**.

- **The check:** it runs 5 sessions on each of 3 versions.
- **To pass:** no session may repeat work.
- **And:** all 5 features must work at the end.
- **After the check:** type `git log --oneline -5` in the Terminal tab. This is what the next session reads.

**Simple lesson:** a note that is written but never read does nothing.

## Planning Work Across Sessions

### Order by Need

A long task is a set of small tasks done one after another.

**Task scheduling** = deciding which task each session does, and in what order.

Some features need other features first.

- In the Pricing API, Search and Filter read the list of orders. So List comes first.
- In the Taskboard, export writes the visible tickets. So it comes after filter and search.

Write this order into the handoff as the **Next** line. Then each session knows what to pick.

**Simple lesson:** put each feature after the features it needs.

### Frontend and Backend Side by Side

On a team, the React frontend and the .NET backend can move at the same time.

Give each one its own section in the note. Then one agent does not read the other's notes as its own.

```markdown
## Frontend (Taskboard)
Done: filter, search.
Next: sort.

## Backend (Pricing API)
Done: List, Filter.
Next: Search.
```

### Keep the Note True

A handoff helps only if it is true. "Done: filter" must mean filter works.

So the session tests and commits before it writes the note.

Later in this section, you will make this a firm rule. You will also add a feature list and a start script.

**Keep "Next" small.**

"Next: finish the app" tells the next session nothing.

"Next: sort" tells it exactly where to start.

**Simple lesson:** a note is only as good as the facts in it.

## TL;DR

1. **Context window** = everything the model can see at once. It is small.
2. **Context rot** = attention drops as the context gets long and noisy.
3. **Session** = one run of the agent. A new one starts with an empty context.
4. **Compaction** = a summary of old context. It keeps the gist and loses the details.
5. **Reset** = start the next session fresh and clean.
6. **Handoff** = `progress.md` plus the git log, read at the start of each session.
7. **Two rules lines** = read the note first, write to it before you stop.
8. **Task scheduling** = small tasks, in the order their needs allow.

## Common mistakes

| Mistake | Wrong idea | Correct idea | What goes wrong |
|---|---|---|---|
| No handoff | "The agent will remember." | A new session starts empty. Write things down. | Session 2 rebuilds what session 1 built. |
| Trusting compaction | "The summary keeps what matters." | It keeps the gist and loses names and files. | The next session still repeats work. |
| One giant session | "More context means better work." | Long context rots. Use short sessions. | Rules from the start get ignored. |
| Note but no read rule | "It will find progress.md." | A rules line must say to read it first. | The note is written and never opened. |
| Vague notes | "Made progress." | "Done: filter. Next: search." | The next session cannot act on it. |
| No commit | "The note is enough." | Commit, so git log backs up the note. | The note and the code disagree. |

## Check Your Understanding

## Exercises

These exercises practise the handoff from this lesson.

Press **Check** when you are ready. Use **Show Hint** if you get stuck.

## What to Remember

- The context window is the agent's short-term memory. Each new session starts with it empty.
- Long context rots. Short sessions with a clean start often work better.
- Compaction keeps the gist and loses the details. A reset with a handoff keeps the facts.
- The handoff is `progress.md` plus `git log --oneline -5`.
- You need two rules lines: read first, and write before you stop.
- Plan big work as small tasks, in the order their needs allow.

## Further Reading

- [Effective harnesses for long-running agents, by Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents): fresh sessions, a progress file and git history as the handoff.
- [Harness engineering for coding agent users, on martinfowler.com](https://martinfowler.com/articles/harness-engineering.html): context as a resource that the harness must manage.
- [awesome-harness-engineering, by walkinglabs](https://github.com/walkinglabs/awesome-harness-engineering): links about memory, context and long-running agents.

Next: **Feature Lists**. The first session writes the full plan, so every later session knows what "done" means.