DEV Community: Yukihiro Kimura

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

Yukihiro Kimura — Mon, 03 Aug 2026 23:35:00 +0000

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:

Who writes or retrieves the information?
Where does it live?
Where can it be used?
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:

CLAUDE.md files containing instructions you wrote
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.

I automated my weight logging into Notion, and gave myself a new daily chore

Yukihiro Kimura — Fri, 31 Jul 2026 21:28:27 +0000

What I wanted

I'm building a system where all my daily records live in Notion, so I can point an AI at it and get feedback. Goals, tasks, daily logs, finances — those are all manual entry, and that's fine. But one day it hit me that weight would be nice to sync automatically.

The requirements were simple:

Every morning, my weight and body fat percentage get appended to a Notion database as one row
No manual typing

That's it. My scale is a Withings Body Smart.

The design I picked first

This one:

Scale → vendor app → Apple Health → iOS Shortcut → Notion API

I chose Apple Health as the hub for these reasons:

It doesn't depend on the scale model. As long as the data lands in Health, the same implementation works for any vendor.
No server required. A time-based Shortcuts automation handles it end to end — no always-on machine, no cron.
Free. No extra subscription.
Extensible later. Anything that's already in Health — steps, sleep, heart rate — could be added the same way (if I ever wanted to).

Generic, zero cost, extensible. The design looked sound to me.

Implementation

Here's what the Shortcut looks like:

1. Find Health Samples          [Weight] latest, limit 1
2. Get Details of Health Sample [Value]      → variable Kg
3. Get Details of Health Sample [Start Date] → variable SampleDate
4. Format Date                  yyyy-MM-dd   → variable Ymd
5. If Ymd == today
6.   Text                       ← build the JSON
7.   Get Contents of URL        ← POST to the Notion API

Step 5 matters. Without it, on a day you don't step on the scale, yesterday's weight gets appended under today's date.

Here's the JSON built in step 6:

{
  "parent": { "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" },
  "properties": {
    "Date":       { "title": [ { "text": { "content": "@@YMD@@" } } ] },
    "Measured":   { "date": { "start": "@@YMD@@" } },
    "Weight kg":  { "number": @@KG@@ },
    "Body fat %": { "number": @@FAT@@ }
  }
}

(My real database uses Japanese property names. What matters is that they match your database exactly.)

I write this as a plain string in a Text action and hand it to the POST action.

Setting up the Notion side

Use an access token, not OAuth

Notion offers two auth methods for a connection: an internal access token, and OAuth. OAuth is meant for apps that get installed into other people's workspaces, or listed on the Marketplace — so for this I went with the access token.

I attached the connection at the parent page

Notion permissions are inherited by child pages. If you connect an integration at a parent page, everything underneath it becomes reachable.

In my case I may want to auto-sync things other than weight later, so I granted access at the parent page that holds my personal data.

Note: if you're doing this at work, you'd want to scope it down to the minimum necessary permissions.

I hit a 400 twice

First: it says there's no `parent`

{
  "status": 400,
  "code": "validation_error",
  "message": "Provide a `parent.page_id` or `parent.database_id` parameter to create a page,
              or use a public integration with `insert_content` capability.
              Internal integrations aren't owned by a single user, so creating
              workspace-level private pages is not supported."
}

My JSON has a parent. And I still got this.

The cause was that I never wired the JSON into the request body. When I set up the POST action in Shortcuts, I hadn't configured it to actually take the JSON — so I was POSTing an empty body. Yeah.

Second: `invalid_json`

{ "status": 400, "code": "invalid_json", "message": "Error parsing JSON body." }

Weight was appending fine, so I went to add body fat percentage. When I added the property, I forgot the trailing comma on the previous line.

    "Weight kg":  { "number": 67.878 }      ← no comma
    "Body fat %": { "number": 16.058 }

Shortcuts has no syntax highlighting and no linter, so I walked right past it.

The only debugging tool you get

Drop a Quick Look action immediately after the Text action. It shows you the expanded JSON exactly as it will be sent, so you can confirm the variables actually resolved to values.

In Shortcuts development this is effectively your only debugging tool. When you're stuck, look at the payload.

Rounding the numbers

The weight coming out of Health was something like 67.87800598144531.

I first tried to round it inside Shortcuts, but somehow I could not get it to work, so I rounded on the Notion side instead.

Add one formula column to the weight database:

round(prop("Weight kg") * 10) / 10

Then hide the raw column in the view and show only the rounded one. Much easier to read.

As a side effect this turned out to be the better design anyway: the raw value stays in the database, and rounding is a display concern.

It works. And then I noticed something

It ran. Rows appeared in Notion.

But there was one problem left.

Apple Health doesn't get the data unless I open the Withings app.

Stepping on the scale every morning isn't enough. If I want a row every day, I have to open the Withings app every day. Background App Refresh is on, and even then there's no guarantee it syncs daily.

So the actual workflow is:

Step on the scale
Open the Withings app ← New!
The Shortcut runs (I changed the trigger to "when the Withings app is closed"...)

The appending is automated now, but a daily manual step survived. What I actually wanted was for stepping on the scale to be the whole interaction.

What I got wrong

Apple Health is a bucket that gets written to when a connected app launches — it isn't necessarily something that goes and fetches data on its own. I thought I was picking a hub. What I actually put in the middle of the path was a bucket waiting for the Withings app to open.

Meanwhile, Withings has a public API. The scale is on Wi-Fi and presumably pushes measurements straight to the cloud, so a path like this might work:

Scale --Wi-Fi--> Withings cloud --webhook--> my own endpoint --> Notion

A row appears in Notion the moment I step on the scale. There's no app to open.

I picked Health because I wanted the design to be generic — but the scale I actually own is one of the models that can skip that generic layer and be called directly. By choosing "a design that works with any scale," I missed the better path that only my scale had.

The lesson

When you design an automation path, check up front whether each hop can push data forward on its own. If even one hop is pull-based — it only moves data when something comes asking — that's where a human eventually ends up doing the work.

Originally published in Japanese on Zenn: 体重を自動でNotionに記録したかったが、毎朝アプリを開く仕事が残った