Memory and Persistence

Overview

Every time you start a new session with an AI coding agent, the agent knows nothing about what happened in previous sessions. It does not remember that your test suite requires a running database. It does not recall that you prefer functional patterns over class hierarchies. It has no memory of the three debugging sessions where you discovered that the payment module has a race condition under load. Persistent memory systems change this. They allow agents to carry knowledge across sessions, so each conversation builds on the last instead of starting from scratch.

The Groundhog Day Problem

Without memory, every agent session is a fresh start. The agent reads CLAUDE.md, loads whatever context it can find, and begins working. If the task requires knowledge that is not in CLAUDE.md or the code itself -- things the agent discovered through interaction -- that knowledge is lost.

The Groundhog Day problem: across three separate sessions, the developer asks about flaky payment tests. Each time, the agent rediscovers the same race condition in the database pool, applies the same mutex fix, and the knowledge is lost when the session ends. The agent never learns from previous sessions.

This is the Groundhog Day problem: the agent relives the same discovery process over and over. Each session pays the full cost of understanding something the agent already figured out before.

The impact compounds across a team. If five developers each have sessions that rediscover the same facts about the codebase, that is five times the wasted context, five times the wasted compute, and five times the developer frustration.

How Memory Works

A memory system for AI agents records observations from each session and injects relevant ones into future sessions. It operates in three phases:

Memory system in three phases: Phase 1 Record — the agent observes something noteworthy, the memory system captures it, and it is stored persistently. Phase 2 Retrieve — a new session begins, the memory system searches for relevant past observations, and matched observations are injected into context. Phase 3 Apply — the agent uses past knowledge without rediscovery, leading to better decisions and fewer mistakes.

Recording happens during or after a session. The memory system observes the agent's actions, the developer's corrections, and the facts discovered during the session. Not everything is recorded -- the system filters for observations that are likely useful in future sessions.

Retrieval happens at the start of each new session. Given the current task or the files being worked on, the memory system searches its store for relevant past observations and injects them into the agent's context.

Application is implicit. Once past observations are in the context, the agent uses them naturally. It does not need special instructions to "use memory" -- the observations become part of the information it reasons with.

Types of Memory

Not all memories are equal. Different types of information serve different purposes, and organizing them helps both the memory system and the developer understand what is stored.

Project facts are truths about the codebase that do not change often. "This project uses pnpm." "The database is PostgreSQL 15." "Integration tests require REDIS_URL to be set." These are the most valuable memories because they prevent the agent from guessing or using incorrect defaults.

Feedback corrections are things the developer corrected during a session. "Do not use any in TypeScript -- use unknown instead." "Always destructure props in React components." These capture the team's preferences that go beyond what is written in CLAUDE.md.

Discovery notes are insights the agent gained through investigation. "The processPayment function has a subtle race condition when called concurrently." "Module X depends on module Y even though it is not in the import graph -- it uses dynamic imports." These are expensive to rediscover.

User preferences are personal to the developer. "I prefer verbose variable names." "Show me the diff before applying changes." "Explain your reasoning before writing code." These shape the agent's interaction style.

Memory vs. CLAUDE.md

Memory and CLAUDE.md serve different purposes, and understanding the distinction prevents duplication and conflict.

CLAUDE.md is the authoritative, version-controlled source of truth. It contains the team's agreed-upon conventions, the correct build commands, and the project's architectural rules. Every developer on the team shares the same CLAUDE.md, and changes to it go through code review.

Memory is supplementary, personal or project-scoped, and often auto-generated. It fills in the gaps that CLAUDE.md does not cover -- the discovered facts, the individual preferences, the corrections from past sessions.

When memory conflicts with CLAUDE.md, CLAUDE.md wins. Memory is a convenience layer; CLAUDE.md is the contract. If you find that memory keeps recording something that should be in CLAUDE.md, promote it: add the information to CLAUDE.md and let the memory entry become redundant.

Rule of thumb: If the information is true for everyone on the team and should be enforced consistently, put it in CLAUDE.md. If it is personal, transient, or discovered rather than designed, let memory handle it.

How Memory Gets Injected

The mechanics of memory injection vary by tool, but the general pattern is consistent. At the start of a session, the memory system receives a signal (the task description, the files being opened, or just the project name) and returns relevant observations. These observations are added to the agent's context alongside CLAUDE.md and other system instructions.

Memory injection sequence: the developer asks to fix a flaky payment test. The agent queries the memory system for 'payment test flaky,' which returns three relevant memories (connection pool limit, JWT test fixtures, db migration requirement). The agent immediately applies this knowledge and goes straight to the fix without rediscovery.

Notice the difference from the Groundhog Day scenario. Instead of rediscovering the connection pool issue, the agent starts with that knowledge and goes straight to the fix.

Configuring Memory Effectively

Memory systems work best when they are tuned to record the right things and ignore the noise. Here are practical guidelines:

Let it learn from corrections. The most valuable memories come from moments when you correct the agent. "No, use pnpm, not npm." "That is the wrong test command." These corrections are high-signal because they indicate a gap between what the agent assumed and what is actually true.

Prune periodically. Memory accumulates. Old observations about a module that has been rewritten, preferences that have changed, or facts about a dependency that has been replaced -- these become noise. Review stored memories periodically and remove what is no longer accurate.

Scope appropriately. Project-level memory should contain facts about the codebase. User-level memory should contain personal preferences. Mixing the scopes means your personal preferences get injected into your teammate's sessions, which is rarely helpful.

The Memory Budget

Memory itself consumes context. If the memory system injects twenty observations at the start of every session, that is potentially thousands of tokens before the agent even reads a file. This creates a new version of the drowning problem: too much memory flooding the context with marginally relevant past observations.

The solution is the same principle we apply everywhere: be selective. A good memory system retrieves the 5-10 most relevant observations, not everything it has ever recorded. It weighs recency, relevance to the current task, and the confidence of the match.

Think of memory as a filter, not a firehose. The goal is to inject the three facts that will save the agent from making a mistake, not to replay the entire history of past sessions.

Anti-Patterns

Recording everything. If the memory system saves every observation from every session, retrieval becomes noisy and slow. Be selective about what crosses the persistence threshold.

Never pruning. Memory without maintenance becomes stale. Facts about the codebase change. Preferences evolve. Old memories that contradict current reality cause more harm than having no memory at all.

Duplicating CLAUDE.md. If a fact is already in CLAUDE.md, storing it in memory is redundant. It wastes the memory retrieval budget and creates a risk of the two sources drifting apart.

Ignoring memory conflicts. When the agent receives contradictory guidance from memory and CLAUDE.md, it must have a clear precedence rule. Without one, the agent's behavior becomes unpredictable.

Summary

• Without memory, agents suffer the Groundhog Day problem -- rediscovering the same facts session after session
• Persistent memory records observations from sessions and injects relevant ones into future sessions
• Memory comes in four types: project facts, feedback corrections, discovery notes, and user preferences
• CLAUDE.md is the authoritative source of truth; memory is supplementary -- when they conflict, CLAUDE.md wins
• Memory systems should be selective about what they record and retrieve to avoid flooding context with irrelevant history
• Prune regularly -- stale memories that contradict current reality cause more harm than no memory at all
• Treat memory as a filter that surfaces the few critical facts that prevent mistakes, not a firehose of every past observation