The prevailing belief that CLAUDE.md, AGENTS.md, or Cursor rules constitute true agent memory is fundamentally flawed, according to a recent analysis published on DEV.to. The author argues that these markdown files, which are simply loaded into the context window, function more like growing sticky notes than intelligent recall systems. While acceptable for solo experimentation, this approach collapses under the weight of multi-developer workflows, creating fragmented knowledge silos that agents cannot bridge.

The Solo Developer's Context Trap

Even for a single developer, the file-based approach degrades rapidly over months. The agent loads the entire file every session, consuming valuable context tokens with irrelevant or outdated information. There is no search capability; the file is read top-to-bottom or ignored entirely. Past investigations, such as ruling out specific connection pool issues, often vanish from the record, forcing agents to repeat the same dead-end analyses. Furthermore, switching tools between Claude Code, Cursor, and Codex splits memory into three distinct, non-communicating silos on the same machine.

Team Collaboration Breaks Down

When multiple developers are involved, the limitations become catastrophic. The article outlines a scenario where one developer, Ana, solves a flaky checkout test caused by a timezone default in fixtures. Her agent records this in her local memory. However, when teammate Ben encounters a similar failure in the billing job, his Cursor session has no access to Ana's findings. It starts from zero, repeating the same two-hour investigation. This lack of shared recall means the knowledge exists, but it is trapped in the wrong agent's context window.

Bloat, Contradictions, and Merge Conflicts

Teams attempting to fix this by committing a shared CLAUDE.md file often end up with a 1,400-line monolith where half the entries describe code that no longer exists. Contradictions pile up, such as conflicting instructions to 'always use the v2 client' versus 'v2 client is deprecated.' Because agents are excellent at appending but poor at deleting, stale entries silently mislead. When multiple agents update the same file, it creates merge conflicts that developers resolve carelessly, accepting both sides and further polluting the context with noise.

Rules Without Reasons Are Dangerous

A critical failure of markdown memory is the loss of reasoning. Files often contain imperative rules like 'Don't use Redis for the job queue' without the accompanying context of why that decision was made. Was it cost? Ops burden? A past incident? Without the 'why,' agents may blindly follow outdated rules or 'improve' them away incorrectly. New teammates cannot challenge these rules because the historical context is absent, turning shared memory into a source of confusion rather than clarity.

Practical Mitigations for File-Based Systems

For teams sticking with files, the author recommends strict hygiene. Keep CLAUDE.md under 200 lines, containing only stable, imperative rules. Move decision rationale to separate, dated files in a docs/decisions/ folder, linked from the main rules file. Crucially, agents must propose memory changes via pull requests rather than committing them directly, ensuring human review. A monthly pruning schedule is also essential to delete stale entries, as outdated memory is more dangerous than no memory at all.

Key Takeaways

  • Markdown files are context loaders, not searchable memory databases.
  • Tool-switching fragments agent knowledge across separate silos.
  • Shared CLAUDE.md files rapidly bloat with contradictory, stale data.
  • Missing 'why' context leads agents to blindly follow or incorrectly discard rules.
  • Proposed changes to memory files should require human review via PRs.

The Bottom Line

True agent memory requires semantic search and shared state, not just bigger context windows. Until we move beyond markdown blobs, teams are just coordinating their amnesia.