I was running more than 60 projects through synthesis engineering, my practice of sustained human-AI collaboration, with Claude Code as my primary development partner. Each project's CONTEXT.md was the starting record for a session. For months, one file per project worked. Then the current work started disappearing into the history.
The largest CONTEXT.md had reached 1,014 lines. My context files mixed session logs from December, team rosters that hadn't changed in weeks, completed checklists, architecture decisions made months earlier, and the three tasks I needed to work on that day. Loading all of it into every session consumed tokens and diluted the AI's attention.
An audit of all 60+ projects revealed this wasn't an isolated problem. Eighteen projects had CONTEXT.md files over 500 lines. The median was 178 lines and growing. There was no mechanism for information to leave these files once written, except by closing the entire project and starting fresh.
The problem was structural, and I built a structural solution: the tiered context architecture. Its purpose is to put the next session's immediate work within reach while preserving a reliable path to everything else.
Four kinds of information, three places to keep it
A single context file can serve four functions with different lifecycles:
| Information | When it is needed | Maintenance |
|---|---|---|
| Current state and active tasks | At the start of work | Refresh as the work changes |
| Stable facts, locations and decisions | When a task depends on them | Update the current reference; retain the reason and source |
| Session history | When reconstructing a decision or investigating a change | Keep a dated, searchable archive |
| Completed checklists | When they establish what was done or verified | Archive the useful record; remove duplicates from active context |
Appending 60 lines after each of 15 sessions adds 900 lines. Most of that accumulated history is not needed before beginning today's work. Separate information by how it is used and how it changes: the hot/warm/cold distinction from systems design gives me a useful way to make those decisions.
The file layout gives each kind of information a destination:
project/
├── CONTEXT.md # Current state, active tasks, recovery pointers
├── REFERENCE.md # Stable facts, decisions and their sources
├── sessions/
│ └── YYYY-MM.md # Dated session history
└── [other files] # Code, original evidence and other project material
CONTEXT.md is working context: the short record an assistant reads first. It holds the project's present state, active tasks with priorities, unresolved blockers, and a summary of the most recent work. My budget is 150 lines, with a review trigger at 120. Those are operating choices, not a universal model limit. A line count is also a rough size measure: a file with very long lines may still consume substantial context.
REFERENCE.md holds relatively stable information: repository locations, architecture, configuration and decisions. When a fact changes, update the current entry. Give consequential facts a source and a verification date so the next reader can tell what was checked. A deployment URL may be stable; its recorded health is time-sensitive.
The sessions/ directory holds dated accounts of what changed and why. Monthly files are one useful grouping. When a decision changes, the reference should carry the current decision and its reason; the session record should document the change and point to that reference. Updating only one leaves either the current guidance or the historical account incomplete.
The human-memory analogy helps explain the different jobs:
| Memory role | Project record | Maintenance choice |
|---|---|---|
| Working | CONTEXT.md | Keep current work visible and refresh it frequently |
| Semantic | REFERENCE.md | Update facts and relationships; preserve their sources |
| Episodic | sessions/ | Retain dated events and the reasons for changes |
| Procedural | Instructions and lessons/ | Capture how to do the work and refine the rules |
The cache analogy adds a loading policy:
| Access tier | Project record | Loading choice |
|---|---|---|
| Hot, like L1 | CONTEXT.md | Read first; I use a 150-line budget |
| Warm, like L2 | REFERENCE.md | Retrieve the facts the task needs; my original bounded-project budget was 300 lines |
| Cold, like a later cache tier | sessions/ | Search when a question needs the historical account |
| Underlying storage | Transcripts, code and original evidence | Read the actual source when a claim depends on it |
These analogies help decide what to store, when to retrieve it and how to maintain it. The files still need an explicit loading and maintenance procedure. A standing operations project may accumulate more reference knowledge than a bounded project; organize that material into topics instead of discarding useful knowledge to meet the original single-file budget.
Archive before removing
I review old material at session boundaries and when working context approaches its budget. Age helps identify candidates, but an unresolved decision stays visible even if it is months old.
- Copy completed work records and old session summaries into the appropriate archive. Put current stable facts in the reference file, retaining their provenance.
- Read the destinations and verify that the facts, reasons, results and unresolved questions survived. A file's existence alone is insufficient.
- Replace the migrated material in working context with any pointers the next session needs.
- Check the remaining context against the budget and the active task list.
Keep the source intact until the destination and its recovery pointers have been checked. After an interruption, inspect the actual files before continuing; do not infer that a write completed from an earlier plan or an existing filename.
If two people or agents can edit the same records, designate the writer or coordinate the edits before migration. A backup or Git commit gives you a recoverable version; it does not merge conflicting accounts or establish which one is current.
The question for each passage is where it will next be needed. Current work stays in CONTEXT.md. Stable facts move to REFERENCE.md. Dated events belong in sessions/. Reusable guidance belongs in a lesson or instruction file. Remove disposable duplication only after checking that it carries no unique evidence, obligation or unresolved question.
September 2026 additions: the worked migration, the March 4 snapshot comparison, and the current product and implementation details below.
A worked migration
Consider an illustrative CSV import project. Its working context includes the active task “Add a duplicate-ID regression case,” an old decision, and a completed test note. The old decision remains relevant, but its full explanation need not occupy the active task list.
Preserve these two passages before editing:
Decision: Reject duplicate order IDs before writing any records.
Reason: A partial import would require the operator to reconcile two states.
2026-09-20: Added the empty-file test; it passes.
Duplicate-ID behavior still needs a regression case.
The current reference becomes:
# CSV import reference
## Duplicate order IDs
Reject duplicate order IDs before writing any records.
Reason: A partial import would require the operator to reconcile two states.
Source: the illustrative project's decision record.
The archive carries the dated work record:
# September 2026 sessions
## 2026-09-20
Added the empty-file test; it passes.
Duplicate-ID behavior still needs a regression case.
The next session starts from:
# CSV import — working context
## Current state
Empty-file handling has a passing test, recorded in sessions/2026-09.md.
## Next task
Add a duplicate-ID regression case using REFERENCE.md's rejection rule.
The duplicate-ID case remains unverified.
Check the relationship among all three files. The reference preserves both the rejection rule and its reason. The archive preserves what the example says was tested. Working context still distinguishes the passing empty-file test from the unverified duplicate-ID case. Shortening the file must not turn a pending test into a completed one.
These files can be checked offline for preserved passages and valid pointers. A separate recovery check asks the assistant to identify the next task, the governing rule and the unverified behavior from those records. That is the check that exercises retrieval. A successful file-copy check alone cannot establish that an assistant loaded or used the records.
Results across the project portfolio
I applied the architecture across 62 projects in a session. The table below uses a separate comparison of the tracked projects/<project>/CONTEXT.md files in the retained March 4, 2026 repository snapshots, immediately before and after the migration.
| Metric in those repository snapshots | Before | After |
|---|---|---|
| Tracked project context files | 58 | 62 |
| Largest context file | 1,014 lines | 128 lines |
| Median context-file length | 183.5 lines | 69.5 lines |
| Context files above 150 lines | 34 | 0 |
| Context files above 500 lines | 7 | 0 |
Projects with REFERENCE.md | 1 | 21 |
| Projects with tracked session archives | 1 | 14 |
Four context files were added, so the before and after medians describe different populations. The counts use logical lines throughout.
After the migration, 41 of the 62 projects had neither a reference file nor a session archive. The architecture scales down as well as up: create the other tiers when the project has material that belongs in them.
The migration put active records within the chosen budget and gave stable facts and history their own destinations. The next check is recovery: can an assistant find the current task and the decision that governs it? File organization is the foundation for that workflow; the worked example above shows what to verify.
Working with product memory
Product memory and project-owned records can work together. The useful choice is which system owns the facts and decisions you need to inspect, update and carry across tools.
As documented on September 28, 2026:
| Surface | Relevant documented behavior |
|---|---|
| Claude Code auto memory | Uses a MEMORY.md index and separate topic files. It loads the first 200 lines or 25 KB of the index, whichever comes first, and retrieves topic files on demand. Users can inspect, edit or delete the files. |
| ChatGPT projects | Group chats, files and instructions. Project-only memory can draw on conversations inside the project while excluding outside conversations and saved personal memories. Available behavior depends on account and workspace settings. |
| Project-owned context, reference and archives | Let a team choose its record structure, review changes in Git, and give different tools the same current decisions and source pointers. The team must still arrange loading, access and maintenance. |
I keep explicit project records because I can inspect the chosen state, review its changes in Git, and carry the same decisions and source pointers to another client. Tool-native memory is a useful supplement: it can catch preferences and context I did not explicitly save. Deliberate project records play the role that version control plays alongside autosave. To use them across clients, configure a supported reading path and the appropriate permissions, then check that the next session can recover the intended state.
Starting with one project
Create a project directory and a short working context. If you manage several projects, a registry helps locate them:
projects:
- id: csv-import
name: CSV import
status: active
description: Validate incoming order files before import
last_session: 2026-09-27
These values belong to the illustrative project. Your registry should use the actual project and session date. Its job is discovery; the detailed active state belongs in the project's working context.
Start with CONTEXT.md alone when that is sufficient. Add reference material and archives when there is something useful to put in them. Reaching 120 lines is a prompt to review the contents, not a reason to manufacture extra files. For routine session cleanup, my rule of thumb is two or three minutes. A migration or disputed record needs the time required to preserve and reconcile it.
Put the lifecycle procedure in instructions your assistant actually loads. For example:
## Project context
At session start, read projects/csv-import/CONTEXT.md and follow the pointers
needed for the task. Verify time-sensitive facts against their source.
After significant work:
- Update the active state, next task and unresolved questions.
- Update stable reference facts and preserve their sources.
- Archive dated work records before removing them from active context.
- Verify the destinations, then check the 150-line working-context budget.
- Update the registry's actual last-session date.
- Review the diff and commit the intended project changes.
Instruction discovery is client-specific. Codex documents an AGENTS.md discovery chain from the project root toward the working directory, with overrides and a configurable byte limit. Claude Code documents both CLAUDE.md and conditional direct AGENTS.md loading; direct support requires version 2.1.277 or later, and the default depends on which Claude instruction files exist in the directory ancestry. Check the documented settings and exceptions for your session.
Make the budget executable where it needs to govern a write. The current context editor source includes line-budget checks; a Markdown instruction alone does not block an over-budget change. Verify the check at the boundary your workflow actually uses.
Where this is going
- Ad hoc: re-explain the project each session.
- Monolithic: preserve context in one accumulating file.
- Tiered: separate working context, reference and history, with deliberate movement between them.
- Compiled: assemble context from current project state, code and history.
Tiered context is the 80/20 solution I wanted: enough structure to make long-running collaboration sustainable without requiring a complete context compiler first. The larger ambition is to have the next session's context assembled from the current state of the work.
The project-management source already includes a bounded step toward that goal: it renders a current-state block in CONTEXT.md from structured project state, including the phase, accepted baseline, controlling plan and next actions. Assembling the wider task context from live code, records and history remains the broader design goal. That assembly needs to retain unresolved questions and show which sources it used; compiling stale input would preserve the original problem.
The public context-lifecycle skill and project-management skill contain the broader implementation and templates; both skill documents declare CC0-1.0 licensing. The project-record system explains how these records fit into ongoing work.
For your first migration, keep the original file, move one completed passage, and check whether a new session can recover the next task and the reason behind its governing decision. That gives you a concrete test of the design before applying it across a portfolio.
This article is part of synthesis engineering.