The instruction budget is
your real bottleneck
Two markdown files. Persistent memory across sessions.
Works with every AI coding agent.
Context engineering is a fundamental
Git. Tests. CI. The stuff that doesn't change every six months. The stuff that makes everything else easier once you learn it. Context engineering just made the list.
The frustrating pattern: spend an hour getting an agent up to speed on a project — conventions, gotchas, architecture — then close the session and start from zero the next day. Every session is a cold start.
This template fixes that. Two markdown files. The agent reads both at the start of every session and updates the local one at the end. No plugins, no infrastructure. Just files.
How it works
Two files, one idea. Committed knowledge + personal scratchpad.
AGENTS.md
Committed • Shared • Always loaded
Your project's source of truth. Stack, commands, architecture, compressed knowledge. Under 120 lines. Every agent gets this on every turn.
## Project - Stack: TypeScript, Next.js 15, Prisma - Commands: pnpm build | pnpm test ## Patterns named exports only | src/components/ Result<T,E> over throw | src/lib/errors.ts
.agents.local.md
Gitignored • Personal • Grows over time
Your personal scratchpad. The agent logs learnings at the end of each session. Patterns that recur get flagged for promotion to AGENTS.md.
## Session Log ### 2026-02-07 — Auth refactor - Learned: middleware can't access DB - Worked: JWT-only checks at edge ## Ready to Promote edge middleware is JWT-only | auth
Knowledge lifecycle
Built on research, not vibes
Every design decision comes from real data about how agents consume context.
Instructions per session
HumanLayer found frontier LLMs reliably follow about 150-200 instructions. Claude Code's system prompt uses ~50. That's why AGENTS.md stays under 120 lines.
HumanLayer research →Pass rate with passive context
Vercel's evals: embedded docs = 100% pass. Skills where agents decide to read = 53%. Same as having nothing. Passive context beats active retrieval.
Vercel evals →Repos analyzed
GitHub found the files that work are specific. Executable commands early. Code examples over prose. Explicit boundaries. "Helpful assistant" does nothing.
GitHub analysis →When subagents enter the picture
Subagents don't inherit conversation history. AGENTS.md is the only shared brain preventing five parallel agents from making conflicting decisions.
Claude subagents docs →What subagents actually see
AGENTS.md is the only context that flows to every parallel agent.
Works with every agent
AGENTS.md is the cross-platform standard. One file, every tool.
| Agent | Setup |
|---|---|
 OpenClaw |
Clone into skills/ directory — reads AGENTS.md natively
|
 Cursor | Reads AGENTS.md natively. Nothing to configure. |
| GitHub Copilot & Copilot CLI | Reads AGENTS.md natively. Nothing to configure. |
| Codex | Reads AGENTS.md natively. Nothing to configure. |
 Windsurf | Reads AGENTS.md natively. Nothing to configure. |
 Claude Code | CLAUDE.md symlink → AGENTS.md (created by init)
|
Auto-Reflect
Your agent observes, reflects, and learns — automatically
Continuous observation
Your agent logs what happens during sessions — tool usage patterns, corrections, preferences — building a living record in .agents.local.md.
Session-end reflection
At the end of each session, your agent reviews its observations, identifies recurring patterns, and surfaces them as candidates for promotion into AGENTS.md.
.agents.local.md
## Scratchpad (auto-updated) - User prefers pnpm over npm (observed 4 sessions) - Always run lint before committing (corrected twice) - Test files use .spec.ts, not .test.ts ## Ready to Promote | Pattern | Seen | Action | |--------------------------------|------|----------| | pnpm over npm | 4× | suggest | | lint before commit | 3× | suggest | | .spec.ts naming convention | 2× | observe |
suggest Default — asks before promoting
auto Promotes when confident
off No reflection, manual only
Inspired by Mastra's Observational Memory research
Quick start
One command. Under a minute.
1 GitHub template Recommended
# Create from template gh repo create my-project --template AndreaGriffiths11/agent-context-system # Initialize cd my-project ./agent-context init
2 Existing project
# Clone and copy files git clone https://github.com/AndreaGriffiths11/agent-context-system.git /tmp/acs cp /tmp/acs/AGENTS.md /tmp/acs/agent-context /tmp/acs/agent_docs your-project/ # Initialize cd your-project ./agent-context init
3 OpenClaw users
# Clone into your skills directory
git clone https://github.com/AndreaGriffiths11/agent-context-system.git skills/agent-context-system OpenClaw picks it up as a workspace skill on the next session.
4 Copilot CLI skill
# Install as a Copilot CLI skill
npx skills add AndreaGriffiths11/agent-context-system
bash .agents/skills/agent-context-system/scripts/init-agent-context.sh After setup
- 1. Edit AGENTS.md — Fill in your stack, commands, patterns. The template has examples to show the format.
- 2. Edit agent_docs/ — Replace the examples with your project's architecture, conventions, gotchas.
- 3. Work — The agent reads both files, does the task, updates the scratchpad.
- 4. Promote — Run
agent-context promoteto find recurring patterns ready for AGENTS.md.
FAQ
Common questions about how this fits your workflow.
I use OpenClaw. Do I need this?
If OpenClaw is your only coding agent, you probably don't. OpenClaw reads AGENTS.md natively and handles session context on its own.
But if you also code with Claude Code, Cursor, Copilot, or Windsurf, this is where it gets useful. Agent-context gives you one shared context file that works across every agent. Write your project rules once in AGENTS.md, and every tool your team uses picks them up — no per-tool configuration, no drift between agents.
How is this different from built-in memory (Claude auto memory, Copilot Memory)?
Built-in memory learns about you — your preferences, patterns, style. It's personal and tool-specific. 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 like any other code.
Why is AGENTS.md capped at 120 lines?
Research from HumanLayer found frontier LLMs reliably follow about 150-200 instructions per session. Your agent's system prompt already uses ~50. That leaves room for about 120 lines of project context before instruction-following quality degrades. Deeper docs go in agent_docs/ and are loaded on demand.
Does this require any infrastructure or plugins?
No. It's two markdown files and a bash CLI. No background processes, no API keys, no dependencies beyond bash. The convention lives inside the files themselves.
Stop starting from zero
Two files. Persistent memory. Every agent.