[DOCS] Clarify CLAUDE.md Persistence Through Context Compression Cycles

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Affected Documentation Pages: - memory.md - hooks.md - hooks-guide.md - checkpointing.md - settings.md --- #### Problem Statement The current documentation does not clearly explain whether CLAUDE.md file content persists through context compression cycles (manual /compact or automatic compression when context window fills). This creates uncertainty for users who: 1. Rely on CLAUDE.md instructions to direct Claude Code behavior (e.g., "use MCP memory-server for all planning") 2. Use hooks to enforce project-specific workflows 3. Need to ensure critical instructions remain active throughout long sessions 4. Integrate external memory systems (MCP servers) that require consistent behavior --- #### Specific Documentation Gaps ##### 1. memory.md - CLAUDE.md Lifecycle Current State: - Documents that CLAUDE.md files are "automatically loaded into Claude Code's context when launched" - Explains hierarchical loading (user → project → local) Missing Information: - ❓ Does CLAUDE.md content remain in system prompt after compression? - ❓ If not preserved, what mechanism re-loads it? - ❓ Do users need hooks to restore CLAUDE.md directives post-compression? ##### 2. hooks.md - Post-Compression Hooks Current State: - Documents PreCompact hook (runs before compression) - Documents SessionStart hook (runs "when Claude Code starts or resumes a session") Missing Information: - ❓ Does a PostCompact hook exist? (Only PreCompact documented) - ❓ Does SessionStart fire after automatic compression events? - ❓ Can hooks inject/restore CLAUDE.md content after compression? - ❓ What hook patterns preserve context through compression? Example Use Case: ```json { "hooks": { "SessionStart": [{ "type": "prompt", "prompt": "Review CLAUDE.md for memory storage preferences." }] } } Does this pattern ensure CLAUDE.md instructions remain active after compression? 3. checkpointing.md - Compression vs. Checkpointing Current State: - Explains code state restoration via checkpoints - Notes checkpoints track file edits, not bash commands Missing Information: - ❓ How does context compression relate to checkpointing? - ❓ When restoring "conversation + code", does CLAUDE.md context restore? - ❓ Are CLAUDE.md instructions part of "conversation" or "system prompt"? 4. settings.md - Compression Configuration Current State: - Mentions CLAUDE.md as "instructions and context that Claude loads at startup" Missing Information: - ❓ Are there settings controlling CLAUDE.md persistence behavior? - ❓ Can users configure compression strategy for system prompts? - ❓ Does cleanupPeriodDays affect CLAUDE.md availability? --- Requested Documentation Enhancements Please add sections addressing: 1. Context Compression Mechanics (new section or addition to memory.md) - What content is preserved vs. summarized during compression - Whether system prompts (CLAUDE.md) remain verbatim or are compressed - Token budget allocation for CLAUDE.md vs. conversation history 2. CLAUDE.md Lifecycle Through Compression (addition to memory.md) - Explicit confirmation: "CLAUDE.md content [is/is not] preserved through compression" - If not preserved: recommended patterns for restoration - If preserved: confirmation it remains in full context 3. Hook Patterns for Context Preservation (addition to hooks-guide.md) - Example: Using PreCompact to store context to external memory - Example: Using SessionStart to restore critical instructions - Clarify whether PostCompact hook exists or is planned 4. Compression Event Lifecycle (new diagram or addition to hooks.md) [Before Compression] → PreCompact hooks → [Compression] → ??? → SessionStart hooks? 4. Show which hooks fire and when CLAUDE.md content is available

Current Documentation

The current documentation does not clearly explain whether CLAUDE.md file content persists through context compression cycles
(manual /compact or automatic compression when context window fills). This creates uncertainty for users who:

1. Rely on CLAUDE.md instructions to direct Claude Code behavior (e.g., "use MCP memory-server for all planning")
2. Use hooks to enforce project-specific workflows
3. Need to ensure critical instructions remain active throughout long sessions
4. Integrate external memory systems (MCP servers) that require consistent behavior

Affected Documentation Pages:

• memory.md
• hooks.md
• hooks-guide.md
• checkpointing.md
• settings.md

What's Wrong or Missing?

Specific Documentation Gaps

1. memory.md - CLAUDE.md Lifecycle

Current State:

• Documents that CLAUDE.md files are "automatically loaded into Claude Code's context when launched"
• Explains hierarchical loading (user → project → local)

Missing Information:

• ❓ Does CLAUDE.md content remain in system prompt after compression?
• ❓ If not preserved, what mechanism re-loads it?
• ❓ Do users need hooks to restore CLAUDE.md directives post-compression?

2. hooks.md - Post-Compression Hooks

Current State:

• Documents PreCompact hook (runs before compression)
• Documents SessionStart hook (runs "when Claude Code starts or resumes a session")

Missing Information:

• ❓ Does a PostCompact hook exist? (Only PreCompact documented)
• ❓ Does SessionStart fire after automatic compression events?
• ❓ Can hooks inject/restore CLAUDE.md content after compression?
• ❓ What hook patterns preserve context through compression?

Example Use Case:

{
"hooks": {
  "SessionStart": [{
    "type": "prompt",
    "prompt": "Review CLAUDE.md for memory storage preferences."
  }]
}
}
Does this pattern ensure CLAUDE.md instructions remain active after compression?

3. checkpointing.md - Compression vs. Checkpointing

Current State:
- Explains code state restoration via checkpoints
- Notes checkpoints track file edits, not bash commands

Missing Information:
- ❓ How does context compression relate to checkpointing?
- ❓ When restoring "conversation + code", does CLAUDE.md context restore?
- ❓ Are CLAUDE.md instructions part of "conversation" or "system prompt"?

4. settings.md - Compression Configuration

Current State:
- Mentions CLAUDE.md as "instructions and context that Claude loads at startup"

Missing Information:
- ❓ Are there settings controlling CLAUDE.md persistence behavior?
- ❓ Can users configure compression strategy for system prompts?
- ❓ Does cleanupPeriodDays affect CLAUDE.md availability?


### Suggested Improvement

Requested Documentation Enhancements

Please add sections addressing:

1. Context Compression Mechanics (new section or addition to memory.md)
- What content is preserved vs. summarized during compression
- Whether system prompts (CLAUDE.md) remain verbatim or are compressed
- Token budget allocation for CLAUDE.md vs. conversation history
2. CLAUDE.md Lifecycle Through Compression (addition to memory.md)
- Explicit confirmation: "CLAUDE.md content [is/is not] preserved through compression"
- If not preserved: recommended patterns for restoration
- If preserved: confirmation it remains in full context
3. Hook Patterns for Context Preservation (addition to hooks-guide.md)
- Example: Using PreCompact to store context to external memory
- Example: Using SessionStart to restore critical instructions
- Clarify whether PostCompact hook exists or is planned
4. Compression Event Lifecycle (new diagram or addition to hooks.md)
[Before Compression] → PreCompact hooks → [Compression] → ??? → SessionStart hooks?
4. Show which hooks fire and when CLAUDE.md content is available

### Impact

Medium - Makes feature difficult to understand

### Additional Context

_No response_