How Agent Context System works: the two-file model

Learn how two markdown files solve the agent cold-start problem and give your coding agent persistent, reviewable project knowledge across every session.

Every time you start a new agent session, your agent starts from zero. You spend time re-explaining your project’s conventions, reminding it about gotchas it already fixed last week, and repeating decisions that took hours to reach. This is the cold-start problem — not a model limitation, but a context delivery problem. The Agent Context System solves it with two markdown files and a session workflow your agent follows automatically.

The cold-start problem

Agents are stateless by design. Each session opens with a blank context window. Anything your agent learned in a previous session — the pattern you established, the dead end you already explored, the architectural decision you made — is gone. You either re-explain it every time, or the agent rediscovers it from scratch.

The cost compounds as your project grows. The more conventions, boundaries, and gotchas your codebase accumulates, the more time each session wastes on context re-establishment instead of actual work.

The two-file solution

The Agent Context System gives your agent two files to read at the start of every session:

AGENTS.md

Committed and shared. Always loaded into the agent’s prompt. Stays under 120 lines. Contains compressed project knowledge: patterns, boundaries, gotchas, commands, and architecture. Every agent on your team reads this file.

.agents.local.md

Gitignored and personal. Your private scratchpad. Grows over time as the agent logs what it learns at the end of each session. Session notes, dead ends, preferences, and patterns that haven’t been promoted yet.

No plugins, no infrastructure, no background processes. The convention lives inside the files themselves, and the agent follows it.

The session workflow

1. Agent reads both files at session start

   When you open a session, the agent reads AGENTS.md first — giving it compressed project knowledge it can act on immediately. Then it reads .agents.local.md, loading accumulated learnings from past sessions. The agent now has context that persists across sessions without you lifting a finger.

2. Agent does the task

   With both files loaded, the agent works with the full context of your project: the patterns to follow, the boundaries to respect, the gotchas to avoid. It doesn’t need to rediscover these things — they’re already in its prompt.

3. Agent logs learnings at session end

   At the end of the session, the agent appends a session log entry to .agents.local.md: what changed, what worked, what didn’t, decisions made, patterns learned. The scratchpad grows over time, building up a personal knowledge base specific to you and your project.

Agents don’t have session-end hooks. Sessions end when you stop talking. Logging only happens if you prompt the agent: “log this session” or “update the scratchpad.” Claude Code handles this automatically via auto memory. For other agents, build the habit of asking for a log when meaningful work was done.

Why passive context beats active retrieval

You might wonder: why not just keep all this knowledge in separate reference docs and let the agent look things up when it needs them?

Vercel ran evals that answer this directly:

Approach	Pass rate
No docs	53%
Skills (agent decides when to read)	53%
Compressed docs embedded in root file	100%

Available docs are not the same as used docs. When the agent must decide to look something up, it often doesn’t — and performance is identical to having no docs at all. When knowledge is embedded directly in the prompt, the agent cannot miss it.

This is why AGENTS.md is designed to be passive context: always loaded, always present, always applied. The agent doesn’t choose to use it — it’s already there.

Keep your AGENTS.md dense. Use pipe-delimited shorthand for patterns, boundaries, and gotchas. Every line you write becomes context the agent carries on every single turn.

The instruction budget

Frontier LLMs reliably follow about 150-200 instructions. Claude Code’s built-in system prompt already uses around 50 of those. That leaves roughly 120 instructions for your project context — which is exactly why AGENTS.md has a 120-line limit.

Going over that limit doesn’t give you more coverage. It gives you instructions that quietly get deprioritized. Staying under 120 lines is a feature, not a constraint.

This budget matters even more when you use subagents. Each subagent spawned by a lead agent starts fresh with a clean context window. If your AGENTS.md is 500 lines, you’re paying that token cost for every agent you spawn — and still risking deprioritization. Under 120 lines keeps the shared brain lean and reliable.