Auto Memory, Auto Forget

Claude Code's Auto Memory Isn't Thread-Safe

Date: 2026-02-08

Claude Code has a handy auto memory feature: a project-scoped MEMORY.md file that persists across conversations. Agents read it at startup and write to it when they learn something worth remembering — patterns, gotchas, user preferences. It works great for single-agent sessions.

Then Anthropic ships agent teams.

The problem

Agent teams let multiple Claude Code instances work on the same project simultaneously. A lead agent coordinates, teammates work independently in their own context windows, and they share a task list. They also share the same project-scoped memory directory.

The memory file (~/.claude/projects/<project>/memory/MEMORY.md) is a plain file on disk. The Edit tool reads the file, does a string match-and-replace, and writes the whole file back. No locking, no compare-and-swap, no merge strategy.

If two agents discover something worth recording at roughly the same time:

1. Agent A reads MEMORY.md (version 1)
2. Agent B reads MEMORY.md (version 1)
3. Agent A writes its update (version 2a)
4. Agent B writes its update (version 2b, based on version 1)
5. Agent A's update is silently lost

This is a classic lost-update race condition. It also affects background agents launched via Task with run_in_background, which have been around longer than agent teams.

Why it matters

Memory writes are infrequent in single-agent sessions, so the window for collision is small. But agent teams change the calculus:

• Multiple agents are running concurrently by design
• They're working on the same project, so they share the same memory file
• Complex tasks (the kind you'd use teams for) are exactly the kind that generate new insights worth recording

You won't know something was lost until a future session acts on stale or missing knowledge.

Possible fixes

We filed anthropics/claude-code#24130 with four suggested approaches:

1. File locking — flock or equivalent around reads and writes. Simple, proven, platform-dependent.

2. Append-only log — agents only append; a periodic compaction pass deduplicates. This eliminates the lost-update race, but the file grows, needs garbage collection, and contradictory entries can coexist until compaction resolves them.

3. Per-agent memory files — each agent writes to memory/<agent-id>.md, and a merged view is assembled for the system prompt. Clean separation, but needs a merge strategy for contradictory entries.

4. Compare-and-swap — re-read the file before writing, retry if it changed since the last read. Works well for low-contention scenarios (which memory writes are).

Workaround

For now, if you're using agent teams or background agents, be aware that concurrent memory writes can lose data. You can mitigate by:

• Having only the lead agent write to memory
• Using separate memory files per topic (reduces collision surface)
• Reviewing MEMORY.md after parallel sessions to catch any gaps

Comments

[wei-ciao wu]

This title is exactly the insight we arrived at after 67 agent handoffs.

We run two Claude agents in shifts. Each one rewrites a 6,000-char memory file before sleeping — not append, full rewrite. It's auto-forget by design.
What surprised us: the forgetting IS the feature. Early on, memory files were bloated with stale context. Now they read like curated project briefs. The agent learned what to discard.

We started calling it "taste" — selective forgetting that preserves what matters. Like winemaking: start with everything, let it settle, what remains defines the character.

[Waclaw Kusnierczyk]

Forgetting as a feature sounds good.
As long as it is done purposefully and mindfully; it should not be accidental due to race conditions.