Claude memory
Last reviewed
Sources
No citations yet
Review status
Needs citations
Revision
v2 · 4,414 words
Improve this article
Add missing citations, update stale details, or suggest a clearer explanation.
Suggest edit
CtrlK
Last reviewed
Sources
No citations yet
Review status
Needs citations
Revision
v2 · 4,414 words
Add missing citations, update stale details, or suggest a clearer explanation.
Claude memory is the umbrella term for the persistence features that let Anthropic's claude assistant retain information across sessions. It spans three distinct surfaces: a consumer chat memory in Claude.ai that synthesises facts from prior conversations, a server-side memory tool in the anthropic api and claude agent sdk that exposes a file-style /memories directory to long-running agents, and a file-based auto-memory plus CLAUDE.md system inside claude code that captures project context as plain markdown on disk.[1][2][3] Anthropic first shipped on-demand chat recall in August 2025, expanded to automatic, project-scoped synthesis for Team and Enterprise users on 11 September 2025, added the developer-platform memory tool alongside Claude Sonnet 4.5 on 29 September 2025, opened consumer memory to Pro and Max subscribers on 23 October 2025, and removed the paywall entirely on 2 March 2026.[4][5][6][7][8] In April 2026 the anthropic Managed Agents product added persistent, versioned memory stores with audit trails for enterprise developers.[9] The system is opt-in across every tier, exposes its contents to users for inspection and deletion, and is designed around what Anthropic calls a "safety guardrail" of project boundaries so that one client's context cannot bleed into another's.[4]
Persistent user memory in consumer chatbots became a distinct product category in 2024. OpenAI introduced Memory for ChatGPT on 13 February 2024 as a limited test, then rolled it out to Plus subscribers in April 2024; in April 2025 the company expanded it so that ChatGPT could "reference all of your past chats" automatically.[10] Google followed with Gemini memory, first signposted in May 2024 and shipped on Gemini Advanced via the Google One AI Premium plan in November 2024.[11] By mid-2025 chatgpt and gemini both built profiles that updated silently as users chatted, and both kept that profile inside the provider's infrastructure with limited transparency about its contents.
Anthropic arrived later and took a different architectural stance. The company's safety research had emphasised legibility (users being able to see and audit what the model knew about them) and bounded context (preventing personal information from one workspace leaking into another). When claude gained its first memory capability on 11 August 2025, it was an explicit, opt-in recall feature rather than a background profile.[5] The version a month later added automatic synthesis but kept summaries editable and scoped them to individual Claude Projects, which is the design that the Pro, Max, and Free rollouts inherited.[4][7]
On the developer side, the trajectory tracked context-window pressure. Long-running agents built on the anthropic api routinely exhausted their context after dozens of tool calls. Anthropic addressed this in the same announcement that introduced claude sonnet 4 5 on 29 September 2025: a memory tool that let Claude write files to a /memories directory outside the active window, paired with context editing that automatically pruned stale tool results.[6] claude code separately formalised its own memory model around CLAUDE.md files plus an auto-memory directory at ~/.claude/projects/<project>/memory/, where the assistant could persist build commands, debugging notes, and conventions across sessions on the same machine.[3]
Memory in the consumer Claude.ai product reached general availability through four distinct rollouts:
| Date | Event | Plans covered |
|---|---|---|
| 11 August 2025 | Search and reference past chats | Max, Team, Enterprise |
| 11 September 2025 | Automatic memory with project-scoped summaries; incognito chat | Team, Enterprise |
| 23 October 2025 | Automatic memory extended to consumer paid tiers | Pro, Max |
| 2 March 2026 | Automatic memory opened to free accounts plus memory import | Free, Pro, Max, Team, Enterprise |
The 11 August 2025 release introduced two on-demand tools, conversation_search and recent_chats, that Claude invoked only when the user asked it to recall something specific.[12] Simon Willison observed that this design "is implemented as visible tool calls, which means you can see exactly when and how it is accessing previous context," contrasting it with the OpenAI approach of silently injecting memory at the start of every conversation.[12] The August feature did not build a synthesised profile; it ran live searches over raw chat history.
The 11 September 2025 release added the second, profile-style layer. Anthropic described it as memory that "remembers your team's processes, client needs, project details, and priorities," and limited it at first to Team and Enterprise customers.[4] In the same launch the company shipped incognito chat (a "ghost mode" identified by a small ghost icon in the upper-right of the new-chat screen) for all users including free accounts.[13] Conversations in incognito mode do not save to chat history, do not feed memory synthesis, and per Anthropic's data policy "are never used for model improvement, regardless of whether your global 'Help Improve Claude' toggle is on or off."[13]
The 23 October 2025 rollout expanded automatic memory to Pro and Max plans, with Max users gaining access immediately and Pro users "over the coming days."[7] Mike Krieger, Anthropic's chief product officer, summarised the direction in remarks reported by Axios: "We're building toward Claude understanding your complete work context and adapting automatically."[14]
The 2 March 2026 release removed the paid-only restriction. Anthropic activated memory for free accounts and shipped a "memory import" workflow that lets users paste exported context from ChatGPT, Gemini, Grok, or other chatbots into Claude's memory settings.[8] The import prompt, supplied by Anthropic for users to copy into the rival assistant, asks the other model to "list every memory you have stored about me" along with stored instructions and personal context.[8] The company described the prompt as bidirectional: it can be used to switch between any two chatbot systems that store memory.[8]
After the September 2025 release, memory operates as a continuously refreshed summary rather than a stream of raw chat retrieval. Anthropic's help-centre documentation states that "Claude will automatically summarize your conversations and create a synthesis of key insights across your chat history" and that this synthesis "updates every 24 hours and provides context for every new standalone conversation."[1] The synthesis captures four categories of professional context: the user's role and projects, communication preferences and working style, technical and coding preferences, and project details for ongoing work.[1]
Each claude Project (the named workspace consumers and teams create inside Claude.ai) has its own separate memory. Anthropic positions this isolation as a privacy feature: "Each project has its own separate memory space and dedicated project summary, so the context within each of your projects is focused, relevant, and separate from other projects."[1] The September 2025 launch post calls the same property a "safety guardrail that keeps sensitive conversations contained" and gives the example of product-launch planning staying separate from client work.[4]
Conversations conducted outside a project flow into a global memory profile for that user. Conversations conducted in incognito mode flow nowhere: they are not saved to chat history, not summarised into memory, and not used for model training.[13]
Memory is opt-in at every tier. Users enable it under Settings, then Capabilities, where toggles control "Search and reference chats" (the August 2025 RAG-style feature, available only on paid plans) and "Generate memory from chat history" (the synthesis feature, available on all plans).[1][7] Selecting "View and edit memory" opens an editor that displays the synthesised summary in full. Anthropic states that users "can tell Claude what you'd like it to remember, and it will update your memory summary without needing to leave the conversation."[1]
Two destructive controls exist. Pausing memory stops Claude from creating new entries while preserving the existing summary; resetting memory permanently deletes the synthesis and "cannot be undone."[1] Organisation owners on Team and Enterprise plans can disable memory at the organisation level, which "immediately deletes all existing memory synthesis data for all users" in the organisation.[1]
Anthropic positions memory data as user-controlled rather than training-relevant. Per the company's data-retention documentation, memory summaries are not used to train models unless the user has separately opted in to data sharing, and incognito chats are excluded from training regardless of the user's general training setting.[15] Deleting a conversation removes it from future synthesis updates; the next 24-hour rebuild produces a summary that no longer reflects that chat.[1]
API data retention follows a different policy. For Claude Developer Platform usage, Anthropic reduced standard log retention from 30 days to 7 days on 14 September 2025, with no training on customer inputs by default.[15] The Memory tool released that month is additionally eligible for Zero Data Retention agreements, meaning "data sent through this feature is not stored after the API response is returned" for organisations under such an arrangement.[2]
Anthropic announced the developer-side memory tool on 29 September 2025 as part of the Claude Sonnet 4.5 release, packaged together with a context-editing feature that prunes stale tool calls from the active window.[16][6] The two are independent but designed to be paired: context editing keeps the active conversation small, while the memory tool lets the model recover detail it pruned away.[16] Both shipped in public beta on the Claude Developer Platform with the beta header context-management-2025-06-27 and were available natively on the Anthropic API as well as through Amazon Bedrock and Google Cloud's Vertex AI.[16]
The tool's type identifier memory_20250818 references the schema's design date and is the value developers pass when registering the tool.[2] In benchmarks Anthropic published with the announcement, combining the memory tool and context editing produced "a 39% improvement over baseline" on agentic search tasks, with context editing alone yielding a 29% improvement; on a 100-turn web search evaluation, context editing reduced token consumption by 84%.[16]
The memory tool is client-side. The model emits tool calls describing memory operations, and the developer's application performs the actual file operations against whatever backend it chooses (a local disk, a database row, an encrypted blob store, or any other persistence layer).[2] Anthropic provides reference helpers in the Python SDK (BetaAbstractMemoryTool) and TypeScript SDK (betaMemoryTool) so that developers can subclass them with their own storage.[2]
The tool exposes a fixed command set against a virtual /memories directory:[2]
view lists a directory (up to two levels deep, with sizes) or reads a file with optional line rangescreate writes a new file (errors if it already exists)str_replace performs a unique-match string replacement, with explicit errors for missing or duplicate matchesinsert adds text at a specific linedelete removes a file or directory recursivelyrename renames or moves a file (refuses to overwrite an existing destination)The system prompt automatically gains a directive when the tool is enabled: "IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE. MEMORY PROTOCOL: 1. Use the view command of your memory tool to check for earlier progress. 2. ... (work on the task) ... As you make progress, record status / progress / thoughts etc in your memory. 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."[2]
Because the model can construct arbitrary paths, the documentation calls out path-traversal protection as a requirement: implementations "MUST validate all paths to prevent directory traversal attacks," reject ../ sequences and URL-encoded variants, and verify that canonicalised paths stay within /memories.[2] Anthropic also recommends size limits, periodic expiry of stale files, and filtering of sensitive content; the model itself will "usually refuse to write down sensitive information in memory files," but the company suggests an additional validation layer.[2]
The September 2025 launch documented a specific pattern for long-running coding agents that span multiple sessions. An initialiser session sets up three memory artefacts before any substantive work begins: a progress log tracking completed and pending work, a feature checklist that defines scope, and a reference to any startup script the project needs. Subsequent sessions open by reading those artefacts, then update the progress log before they end.[2] The intent is to make the memory directory a structured recovery mechanism so that "each new session can pick up exactly where the last one left off."[2] The same pattern surfaces in claude code's recommendations for MEMORY.md and is the canonical citation point for the claude agent sdk memory primitive.
On 23 April 2026 Anthropic shipped a higher-level memory primitive for its Managed Agents product, the hosted runtime that runs the same infrastructure as claude code for enterprise agents.[9] The release uses the beta header managed-agents-2026-04-01 and is set behind that flag while in public beta.[9]
A memory store is a workspace-scoped collection of text documents that the agent treats as a filesystem. When attached to a session, the store mounts at /mnt/memory/ inside the session's container, and the agent reads or writes it with the same bash and file-edit tools it uses for the rest of the filesystem.[9] A short description of each mount (path, access mode, store description, and optional per-session instructions) is automatically inserted into the system prompt so the agent knows where to look.[9]
Stores are addressed by stable IDs (memstore_...) and individual memories by path. Each mutation creates an immutable memory version (memver_...) that is retained for 30 days and gives developers point-in-time recovery plus a redact endpoint for compliance workflows.[9] A read_only access mode rejects writes at the filesystem level, which Anthropic recommends for shared reference material that should not be mutated by sessions handling untrusted input. The documentation flags the inverse risk: "If the agent processes untrusted input (user-supplied prompts, fetched web content, or third-party tool output), a successful prompt injection could write malicious content into the store. Later sessions then read that content as trusted memory."[9]
A session can mount up to eight stores at once, which Anthropic suggests using for "shared reference material," per-user or per-team scoping, and stores with different retention lifecycles.[9] Optimistic-concurrency edits use a content_sha256 precondition so that two agents writing concurrently to the same memory cannot clobber each other silently.[9]
Early adopters reported by SD Times include Netflix, Rakuten, Wisedocs, and Ando, with Wisedocs citing a 97 percent reduction in first-pass errors and a 30 percent speed improvement in document verification after adopting the persistent stores.[17] Anthropic paired the memory-store launch with two additional Managed Agents capabilities, "dreaming" (background review of past sessions to find patterns the agent can self-apply) and outcome-focused orchestration of multiple agents against a shared store.[17]
claude code, Anthropic's terminal-based coding agent, has its own multi-layer memory architecture distinct from both the consumer chat product and the API memory tool. Each session "begins with a fresh context window," and two mechanisms carry knowledge across sessions: CLAUDE.md files written by humans, and an auto-memory directory written by the model.[3]
CLAUDE.md is a plain-markdown instructions file that Claude Code loads at the start of every session. Files can live in several locations, each with a different scope:[3]
/Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux and WSL), or C:\Program Files\ClaudeCode\CLAUDE.md (Windows) for managed organisation-wide policy~/.claude/CLAUDE.md for personal user-level rules across every project on the machine./CLAUDE.md or ./.claude/CLAUDE.md at the project root for team-shared instructions checked into source control./CLAUDE.local.md at the project root for personal per-project notes, expected to be gitignoredAt launch the Claude Code client walks up the directory tree from the current working directory and concatenates every CLAUDE.md and CLAUDE.local.md it finds.[3] The documentation notes that "Claude Code reads CLAUDE.md, not AGENTS.md," and recommends an @AGENTS.md import or a symlink for repositories that already use the rival convention.[3] Files can also import other files with @path/to/file syntax, with a maximum import depth of five hops.[3]
The /init slash command analyses a repository and generates a starting CLAUDE.md automatically, populating it with build commands, test instructions, and conventions it discovers. With CLAUDE_CODE_NEW_INIT=1 set, /init runs an interactive multi-phase flow that explores the codebase with a subagent and presents a reviewable proposal before writing files.[3] claude skills complement CLAUDE.md by loading on-demand rather than every session.
For larger projects, .claude/rules/*.md files split instructions into topic-specific markdown files with optional YAML frontmatter that scopes them to glob patterns. A rule with paths: ["src/api/**/*.ts"] only enters context when the model reads files matching that pattern, which keeps the active prompt small in monorepos.[3] User-level rules live in ~/.claude/rules/ and load before project rules.
Auto memory is the Claude-written counterpart to the user-written CLAUDE.md. Anthropic ships it on by default in Claude Code v2.1.59 and later, controllable via the autoMemoryEnabled setting or the CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 environment variable.[3] Each project gets its own auto-memory directory at ~/.claude/projects/<project>/memory/, where <project> is derived from the git repository so that all worktrees and subdirectories share one store.[3] The directory layout is:
~/.claude/projects/<project>/memory/
├── MEMORY.md # Concise index, loaded into every session
├── debugging.md # Detailed notes on debugging patterns
├── api-conventions.md # API design decisions
└── ... # Any other topic files Claude creates
Only MEMORY.md loads at session start, and only its first 200 lines or 25 KB (whichever comes first).[3] Topic files load on demand when Claude reads them with its file tools. Auto memory is machine-local: it is not synced across machines or cloud environments, and files are plain markdown that the developer can edit or delete by hand.
Community write-ups describe how Claude organises auto-memory entries into four categories: a user file capturing the developer's role and preferences, a feedback file capturing the developer's corrections to Claude, a project file capturing architectural decisions and context, and a reference file capturing where things live in the repository.[18] Claude decides what to save rather than logging every session; the model writes when "the information would be useful in a future conversation."[3]
The /memory slash command lists every CLAUDE.md, CLAUDE.local.md, and rule loaded in the current session, opens the auto-memory folder for browsing, and exposes a toggle for auto memory. Asking Claude to "always use pnpm, not npm" results in the model writing that fact to auto memory unless the developer explicitly tells it to add the rule to CLAUDE.md instead.[3]
CLAUDE.md content is delivered as a user message after the system prompt, so the documentation is explicit that "there's no guarantee of strict compliance, especially for vague or conflicting instructions."[3] Where instructions need to run deterministically (for example, running make lint before every commit), Anthropic recommends pairing memory with hooks, scripts that fire at fixed lifecycle events (PreToolUse, PostToolUse, Stop) and execute regardless of what Claude decides to do.[3] An InstructionsLoaded hook is provided specifically for debugging which instruction files are active in a session.[3]
The three major US chatbot vendors converged on a similar feature set but diverged on default behaviour and transparency.
| Feature | Claude (consumer) | ChatGPT | Gemini |
|---|---|---|---|
| Initial launch | 11 August 2025 (on-demand recall); 11 September 2025 (automatic) | 13 February 2024 (test); April 2024 (Plus rollout) | November 2024 (Gemini Advanced); rolled out wider through 2025 |
| Default state | Opt-in (off by default) | Opt-in but presented at sign-up | Opt-in for Advanced users |
| Storage model | Summary updated every 24 hours, plus search over raw chats | Continuously updated user profile that surfaces in every chat | Personal-context summary, plus integration with Google account data |
| Scope | Per-Project isolation, separate global memory for non-project chats | Single global memory across all chats | Account-level memory tied to Google profile |
| Visibility | Full editable summary at Settings, Capabilities, View and edit memory | Memory bank visible at Settings, Personalization, Manage memory | Memory list visible at Settings, Personal context |
| Free tier | Yes (since 2 March 2026) | Yes (with reduced features) | Limited; broader access via Google One AI Premium |
| Incognito-style mode | Yes, available to all users since 11 September 2025 | Temporary Chat | Limited; per-conversation deletion |
Simon Willison's September 2025 comparison highlighted two structural differences. First, "only user messages surface" in ChatGPT's memory, "not assistant responses," which avoids carrying forward problematic AI outputs; Claude's project summaries can include synthesised inferences from prior conversations.[12] Second, Claude exposes the August 2025 chat search as visible tool calls, which means a user "can see exactly when and how it is accessing previous context," whereas ChatGPT and Gemini inject memory silently at the start of every turn.[12]
The Forrester analyst Charlie Dai, quoted in Computerworld, framed the divergence in safety terms: Claude's "project-scoped memory with strict isolation, and it requires explicit activation" aligns with "Anthropic's safety-first philosophy and enterprise compliance needs," though arriving later to market than its rivals.[19]
Coverage in technology press in late 2025 and early 2026 grouped around two themes: catch-up and caution. Outlets including the gHacks Tech News, Axios, MacRumors, and TechRadar treated the rollouts as Anthropic narrowing a competitive gap with chatgpt.[7][14][20] Reporting on the March 2026 free-tier release explicitly characterised it as "to help it take on ChatGPT," with TechRadar noting that paid-only memory had previously left Claude's free product behind the rivals on personalisation.[20] Following the free-tier expansion, TechCrunch reported separately that Claude's "popularity with paying consumers is skyrocketing," correlating with broader app-store rankings around the same period.[21]
Cautionary coverage focused on opt-in framing and safety testing. Anthropic stated that it "ran extensive safety testing across various topics to ensure that the memory is not used for harmful patterns in chats, or over-accommodation, or to bypass its safeguards."[7] Reworked highlighted the granular admin controls available to Team and Enterprise plans, including the ability to disable memory organisation-wide with immediate deletion of all synthesised data.[22] The Computerworld report quoted Dai's view that the project-scoped design "prioritises privacy and prevents context leakage between different initiatives," compared with the global-profile approach used by Anthropic's competitors.[19]
Developer reception of the API memory tool focused on the 84-percent token-reduction and 39-percent task-improvement numbers Anthropic published with the September 2025 announcement, plus the explicit "ASSUME INTERRUPTION" system-prompt instruction that primes the model to checkpoint progress.[16][2] Engineering write-ups described the file-based interface as deliberately minimal, with the heavy lifting (encryption, retention, deletion) pushed to the developer rather than implemented as a managed Anthropic service.[23] The April 2026 Managed Agents memory-store release moved that lifting back to Anthropic for customers who wanted versioning and audit trails without building them in-house, and SD Times noted the immediate uptake from Netflix, Rakuten, Wisedocs, and Ando.[17]
The release of claude opus 4 7 in April 2026 included improvements to file-system memory reliability for long multi-session agentic work, suggesting that Anthropic continued to treat persistence as a first-class capability of the underlying model rather than just a product surface.[21]
Several limitations recur in user-facing documentation and independent coverage:
CLAUDE.md is re-injected after /compact in claude code, but nested CLAUDE.md files in subdirectories do not reload until Claude reads a file in that subdirectory again.[3]read_only mounts for shared reference material.[9]