The Three-File System That Fixed Claude Code's Amnesia Across 11 Projects

ZTW — Wed, 02 Sep 2026 08:58:25 +0000

I run Claude Code across eleven projects at the same time.

Not eleven files. Eleven separate products, each with its own stack, its own history, and its own set of decisions I made months ago and no longer remember making.

At one project, session amnesia is a papercut. At eleven, it is the job.

This is the structure that finally fixed it. No prompt engineering, no clever wording — just files, and hooks that enforce them.

The problem isn't that CLAUDE.md doesn't work

It works fine. That's what makes the failure so slow to notice.

You write a good CLAUDE.md. The agent reads it. Things improve. So when a new problem appears, you add a section. Then another. Six weeks later the file is 400 lines, half of it is stale project state, and the agent is quietly ignoring the middle of it because the rules are buried under a changelog.

The mistake isn't the length. The mistake is that you put three different kinds of information in one file, and they change at completely different rates.

Split by rate of change, not by topic

Here's the split that fixed it:

Layer	File	Changes	Compressed?
Law	`CLAUDE.md`	Rarely, deliberately	Never
State	`PROGRESS.md`	Every work turn	After 24h
Wisdom	`LESSONS.md`	When you correct the agent	Never

Law is rules. "Always show physical evidence before claiming success." "Never edit .env." These change maybe once a month, when you decide they change.

State is where the project is right now. Current phase, what's in flight, what's verified, what's broken. This churns constantly.

Wisdom is what you learned the hard way. Corrections you issued. Traps that cost you an afternoon. This only ever grows.

Why the separation is the whole trick

Because compression has to happen, and it has to happen selectively.

State churns daily. If you never compress it, every session start re-reads weeks of narrative you'll never need again, and you pay tokens for it on every single project, every single day.

Wisdom is permanent. Compressing it destroys the exact thing you kept it for — a lesson summarized into a hint stops being a lesson.

Put them in one file and there is no setting that works. Compress aggressively and you shred your hard-won lessons. Don't compress and you bleed tokens forever. The only way out is to stop asking one file to do both jobs.

The rule with the best cost-to-value ratio

At the start of every session, before anything else:

Read PROGRESS.md and open with exactly three lines: current phase, what was in progress, what's next.

That's it. Roughly 50 tokens.

It removed more daily friction than anything else I did. Instead of "what were we doing?" followed by three minutes of re-explaining, the session opens with:

1. Phase: auth rewrite
2. In progress: token refresh, 2 tests still red
3. Next: fix the expiry edge case, then ship

The agent knows. You didn't have to tell it.

Don't ask the agent nicely. Use hooks.

This is where most CLAUDE.md setups stop, and it's why they drift.

A rule in a markdown file is a request. The agent usually honors it. Usually is doing a lot of work in that sentence.

Two things I moved from request to enforcement:

1. Secret files. Instead of "please don't edit .env", a PreToolUse hook that denies the write outright:

BLOCKED_PATTERNS = [".env", ".env.*", "*credential*.json",
                    "client_secret*", "*.pem", "*.key", "id_rsa*"]

def is_blocked(basename):
    if any(fnmatch(basename, p) for p in ALLOWED_PATTERNS):
        return False
    return any(fnmatch(basename, p) for p in BLOCKED_PATTERNS)

The agent is good at deciding what code should say. It's bad at deciding what a secret file should say. So I removed the decision entirely.

2. Tests on save. A PostToolUse hook that runs the test suite the instant code changes and feeds failures straight back to the agent. Self-review doesn't catch what an adversarial step catches.

One detail that cost me an afternoon: run the test command from the project root, not from the edited file's directory. Projects with tests/ separate from src/ report "0 tests collected" when the runner starts in the wrong place — and a green zero looks exactly like a pass.

The failure that took longest to notice

This one is worth the whole post.

The agent would diligently update the local progress file, and silently skip the shared knowledge log.

Nothing errors. Nothing looks wrong. You find out weeks later, when you go looking for an answer that should be there and isn't.

Silent gaps are worse than loud failures. A loud failure interrupts you. A silent gap accumulates.

The fix is to treat the two writes as one action, with an explicit self-check before the agent reports anything: did both get written? If either is missing, write it before reporting.

What breaks first, in order

If you're scaling up, this is the order the failures arrive:

Session amnesia (project 1) → wake-up briefing
Cross-project blindness (project 3) → a registry the agent can read
Repeated mistakes (project 4) → a lessons file separate from state
Token bleed (project 8) → compression discipline
Silent write gaps (project 10) → same-turn write pairing

You don't need to solve five before you have one. But knowing the order means you recognize each failure when it shows up, instead of concluding the whole approach doesn't work.

Try the ideas free

Everything above is structural — you can build it yourself in an afternoon with the table and the two hook snippets. That's genuinely the point of the post.

If you'd rather not spend the afternoon, I packaged the whole thing: four document templates, both hooks, a scaffolding script that lays down a project's doc kit in one command, a registry audit script, and the twelve rules each written next to the specific failure that produced it.

Every script ships with a --demo self-check so you can verify it before trusting it with your repo:

$ python hooks/guard_secrets.py --demo
guard_secrets: all checks passed

If you just want the structure, the three templates are free and MIT-licensed:

github.com/wondi81/agent-os-lite

That's the part you should have for nothing — you can rebuild it yourself in an
afternoon once you've seen the shape, so there's no reason to charge for it. What
it doesn't do is enforce anything; markdown asks nicely and an agent can talk
itself out of a request.

The full version is where the hooks live, plus the scaffolding and the registry
audit:

Agent OS — $29 · zero dependencies, 30-day refund.

If you're running Claude Code across multiple projects, I'd genuinely like to hear which of the five failures hit you first. My guess is #3 catches more people than they realize.

DEV Community: ZTW