Bloated Memory

Also known as

Bloated AGENTS.md, over-specified memory file, memory dump.

Context

For months, the team keeps adding to the project memory file. After every incident with the agent, developers add a rule, but rarely check whether it is still needed. The file grows and never shrinks.

Problem

The memory file accumulates hundreds of lines of duplicates, contradictions, and retellings of the code. The agent finds it harder to pick out the applicable instructions from the rest, so even a rule that is written down may go unheeded.

Why people do it

  • Every rule was needed at some point, and developers are afraid to delete it without knowing the original reason.
  • The team expects additional instructions to make the agent's behavior more predictable and does not check the effect of piling them up.
  • Developers put architecture descriptions and long procedures into memory that would be better off as separate documents.
  • The whole team adds to the file, but nobody is responsible for reviewing it.

Consequences

  • ➖ The agent misses the instruction it needs among all the others.
  • ➖ Every extra line costs tokens in every session that loads the file.
  • ➖ When instructions contradict each other, the agent may pick different rules in different sessions.
  • ➖ New colleagues have to wade through a long file to find the convention they need.

Signs

  • The file has hundreds of lines and keeps growing.
  • The agent does what the memory explicitly forbids.
  • The file retells the directory structure and dependencies that the agent can read in the repository.
  • Some rules are ones the agent follows even without the instruction.
  • Nobody can say why half of the lines are there.

A better way

Review the memory using the rule from the pattern of the same name. For each line, find out which mistake it prevents. If the agent gets the same information from the code or follows the rule without a reminder, the line can be deleted. Move long procedures into skills that load on demand. After trimming the file, check on real tasks whether the behavior you need is preserved.

Example

Before:

AGENTS.md has accumulated 420 lines. Most of it is an architecture overview, a list of packages, and copied linter rules. Among them, on line 287, is a ban on changing legacy code that the agent violated yesterday.

Architecture overview 120Deleted 265Package list 60Linter style guide 85Release procedure 95Skill /release 95Frontend rules 30src/frontend/AGENTS.md 30Legacy ban 5Required CI check 5Commands and conventions 25AGENTS.md (stays) 25
Architecture overview 120Deleted 265Package list 60Linter style guide 85Release procedure 95Skill /release 95Frontend rules 30src/frontend/AGENTS.md 30Legacy ban 5Required CI check 5Commands and conventions 25AGENTS.md (stays) 25

The diagram deletes 265 lines that repeat code and linter settings. Move the 95-line release procedure to a skill, the 30 frontend rules to src/frontend/AGENTS.md, and the five-line legacy ban to a required CI check. The root file keeps 25 lines of commands, conventions and pointers to area instructions.

After

AGENTS.md is down to 25 lines. The agent gets the release procedure from /release and reads src/frontend/AGENTS.md before frontend work. A required CI check rejects changes to legacy code.

  • Project Memory sets the rules for selecting and reviewing persistent instructions.
  • Skills let procedures load on demand.
  • Context Engineering explains how extra text gets in the way of using the information you need.
  • Premature Specification describes a similar attempt to gain control through excessive instructions.
  • Scheduled Maintenance keeps memory from bloating: a monthly pass removes duplicates and rules that change nothing.

results matching ""

    No results matching ""