Audit and document the memory maintenance pipeline end to end

[Lyellr88]

Summary

Audit and tighten the memory maintenance pipeline docs and code comments so contributors can follow the lifecycle from write to consolidation to compaction more easily.

Discussion: #49

Why this matters

The stack is still intentionally lightweight, but the internal flow is no longer trivial. Right now the maintenance pipeline includes:

• write queue behavior
• consolidation
• compaction staging
• compaction apply/discard
• fallback summarization

This is a good first issue for someone who likes reading code carefully and improving clarity without changing behavior.

Good first scope

• Audit current docs and comments for the pipeline
• Tighten any stale or ambiguous descriptions
• Add concise comments only where the flow is hard to infer
• Prefer clarification over refactor

Candidate files

• README.md
• MCP-HANDBOOK.md
• docs/current/**
• marm_mcp_server/endpoints/compaction.py
• marm_mcp_server/services/compaction_apply.py
• marm_mcp_server/core/memory.py

Constraints

• No behavior changes required
• Keep edits surgical
• Avoid comment bloat and narration

[tomatotomata]

I’m taking the surgical documentation pass for the memory maintenance pipeline. I’ll trace the write, consolidation, staging, apply/discard, and fallback paths, then update only stale descriptions or add a few clarifying comments where the flow is hard to infer. No behavior changes or comment narration. Let me know what you think.