Agent Context System

The Problem

Agents start from zero every session. You spend an hour getting your coding agent up to speed on a project, close the session, and start from zero the next day. The agent forgot everything. Every session is a cold start.

This isn't a limitation of the model. It's a context delivery problem. The agents have the capacity to remember — they just don't have the right inputs at the right time in the right format.

The Solution

Two markdown files. One committed, one gitignored. The agent reads both at the start of every session and updates the local one at the end.

• AGENTS.md — Your project's source of truth. Committed and shared. Always in the agent's prompt. Under 120 lines. Contains compressed project knowledge: patterns, boundaries, gotchas, commands, architecture.

• .agents.local.md — Your personal scratchpad. Gitignored. Grows over time as the agent logs what it learns each session. Session notes, dead ends, preferences, patterns that haven't been promoted yet.

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

How It Works

1. Setup

Run the init script. It creates .agents.local.md from a template, ensures it's gitignored, and wires up your agent tool's config (CLAUDE.md symlink for Claude Code, .cursorrules for Cursor, .windsurfrules for Windsurf, copilot-instructions.md for Copilot).

# If you cloned the template repo:
./scripts/init-agent-context.sh

# If you installed as a skill (npx skills add):
bash .agents/skills/agent-context-system/scripts/init-agent-context.sh

Then edit AGENTS.md with your project specifics: name, stack, commands, actual patterns and gotchas from your codebase. This is the highest-leverage edit you'll make.

2. During Sessions

The agent reads both files at session start. AGENTS.md gives it compressed project knowledge. .agents.local.md gives it accumulated learnings from past sessions. The agent now has context that persists across sessions.

At session end, the agent proposes the session log entry to the user before writing. The agent must not append directly — it shows the proposed entry and waits for user approval before writing to .agents.local.md. Most agents (Copilot Chat, Cursor, Windsurf) don't have session-end hooks, so this depends on Rule 7 in AGENTS.md being seen and acted on, or the user saying "log this session." Claude Code handles this automatically via auto memory.

3. Over Time

The scratchpad grows. When it hits 300 lines, the agent compresses: deduplicate, merge related entries, keep it tight. During compression, if a pattern has shown up across 3+ sessions, the agent flags it in the scratchpad's "Ready to Promote" section using the same pipe-delimited format that AGENTS.md expects.