Auto-memory system lacks clear boundary with CLAUDE.md, leading to scope creep

Resolved 💬 3 comments Opened Mar 13, 2026 by antonio-mello-ai Closed Apr 12, 2026

Problem

The auto-memory system (MEMORY.md + sub-files) has no clear boundary separating it from CLAUDE.md, which causes the memory system to gradually absorb operational instructions, how-tos, and behavioral rules that belong in CLAUDE.md. Over time, power users end up with two competing instruction systems with no well-defined frontier.

How it happens

  1. The memory prompt defines broad save categories — user, feedback, project, reference — that naturally overlap with CLAUDE.md content (e.g., "reference" memories about deploy checklists, credential locations, or tool configurations are effectively operational instructions)
  2. MEMORY.md has a 200-line limit, which is reasonable
  3. When the limit is hit, the system suggests: "Move detailed content into separate topic files and keep MEMORY.md as a concise index"
  4. This treats the symptom (too many lines) rather than the cause (wrong content type being saved)
  5. Result: a proliferation of memory/*.md sub-files containing operational how-tos, tool configurations, and behavioral rules — content that should live in CLAUDE.md

Concrete example

After ~3 weeks of intensive use across multiple projects, my MEMORY.md contained:

  • Deploy checklists (operational instruction → belongs in CLAUDE.md)
  • Credential locations and connection details (operational reference → CLAUDE.md)
  • "Always use QMD as default search" (behavioral rule → CLAUDE.md)
  • MCP server configurations (derivable from claude mcp list — shouldn't be saved at all)
  • Infrastructure details (derivable from project docs — shouldn't be saved at all)

Mixed in with actual memory content:

  • User profile and preferences (correct use of memory)
  • Strategic decisions with rationale (correct use of memory)
  • Feedback corrections (correct use of memory)

Root cause

The memory prompt's "What NOT to save" section says to avoid "code patterns, architecture, file paths" but doesn't address the more common failure mode: saving behavioral instructions and operational how-tos that are CLAUDE.md content, not memory.

The distinction should be simple:

  • Memory: facts learned about the user/context that can't be derived from code or config (who they are, decisions made, feedback given)
  • CLAUDE.md: instructions for how to behave, operate, and execute tasks

But this boundary isn't explicit in the current prompt, so the model defaults to saving everything useful → memory bloat → sub-file workarounds.

Suggested improvement

  1. Add an explicit boundary rule to the memory prompt: "If the content is an instruction for how you should behave or operate (a rule, checklist, how-to, or workflow), it belongs in CLAUDE.md, not memory. Memory stores facts about the user and context, not instructions for yourself."
  2. Consider adding a self-check before saving: "Would this content make more sense as a CLAUDE.md instruction than as a memory? If yes, suggest adding it to CLAUDE.md instead."
  3. The "move to sub-files" guidance should include a warning: "If you're creating sub-files to store operational instructions or how-tos, that content likely belongs in CLAUDE.md instead."

Impact

  • Power users accumulate redundant/competing instruction sources
  • Memory sub-files become a shadow CLAUDE.md with no versioning or review
  • The 200-line limit loses its effectiveness when bypassed with unlimited sub-files
  • Model behavior becomes unpredictable when instructions come from both CLAUDE.md and memory files

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗