A discipline for writing and maintaining persistent documentation that AI agents consume across sessions — so each new session starts smarter instead of starting from scratch.

The Pattern

At the end of every work session, review what was learned and write it to a persistent context file. But not as a journal entry — as reusable intelligence that a fresh agent with zero history can act on immediately.

Five types of persistent context, ranked by value:

1. Anti-patterns. What NOT to do. "Don't use bulk PUT on this API — it replaces all records, not just the one you're updating." Anti-patterns prevent the most expensive mistakes: repeating failures that a previous session already debugged.

2. Decision rationale. WHY something was decided, not just what. "We use polling instead of webhooks because the upstream API has a 30-second webhook delivery lag." Future sessions can re-evaluate the decision if conditions change. Without the rationale, they'll either blindly follow it or blindly change it.

3. Preferences. Explicit statements of choice. "Always use library X over library Y because Z." "Format outputs as tables, not prose." These eliminate guesswork and prevent style drift across sessions.

4. Gotchas. Non-obvious behaviors that took effort to discover. "This CLI tool silently truncates output after 1000 lines." "The API returns 200 even on partial failures — check the response body."

5. Verified facts. Things that were tested and confirmed. "The database supports up to 50 concurrent connections." "Deployment takes 3-4 minutes." Separate verified facts from assumptions.

Organization rules:

• Group by topic, not by date. "Authentication patterns" not "Session on Tuesday." Date-based organization forces the reader to scan everything; topic-based lets them jump to what's relevant.
• Prune aggressively. Stale context is worse than no context — it causes confident, wrong behavior. When something changes, update or remove the entry. Review the full file periodically and delete anything outdated.
• Write for a stranger. The next session has zero memory of your session. Include enough context that someone unfamiliar can understand and act on each entry without asking follow-up questions.

Key Decisions

Append-and-prune over append-only. Append-only logs grow until they exceed context windows and become useless. Regular pruning keeps the file at a manageable size with only current, accurate information.

Structured entries over free-form notes. Each entry should have a clear category (anti-pattern, decision, preference, gotcha, fact) so agents can quickly scan for what they need. Unstructured notes require reading everything to find anything.

One file per domain over one big file. Split context by topic area. An agent working on deployments shouldn't have to load authentication context. Smaller, focused files load faster and stay within token limits.

When to Use It

Any ongoing project where you work with AI across multiple sessions. The more sessions you run, the more value the context file provides. First session: you're teaching the AI everything. Tenth session: the AI already knows your stack, your preferences, your past mistakes, and your architectural decisions. The compound effect is significant — each hour invested in context documentation saves 15-30 minutes per future session.