This is the fourth post in a series about context management in AI-assisted work. The first covered the problem, the second a practical fix using .md files as external memory, and the third explored how those files map to agent memory architecture. That third post ended with a prediction: multi-agent workflows would need shared memory stores to work well.

I recently split my single-agent setup into a team — a Lead, a Builder, and a Validator — for a personal CMS migration project. The workflow change was obvious. What surprised me was how much the context architecture changed with it.

The single-agent context problem

In a single-agent setup, one context window holds everything: project decisions, implementation details, validation findings, debugging sessions. My five .md files (CLAUDE.md, PROGRESS.md, DECISIONS.md, TECHNICAL.md, HANDOVER.md) helped enormously — they externalized state so it survived across sessions.

But within a session, the window was still a soup of concerns. Claude would be mid-way through writing an AEM component, holding HTL syntax and Sling Model patterns in context, when I'd interrupt with a validation finding. Now the window contains both implementation and correction context, competing for attention. The .md files solved the cross-session problem. They didn't solve the within-session attention problem.

Separated concerns, separated context

With the team split, each agent's context window stays focused on its domain.

The Builder's window is full of AEM patterns, HTL syntax, component specifications, and Maven configuration. When the Validator sends a finding, the Builder receives a targeted fix description — not a sprawling comparison against the Sitecore original. The correction is scoped to what the Builder needs to act on.

The Validator's window is full of Sitecore reference material, visual comparison results, and accessibility checks. It never sees the implementation complexity of how the Builder chose to structure the Sling Model. It just evaluates the output.

The Lead's window holds project state — the migration map, progress, decisions, blockers — without any implementation or validation detail. It reads the .md files, coordinates priorities, and triages the Validator's findings into actionable tasks for the Builder.

This is the principle from the first post taken one step further. Context hygiene isn't just about what the AI remembers across sessions — it's about what it's paying attention to right now. Fewer concerns in the window means higher attention quality on each one.

The .md files became a shared memory layer

Here's what I didn't expect: the file-based memory system I built for a single agent turned out to be exactly the shared context layer the team needs.

CLAUDE.md is the project constitution all three agents reference. DECISIONS.md prevents any agent from re-litigating settled choices. PROGRESS.md gives the Lead a build log to coordinate from. HANDOVER.md captures session state so the whole team can resume cleanly.

The new addition — MIGRATION-MAP.md — is the work queue both Builder and Validator reference. The Lead updates component status as work progresses. It's the shared memory store I predicted in the third post would replace "agents shouting across a room."

And VALIDATION.md is the Validator's findings log. The Lead reads it to triage priorities. The Builder reads it to understand what needs fixing. Three agents, one document, three different uses.

The files didn't change. What changed is that instead of one agent reading and writing them, multiple agents share them as coordination state — each reading what's relevant to their role, each writing to the parts they own.

What this maps to

In my third post, I mapped the five .md files to memory architecture concepts: long-term knowledge, episodic memory, working memory. The agent team setup adds a new dimension: scoped retrieval. Each agent loads only the context relevant to its role from the shared files, rather than one agent loading everything.

The Builder doesn't need to read VALIDATION.md in full — it gets the specific findings relevant to the component it's working on. The Validator doesn't need TECHNICAL.md — it evaluates output, not implementation strategy. The Lead reads everything but writes no code.

This mirrors what the agent memory research calls "role-based context filtering" — different retrieval strategies for different agent types, drawing from the same underlying store. I'm doing it manually through prompt instructions ("Builder: read MIGRATION-MAP.md for your current task"). The automated version would be a retrieval layer that serves each agent the right slice of shared memory without explicit instructions.

Where the ceiling is now

The file-based approach works, but it has an obvious scaling limit. With three agents and six .md files, the coordination is manageable. With ten agents and twenty files, it would be chaos. The manual approach — explicit read/write instructions in the prompts — doesn't scale gracefully.

The next evolution is probably what I described in the third post: a structured semantic layer that agents query rather than files they read in full. But for a team of three on a well-scoped migration project, the .md files are more than sufficient. Sometimes the crude solution is the right solution.

Context management got me from "the AI keeps forgetting" to "the AI remembers but I'm the bottleneck." Agent teams got me from "I'm the bottleneck" to "I'm the stakeholder." The shared files are what makes the team coherent instead of chaotic.