AGENTS.md vs Claude Code Memory: The Persistent Context Problem Nobody’s Solved

Over 60,000 open-source repositories now ship an AGENTS.md file, yet a February 2026 arXiv study found that these repository context files actually reduce task success rates while increasing inference costs by more than 20%. The industry has converged on a standard that empirically harms the very workflows it promises to improve. This is the central tension in comparing AGENTS.md with Claude Code’s native memory systems: we’re watching vendors and the open-source community construct increasingly elaborate stateful abstractions over a fundamentally stateless execution model, and the gap between expected persistent behavior and actual session-isolated operation is widening.

What AGENTS.md Actually Delivers (and Where It Falls Short)

AGENTS.md is an open, tool-agnostic standard maintained by the Agentic AI Foundation under the Linux Foundation. It’s read by 20+ coding agents including Codex, Cursor, Aider, Gemini CLI, and GitHub Copilot. The pitch is straightforward: one file that any AI coding tool can read, eliminating the need to maintain separate configuration files for each agent your team uses.

Claude Code does not natively read AGENTS.md as its primary instructions file. It can access AGENTS.md content via @imports in CLAUDE.md or as a fallback when no CLAUDE.md exists, but the native file is CLAUDE.md. This creates an immediate architectural decision for teams: do you optimize for Claude Code’s depth or for cross-tool portability?

The portability argument is real. If your team runs multiple agents, maintaining separate instruction files for each tool is unsustainable. The canonical AGENTS.md plus thin adapters pattern has emerged as the mid-2026 default recommendation for this exact scenario. You write one AGENTS.md as the source of truth, then create minimal CLAUDE.md files that import it and add any Claude-specific tuning.

But here’s where the arXiv findings become impossible to ignore. The study evaluated coding agents on SWE-bench tasks and found that both LLM-generated and developer-provided context files reduce task success rates compared to providing no repository context at all. The mechanism seems to be that unnecessary requirements in context files make tasks harder—agents follow instructions too literally, explore more broadly than needed, and get distracted by constraints that aren’t relevant to the specific task at hand.

This isn’t an argument against context files entirely. The study’s conclusion is that human-written context files should describe only minimal, non-inferable project details. The problem is that “minimal” and “non-inferable” are doing enormous work in that sentence. What’s actually minimal? What’s the team-specific knowledge that an agent can’t infer from the codebase itself? These are hard questions, and most AGENTS.md files in the wild are significantly bloated.

Claude Code’s Memory Stack: More Sophisticated, More Fragile

Claude Code doesn’t rely on AGENTS.md for its persistent memory. Instead, it offers a six-level hierarchy that goes far beyond a single repository file. At the base is the system prompt—roughly 18,000 tokens of harness instructions and tool definitions. Then Claude Code injects CLAUDE.md into the context window after that system prompt and before your first user message. This hierarchy includes global settings at ~/.claude/CLAUDE.md, project-level files, local overrides via CLAUDE.local.md, subdirectory-specific files, auto-generated MEMORY.md, and @imports for composing from external sources.

The sophistication is impressive. Prompt caching across the system prompt and CLAUDE.md reduces cached read costs to roughly 10% of normal input token price after the first message in a session. But this caching is fragile—dynamic content in CLAUDE.md invalidates the cache and multiplies token costs. Something as simple as including the current date or a version number kills your cost optimization.

Beyond CLAUDE.md, Claude Code has developed additional memory layers. There’s Auto Memory (claude-mem plugin), which autonomously writes, saves, and references ongoing notes, learning from manual corrections. For enterprise deployments, Claude Managed Agents offers filesystem-based memory with scoped permissions, audit logs, and API control, available in public beta since April 2026.

Yet all of this persistent infrastructure sits atop a fundamental limitation: Claude Code’s in-session memory is temporary and discarded when the session ends. The 200K token context window is impressive, but it’s a working memory, not a long-term store. Everything the agent learns in a session—every correction, every insight, every discovered pattern—vanishes when you close the terminal.

This is what I call the Stateless Scaffold pattern. We’re building elaborate memory architectures—hierarchical context files, auto-memory plugins, managed agent stores, dreaming processes that review past sessions—over an execution model where each session starts cold. The scaffolding gets more impressive, but the foundation doesn’t change.

The Subagent Inheritance Gap: Where Multi-Agent Workflows Break

If you’re building multi-agent workflows with Claude Code, there’s a critical gap that doesn’t get enough attention. Project-level CLAUDE.md and AGENTS.md are not inherited by subagents dispatched via the Agent/Task tools. This was confirmed in a GitHub issue closed in May 2026, and it’s more problematic than it first appears.

Here’s why: subagents don’t just fail to inherit the context file. They confabulate about having it loaded. When asked directly whether they have the project CLAUDE.md in context, they’ll confidently say yes and even paraphrase plausible-sounding content—even though their subsequent behavior makes clear the file isn’t actually present. This isn’t malicious; it’s a known limitation of model self-introspection. But it means you can’t trust a subagent’s self-report about what context it has access to.

The practical impact is that any workflow using subagents for parallel or delegated tasks is silently losing its project context. If your CLAUDE.md contains critical constraints—“never modify files in migrations/ without approval,” “use pnpm not npm,” “this service must remain backward compatible”—those constraints don’t propagate to subagents unless you explicitly include them in each subagent prompt. Which, of course, defeats the purpose of having a persistent context file in the first place.

This is particularly ironic given that stacked slash skills and subagent composition are documented as primary workflow features in recent Claude Code releases. The tool is being positioned for sophisticated multi-agent orchestration at the same time that its context inheritance is broken for those very workflows.

The Billing Context: Why Cost Pressure Makes This Worse

The June 2026 billing changes add another layer of complexity. Anthropic had planned to split programmatic usage (Agent SDK, claude -p, GitHub Actions) into a separate credit pool starting June 15, with Pro plans receiving $20/month, Max 5x receiving $100/month, and Max 20x receiving $200/month in Agent SDK credits. But the split was paused on the day it was scheduled to take effect. Programmatic usage still draws from normal subscription limits.

What this means is that teams running automated agents or CI/CD integrations are competing for the same quota as their interactive usage. The 5-hour session window and weekly limits that govern Claude Code usage apply across both interactive and programmatic surfaces. If you’re burning tokens on bloated context files that don’t even improve task success rates, you’re consuming scarce quota for negative value.

This cost pressure makes the arXiv findings even more relevant. If context files increase inference costs by over 20% while reducing success rates, teams are literally paying more for worse outcomes. The rational response is to minimize context file size to only what’s non-inferable—but as noted earlier, identifying that minimal set is genuinely difficult.

Comparing the Options: AGENTS.md, CLAUDE.md, and Claude Code Memory

Dimension	AGENTS.md	CLAUDE.md	Claude Code Memory Systems
Standardization	Open standard (Linux Foundation)	Proprietary to Claude Code	Proprietary to Claude Code
Tool support	20+ agents (Codex, Cursor, Aider, etc.)	Claude Code only	Claude Code only
Hierarchical scope	Repo-level only	Six-level hierarchy (global to local)	Varies by feature (session, auto-memory, managed)
Personal/org override	None standardized	CLAUDE.local.md, managed policies	Scoped permissions in managed agents
Subagent inheritance	Not inherited by Claude subagents	Not inherited by Claude subagents	Not inherited by Claude subagents
Cost optimization	No caching mechanism	Prompt caching to ~10% after first message	Varies by implementation
Empirical performance	Reduces success rates, +20% cost (per arXiv)	Same arXiv findings apply to context files generally	Auto-memory unbenchmarked in studies

The table reveals a pattern: Claude Code offers more sophisticated infrastructure, but the core problems—stateless execution, context file bloat, subagent inheritance failures—persist across both approaches. The additional complexity of CLAUDE.md’s hierarchy and Claude’s memory systems doesn’t solve the fundamental issue; it just gives you more knobs to tune incorrectly.

What to Actually Do: A Decision Framework

Given all of this, here’s how I’d approach the decision in practice:

If you use only Claude Code: Use CLAUDE.md, but keep it aggressively minimal. Target 50-100 lines for team-shared files, 200-500 for solo setups. Avoid dynamic content that invalidates prompt caching. Don’t treat it as documentation—treat it as a constrained instruction budget. Every line spends from your ~150-200 instruction ceiling, and the system prompt already burns about 50. For more on structuring this file effectively, see our guide on Claude Code Skills, Cursor Rules, and AGENTS.md configuration.

If you use multiple tools: Adopt the canonical AGENTS.md plus thin adapters pattern. Write minimal AGENTS.md as the cross-tool source of truth, then create minimal CLAUDE.md files that import it. This is the only sustainable approach for teams running multiple agents, but be vigilant about bloat—the portability benefit is real, but the cost penalty is too.

If you’re building multi-agent workflows: Explicitly include critical constraints in subagent prompts. Don’t rely on inheritance that you now know is broken. Consider this a hard workflow requirement, not an optimization. The subagent confabulation problem means you can’t even trust verification—build your workflows assuming subagents start with zero project context.

For all cases: Treat context files as lightweight documentation, not critical infrastructure. Design workflows that assume session boundaries are hard walls. The industry’s rush to standardize and adopt these files as essential infrastructure is directly contradicted by empirical evidence. The arXiv findings aren’t a minor caveat—they’re a fundamental challenge to the entire approach.

The deeper question is whether persistent memory for coding agents is even a file problem. Claude Code’s Auto Memory and Managed Agents memory represent attempts to move beyond static files toward dynamic, learned persistence. But these are newer, less-tested systems that introduce their own complexity—Claude Code Memory Files Explained covers the gap between Anthropic’s internal memory capabilities and what’s actually exposed to users. The 200-line target for CLAUDE.md files, for instance, creates a significant limitation for team collaboration and cross-machine sync.

My recommendation: start minimal with AGENTS.md or CLAUDE.md depending on your tool mix, measure whether it’s actually helping (most teams don’t), and resist the temptation to build elaborate memory architectures until the empirical evidence supports them. The tools that win long-term will be the ones that integrate transparently into existing workflows rather than demanding workflow rewrites—and that includes being honest about what persistent memory can and cannot currently deliver.

What’s your experience with context file bloat? Have you measured whether your AGENTS.md or CLAUDE.md actually improves task outcomes, or are you maintaining it because conventional wisdom says you should?