AI & Development
AI models have no memory between sessions by default. Here's how to give Claude Code and AI agents persistent context
Every Claude session starts with no memory of previous sessions. The model does not remember what it did yesterday, which files it changed last week, or what decision was made in the last conversation. This is not a bug or a limitation to work around - it is the designed behavior of stateless language models. Working effectively with AI agents requires understanding this constraint and building the persistence layer yourself, outside the model.
Persistent context for AI agents is implemented through four distinct mechanisms, each appropriate for different types of information and different time horizons.
CLAUDE.md - session-level project context. CLAUDE.md is a Markdown file at the root of your project that Claude Code reads at the start of every session. It is the mechanism for project-level context that should be available in every session: coding conventions, architecture decisions, testing requirements, environment setup, known technical debt, and anything else that is always relevant to working in this codebase. CLAUDE.md is loaded automatically - no explicit loading step is required. Information in CLAUDE.md is equivalent to context that exists in every session.
Memory files - long-term knowledge store. Claude Code's auto-memory system stores specific knowledge in structured Markdown files in a designated directory (typically ~/.claude/projects/[project-id]/memory/). Each memory file has frontmatter specifying its name, description, and type (user profile, feedback, project context, or reference). An index file (MEMORY.md) is loaded in every session and points to specific memory files that should be retrieved when relevant. Memory files persist across sessions and across conversations about the same project. They are the right place for: user preferences, feedback from past conversations, learned project context, and reference information about external systems.
Structured handoff files - task-level state. For multi-session tasks - work that spans more than one conversation - structured handoff files record where the task left off. A handoff file is a formatted summary written at the end of a session and read at the start of the next, containing: what was completed, what is in progress, what comes next, and any decisions made that affect subsequent work. Handoff files are ephemeral (they exist for the duration of a multi-session task) and should be explicitly cleaned up when the task completes.
Vector stores - semantic long-term memory. For AI agents that need to retrieve relevant past information from a large knowledge base - previous conversations, documentation, meeting notes, design decisions - a vector store provides semantic search over stored text. When a new session starts, the agent queries the vector store for context relevant to the current task and loads only the most relevant fragments. Vector stores are appropriate for large knowledge bases where loading everything into context would be impractical or where different sessions need different subsets of the stored knowledge.
CLAUDE.md is loaded in every session. This means information in CLAUDE.md has a constant cost: it takes up context window space in every conversation, regardless of whether it is relevant to the current task. This cost discipline matters - include in CLAUDE.md only information that is relevant to most sessions.
CLAUDE.md typically contains: the project description and tech stack, the directory structure, the coding conventions (naming, formatting, testing), the commands for running tests and builds, environment setup notes, known issues and constraints, and pointers to specialized skill files for specific workflows. It does not contain: task-specific state, historical decisions that are no longer relevant, or large blocks of reference material better stored in memory files.
Memory files serve four categories of persistent knowledge:
User profile: Information about the developer's preferences, expertise, and working style. "Prefers TypeScript to JavaScript. Deep backend expertise, newer to frontend React. Prefers direct answers without explanatory preamble." This allows the AI to calibrate its responses to the specific developer across sessions.
Feedback: Corrections and confirmed approaches from previous sessions. "Do not mock the database in tests - the team was burned when mock tests passed but the production migration failed. Always use real database connections." Feedback memories prevent the AI from making the same mistake twice across different sessions.
Project context: Ongoing work, decisions, and context that is not derivable from the codebase. "The auth middleware rewrite is driven by legal/compliance requirements - scope decisions should prioritize compliance over developer ergonomics." This context would be lost between sessions without explicit storage.
Reference: Pointers to external resources. "Bug tracker is in Linear project INFRA. Design specs are in Figma at [link]. Staging environment credentials are in 1Password under 'Dev Staging'." Reference memories give the AI a map to external context it may need to access.
Memory files have a cost: they must be read, interpreted, and kept current. Store information that is non-obvious and durable. Do not store information that is derivable from the code (architecture patterns, recent changes, file structure), available in git history (what changed, who changed it, when), or ephemeral (in-progress task state, current conversation context). The most common memory system failure is over-storing - filling memory with easily-derivable information that the model could read from the codebase directly, at the cost of loading irrelevant context in every session.
Memory files become stale. A project context memory written six months ago may reference a system that has since been replaced. A feedback memory about a library may be outdated after a major version upgrade. Memory files should be reviewed periodically - before acting on a memory about a specific file or function, verify that the file and function still exist with the behavior the memory describes.
The right memory maintenance cadence: quarterly review of all memory files, checking each against the current codebase state. Delete memories that are no longer accurate. Update memories whose context has changed. The goal is a memory system that is small, accurate, and genuinely useful - not a large archive of potentially outdated context.