Skip to main content
Common questions about the Agent Context System, gathered from real usage across Claude Code, Cursor, Copilot, Windsurf, and OpenClaw.
If OpenClaw is your only coding agent, you probably don’t — OpenClaw reads AGENTS.md natively without any wrapper or directive.Where it becomes useful is 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 in AGENTS.md, and every tool picks them up through its own config file. You also get the promotion workflow, instruction budget discipline, and the scratchpad — none of which depend on OpenClaw specifically.
Built-in memory learns about you — your preferences, patterns, and style. It is personal and agent-specific.Agent-context handles what every agent needs to know about your project — the stack, architecture decisions, conventions, and known traps. It is shared, version-controlled, and reviewable in PRs. When a new developer joins the team or you switch agents mid-project, AGENTS.md gives every tool the same grounding from day one.The two systems are complementary. Claude auto memory tracks your preferences; AGENTS.md tracks your project’s conventions. Both load at session start; they cover different things.
HumanLayer’s research found that frontier LLMs reliably follow approximately 150–200 instructions. A coding agent’s system prompt already uses around 50 of those slots. That leaves roughly 120 lines for project context before instructions start competing for attention and getting quietly deprioritized.The 120-line limit is not a style constraint — it is an instruction budget constraint. Content that fits in AGENTS.md is passive context: it loads into every prompt on every turn. Content that exceeds the budget belongs in agent_docs/, where it loads on demand when a task requires it.Vercel’s evals showed passive context achieves 100% task pass rate versus 53% when agents must decide to look things up. Dense beats verbose. Keeping AGENTS.md lean means what is there is actually followed.
Yes, and subagents are one of the strongest arguments for using the system.Claude Code can spawn subagents that run tasks in parallel. Each subagent starts with a clean context window — it does not inherit the main conversation’s history. The only shared knowledge across all subagents is your root instruction file. When you go from one agent to five parallel agents, AGENTS.md goes from “helpful context” to the only thing preventing five agents from making conflicting decisions about your codebase.The template’s Rule 1 explicitly applies to subagents: “Read this file and .agents/local.md (if it exists) before starting any task. This applies whether you are the main agent or a subagent.” Without that instruction, subagents skip the scratchpad entirely.GitHub Copilot CLI’s /fleet command has experimental subagent support. The same principle applies: each fleet agent starts fresh, and AGENTS.md is the shared brain.Keeping AGENTS.md under 120 lines also matters more with subagents. A 500-line file costs that token budget for every subagent spawned, multiplied across the fleet.
Compression triggers at 300 lines. The agent deduplicates entries, merges related session notes, and trims the file back down. Compression is logged in the ## Compression Log section so you have an audit trail of what happened to older notes.During compression, the agent scans for patterns that have appeared across three or more sessions. Those patterns get flagged in the ## Ready to Promote section using the same pipe-delimited format that AGENTS.md expects. The flagged items stay in the scratchpad until you explicitly promote them — either manually by copying them into AGENTS.md, or automatically with agent-context promote --autopromote.You can also trigger consolidation manually at any time:
./scripts/consolidate-memory.sh
Or preview what would happen without writing:
./scripts/consolidate-memory.sh --dry-run
Only in auto promote mode, which you opt into explicitly. The default behavior is suggest mode.The system checks the promote mode from .agents.local.md — look for the comment <!-- auto-reflect: promote=auto|suggest|off -->:
  • suggest (default if not set): The agent writes flagged patterns to ## Ready to Promote in the scratchpad only. It never touches AGENTS.md without your approval. You use agent-context promote --autopromote when you are ready to move them.
  • auto: The agent promotes patterns directly to AGENTS.md and logs the promotion under ## Auto-Promoted in the scratchpad. Use this only if you trust the agent’s pattern-detection and want a fully automated workflow.
  • off: Reflection is skipped entirely.
In all modes, the agent must show you a proposed session log entry and wait for approval before appending to the scratchpad. Scratchpad writes are never fully automatic.