Spring Cleaning Your AI Agent: How Context Hygiene Makes Claude Code Smarter

I had 498 permission rules protecting nothing — because one global setting was silently allowing everything.

That discovery kicked off a full context hygiene audit of my Claude Code setup. What I found was worse than I expected: a bloated instruction file repeating itself across sections, a memory index full of stale references, and a permissions file that had ballooned to 132KB while doing absolutely nothing useful. Every single session was paying the cost of loading all of this — and getting nothing back.

This post is about what I cleaned up, what I learned, and why you should probably do the same thing.

What Is Context Hygiene?

Every time Claude Code starts a session, it loads your configuration into its context window. That means CLAUDE.md (project instructions), MEMORY.md (accumulated knowledge), and your permissions file (what the agent is allowed to do). These aren't optional extras — they're read on every single interaction.

The context window has a fixed size. You can't make it bigger. But you can control how much of it gets consumed by configuration overhead versus actual work.

Context hygiene is the practice of keeping those configuration files lean, current, and non-redundant — so the agent spends its capacity on your problem, not on re-reading instructions it doesn't need.

Think of it like a cluttered desk. The desk is the same size whether it's covered in old papers or clean. But the clean desk lets you actually spread out your work.

The CLAUDE.md Bloat Problem

CLAUDE.md is the instruction file that tells Claude Code how your project works. Architecture, conventions, gotchas, common commands. It's the single most important file in your setup because it shapes every response.

Mine had grown to 121 lines. That doesn't sound bad until you look at what was in there.

I had the same gotcha documented in three different sections. The Turso ordering bug appeared in "Architecture," in "Gotchas," and again in "Common Tasks" as a note. Instructions about the admin API auth were in the top-level overview and in the gotchas section with slightly different wording. There were notes about projects I'd finished months ago. Commands I'd long since memorized. Warnings about issues I'd already fixed.

None of it was wrong. All of it was redundant or stale.

The cleanup process was straightforward:

1. Deduplicate. Search for any instruction that appears in more than one section. Keep the most specific version, delete the rest.
2. Remove resolved issues. If you fixed the bug, delete the warning about it. Keeping old warnings trains the agent to worry about things that no longer exist.
3. Cut what the agent already knows. Claude Code knows how to run npm run dev. You don't need to tell it. Reserve CLAUDE.md for things that are genuinely specific to your project.
4. Consolidate related rules. Five scattered notes about the admin API become one "Admin API" section with all the quirks in one place.

121 lines became 43. Not by losing information — by eliminating repetition and removing things that no longer applied.

Memory Pruning

MEMORY.md is Claude Code's accumulated knowledge index — a table of contents pointing to detailed knowledge files about your projects, tools, workflows, and preferences. It grows automatically as you work. And like any system that only grows, it eventually fills with dead weight.

My index had 65 entries. Some pointed to projects I'd archived. Others referenced tools I'd stopped using. A few were near-duplicates — two entries about the same workflow, created weeks apart, slightly different titles.

The problem isn't disk space. It's attention. Every entry in the memory index is a signal to the agent: "this matters." When half the entries point to things that don't matter anymore, the signal gets diluted.

I pruned it to 39 entries:

The rule I settled on: if I haven't referenced this entry in the last 30 days, and the underlying project or tool isn't active, it goes. If two entries cover the same topic, merge them into one.

The Permission Bomb

This was the real discovery. The one that made me question every session I'd run in the past three months.

Claude Code uses a permissions file to control what the agent can do — which commands it can run, which directories it can access, which tools it can invoke. Over time, I'd been adding specific rules. Granular stuff:

Allow: Bash(npm run build)
Allow: Bash(npx prisma generate)
Allow: Bash(git push origin main)
Allow: Bash(curl -X POST http://localhost:3000/api/admin/*)
...and 494 more

498 rules total. The file was 132KB. I felt good about this. Specific permissions. Least privilege. Security-conscious.

Then I found it. Buried somewhere in the middle of 498 rules, one line:

Allow: Bash

No arguments. No restrictions. A bare Bash permission that says "this agent can run any command it wants."

That single bare Bash permission was a superset of every other rule in the file. The agent didn't need Allow: Bash(npm run build) because Allow: Bash already covered it. It didn't need Allow: Bash(git push origin main) because Allow: Bash already covered that too.

Every single one of those 498 rules was doing nothing. They were load — parsed, stored, referenced — but functionally meaningless. The security posture I thought I had was theater.

How did this happen? Probably early on, during initial setup, I clicked "Allow" on a prompt without specifying a command. One quick approval in a moment of impatience. Then every subsequent "Allow this specific command?" prompt was just adding ornaments to a Christmas tree that was already on fire.

Before and After: The Full Picture

Here's the complete before-and-after for the audit:

The permissions change is the most dramatic. 132KB to 59 bytes. That's not a typo. The new file has 56 intentional, specific rules — and no global overrides. Every rule does exactly what it says.

But the numbers don't capture the real improvement. The agent is faster now. Not because it's a different model or a different plan — because it's not wading through 121 lines of contradicting instructions to figure out which version of the Turso gotcha to follow. There's only one version now.

The Single Source of Truth Principle

The root cause of most of the bloat was violating a principle that every engineer knows from databases: single source of truth. One fact should live in one place.

When I had the admin API auth requirement in both the overview section and the gotchas section of CLAUDE.md, two things happened. First, they drifted. One said "use Bearer token auth" and the other said "pass the admin password as a header." Both were partially correct, neither was complete. Second, the agent had to reconcile conflicting instructions — burning context window capacity on disambiguation instead of work.

The fix is boring but effective:

• One gotcha, one location. If the Turso ordering bug is documented, it's in the Gotchas section. Nowhere else.
• Memory entries point, they don't duplicate. A memory entry says "Turso has an ordering bug — see CLAUDE.md Gotchas." It doesn't re-explain the bug.
• Permissions are specific and non-overlapping. No global override hiding behind hundreds of specific rules.

# Bad — same fact in two places, slightly different
## Overview
Admin API uses Bearer token auth with ADMIN_PASSWORD

## Gotchas
Admin API: pass the admin password in the Authorization header

# Good — one place, complete
## Gotchas
Admin API auth: `Authorization: Bearer $ADMIN_PASSWORD` header required on all endpoints

When the agent reads one clear instruction instead of triangulating between two partial ones, the response quality improves immediately. Not because the model got smarter — because the input got cleaner.

Building a Monthly Cleanup Cadence

The audit took about 30 minutes. But it only worked because I'd let things accumulate for months. The better approach: don't let it get that bad.

I now run a context hygiene check on the first session of every month. Here's the checklist:

The whole check takes 10-15 minutes once it's a habit. The first time is longer because there's a backlog of accumulated cruft. After that, you're only dealing with one month of drift.

I also added a rule to my CLAUDE.md about the cleanup itself — which feels appropriately meta:

## Monthly Cleanup
First session of each month: audit CLAUDE.md and memory for stale content.

The agent now reminds me if I haven't done it. The system maintains itself.

The Cluttered Desk

There's a temptation to treat AI agent configuration as write-only. You add instructions when you discover a gotcha. You add memory entries when you start a new project. You click "Allow" when the permissions prompt interrupts your flow. The file only ever grows.

But here's the thing about a cluttered desk: you can still technically work at it. Every paper that's on it was important at some point. You can even find what you need if you dig long enough. It doesn't feel broken because it happened gradually.

The same thing happens with AI agent context. 121 lines of instructions still works. The agent still follows (most of) them. 498 permission rules don't cause an error — they just silently do nothing while making you think you're being careful. The degradation is invisible until you clean it up and feel the difference.

After the cleanup, I noticed the change immediately. Responses were more focused. The agent stopped hedging between contradicting instructions. It stopped asking for clarification on things that were clear — because the instructions were actually clear now, instead of being three slightly different versions of the same thing.

The context window is the same size it's always been. But the usable space inside it — the room available for actual reasoning, code generation, problem-solving — that changed dramatically. Same desk. Clear surface. Better work.

If you've been using Claude Code for more than a month and haven't audited your context files, now's the time. Check your permissions file for global overrides. Read your CLAUDE.md for duplicates. Prune your memory index. It'll take 30 minutes, and every session after that will be better for it.

Your agent is only as smart as the context you give it. Make sure you're not wasting half of it on instructions about bugs you already fixed.