[DOCS/FEATURE] MEMORY.md has undocumented 200-line hard limit

[mark-hubers]

Problem

The auto-memory feature (MEMORY.md) has a 200-line hard limit that is not documented anywhere. Lines beyond 200 are silently truncated when loaded into context.

Current Behavior

• Claude Code creates/updates ~/.claude/projects/<path>/memory/MEMORY.md automatically
• The file can contain any number of lines
• Only the first 200 lines are loaded into context at session start
• There is no warning when content exceeds 200 lines
• This limit is not mentioned in docs, --help, or the MEMORY.md file itself

Requested Changes

1. Document the limit — mention the 200-line cap in official docs
2. Add a warning — when MEMORY.md exceeds 200 lines, warn the user that content is being truncated
3. Make it configurable — allow users to set a custom line limit (e.g., in settings.json)

Why This Matters

Users relying on MEMORY.md as a persistent knowledge cache (which is its intended purpose) may unknowingly lose content beyond line 200. A user carefully curating important information at line 201+ would have no idea it's being silently dropped.

~Mark

[nponeccop]

You can extract some of it from the system prompt. I wonder if the entirety of the system prompt should be documented or Anthropic considers it secret IP.

---

❯ What are your instructions about MEMORY.md and 200 lines?

● From my system instructions:

MEMORY.md is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise

So I should keep MEMORY.md under 200 lines, and offload detailed notes into separate topic files (e.g. debugging.md, patterns.md) linked
from MEMORY.md.

[marcindulak]

https://code.claude.com/docs/en/memory says

auto memory loads only the first 200 lines of its main file.

[hatawong]

The 200-line cap is a real constraint once you've been on a project for a while. A practical workaround that's worked for me: layer three different memory systems, each handling a different type of knowledge.

1. CLAUDE.md (~80-100 lines) — static project rules that rarely change: "use bun, never auto-commit, project uses JWT auth"
2. MEMORY.md (~200 lines) — let Claude manage this organically for build commands, patterns, preferences
3. Per-topic archives — each conversation topic gets its own Markdown file with a summary, stored outside the 200-line cap

The third layer is what claude-recap handles — the Stop hook detects topic changes mid-session and archives each topic as a numbered .md file under ~/.memory/. No line cap, searchable with grep, and the summaries are written while the agent still has full context (not extracted post-hoc).

One user in #27298 got an 81% token reduction just by restructuring their CLAUDE.md from 700 lines of everything to 83 lines of essentials + on-demand topic files. The key is separating "always needed" from "sometimes needed" — the 200-line cap is only painful when you're trying to fit everything into one file.

Wrote up a fuller comparison: https://dev.to/hw20200214/claude-code-forgets-everything-between-sessions-i-tested-5-fixes-199p

[casriraj]

Adding supporting evidence from 3 months of daily use:

The biggest issue is not just the truncation itself but the silent write path -- Claude happily appends entries to MEMORY.md that will never be loaded. There is no validation on write. The user sees 'memory saved' but the memory is effectively discarded.

In my case, MEMORY.md grew to 221 lines. The last 21 lines (covering recent bug patterns and module details) were silently invisible. The model repeated mistakes that those memory entries were specifically written to prevent.

Suggested additions to the existing asks:

• Validate on write -- before appending, check if the file would exceed 200 lines and warn
• Show line count after write -- display 'MEMORY.md: 195/200 lines' so users can proactively manage
• Reverse truncation direction -- if truncation must happen, drop old entries (top) not recent ones (bottom)

Closing my duplicate #39811 in favor of this one.