memory.md and 'Claude Memory': What It Actually Is

memory.md. Claude memory. ChatGPT memory. Cursor memory. Mem0. Memory bank. Auto memory.

The word does a lot of work in the AI tooling world right now. It covers four mechanically distinct things, the four resemble each other only at the marketing layer, and the gap between the marketing and the mechanism is where teams get in trouble.

This article is for the operator who has heard their AI tool described as "having memory" and wants to know what is happening when the agent claims to remember something. It is also for the platform team making procurement decisions where "has memory" shows up on the spec sheet. For the live editorial scoring of every coding agent referenced here, see our AI Coding Assistants directory.

Here is the four-mechanism taxonomy, the trust model for each, and the three misconceptions worth naming explicitly.

The misconception

In human terms, memory has four properties: it is continuous (yesterday flows into today), it is associative (one cue retrieves a cluster of related material), it is salient (important things rise to the top), and it forgets (left alone, fidelity decays).

In AI tools, the word memory describes a different set of mechanisms entirely. Each pattern provides a partial substitute for one or two of the human properties, and each one comes with a different trust model, a different governance shape, and a different failure mode.

The gap matters because operators procure on the human framing and operate on the engineering reality. A platform team that hears "the agent remembers our conversations" and assumes continuous, associative, salient memory will be surprised by what shipped. A compliance team asked "is this auditable?" will get four different answers depending on which mechanism is in use.

The rest of this article unpacks the four mechanisms, the trust model for each, and the three confusions that come from collapsing two or more of them into one bucket.

The four mechanisms

2.1 Author-written contract files

Examples: CLAUDE.md, AGENTS.md, .cursorrules, .clinerules.

What it is. A Markdown file you write and check into the repository. The agent reads it as context at session start. The file is a config artifact in the same way that .eslintrc or tsconfig.json is a config artifact.

Trust model. Same as any config file you write. You audit it because you wrote it. You version it because it sits in git. You review it in pull requests because it changes the agent's behaviour for everyone on the team.

Why it gets called memory. Vendors describe these files as "agent memory" because they persist context across sessions. The label is misleading. The file is a contract. You and your team write every word. The agent is a reader of the file.

Failure mode. The file rots. Someone added a rule six months ago that has been overridden in practice; the rule stays in the file and the agent keeps following it. The fix is the same as for any rotting config: review it, prune it, ship the change in a pull request.

The mechanics of this layer are covered in the AGENTS.md and CLAUDE.md sibling explainers in this series.

2.2 Agent-written notes files

Examples: Claude Code's auto memory (the directory the agent writes to during a session), ChatGPT's Saved Memories (notes the model writes about you when you say "remember this" or when ChatGPT decides a fact is worth saving) [4].

What it is. A file or set of files the agent writes itself, based on what happened in your sessions and what it decided was worth keeping. You can audit it. The agent can rewrite it.

Trust model. The agent decides what to write. You have to read what is there. The file sits on disk and is visible to anyone with file access. For ChatGPT, it sits in the account and is visible to anyone with account access.

Anthropic's load behaviour for Claude Code auto memory [2]: the first 200 lines or 25 KB of the auto-memory directory load into context at session start. Mem0's analysis of leaked Claude Code source code [6] confirms this from the implementation side and frames it as a 200-line cap that "silently forgets at line 201." The behaviour is the same fact under both descriptions; the framing is editorial. Operators do still hit the cap unexpectedly when the agent has been writing for a while, and surfacing the limit deliberately matters.

ChatGPT's Saved Memories [4]: stored in a notepad separate from chat history. Even if you delete a chat, any saved memories from that chat persist in the notepad. ChatGPT can manage them on its own, adding, combining, and removing them across sessions. ChatGPT Plus and Pro plans now include automatic memory management that prioritises recent and frequently referenced memories.

Failure mode. The agent writes things you would have wanted to vet, or it stops writing things it should be writing. The first failure mode is privacy and accuracy. The second is silent regression in agent behaviour over time.

2.3 Server-side conversation summaries

Examples: Claude.ai memory (Anthropic launched a free memory feature with a ChatGPT import tool on March 2, 2026) [3], ChatGPT's Reference chat history setting [4].

What it is. The vendor's servers maintain a synthesis or retrieval index of your past conversations. When you start a new conversation, the synthesis is consulted and relevant material is brought into context. You see only the effects on the model's responses; the synthesis itself is server-side.

Trust model. Opaque. The synthesis is a vendor-side artifact. You can ask the model what it remembers about you. What you get back is the synthesis re-narrated, with the synthesis itself remaining server-side.

Anthropic's Claude.ai memory [3] is project-scoped, which limits cross-conversation reach. The launch on March 2, 2026 made the feature free across all plans and shipped a ChatGPT import tool to lower the switching cost for users moving from ChatGPT to Claude.

ChatGPT's Reference chat history [4] reaches across all of your conversations by default. It can be turned off independently of Saved Memories, and the help docs note that data retention for some services may be affected by recent legal developments (the ongoing NYT data demands).

Failure mode. The synthesis includes something that should have stayed in one conversation, or it omits something the user expected to be remembered. Operators must rely on vendor disclosures to debug either failure.

2.4 Structured external memory stores

Examples: Anthropic Memory Tool API [1], Mem0 [6], Cline Memory Bank [8][9], claude-mem, Basic Memory, Recallium.

What it is. A dedicated storage system the agent reads from and writes to through tool calls. The developer controls the storage backend (file system, database, encrypted store, cloud blob, vector database). The agent treats the store as an external resource accessed through a defined API.

Anthropic's Memory Tool [1] uses a filesystem metaphor under /memories with six commands: view, create, str_replace, insert, delete, rename. The tool name is memory_20250818. The launch was September 29, 2025 [7]. Anthropic auto-injects this system prompt when the tool is enabled:

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE. ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory. [1]

Cline Memory Bank [8][9] is a documentation methodology. It describes a structured Markdown folder the agent reads at session start, with custom instructions guiding what gets written where. It works with any agent that can read documentation; the discipline is in the structure.

Trust model. Whatever you choose for the storage backend. File on disk: standard filesystem auditing applies. Database: standard database auditing. Encrypted store: standard key management applies. The mechanism is governable in a way the previous three are because the developer owns the surface.

Failure mode. The store accumulates noise the agent reads on every turn, or the store gets corrupted by indirect prompt injection (Section 6 covers this). Both are addressable through normal data hygiene plus injection defences.

The cross-tool comparison

Two tools that both market memory can sit in different categories with different trust models. The column that matters for procurement is the rightmost one: which mechanism category each tool occupies.

Cursor's .mdc files (category 1) and Cursor with Memory Bank (category 4) live in the same IDE, are both checked into git, and behave entirely differently at runtime.

The three misconceptions worth naming

4.1 "My agent remembers our conversations"

It has a summary it wrote, a search index, or pattern matches. None of those qualify as memory in the cognitive sense.

ChatGPT's own help docs are explicit [4]: "Memory is intended for high-level preferences and details, and should not be relied on to store exact templates or large blocks of verbatim text."

The practical implication is that operators who treat memory as durable storage of conversation content are setting themselves up for surprise. Memory is a loose, lossy summary. For exact templates, use a structured external store (mechanism 4) or a regular database.

4.2 "memory.md (or CLAUDE.md) is private"

For mechanisms 1 and 2, the file lives on disk. It is in git. It is in CI. It syncs through cloud drives. Anyone with repo access reads it.

Anthropic's Memory Tool documentation [1] includes explicit security guidance on path traversal, sensitive information handling, and storage size. The default assumption is that the storage is auditable across the team.

The practical implication is that operators should treat agent-written notes the way they treat any other file that lives next to the code: review before committing, rotate anything that looks like a credential, and audit periodically.

4.3 "Deleting memory makes the agent forget"

The ChatGPT Memory FAQ [4] is explicit on three points worth naming:

First, deleted Saved Memories enter a retention log for up to 30 days for safety and debugging purposes. The deletion is logged before it propagates.

Second, a memory deleted from the Saved Memories notepad can still appear in past chats unless those chats are also deleted. The memory store and the chat archive are separate; deleting from one leaves the other intact.

Third, anything already in the current session's context window is unaffected by a memory deletion. The session retains what is already loaded.

The practical implication is that "deleting memory" is a multi-step operation. It removes the future-reference of the fact while leaving the historical references and the in-session context intact. Reset is real and takes time.

How to use these mechanisms well

For the visual map of where memory.md sits alongside SKILL.md, AGENTS.md, and CLAUDE.md, see the Agent Skills Landscape infographic.

Why this matters for governance

Multi-tenant isolation requires knowing which mechanism is in use. The four mechanisms have four different governance shapes:

• Mechanism 1 (author-written contract): standard secret-management and source-control auditing apply. Everything is in git.
• Mechanism 2 (agent-written notes): auditable in principle (the file is on disk), opaque in practice unless someone reads it. Plan for periodic audits.
• Mechanism 3 (server-side summary): opaque. Vendor disclosures matter. Data-residency complications apply. Compliance frameworks treat this category most cautiously.
• Mechanism 4 (structured external store): governance follows the storage backend the developer chose. The most flexible and the most the developer's responsibility.

Indirect prompt injection on memory [11]: Palo Alto Unit 42 published research demonstrating that injected instructions can poison long-term agent memory across sessions, persist after the original conversation ends, and be used to exfiltrate data. The risk surface scales with mechanisms 2 and 4, where the agent or a connected tool writes to the store on the operator's behalf.

The practical implication for operators running anything beyond a single-user prototype: the four mechanisms each need a governance posture, and the posture differs by category. The harness around the agent is the layer that enforces these postures consistently.

You have probably already touched one

If you have used Claude Code, ChatGPT, Claude.ai, Cursor, or Cline at all in the past year, you have already worked with at least one of these four mechanisms. You may have written a CLAUDE.md. You may have noticed ChatGPT remembering that you live in San Francisco. You may have hit the auto-memory cap on Claude Code wondering what was happening. The mechanisms are already in your workflow; the question is whether you can name which one you are using when something surprises you.

The useful discipline is small. Name the mechanism. Audit the file. Treat the storage like the config artifact it is. Pick mechanism 4 when the governance posture demands it.

The word "memory" will keep doing too much work for a while yet. The taxonomy is what survives.

Four mechanisms. Four trust models. One word doing the work for all of them.