Claude Code memory

Claude Code memory: what belongs in the repo, and what doesn’t.

Q: Does Claude Code have memory?

Yes, two kinds: CLAUDE.md files that you write and that load at the start of every session, and auto memory, where Claude keeps its own notes per repository on your machine. With /memory you can see and edit both. Neither reaches across repos, machines or other tools; for that, you connect a memory over MCP.

Q: What’s the difference between CLAUDE.md and auto memory?

You write CLAUDE.md: instructions and rules, and in the project also for the whole team through Git. Claude writes auto memory: preferences, corrections and project context, only on your machine and only for that repository.

Q: How do I add an MCP server to Claude Code?

With claude mcp add. For WhyVault: claude mcp add --transport http --scope user whyvault https://mcp.whyvault.io, then sign in in the browser with /mcp or claude mcp login whyvault. claude mcp list shows whether the connection works. Claude Code guide

Q: Can I share the memory with my team?

You share the project CLAUDE.md through Git. WhyVault is a personal vault, but you can share the setup: with --scope project, the connection goes into the repo’s .mcp.json, and everyone signs in with their own account. Never commit an access key.

Claude Code starts every session with no memory. `CLAUDE.md` and auto memory help, but both stay with one repository on one machine. Here’s what goes in `CLAUDE.md`, what goes in a shared memory over MCP, and how to connect the two in five minutes.

Reading time: 8 minutesUpdated: October 12, 2026

In short

Claude Code remembers things through CLAUDE.md files you write (in the project, in your home folder or local only) and through auto memory, which Claude keeps itself, per repository, on your machine. The rule of thumb: anything that only applies to this repo and should be versioned with the code – build commands, conventions, architecture – goes in CLAUDE.md. Decisions and their why, knowledge that spans projects, and anything Claude, ChatGPT or Cursor need too go in a shared memory over MCP, such as a WhyVault connected with claude mcp add.

How Claude Code remembers

As of October 2026, according to the official Claude Code docs. Details change quickly; when in doubt, the docs win.

CLAUDE.md is the memory you write. Claude Code reads it at the start of every session. It exists at several levels: ./CLAUDE.md in the project (for the whole team, shared through Git), ~/.claude/CLAUDE.md for you across all projects, and CLAUDE.local.md for personal notes on one project that shouldn’t be committed. When several exist, they’re combined, not replaced. Run /init to generate a first draft.

Imports keep the file lean. With @path/to/file you pull in other files, such as @README or @docs/git-workflow.md. For rules that only apply to part of the code, there’s .claude/rules/. The docs recommend keeping a CLAUDE.md under about 200 lines: everything in it costs context in every session.

Auto memory is the memory Claude writes. Claude Code keeps notes per repository: your preferences, corrections, ongoing work. They live as Markdown in ~/.claude/projects/<project>/memory/, and an index called MEMORY.md is loaded at the start of every session. With /memory you see the files and switch auto memory on or off.

Both are well made and cost nothing extra. But both share the same limit: they stay with one repository, on one machine, in one tool. According to the docs, auto memory isn’t shared across machines, and Claude Code doesn’t see project A’s CLAUDE.md while working in project B. Claude on the web, ChatGPT and Cursor see neither.

Where Claude Code’s memory lives

The files Claude Code reads at the start of a session, and where WhyVault comes in:

~/.claude/
├── CLAUDE.md                 you, all projects
└── projects/<project>/memory/
    └── MEMORY.md             auto memory, written by Claude

my-repo/
├── CLAUDE.md                 team, shared through Git
├── CLAUDE.local.md           only you, don’t commit
└── .claude/rules/            rules for parts of the code

https://mcp.whyvault.io       shared memory over MCP

~/.claude/CLAUDE.md: Your rules for every project. This is where the short pointer to WhyVault goes, so Claude Code uses the memory in every repo on its own.
CLAUDE.md: What everyone on the team needs to know about this repo: commands, conventions, layout. Versioned and reviewed with the code.
memory/MEMORY.md: Claude’s own notes on this repo. Handy, but only on your machine and only for Claude Code.
mcp.whyvault.io: Notes outside any repo that Claude Code, Claude, ChatGPT and Cursor read and write. Every change is a version, undo in one click. Connect Claude Code

The rule of thumb: CLAUDE.md or MCP memory?

For every entry, ask: does this only apply to this code, or beyond it?

–	CLAUDE.md	Shared memory (WhyVault over MCP)
Typical content	Build, test and lint commands, code conventions, folder layout, “always X, never Y”	Decisions and their why, rejected approaches, assumptions, project status
Applies to	This one repository	All your projects, repos and topics beyond the code
Who reads it	Claude Code in this repo	Every MCP client: Claude Code, Claude, ChatGPT, Cursor and more
Versioned	With Git, alongside the code, reviewed in pull requests	Every change as a version with the agent’s name, undo in one click
Length	Short, under about 200 lines: all of it loads in every session	As many notes as you like: the agent searches for what it needs
Personal preferences	Coding only, in `~/.claude/CLAUDE.md`	How you work and write, for every tool, in `9_System`
Where it lives	In your repo and on your machine	EU-hosted (Frankfurt) · GDPR-compliant; what an agent reads, its provider processes too

Typical content: CLAUDE.mdBuild, test and lint commands, code conventions, folder layout, “always X, never Y”; Shared memory (WhyVault over MCP)Decisions and their why, rejected approaches, assumptions, project status
Applies to: CLAUDE.mdThis one repository; Shared memory (WhyVault over MCP)All your projects, repos and topics beyond the code
Who reads it: CLAUDE.mdClaude Code in this repo; Shared memory (WhyVault over MCP)Every MCP client: Claude Code, Claude, ChatGPT, Cursor and more
Versioned: CLAUDE.mdWith Git, alongside the code, reviewed in pull requests; Shared memory (WhyVault over MCP)Every change as a version with the agent’s name, undo in one click
Length: CLAUDE.mdShort, under about 200 lines: all of it loads in every session; Shared memory (WhyVault over MCP)As many notes as you like: the agent searches for what it needs
Personal preferences: CLAUDE.mdCoding only, in ~/.claude/CLAUDE.md; Shared memory (WhyVault over MCP)How you work and write, for every tool, in 9_System
Where it lives: CLAUDE.mdIn your repo and on your machine; Shared memory (WhyVault over MCP)EU-hosted (Frankfurt) · GDPR-compliant; what an agent reads, its provider processes too

In short: CLAUDE.md says how work is done in this repo. The vault knows why it’s done that way, and still remembers when you switch repos.

Three examples of what goes where

Day to day, the line is usually easy to draw:

“Tests run with pnpm test”
Goes in CLAUDE.md. It only applies to this repo, changes with the code and has to be there in every session from the start.
“We use Postgres, not MongoDB, because …”
Goes in the vault, as a decision note with options and assumptions. CLAUDE.md gets one line at most: “The database is Postgres.”
“I like small commits and short messages”
If it only matters for coding, ~/.claude/CLAUDE.md is enough. If Claude on the web or ChatGPT should know it too, it goes in the vault under 9_System.

Connect Claude Code to WhyVault

One command, one sign-in, a few lines in CLAUDE.md. Tested with Claude Code 2.1.

1
Add WhyVault
Without a key, signing in in the browser. With --scope user, the memory is available in all projects. If you’d rather use an access key, for example on servers or in containers, the app shows the ready-made command under Connect agents.
```
claude mcp add --transport http --scope user whyvault https://mcp.whyvault.io
```
2
Sign in
Start Claude Code, type /mcp, pick whyvault and sign in in the browser – or run claude mcp login whyvault. After that, claude mcp list shows the server as connected.
```
claude mcp login whyvault
```
3
Try it
Ask about the status in any project. Claude Code calls vault_overview first, then searches specifically.
```
Read my WhyVault and tell me which decisions exist for this project.
```

Point to the vault

A few lines in ~/.claude/CLAUDE.md make Claude Code use the memory without being asked. The full guide

## Memory

- WhyVault (MCP server "whyvault") is my long-term memory across projects.
- Before larger changes, search WhyVault for earlier decisions on the topic.
- When we decide something with consequences, record it in the project's room in WhyVault.
- Commands and conventions of this repo belong in CLAUDE.md, not in the vault.

9_System/Coding rules.md

# Coding rules## What goes in the vault- Decisions with consequences: question, options, reasoning, assumptions.  Location: 3_Rooms/<Context>/<Project>/01 Decisions/- Rejected approaches and why they didn't work.- The status at the end of a session, in the room's overview.- Knowledge that applies to several projects, in 1_Knowledge/.## What doesn't go in the vault- Build commands, conventions, folder layout of a repo.  Those live in the repo's CLAUDE.md.- Code, logs, credentials, customer data.## How- Search first, then write. Extend existing notes.- One-line summary for every change.- Tell me at the end what you saved.

A rules note for your vault

CLAUDE.md only reaches Claude Code. Every connected agent reads this note, because vault_overview returns the rules from 9_System.

What goes in the vault: The clearer the list, the less clutter ends up in memory. Decisions and abandoned paths are exactly what a repo doesn’t tell you.
What doesn’t: The line to CLAUDE.md is spelled out. Otherwise you end up maintaining the same commands in two places.
No credentials: What an agent reads, its provider processes too. Secrets belong in your password manager, not in notes.
How: Targeted edits instead of a new note for everything. Every change shows up in the history with the connection’s name. History and privacy

A decision log while you code

In the middle of work, in a repo you haven’t touched for a few weeks:

Claude Code

You: We’re at about 4,000 orders a day now and need background jobs. Did we ever decide anything about that?
Tool: search_notes · “background jobs queue”
Claude Code: Yes: “2026-08-03 No dedicated queue” in the Shop room. Rejected back then because cron jobs were enough. The assumption behind it: under 1,000 orders a day. At 4,000 that no longer holds.
You: Then let’s build the queue. Record the new decision and link to the old one.
Tool: create_note · “01 Decisions/2026-10-12 Queue for background jobs”
Claude Code: Saved, with question, options, reasoning, assumptions and a link to the August decision. I’ll add the command for starting the worker to CLAUDE.md – that belongs in the repo.

The why lives in the vault, the how in CLAUDE.md. [Decision template](/guides/decision-log)

Two more workflows

Besides the decision log, these two are where a shared memory makes the difference.

Handing over between sessions
Before you close a session: “Write the status into the room’s overview: what’s done, what’s open, what’s next.” Tomorrow, on another machine or in Cursor, you start with “Where were we?” Claude Code only changes that one section.
Several repos, one memory
Frontend, backend, infrastructure: each repo has its own CLAUDE.md, but they all share one room in the vault. Knowledge that applies everywhere, such as how you name APIs, lives in 1_Knowledge. A decision made in the backend is then known in the frontend too.

CLAUDE.md explains the code. The vault explains the decisions behind it.

Frequently asked questions

Does Claude Code have memory?

Yes, two kinds: CLAUDE.md files that you write and that load at the start of every session, and auto memory, where Claude keeps its own notes per repository on your machine. With /memory you can see and edit both. Neither reaches across repos, machines or other tools; for that, you connect a memory over MCP.

What’s the difference between CLAUDE.md and auto memory?

You write CLAUDE.md: instructions and rules, and in the project also for the whole team through Git. Claude writes auto memory: preferences, corrections and project context, only on your machine and only for that repository.

Do I still need CLAUDE.md if I use WhyVault?

Yes. A repo’s commands, conventions and layout still belong in CLAUDE.md, versioned with the code. WhyVault doesn’t replace it; it holds what goes beyond it: decisions, their why and knowledge across projects.

How do I add an MCP server to Claude Code?

With claude mcp add. For WhyVault: claude mcp add --transport http --scope user whyvault https://mcp.whyvault.io, then sign in in the browser with /mcp or claude mcp login whyvault. claude mcp list shows whether the connection works. Claude Code guide

Can I share the memory with my team?

You share the project CLAUDE.md through Git. WhyVault is a personal vault, but you can share the setup: with --scope project, the connection goes into the repo’s .mcp.json, and everyone signs in with their own account. Never commit an access key.

Can Claude Code break anything in my vault?

Every change becomes a version with the connection’s name, and you undo it in one click. Deleting is off until you allow it for a connection. If Claude Code should only read, set the connection to Read only. History, export and privacy

Where are my notes stored?

WhyVault is hosted in the EU, in Frankfurt, and GDPR-compliant. What Claude Code reads from your vault is also processed by Anthropic. WhyVault is free up to 20 notes; Pro costs €9.99 a month. More on Claude memory

All guides

One memory for every repo.

One command in Claude Code, and your decisions carry over to every project, and to Claude, ChatGPT and Cursor too. Free, no credit card.

Start for free

Claude Code memory: what belongs in the repo, and what doesn’t.

How Claude Code remembers

Where Claude Code’s memory lives

The rule of thumb: CLAUDE.md or MCP memory?

Three examples of what goes where

“Tests run with pnpm test”

“We use Postgres, not MongoDB, because …”

“I like small commits and short messages”

Connect Claude Code to WhyVault

Add WhyVault

Sign in

Try it

Point to the vault

A rules note for your vault

A decision log while you code

Two more workflows

Handing over between sessions

Several repos, one memory

Frequently asked questions

Does Claude Code have memory?

What’s the difference between CLAUDE.md and auto memory?

Do I still need CLAUDE.md if I use WhyVault?

How do I add an MCP server to Claude Code?

Can I share the memory with my team?

Can Claude Code break anything in my vault?

Where are my notes stored?

Claude memory

Decision log

MCP memory server

One memory for every repo.

How Claude Code remembers

Where Claude Code’s memory lives

The rule of thumb: CLAUDE.md or MCP memory?

Three examples of what goes where

“Tests run with pnpm test”

“We use Postgres, not MongoDB, because …”

“I like small commits and short messages”

Connect Claude Code to WhyVault

Add WhyVault

Sign in

Try it

Point to the vault

A rules note for your vault

A decision log while you code

Two more workflows

Handing over between sessions

Several repos, one memory

Frequently asked questions

Does Claude Code have memory?

What’s the difference between CLAUDE.md and auto memory?

Do I still need CLAUDE.md if I use WhyVault?

How do I add an MCP server to Claude Code?

Can I share the memory with my team?

Can Claude Code break anything in my vault?

Where are my notes stored?

Keep reading

Claude memory

Decision log

MCP memory server

One memory for every repo.