Skip to main content
Agent Context System solves a context delivery problem: your coding agent starts every session from zero, rediscovering your project’s patterns, gotchas, and constraints from scratch. This system gives every agent on your team a shared, version-controlled source of project truth — so agents spend less time relearning and more time doing useful work.

​
The problem with agent memory today

Built-in tools like Claude Code auto memory and GitHub Copilot Memory do real work on the individual side. They remember your preferences, your shortcuts, your style. That’s a genuine improvement for developer experience. But there’s a layer they don’t cover: shared, reviewable, version-controlled project context. The stuff your whole team needs every agent — human or AI — to know. Without it, you hit the same walls:
  • The “rules of the repo” live in chat threads and tribal knowledge
  • A new agent or subagent starts without the constraints that matter
  • The agent learns something once, but you can’t review it like code
  • Context drifts because nobody promotes stable decisions into a shared source of truth
Agent Context System is a small, boring fix for this. It doesn’t replace built-in memory — it complements it. Built-in memory handles what the tool learns about you. This handles what every agent needs to know about your project.

​
The two-file approach

The system lives in two markdown files. Your 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 loaded into every agent session. Keep it under 120 lines of compressed project knowledge: patterns, boundaries, gotchas, commands, architecture.

.agents.local.md

Your personal scratchpad. Gitignored and never shared. Grows over time as the agent logs what it learns each session — dead ends, preferences, 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.

​
Why passive context outperforms active retrieval

There are two ways to give agents project knowledge: put it in the prompt on every turn (passive context), or ask the agent to look it up when needed (active retrieval). Research from Vercel’s evals shows the difference is stark: passive context achieves a 100% task pass rate; active retrieval achieves 53%. Available docs aren’t the same as used docs. When the agent has to decide to look something up, it often doesn’t. AGENTS.md is passive context. It loads automatically into every session, every turn, without the agent making any retrieval decision. That’s why it stays under 120 lines and uses compressed formats — dense beats verbose, and every line you add is a line that competes for attention with your actual instructions.

​
What’s different from built-in memory

Claude Code auto memory

Writes to ~/.claude/projects/ — local to Claude Code only. Useful for personal learning, but doesn’t cross to Copilot, Cursor, or Windsurf, and can’t be reviewed like code.

GitHub Copilot Memory

Remembers your personal preferences across sessions. Scoped to the individual developer, not the project. Not committed to the repo.

Agent Context System

Lives in your repo. Committed and shared. Works across every agent your team uses. Reviewable in PRs, versioned with the codebase, portable to every tool.

Why use both?

They solve different problems. Built-in memory knows about you. AGENTS.md knows about your project. Use both — they don’t overlap.

​
Supported agents

Agent Context System works with every major AI coding tool. The init command wires up the right config file for each one automatically.
AgentConfig wired up by init
Claude CodeCLAUDE.md symlink → AGENTS.md
GitHub Copilot.github/copilot-instructions.md
Cursor.cursorrules
Windsurf.windsurfrules
OpenClawReads AGENTS.md natively via skill
Subagents — like those spawned by Claude Code or Copilot CLI’s /fleet — don’t inherit the main conversation’s history. Each one starts with a clean context window. AGENTS.md is the only shared knowledge they all have by default, which makes it load-bearing when you’re running parallel agents on a task.

​
Key features

Auto-reflect

Agents observe significant events during sessions and surface patterns worth promoting at session end. Three modes: suggest (default), auto-promote, or off.

Auto-consolidation

Daily logs compress automatically into curated topic files when triggered by time and session count. ~9:1 compression ratio, zero infrastructure required.

Promote workflow

Patterns that recur across 3+ sessions get flagged in the scratchpad’s “Ready to Promote” section. You decide when to move them into AGENTS.md.

CLI tools

agent-context init, validate, and promote commands handle setup, health checks, and the promotion workflow from a single script.

​
Get started

Quick start

Install Agent Context System and get your agent reading persistent project context in under 5 minutes.