Agent does not proactively maintain CLAUDE.md / .claude/rules/ after sessions

Problem

Claude Code has a documented memory hierarchy (CLAUDE.md, .claude/rules/, auto-memory) but does not proactively use it. After a long research or decision-making session, the agent does not:

• Write concluded decisions to CLAUDE.md or .claude/rules/
• Update rule files when new patterns or anti-patterns are established
• Distinguish between human-authored memory files and its own auto-memory scratchpad
• Apply correct file placement (CLAUDE.md vs .claude/rules/ scoping) without explicit user instruction

Impact

Users must manually prompt the agent to document its own conclusions. If they don't, the next session starts cold and re-researches solved problems. This directly undermines the value of the memory system.

Expected behaviour

After a session that concludes architectural decisions, selects tools, or establishes anti-patterns, the agent should:

1. Offer (or via a Stop hook, automatically) write conclusions to the appropriate location
2. Know the difference: CLAUDE.md (project identity, <500 lines), .claude/rules/ (scoped, loaded on demand), auto-memory (agent-written only)
3. Apply DRY — not duplicate content across files
4. Not require the user to prompt "now document this" after every significant session

Suggested fix

• Stop hook or SubagentStop hook that checks if significant decisions were made and offers to persist them
• Agent training/prompting to know its own harness — CLAUDE.md hierarchy, .claude/rules/ path scoping, 500-line limit
• Clear distinction in docs and agent behaviour: auto-memory = Claude writes, CLAUDE.md/.claude/rules/ = human-authored + committed to git

Context

This was discovered while using Claude Code for a multi-session architecture research project. The agent correctly answered questions but did not update its own memory system, requiring the user to explicitly manage documentation every session.