Coding agents are good at using context. They are terrible at keeping it consistent.

Tools like GitHub Copilot Memory are doing great work on the individual side. Copilot remembers your preferences, your patterns, your stack. That's a real step forward for developer experience.

But there's a layer that built-in memory doesn't cover: shared, reviewable, version-controlled project context. The stuff that lives in your repo and works across every agent your team uses. Teams still 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, then you can't review it like code
• Context drifts because nobody promotes stable decisions into a shared source of truth

This project is a small, boring fix. 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. It makes that context explicit, reviewable, and portable.

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 is your project's source of truth. Committed and shared. Always in the agent's prompt.
• .agents.local.md is your personal scratchpad. Gitignored. It grows over time as the agent logs what it learns each session.

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

your-repo/
├── AGENTS.md                    # Committed. Always loaded. Under 120 lines.
├── .agents.local.md             # Gitignored. Personal scratchpad.
├── agent-context                # CLI: init, validate, promote commands.
├── agent_docs/                  # Deeper docs. Read only when needed.
│   ├── conventions.md
│   ├── architecture.md
│   └── gotchas.md
├── scripts/
│   └── init-agent-context.sh    # Wrapper → calls agent-context init (for npx skills)
└── CLAUDE.md                    # Symlink → AGENTS.md (created by init)

Note: agent-context is the main CLI. scripts/init-agent-context.sh is a thin wrapper for backwards compatibility with npx skills add installs — it just calls agent-context init.

Choose one method based on your agent and needs:

Use the official Copilot skill registry. Gets you updates automatically.

npx skills add AndreaGriffiths11/agent-context-system
bash .agents/skills/agent-context-system/scripts/init-agent-context.sh

Clone into your skills directory. Works natively with OpenClaw's skill system.

git clone https://github.com/AndreaGriffiths11/agent-context-system.git skills/agent-context-system

Restart your OpenClaw session. It will read AGENTS.md automatically.

Copy just the files you need. Good for customizing or if you don't want package managers.

# Clone to a temp location
git clone https://github.com/AndreaGriffiths11/agent-context-system.git /tmp/acs

# Copy the core files
cp /tmp/acs/AGENTS.md /tmp/acs/agent-context ./
cp -r /tmp/acs/agent_docs /tmp/acs/scripts ./

# Initialize
./agent-context init

# Cleanup
rm -rf /tmp/acs

Then add your agent's config file manually:

• Claude Code: Already handled by init (creates CLAUDE.md symlink)
• Cursor: Create .cursorrules with Read AGENTS.md before starting
• Windsurf: Create .windsurfrules with Read AGENTS.md before starting
• Copilot: Create .github/copilot-instructions.md with Read AGENTS.md before starting

Start a new repo from this template, then initialize.

gh repo create my-project --template AndreaGriffiths11/agent-context-system
cd my-project
./agent-context init

Fork this repo if you want to customize templates or contribute back.

gh repo fork AndreaGriffiths11/agent-context-system
git clone https://github.com/YOUR_USERNAME/agent-context-system.git

Which should I choose?

agent-context init      # Set up context system in current project
agent-context validate  # Check setup is correct
agent-context promote   # Find patterns to move from scratchpad to AGENTS.md
agent-context promote --autopromote  # Auto-append patterns recurring 3+ times

1. Write: Agent logs learnings to .agents.local.md at session end
2. Compress: Scratchpad compresses when it hits 300 lines
3. Flag: Patterns recurring 3+ times get flagged "Ready to Promote"
4. Promote: Run agent-context promote to review, or --autopromote to auto-append to AGENTS.md

Subagents: When one becomes five

Claude Code has subagents. Copilot CLI has /fleet (experimental). Both dispatch parallel agents that don't inherit conversation history.

Each subagent starts fresh. The only shared brain is your root instruction file. AGENTS.md goes from "helpful context" to "the only thing preventing five agents from making conflicting decisions."

This is why the template explicitly tells subagents to read .agents.local.md too. They won't get it otherwise.

1. Edit AGENTS.md — Fill in your project name, stack, commands. Replace placeholders with real patterns from your codebase.
2. Fill in agent_docs/ — Add deeper references. Delete what doesn't apply.
3. Customize .agents.local.md — Add your preferences.
4. Work — Agent reads both files, does the task, updates scratchpad.
5. Promote — Run agent-context promote to see flagged patterns. Move stable ones to AGENTS.md.

I use OpenClaw. Do I need this?

If OpenClaw is your only coding agent, you probably don't — OpenClaw reads AGENTS.md natively. But if you also code with Claude Code, Cursor, Copilot, or Windsurf, agent-context gives you one shared context file that works across every agent. Write your project rules once, every tool picks them up.

How is this different from built-in memory (Claude auto memory, Copilot Memory)?

Built-in memory learns about you — your preferences, patterns, style. Agent-context handles what every agent needs to know about your project — stack, conventions, architecture decisions. It's shared, version-controlled, and reviewable in PRs.

Why 120 lines?

HumanLayer found frontier LLMs follow ~150-200 instructions reliably. Your agent's system prompt uses ~50. That leaves ~120 for project context. Deeper docs go in agent_docs/ and load on demand.

MIT