Claude Does Not Have One Memory System: A Map of Chat, Claude Code, and the API

Ask Claude, “Do you remember what we discussed before?” and the answer can feel inconsistent.

Sometimes it knows. Sometimes it does not.

Claude Code may carry a build command into tomorrow's session, then appear to forget it when you open another repository. Clone the same repository on another machine, and some of that context disappears again.

The problem is not simply that Claude has “good” or “bad” memory.

Claude does not have one unified memory system. Chat, projects, Claude Code, and applications built with the Claude API use different mechanisms. They store different things, in different places, and stop at different boundaries.

This article maps those mechanisms by asking four questions:

1. Who writes or retrieves the information?
2. Where does it live?
3. Where can it be used?
4. How do you remove it?

This article reflects the product documentation available on August 4, 2026. Claude's memory experience is currently being migrated, so your plan and settings screen may differ. Check the linked official documentation and the settings shown in your own account.

I also made a 15-slide Japanese overview on Speaker Deck.

My six-container model

“Six containers” is my way of organizing the product. It is not Anthropic's official taxonomy.

Surface	Mechanism	Who manages it?	Effective boundary
Claude Chat	Memory generated from non-project chats	Claude	Chats outside projects
Claude Chat	Project memory	Claude	One specific project
Claude Chat	Past chat search	Claude searches when needed	Non-project chats, or one specific project
Claude Code	CLAUDE.md, CLAUDE.local.md, and .claude/rules/*.md	You	Depends on file location and launch directory
Claude Code	Auto memory	Claude Code	One repository on one machine by default
An app using the Claude API	Memory tool	Claude requests operations; your app executes them	Whatever your application defines

At a high level, the map looks like this:

Claude Chat                  Claude Code                 Your application

chat memory                  CLAUDE.md                   Claude API
project memory               .claude/rules/                 ↓
past chat search             auto memory                memory tool request
                                                             ↓
                                                        storage you control

There are no arrows between the three columns because memory is not automatically shared across them.

What Claude learned in a normal chat does not automatically become Claude Code's auto memory. A CLAUDE.md file does not automatically appear in Claude Chat. The API memory tool is not an endpoint for reading the memory attached to your Claude Chat account.

Claude Chat has both memory and search

The first distinction is easy to miss: memory and past chat search are separate features.

Memory keeps extracted information that may remain useful across conversations: your role, active work, communication preferences, tools, and technical preferences.

Past chat search does not pre-store a summary of everything. Claude searches the original conversation history when it needs a detail. When this happens, the search appears as a tool call in the conversation.

The practical difference is:

• Memory: prepared context that can already influence a new conversation
• Past chat search: retrieval from an earlier conversation when needed

Anthropic documents both behaviors in Use Claude's chat search and memory to build on previous context.

The memory rollout creates two experiences

As of this writing, Claude is moving users to an improved memory experience.

• If you see Settings > Memory, you have the improved experience. Memory is stored as individual entries grouped into categories, and Claude reads, writes, and updates them in real time. Anthropic says this experience is available to Free, Pro, and Max users and is becoming the default for new users.
• If you see memory under Settings > Capabilities, you have the legacy experience. It creates a synthesized memory summary and updates it roughly every 24 hours. Team and Enterprise users are remaining on this experience during the current rollout.

Past chat search has a different plan boundary: Anthropic currently lists it for Pro, Max, Team, and Enterprise plans.

This means “memory” and “search” should not be treated as two names for the same feature.

Search stops at project boundaries

Claude can search:

• all chats outside projects, when you are outside a project;
• conversations inside the current project, when you are working in that project.

It does not perform one account-wide search across both sides of that boundary.

These searches therefore fail by design:

• searching from a non-project chat for something discussed in Project A;
• searching from Project A for something discussed outside projects;
• searching from Project A for something discussed in Project B.

Each project also has its own memory space and project summary. Project A does not inherit the memory accumulated outside projects, and Project B does not inherit Project A's memory.

That separation can feel like forgetting. It is also what prevents one client's context from leaking into another client's project.

Deleting a chat and deleting memory are not always the same action

In the improved memory experience, deleting or expiring the original conversation does not remove memory entries generated from it. You delete those entries from Settings > Memory, or reset memory entirely.

In the legacy experience, deleting a conversation removes it from the synthesized memory. Anthropic says the synthesis is updated within 24 hours.

If you only want to prevent search, you can turn off Search and reference chats in the relevant settings screen without deleting every conversation.

Incognito Chat is temporary, not a secret vault

An Incognito Chat:

• does not use Claude's existing chat memory;
• is not saved to chat history;
• does not create future memory entries;
• is not used by past chat search.

However, profile information such as custom styles and personal preferences can still be available inside the chat.

The conversation data is also not erased the moment you close the window. Anthropic says incognito chats are retained for 30 days by default. Enterprise organizations can configure a longer retention period, and Team and Enterprise exports include incognito chats.

So the right use case is a conversation you do not want carried into future chats, not “a place where sensitive information can never be retained.”

See Use incognito chats for the current retention and availability details.

Claude Code has memory written by you and memory written by Claude

Every Claude Code session begins with a fresh context window. Two mechanisms carry knowledge across sessions:

1. CLAUDE.md files containing instructions you wrote
2. Auto memory containing notes Claude wrote

Anthropic describes both in How Claude remembers your project.

CLAUDE.md: instructions you control

Use CLAUDE.md for things you do not want to explain again:

• build and test commands;
• coding conventions;
• project architecture;
• review requirements;
• actions Claude should avoid.

The common locations have different scopes:

Scope	Location	Typical use
User	~/.claude/CLAUDE.md	Your preferences across all projects
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Team-shared project instructions, usually committed to Git
Local	./CLAUDE.local.md	Personal instructions for this project

CLAUDE.local.md is intended for personal project-specific instructions, but Git does not magically keep it private. Add it to .gitignore if you do not want it committed.

These files are context, not hard enforcement. Claude Code concatenates the instructions it discovers. It does not treat a nearer file as a guaranteed override of every earlier instruction. Contradictory rules can therefore produce inconsistent behavior.

.claude/rules/: split instructions and scope them by path

For a larger project, you can split instructions into arbitrary Markdown files under .claude/rules/:

.claude/
├── CLAUDE.md
└── rules/
    ├── testing.md
    ├── api-design.md
    └── frontend/
        └── accessibility.md

A rule without paths front matter applies to the whole project. Add paths to load it only when Claude works with matching files:

---
paths:
  - "src/api/**/*.ts"
---

# API development rules

- Validate input at every endpoint.
- Use the shared error response format.

My rule of thumb is:

• put short, project-wide instructions in CLAUDE.md;
• use .claude/rules/ for separate topics or path-specific instructions.

Auto memory: notes Claude Code writes for itself

Auto memory stores things Claude judges useful for future sessions: build commands, debugging findings, architecture notes, code style preferences, and workflow habits.

By default, each repository gets a local directory like this:

~/.claude/projects/<project>/memory/
├── MEMORY.md
├── debugging.md
├── api-conventions.md
└── ...

<project> is derived from the Git repository. It is not a name you are expected to choose manually.

MEMORY.md is the entry point. Claude Code loads its first 200 lines or 25 KB, whichever comes first, at the beginning of a conversation. More detailed files such as debugging.md are read on demand.

The important boundary is the machine:

• subdirectories and worktrees in the same repository share one auto-memory directory;
• another machine does not receive it automatically;
• it lives outside the repository by default, so changing .gitignore does not make it team-shared.

Run /memory to inspect or edit the files and toggle auto memory. Everything is plain Markdown.

Which Claude Code memory belongs in Git?

I use this promotion rule:

• team-wide rules and required procedures → commit them in CLAUDE.md or .claude/rules/;
• provisional findings from one machine → leave them in auto memory;
• a finding that repeatedly matters → review it and promote it into a shared file.

Auto memory is useful as a notebook. It should not become the only copy of knowledge your team depends on.

The API memory tool means your application owns the memory

The Claude API memory tool is another mechanism with a similar name and a very different storage model.

Claude can request file operations such as create, read, update, and delete under a logical /memories path. Your application executes those operations and returns the result.

The tool operates client-side. Your application decides:

• whether memory is stored in files, a database, or cloud storage;
• how one user's memory is separated from another's;
• which sessions reconnect to the same memory;
• how long the data is retained;
• how users view and delete it.

Anthropic does not provide an account-level memory store for your application through this tool. The documentation is explicit: Claude requests the operation, while your infrastructure performs it against storage you control.

See the Memory tool documentation.

Five boundaries worth remembering

The product names will change. These boundaries are more durable.

1. Claude Chat / Claude Code

Chat memory and Claude Code's instruction files and auto memory are separate systems. Context does not cross automatically in either direction.

2. Outside a project / inside a project

Project memory and past chat search remain inside one project. Creating a project is also creating a memory boundary.

3. This machine / another machine

Claude Code auto memory is machine-local by default. Cloning the repository elsewhere does not bring it along.

4. Claude Chat / Cowork

What Claude remembers about you in Chat does not currently carry into Cowork. Cowork can maintain separate memory inside Cowork projects, scoped to each project. See Get started with Claude Cowork and Organize your tasks with projects in Claude Cowork.

5. Claude / another application

Memory does not automatically move to another AI service or custom application. Claude's memory import is experimental and requires an explicit import flow. API-based applications must implement their own storage and identity boundaries.

Choose the storage location from the thing you want remembered

What should persist?	Put it here
Your role, communication style, and general working preferences	Memory generated from non-project Claude Chat
Assumptions and decisions for one client or project	A separate Claude project
Coding rules the whole team must follow	Repository CLAUDE.md
Rules for one directory or file type	.claude/rules/*.md with paths
A local finding Claude Code may reuse	Auto memory
A finding needed on another machine or by the team	Promote it from auto memory into a committed file
A temporary conversation that should not affect future memory or search	Incognito Chat, while respecting its retention policy
Persistent information for users of your own application	The API memory tool plus storage and deletion behavior you implement

Duplicating the same fact everywhere does not necessarily make the system safer. It creates multiple copies that can become stale or contradictory.

When Claude appears to have forgotten

Before repeating the information, ask:

• Which product surface created it?
• Was it stored as memory, or was it only present in the original conversation?
• Which project, repository, application, or machine owns it?
• Is the current session still inside that boundary?
• Does deleting the source conversation also delete this type of memory?

“Does Claude remember?” is usually too broad a question.

The more useful question is:

Which memory system am I using, and where does its boundary stop?

---

Originally published in Japanese on Zenn: Claudeの「記憶」はどこにある？ チャット・Claude Code・APIの境界を整理する

This English edition was translated and edited with AI assistance from a Japanese article that I carefully reviewed and revised. I remain responsible for the published content.

Comments

[Tae Kim]

The boundary between auto memory and the CLAUDE instruction file is where most teams stumble — people assume auto memory is team-shared because it feels authoritative, then discover it stays on one machine when a new teammate clones the repo. Your promotion rule (provisional finding in auto memory, explicitly reviewed before committing to a shared file) is exactly the right practice, and I'd add one refinement: schedule a memory review pass after each meaningful sprint so stale auto-memory entries don't become false ground truth. The detail about deleting a conversation not removing improved-experience memory entries is the one that trips up users most — I've seen people clear their chat history to start fresh and then be surprised that Claude still knows their preferences. The API memory tool section nails the design intent: Anthropic provides the request protocol, your application provides the storage, and that separation prevents the ownership confusion that shows up when teams try to share one API key's context across multiple end-user sessions.