Memory and Sessions: Continuity Across Days
Auto-memory, session resume, and building an agent that remembers your project's history.
Claude Code achieves continuity across days by saving every session transcript as an episodic log and by automatically extracting project-critical facts and decisions into CLAUDE.md and a separate memory file. When you resume work tomorrow, the agent searches past transcripts and injects the most relevant memories, so it can recall where you left off without replaying the entire history.
The LLM (large language model) behind Claude Code remembers nothing between calls. Every sensation of “memory” is constructed from files on disk, files that are carefully updated, pruned, and retrieved using heuristics and retrieval logic, not magic.
Where does Claude Code store your conversations?
Every exchange with Claude Code is written to a session transcript in the .claude/sessions/ directory. Each transcript is a JSON (JavaScript Object Notation) file holding the full message history, every prompt you typed, every tool call the agent made, and every response.
Claude Code’s session management docs describe these files as durable records you can revisit or resume. You never lose a conversation, even if you close your terminal. The transcripts serve as the agent’s episodic memory: a raw, time-ordered log of what actually happened.
A typical session for your web app project might record a schema change, a debug session, and a decision to switch from Express to Hono. Each turn includes not just the text but also metadata like timestamps and tool invocation payloads.
This log is purely episodic. It does not, by itself, give the agent a short-cut to what matters. That job falls to the memory system.
How does long-term memory get built across sessions?
Claude Code maintains two persistent memory stores that together form the agent’s semantic memory: the CLAUDE.md file you know from Part 2 and a hidden .claude/memory.json file.
The CLAUDE.md file holds project-level conventions, architecture decisions, and coding guidelines. Updates to it are intentional and often human-reviewed. The memory.json file stores more fluid, user-specific facts and preferences that accumulate automatically.
The automatic extraction works like this. After you finish a task, Claude Code examines the session transcript in the background and distills what it learned. It might record “the API (application programming interface) uses JWT (JSON Web Token) with HS256” in CLAUDE.md and “you prefer functional React components” in memory.json. Memory documentation confirms that Claude Code “automatically adds to the project’s memory as you work”, no explicit command required.
You can also tell Claude Code to remember something explicitly with claude memory add "We are targeting iOS 17 as a baseline". That entry shows up immediately in memory.json and is available in every future session, regardless of which transcript it originated from.
The key design insight: episodic logs are never used directly as memory. Instead, Claude Code transforms them into compact, de-duplicated, time-aware facts that cost far fewer tokens per retrieval. This mirrors the distinction real-world personal assistants make between a daily journal and a to-do list.
How does resuming a session actually work?
When you run claude session resume, Claude Code does not simply dump the entire old transcript into the new conversation. That would blow the token budget on irrelevant history.
Instead, the agent performs a retrieval step. It searches across past session transcripts, not just the one you named, for chunks that are semantically similar to your current query and to the current project state. The session documentation explains that resume “pulls in the most relevant context from earlier conversations.”
In our running example, after a weekend away, you might ask: “What was that edge case we found in the login flow?” Claude Code searches through session transcripts, finds the discussion where you debugged a CSRF token mismatch, and injects the relevant exchange into the new prompt. It does not replay the entire Friday session; it retrieves a few highly-ranked paragraphs.
The retrieval mechanism likely uses embedding-based similarity, possibly combined with keyword indexing. The exact internals aren’t documented, but the observable behavior matches a standard RAG (retrieval-augmented generation) pipeline: embed chunks, index them, and at query time fetch the top-k most relevant chunks bounded by a token budget.
This step is the bridge between the dead storage of past transcripts and the limited working memory of the context window.
What happens under the hood when you start a new day?
When you open your laptop and run claude in your web app repository, the agent starts by reading the project’s CLAUDE.md. It then loads the current memory.json file. These two files act as the static, always-available context backbone.
Next, if you use claude session resume (or if the agent determines it needs context from earlier work), it runs the retrieval step I described. The agent selects memory chunks, both from memory.json entries and from past transcripts, and assembles the final prompt.
The prompt is built in layers: system instructions (including CLAUDE.md’s content), the task preamble, any retrieved memories, the most recent session history if you’re resuming, and finally your new request. This is similar to the “read-before-reasoning” pattern used in Redis-based agent architectures but specialized for a local CLI (command-line interface) agent.
Because Claude Code lives on your machine, all these files are read directly from disk. There is no network round-trip to fetch memories. That makes retrieval cheap and avoids the privacy concerns of cloud-stored long-term memory services.
After the agent responds, the turn is appended to the current session transcript, and the background extraction pipeline may flag new facts for inclusion in memory.json or an update to CLAUDE.md.
Why don’t older sessions blow up the token budget?
Claude Code never stuffs entire transcripts into a prompt. The agent uses retrieval-augmented memory, not raw replay. Only the most relevant chunks from old conversations are injected, and even those are prioritized and pruned to fit within the token limit.
The retrieval step itself applies a hard budget. Claude Code likely uses a strategy similar to what research on RAG-based memory describes: deducting the space already consumed by system prompts and the new user message, then filling the remainder with the top-scoring memory snippets that fit.
Additionally, the agent uses summarization for extra-long transcripts. If a past session contains many turns on a single topic, it may be distilled into a compact summary before being offered to the retrieval index. The automatic memory extraction I described is itself a form of offline summarization, facts in memory.json stand in for the multi-turn conversations that produced them.
The result is that the context window never balloons because your project has a hundred sessions. The agent remembers what’s important, not everything that ever happened.
Quick Reference
- Full transcript dumped into prompt
- Wastes tokens on irrelevant history
- Context window balloons with many sessions
- Retrieval of relevant chunks only
- Hard budget on retrieved tokens
- Summarization for long sessions
The table below lists the key storage locations and commands you’ll use to manage memory and sessions.
| Property | Value |
|---|---|
| Session transcript directory | .claude/sessions/ |
| Project memory file | CLAUDE.md (root of repo) |
| User-specific memory file | .claude/memory.json |
| Resume a session | claude session resume |
| Manually add memory | claude memory add "<fact>" |
| View stored memories | claude memory list |
| Remove a memory | claude memory remove <id> |
Frequently Asked Questions
Q: Can Claude Code use memories from a different project?
No. Memories are scoped to the project directory. Each project has its own CLAUDE.md and .claude/memory.json. This isolates context and prevents one project’s facts from leaking into another.
Q: How can I make Claude Code forget something it automatically remembered?
Use claude memory remove with the ID shown in memory list, or edit .claude/memory.json directly. For facts baked into CLAUDE.md, edit the file and commit the change. The agent respects the current state of these files on every run.
Q: Does resuming a session pull in memories from that session or just the transcript?
When you resume a session, the agent loads the most relevant transcript chunks and any permanent memories from memory.json and CLAUDE.md that relate to the retrieved context. Both episodic and semantic memory contribute.
Q: Can I prevent a particular session from being used for future retrieval?
You can delete the session via claude session delete. That removes the transcript from the search index, so its content won’t be retrieved later. Permanent memories extracted from that session remain unless you remove them explicitly.
Q: How does Claude Code avoid showing me stale memories that are no longer correct?
The agent applies recency heuristics, and you can actively prune with memory remove. However, if a stale memory persists (for example, an old API endpoint), the easiest fix is to use claude memory remove or update CLAUDE.md directly. The system does not auto-invalidate memories based on contradictory new information.
Test yourself
Your web app now uses PostgreSQL instead of SQLite, but Claude Code keeps suggesting SQLite-specific configuration from a memory it extracted weeks ago. How would you ensure the agent never recommends that again?
Answer: Run claude memory list to locate the stale memory entry about SQLite, then run claude memory remove <id> to purge it. If the fact also appears in CLAUDE.md, edit that file to remove the reference. For extra certainty, tell the agent explicitly: “Remember: we always use PostgreSQL, never SQLite.” This creates a fresh memory that will override any residual semantic association. After removal, the next session will no longer inject the old memory, and the agent will rely only on the updated project context.
If you want to know exactly how Claude Code assembles a prompt, and what to do when the agent misunderstands your project because of wrong context, subscribe to Internals Decoded for the next part in this series. We’ll break down the agent’s prompt construction, context injection bugs, and how to debug them like a systems engineer.
Sources
- Claude Code Memory documentation
- Claude Code Sessions documentation
- RAG-based memory research (example)