Last weekend, I sat down to write the actual file.
Not a diagram of it. Not a post about why it matters. The file itself — the CLIENT.md that goes into every agentic AI system I build for retainer clients.
I've been talking about context as the retainer moat for months. Tuesday's piece named the problem: most agency-built agents are missing a persistent memory layer, so they stay frozen at week-1 capability no matter how many months the client is paying. This is the follow-up. What does that memory layer actually look like — section by section — for a real client type?
I'm building this in public because I want the accountability. And because the AI automation space is full of "here's the concept" posts and almost nothing that shows the artefact itself.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧠 Why an AI Agent Needs a CLIENT.md
Every session your AI agent runs, it starts from scratch. No memory of what the client told you in month 1. No memory of the mistake that lost you a client in month 2. No memory of the approval process the client uses, the tone they hate, the shortcuts they've granted, the decisions already made, and closed.
This isn't a Claude problem or an OpenAI problem. It's how large language models work by default. Each run is stateless unless you deliberately build state in.
Anthropic confirmed the commercial cost of this at scale. When they shipped persistent memory for Claude Managed Agents on April 23, 2026, the early data from Rakuten showed 97% fewer first-pass errors when agents carried context across sessions versus starting fresh each time. Rakuten also reported a 27% cost reduction. Netflix is using the same mechanism to eliminate the need to manually re-explain context to reviewers in every session.
Those are enterprise-scale deployments. But the same physics applies to a solo agency owner running a $500/month retainer for a SaaS founder.
Without a CLIENT.md: Your agent stays at week-1 capability indefinitely. The client feels it. By month 4, they're wondering why the system still makes the same avoidable mistakes it made in month 1 — and they start the conversation about whether to continue.
That conversation is the retainer death spiral. The CLIENT.md is what prevents it.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🏗️ The Three Memory Types That Actually Matter for Agency Work
There's a taxonomy rabbit hole here I want to acknowledge and then step around. Nir Diamant's Agent Memory Techniques repo covers 30 distinct memory techniques across six families — episodic, semantic, procedural, cross-session, entity, and more. It's excellent. If you're building production memory infrastructure, go there.
For agency retainer work, I've reduced the 30 to three that matter:
📌 Entity Memory — facts about specific people, projects, preferences, constraints. Who is this client, what do they care about, what have they explicitly said no to?
🔧 Procedural Memory — the playbooks the agent has learned from working with this client. How they communicate, what their approval process looks like, what tone works in their market, what shortcuts they've granted the agent over time.
⚡ Cross-Session Memory — decisions made, corrections given, incidents logged, context built over months. The kind of institutional knowledge that makes a 12-month retainer client feel like the agent genuinely knows their business.
These three combined — scoped to a single client, loaded at session start — is the practical CLIENT.md pattern. Anthropic's own context engineering documentation calls this pattern "structured note-taking" and describes a NOTES.md approach where agents write and retrieve context outside the context window. CLIENT.md is that pattern, named and structured for agency retainer work specifically.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 What I'm Actually Building — The Persona
I'm building the v1 CLIENT.md template against one specific persona: a 5-person SaaS founder automating customer success. I'll call her Priya.
Priya runs a B2B SaaS product. Her customers are mid-market HR teams — not technical buyers, not C-suite. She's hired an AI automation agency (that's me, in this exercise) on a monthly retainer to build and maintain her customer success agent stack: onboarding sequences, health score monitoring, renewal trigger detection.
Here's what happens without a CLIENT.md in Priya's stack:
❌ Month 1: Agent is set up. Works well. Priya is happy.
❌ Month 2: Two customers get automated messages using the wrong tone — too casual for HR buyers. Priya flags it. The agent is corrected. No record of why.
❌ Month 3: Agent is re-run after a platform update. Same tone mistake resurfaces. Priya escalates.
❌ Month 4: Priya starts the conversation about whether this retainer is working.
The problem is not the agent's capability. The problem is that every session started from zero. The correction in month 2 lived in an email thread, not in the agent's context. The agent had no way to know about it.
With a CLIENT.md, the month 2 correction becomes a permanent entry under Procedural Memory: "Tone rule: Priya's customers are HR managers, not developers. Formal-warm, never casual. No exclamation points in automated messages." Every session that runs after that loads the rule.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 The v1 Template — Six Sections
This is what I'm building. Not finished — v1 means it's in progress. But the structure is locked, and I'm filling in Priya's worked example against each section.
🔴 Section 1 — Client Identity: Company name, founder name, team size, product type, target customer. The entity facts the agent needs in every prompt context.
🔴 Section 2 — Business Context: What matters to this client commercially. Priya's health scoring system (green/amber/red, her own definition), her renewal cycle (annual contracts, 60-day notice window), her churn sensitivity (two churns in month 2 are still a live concern).
🔴 Section 3 — Communication Rules: Tone profile. Escalation rules. What the agent can send autonomously vs. what requires Priya's approval. For Priya: renewal conversations are never automated — she handles those personally. This is a hard rule.
🔴 Section 4 — Procedural Playbooks: The step-by-step processes the agent has learned for this client. Onboarding flow. Health check cadence. How to handle a customer who goes amber.
🔴 Section 5 — Decisions Log: Dated entries for every significant architectural or product decision. When a rule was added, why, what incident triggered it. This is the institutional knowledge layer.
🔴 Section 6 — Active Flags: Current open items. Priya's customers who are in amber status. The platform update scheduled for next month that the agent needs to account for. The things that change session to session.
The full template — with Priya's worked example filled in across all six sections — is what I'm packaging as the lead magnet for this post. You can use it as a starting point for your own clients. Adapt the sections to your niche. The structure is the same whether your client is a solo coach, a freelance copywriter, or a 10-person agency.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 Why This Is the Real Switching Cost
The retainer moat I keep talking about isn't the code you wrote in month 1. Code can be replicated. Platforms can be swapped. Another agency can rebuild your Make.com workflows in a weekend.
What can't be replicated is the CLIENT.md that's been growing for 12 months. Every rule. Every correction. Every decision. Every incident. Every preference Priya has ever expressed — captured, dated, loaded at session start.
By month 12, a client trying to switch to a different agency isn't just switching tools. They're starting their institutional knowledge from zero. The new agency's agent will make the exact mistakes your agent stopped making in month 3. That friction is real. That's the switching cost. That's what compounding context actually means.
Anthropic is building this at the platform level — their Managed Agents memory beta is filesystem-based, exportable, cross-agent, and growing more capable with each model release. The direction of travel is clear. For agency owners building retainer businesses today, the question isn't whether to build a memory layer. It's how deliberately you're building it.
The CLIENT.md is the deliberate version. Cheap to start. Compounds over time. Fully under your control.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🤝 What's in the Template
I've packaged the v1 CLIENT.md template as a PDF — the actual file, not a description of it. Here's what's inside:
📌 The blank six-section template with field-by-field instructions for filling it in
📌 Priya's worked example — a fully populated CLIENT.md for a 5-person SaaS founder running customer success automation
📌 A decision log starter — the exact format I use for capturing rule changes and incident-driven updates
📌 A "session loader" prompt — the system prompt snippet that instructs the agent to load CLIENT.md at the start of every run
📌 A v1 → v2 upgrade checklist — what to add to the template after your first 30 days with a live client
If you're building AI agent retainers — or planning to — this is the foundation document I wish I'd had at the start. Comment BLUEPRINT on the LinkedIn post for this newsletter and I'll DM it to you directly. Free PDF, no email capture.
👉 Join the RFA Skool Community — where I'm sharing the full build-in-public journey, every workflow, every version, and every lesson from the CLIENT.md and beyond.
📬 Subscribe to the newsletter for the next piece in the series — what happens when your CLIENT.md grows past 500 lines and you need a retrieval strategy.
Sources
1. Anthropic Managed Agents Memory public beta (April 23, 2026) — ETIH coverage · SD Times
2. Nir Diamant — Agent Memory Techniques (30 runnable notebooks) — github.com/NirDiamant/agents-towards-production
3. Anthropic — Effective Context Engineering for AI Agents — anthropic.com/engineering
4. Skywork AI — Claude Memory deep dive (CLAUDE.md architecture) — skywork.ai