Auto Memory, Auto Forget

Source: Dev.to

The Problem: Lost‑Update Race Condition

• The memory file (~/.claude/projects//memory/MEMORY.md) is a plain text file on disk.
• The Edit tool reads the entire file, performs a string match‑and‑replace, and writes the whole file back.
• No locking, compare‑and‑swap, or merge strategy is employed.

When two agents attempt to write concurrently:

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 (based on version 1) → version 2b.

Agent A’s update is silently overwritten, resulting in lost knowledge.

Why It Matters for Agent Teams

• Concurrency by design: Multiple agents run simultaneously.
• Shared memory: All agents in a team use the same project‑scoped memory file.
• Complex tasks: Teams are employed for tasks that generate valuable insights worth recording.
• Delayed detection: The loss may only become apparent in a later session that relies on stale or missing information.

Suggested Approaches (Issue #24130)

1. File locking – Use flock or an equivalent mechanism around reads and writes. Simple and proven, but platform‑dependent.
2. Append‑only log – Agents only append entries; a periodic compaction pass deduplicates and resolves contradictions. Requires garbage collection and may let conflicting entries coexist temporarily.
3. Per‑agent memory files – Each agent writes to memory/.md. A merged view is assembled for the system prompt. Clean separation, but still needs a strategy for contradictory entries.
4. Compare‑and‑swap – Re‑read the file before writing and retry if it changed since the last read. Works well for low‑contention scenarios (which memory writes typically are).

Workaround Until a Fix Is Implemented

• Designate a single writer: Have only the lead agent perform memory writes.
• Topic‑specific files: Use separate memory files per topic to reduce the collision surface.
• Post‑session review: Inspect MEMORY.md after parallel sessions to identify and fill any gaps.

By being aware of these concurrency issues and applying the suggested mitigations, you can reduce the risk of lost updates when using Claude Code’s auto‑memory with agent teams or background agents.