The problem
AI coding assistants are powerful, but stateless. Every new session starts cold. The agent doesn't know what was decided yesterday, why a particular approach was chosen, or what not to touch while something else is in progress.
This creates invisible risk: the same wrong decision gets made twice, context gets re-explained from scratch every session, and two agents working in parallel can silently collide on the same files.
The pattern
Keep a docs/working-memory.md file in the project root. It is not documentation. It is not a changelog. It is the shared, current-state brain of the project, meant to be read at the start of every session before any code is written.
The file answers four questions:
- What is the current architecture?, the decisions that must not be undone
- What is in progress right now?, the protected work that should not be touched
- What is next?, the agreed next step, not a wishlist
- What changed recently and why?, enough context to reconstruct the reasoning
## Current Architecture
- Articles stored in Vercel KV via lib/content-db.ts
- Git is the source of truth for code, not for content
## Next 2 Steps
### 1. Surface asset readiness in the existing UI
What to do: show distributionState.assets in article editor cards
What not to touch: do not replace the Articles tab structure
### 2. Extend provider fallback to remaining generation routes
What not to touch: do not add per-run ceremony
## Recent Decisions
### 2026-04-24
- distributionState is now the per-article workflow record in KV
- Lazy backfill: if missing, it is built on first read from socialPosts
The update rule
The file only works if it stays current. The rule is simple: whenever a non-trivial decision is made, it gets written here in the same session, before the session ends.
Prefer facts over plans:
- what changed
- why it changed
- what must not be broken next time
Avoid aspirational entries. If something was decided but not yet built, it belongs in a backlog, not here.
For multi-agent workflows
When two agents (or a human and an agent) are working on the same codebase simultaneously, the working-memory file becomes a coordination layer.
Designate a protected lane, files and contracts that only one agent touches at a time. List what the other agent should not touch. This prevents merge collisions without requiring real-time communication.
## Parallel Lane For Claude
Claude can work on these areas while Codex works on the protected lane:
1. test coverage
2. documentation hygiene
3. UI copy polish
Claude should not touch:
- app/admin/page.tsx workflow rendering rewires
- shared distributionState contract changes
The working-memory file is where both agents agree on the boundary.
Why a flat file beats a ticket system for this
Ticket systems are great for task tracking. They are poor at preserving architectural reasoning in a form that an AI agent can read at the start of a session with zero additional context.
A flat Markdown file in the repo has three advantages:
- It is always co-located with the code, no separate system to open
- It can be read by an AI agent as part of the first tool call of a session
- It can be committed alongside code changes, making the decision and the implementation visible in the same diff
The file does not replace PRs, commit messages, or decision logs. It is the short-term working memory that keeps sessions coherent until decisions stabilize into those longer-lived artifacts.
Anti-patterns to avoid
Making it too long. Once it exceeds ~200 lines, agents start missing the critical parts. Keep it scannable.
Using it as a changelog. Recent decisions should drop off after they are no longer at risk of being undone. Rotate old entries out.
Skipping the update. The file is worthless if it is three sessions out of date. The update rule must be treated as non-negotiable, not optional.