AI Coding Agent Memory, Explained: What CLAUDE.md Actually Does

Search "claude code memory" and you'll find posts implying the agent has something like a brain that accumulates knowledge about your project over time. It doesn't. Once a session ends, the agent remembers nothing about it — not the bug you fixed, not the approach you rejected, not the naming convention you agreed on twenty minutes before closing the terminal. What people call "coding agent memory" is almost always one specific, unglamorous thing: a file that gets re-read from disk and pasted back into the model's context window at the start of every session. That's it. No database, no learning, no persistent state inside the model. Understanding that one fact clears up most of the confusion around CLAUDE.md, AGENTS.md, and why your agent sometimes seems to "forget" things it clearly should know.

The uncomfortable truth: there's no memory between sessions

A large language model has no ability to retain anything after a conversation ends. Close the session and whatever happened in it is gone — from the model's side, it's as if it never existed. The next session starts from zero, with only whatever text gets loaded back into its context window. That's exactly why CLAUDE.md and AGENTS.md exist: not as memory, but as a substitute for it. They're project files, checked into the repo like any other source file, that get re-read at the start of a session so the agent starts with the same standing instructions every time. The trick isn't recall. It's re-injection.

The layers people conflate

A few distinct things get lumped together under "agent memory," and they behave very differently:

The context window is the current conversation — everything said and done since the session opened. It's the agent's only working memory, and it vanishes the moment the session ends. Nothing here is retained on its own; anything worth keeping has to be written down somewhere that survives.

A project instructions file — CLAUDE.md for Claude Code, AGENTS.md as the more tool-agnostic convention some editors have converged on — is a plain markdown file the agent re-reads and re-loads into context at the start of every session, every time, whether it's relevant to the current task or not. It's the closest thing to standing memory an agent has, and it's really just a file on disk being pasted back in.

A skill is different from both: it's instructions the agent only loads when a request actually matches it. We've written a full breakdown of what skills are and how they differ from CLAUDE.md — the short version is that a skill is on-demand, while CLAUDE.md is always-on.

Session transcripts and compaction are the last piece, and the one most likely to get mistaken for real memory. When a long session runs low on context, some tools summarize the earlier part of the conversation to free up space — that's compaction. A summary of what happened is not a recall system. It's lossy by design, it only covers the current session, and once that session ends, even the summary is gone unless you've written the important parts down somewhere permanent.

What belongs in CLAUDE.md — and what doesn't

This is the part that actually changes how well an agent performs, and it's worth being strict about.

Belongs: conventions the agent genuinely can't infer from the code — why you chose a pattern that looks unconventional, a naming rule that isn't self-evident from the existing files. The exact commands to run tests, build, or lint, since guessing wrong here wastes a turn. Constraints that aren't visible anywhere else — a service you can't touch in this environment, a dependency version pinned for a reason that isn't in the code. Decisions your team has already made and doesn't want relitigated every session.

Does not belong: anything the repo already states, like a build script your package.json already has. Anything derivable from reading the code — the agent can see your file structure and existing patterns without a paragraph describing them. One-off task notes from a specific piece of work, which belong in a commit message, not a file that loads forever. And a sprawling style guide that reads like a wiki — every rule in it competes for space with the actual conversation you're trying to have.

The cost people don't see

Here's the part that rarely gets said plainly: every line in CLAUDE.md gets sent on every single request, in every session, for as long as that file exists. It's not read once and cached in some persistent way inside the model — it's re-transmitted, in full, every time. A tight file costs a few hundred tokens per turn and pays for itself in fewer wrong guesses. A file that's grown to a few thousand words of accumulated rules, half of them stale, is a permanent tax on every prompt you send, whether or not any given rule is relevant to what you're doing right now. We've written separately about how context windows get squeezed without warning — a bloated instructions file is one of the few causes of that squeeze that's entirely within your control. The fix isn't clever. It's pruning the file the way you'd prune dead code, and asking of every line whether the agent could have figured it out on its own.

Why memory doesn't transfer between tools or models

Because "memory" is really just a file, it only helps to the extent the next session actually reads it. Switch from one coding agent to a different one entirely, and there's no guarantee it looks for a CLAUDE.md at all — it might expect AGENTS.md, or nothing, or its own config format. Switch which underlying model answers your prompts, and the file transfers fine as plain text, but the model reading it has no memory of prior sessions with the old model either way — memory was never coming from the model in the first place. The durable part of your setup is the project files sitting in your repo, not any session state inside a specific product. Anything that only lives inside one vendor's app is memory you don't actually own.

The meshcode angle

meshcode is a native desktop app for macOS and Windows built around a multi-pane agent workspace — each pane is its own agent session, and panes run in parallel rather than taking turns in one shared chat. Rather than inventing a new memory format, meshcode drives your existing Claude Code and Codex CLI subscriptions directly, so the CLAUDE.md or AGENTS.md you've already written, along with your existing CLI config, carries over and works unchanged. You don't rewrite your project instructions to move into meshcode.

Because each pane is a separate session reading the same files on disk, the project-level instructions in CLAUDE.md are shared across every pane automatically, while each pane's own conversation stays independent — one pane's context doesn't leak into another's, but they're all reading from the same standing instructions. meshcode also runs its own metered mesh models, billed pay-as-you-go with no monthly fee, if you want to try a session without bringing an existing subscription.

Keep your CLAUDE.md, change the workspace: meshcode is free to start — download it and run the project instructions you already wrote across parallel panes.

The takeaway

There's no such thing as an AI coding agent that remembers you between sessions in the way a person would. What exists is a file that gets re-read and re-pasted into context every time, and how well that works depends entirely on what you put in it. Keep CLAUDE.md or AGENTS.md tight — conventions the agent can't infer, commands it needs to get right, constraints that would otherwise get relitigated — and prune it the way you'd prune dead code. That's the whole system. Once you see it that way, "agent memory" stops being mysterious and starts being something you can manage.

FAQ

Does Claude Code remember your previous sessions? No, not in the sense of the model retaining anything — but some setups let you reopen or resume a past session's transcript, and that's easy to mistake for memory. What's actually happening is the old conversation text gets loaded back into context, the same way CLAUDE.md does; nothing changed inside the model between sessions.

What's the actual difference between CLAUDE.md and AGENTS.md? Functionally, nothing — both are the same idea, a plain markdown file of standing project instructions re-read at the start of a session. The difference is which filename a given tool looks for by default. If your team runs more than one coding tool, AGENTS.md is the safer name to standardize on, since more tools default to checking for it.

Is there a size or structure limit for what goes in CLAUDE.md? No hard limit, but there's a practical one worth using deliberately: once a project grows into a monorepo or several distinct areas, splitting instructions into separate files and importing the relevant one beats one growing document everyone loads on every task. Repo-wide conventions stay in the root file; something specific to one package only loads when you're actually working there.

Does agent memory transfer between different AI coding tools? Not automatically across tools, since each has its own default filename and lookup behavior — but it does transfer across machines and devices, because it was never tied to either. CLAUDE.md lives in the repo, so cloning it elsewhere brings the same instructions along. That's also what lets it work across several parallel sessions at once — meshcode's multi-pane workspace has every pane read the same CLAUDE.md from disk, so instructions stay consistent across panes without copying anything by hand.

👉 Download meshcode — Mac, Windows