Housekeeping: Context Drift Management for Claude Code

THE CONTEXT DRIFT PROBLEM

When you run Claude Code sessions for hours or days, you hit a fundamental problem that plagues all LLM agents: context drift. Claude gradually forgets things in CLAUDE.md, starts pattern-matching to expectations instead of examining actual evidence, and accumulates cruft in its working memory.

I have watched Claude sessions confidently declare bugs fixed without testing, hallucinate command outputs that were never shown, and rediscover the same solutions I documented weeks ago. I wrote lots of instructions to combat this in CLAUDE.md, but the longer the session runs, the more it drifts from these instructions. This is a result of session context compaction; the procedure by which the session context has pieces of information either shorted through summarization (which loses context almost by definition) or outright removal. This is done algorithmically by the model making determinations as to what is still needed or not and summarizing or eliminating data accordingly. As you might have guessed, information in context not used for a period of time (like those rules) tend to get eliminated first. This leads to Claude failing to obey them, and "apologizing" profusely when you call it out. It promises that it won't happen again.... But it will.

Even worse, completed work clutters the TODO lists. Every session startup wastes thousands of tokens re-reading ancient completed tasks from months ago. Project documentation files balloon to 500+ lines when they should be concise indexes. Critical insights discovered at 2 AM get lost when the session closes.

This is not a Claude problem. It is a stateless agent problem. Every session starts fresh, and every long session gradually degrades.

WHY HOUSEKEEPING SOLVES THIS

I run a "housekeeping" command periodically during complex sessions. Think of it as defragmenting your AI's brain. It does three things that directly combat context drift:

1. REFRESH THE RULES: Explicitly re-state the cardinal rules that tend to drift. These include things like "No conclusions without evidence. Always use MCP tools. Verify user literals before operations." This is like hitting the reset button on the parts of the system prompt that degrade over time.
2. CAPTURE INSTITUTIONAL KNOWLEDGE: Store discoveries in MCP memory so the next session does not start from zero. Error patterns, user preferences, system quirks, solutions that worked. Build a knowledge base that persists across sessions. Tribal knowledge is captured and available for retrieval when needed.
3. CLEAN UP THE CRUFT: Archive completed TODOs, trim bloated documentation, remove one-off test scripts. Reduce the startup context window from 8-12% to 3-5%. Less noise means better signal.

HOW IT WORKS

When I say "housekeeping", here is what happens:

STEP 1: MEMORY REFRESH
Claude re-reads and acknowledges the critical rules. Not all rules, just the ones that drift most. For example:

• No conclusions based on anything other than direct examination of actual evidence. Look at screenshots and describe only what is visible. Read code and report only what is written. Test functionality and report only what happens. No pattern matching, no assumptions, no hallucinations.
• Always use the MCP tools. Sequential-thinking for complex planning. Serena for semantic code search instead of grep. Memory for storing persistent insights. Task tool for delegating complex work.
• Verify user-provided literals before any operation. Claude Code has (or had, by now) a known bug where it corrupts IDs, callsigns, strings, and filenames. Always confirm the exact value before proceeding.
• Genuine verification required. Do not go through the motions of checking without actually analyzing results. If you can immediately know something is broken after I push back without re-examining evidence, you failed the initial verification.

STEP 2: SESSION HANDOFF UPDATE
Update the project's .session_handoff file with what was accomplished, what was learned, and what is next. Keep it under 200 lines. This file is the bridge between sessions. Without it, the next session has no idea what happened.

STEP 3: PROJECT DOCUMENTATION CHECK

I maintain an both an overarching CLAUDE.md AND one for each project, with generic and project specific information, respectively. This keeps the main CLAUDE.md down in size, yet allows me to have important context for a given project in memory as needed. Housekeeping checks if the project's CLAUDE.md file is getting too large (over 100 lines). If it is, extract details into separate docs and keep CLAUDE.md as a concise index. Bloated instruction files slow down every session startup. I will cover more about how I treat separate projects in another post.

STEP 4: CAPTURE TRIBAL KNOWLEDGE
Store discoveries in MCP memory so future sessions can benefit. Error patterns we discovered, user preferences observed, system quirks found, solutions that worked. This builds institutional knowledge that persists.

Example: After debugging a Ghost blog stuck in 503 state, Claude noted that: "Ghost can be active in systemd but stuck serving 503 errors. Apache access logs are authoritative, not Ghost's own logs. Service restart clears stuck state." Now, having stored that in MCP memory, every future session knows this without rediscovering it.

STEP 5: TODO ARCHIVE
Archive completed TODOs to reduce startup context. Completed items go into yearly archive files like PROJECT_TODO_ARCHIVE_2026.md. This keeps the active TODO list focused on current work.

Before archival: 347 lines of TODOs
After archival: 89 lines of active TODOs.
Context reduction: 74% fewer tokens wasted at startup.

STEP 6: DOCUMENT NEW DISCOVERIES
If we discovered something important during the session, create documentation in the project's docs/ folder. Examples: incident reports, architecture decisions, deployment procedures, debugging guides. Documentation is the memory that lasts beyond MCP.

STEP 7: CLEANUP SUGGESTIONS
Identify temporary test scripts that can be removed. Look for files named test_.py, debug_.py, verify_*.py, or anything with _old, _broken, _temp in the name. Suggest removal if they were one-time debugging aids. Less clutter means faster navigation.

STEP 8: SESSION SUMMARY
Claude provides a summary of what housekeeping accomplished:

• How many lines saved in session handoff
• CLAUDE.md status
• How many TODOs archived and context reduction percentage
• How many insights stored to MCP memory
• What documentation was created
• Active reminders for the next session

THE RESULTS

Before I implemented regular housekeeping:

• Sessions would claim bugs were fixed without testing
• I would find the same error pattern documented in 3 different files because sessions forgot it was already solved
• TODO lists had 400+ lines with completions from months ago
• Startup time was slow because Claude re-read mountains of obsolete context

After implementing regular housekeeping:

• Sessions stay disciplined about evidence-based verification
• Institutional knowledge builds session to session
• TODO lists stay focused on current work
• Startup context reduced by 60-75%
• I can switch between 18 different projects and each session picks up exactly where the last one left off. Again, I will make another post that discusses how I isolate projects with Claude Code.

HOUSEKEEPING IS MAINTENANCE FOR CLAUDE CODE

You would not run a database without vacuuming. You would not run a server without clearing old logs. You would not run a development environment without cleaning up test files. Housekeeping is the same principle applied to Claude Code. Regular maintenance that prevents degradation, builds institutional knowledge, and keeps sessions efficient. Without it, you are fighting context drift every day. With it, you have a Claude Code environment that gets smarter over time instead of forgetting everything when the session closes.