Memory hygiene

Memory Hygiene

Persistent memory only works if it gets loaded. Most memory systems have a load window (line limit, token limit, or context budget). Entries past the window exist on disk but never reach the model. They become silent dead weight: the user thinks the rule is in effect, the agent never sees it.

This skill is for any project that uses Claude Code's MEMORY.md, CLAUDE.md, or a similar rules index.

The rules

1. Know your load window

Find the limit. For Claude Code's auto-memory: first 200 lines of MEMORY.md. Past that, truncated. Other tools have token limits or section limits — find yours and write it at the top of the file.

2. Keep index entries one line, ≤150 characters

Index files are indexes, not content. Each entry: title, link, one-line hook.

- [Topic title](path/to/topic.md) — one-line hook

Long entries push later entries past the truncation line. Detail goes in the linked file, never in the index.

3. One section per topic, never split

If "Feedback" appears at line 50 and again at line 220, half is loaded and half is silently lost. Audit periodically: grep -n '^## ' MEMORY.md to see all section headers.

4. Detect orphans regularly

Files that exist on disk but are not referenced from the index are dead. They will never be loaded.

cd memory/
for f in feedback_*.md; do
  grep -q "$f" MEMORY.md || echo "ORPHAN: $f"
done

Run this whenever you add a memory file. If anything prints, fix it (add to index or delete the file).

5. Verify load on add

When you add a new memory entry, check the line number of the new entry vs. the load window. If you put it at line 250 and the window is 200, it does not work. Move it up.

grep -n "feedback_new_thing.md" MEMORY.md
# If line number > load window, move it.

6. Compress before adding

When the index approaches the load window, do NOT just keep appending. Audit:

• Are any entries duplicated across sections?
• Are any verbose entries that could become one-liners?
• Are any obsolete (project killed, decision reversed, lesson superseded)?
• Are any project-specific deep details that belong in their topic file, not the index?

Compress first. Add second.

7. Backup before restructure

Any large rewrite of a memory index: copy to MEMORY.md.backup-YYYY-MM-DD first. Restructures lose information surprisingly often. Backup is cheap insurance.

Audit checklist

Run periodically (monthly, or whenever the file feels bloated):

1. Total lines vs. load window?         (target: ≤ window − 5 line safety margin)
2. Orphan files?                        (target: 0)
3. Sections appearing twice?            (target: 0)
4. Entries >150 chars?                  (target: refactor each)
5. Entries past load window?            (target: 0)
6. Backup exists from last restructure? (target: yes)

Why this is in Karpathy Pro Max

Memory hygiene is invisible until it fails. The user adds a feedback rule, sees it on disk, assumes it works. Six months later they wonder why the agent keeps making the same mistake. The rule was real, the file existed, but it never loaded — buried past line 240 of a 360-line index.

Most rule systems die this way. This skill prevents it.