How to Add Persistent Memory to Claude Code

Disclosure: Membase is our product. Claude Code's built-in memory is good, and for many solo projects it is all you need. We say where. Claude Code features were checked against Anthropic's Claude Code documentation in November 2026.

Quick answer

Claude Code has two kinds of built-in memory:

• CLAUDE.md: instructions you write. Claude Code loads them at the start of every session.
• Auto memory: notes Claude writes for itself as it works, in a MEMORY.md index plus topic files for each project. It needs Claude Code v2.1.59 or later and is on by default.

Use the /memory command to see, open and toggle these files.

Claude Code still forgets in four places: on your other machines, for your teammates, in your other AI tools, and once its memory index grows past what loads at startup. To fix that, add a memory layer that lives outside one machine. With Membase it takes one command:

npx add-mcp 'https://api.app.membase.com/mcp-http'

In this guide: Does Claude Code have memory? · CLAUDE.md · Auto memory · The /memory command · Why Claude Code forgets · What forgetting looks like · Your options · Add persistent memory with Membase · FAQ

Does Claude Code have memory?

Yes, with limits.

Inside one session, Claude Code remembers everything in its context window. When the session ends, that conversation is gone. A new session starts from the files on disk and whatever memory files load at startup.

So "memory" in Claude Code means files: the ones you write (CLAUDE.md) and the ones Claude writes (auto memory).

CLAUDE.md: memory you write

CLAUDE.md is a Markdown file of instructions. Claude Code reads it in full at the start of every session.

It can live in several places, from broadest to most specific:

Tips:

• Run /init in a project to generate a starter CLAUDE.md.
• Import other files instead of copying them, for example @README.md or @AGENTS.md.
• Keep each CLAUDE.md under 200 lines. Longer files use more context, and Claude follows them less consistently.

Good for: stable rules. Build and test commands, coding style, architecture notes.

Not good for: decisions you make while chatting. Claude Code won't add them to CLAUDE.md unless you ask.

Auto memory: memory Claude writes

Auto memory is Claude taking its own notes: fixes that worked, preferences it learned from your corrections, decisions you made together.

How it works:

• Each git repository gets a memory folder at ~/.claude/projects/<project>/memory/. It's shared across worktrees of the same repo, and it stays on that machine.
• MEMORY.md is the index. Claude Code loads its first 200 lines, or first 25 KB, whichever comes first, at the start of each session. Anything past that isn't loaded.
• Other files in the folder (for example debugging.md) are topic files, read only when needed.
• Turn it off in /memory, with "autoMemoryEnabled": false in your settings, or with the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

The files are plain Markdown. Open and edit them yourself to correct what Claude wrote.

The /memory command

Type /memory in Claude Code to:

• See your memory files
• Open CLAUDE.md or auto memory files to edit them
• Turn auto memory on or off

How to clear Claude Code memory: open the file from /memory and delete the lines you no longer want, or delete the project's folder under ~/.claude/projects/<project>/memory/ to start auto memory fresh.

Why Claude Code forgets

The built-ins are designed for one developer, on one machine, in one tool. Outside that, they forget:

1. On your other machines. Auto memory lives in your home directory. A second laptop, a server or a cloud sandbox starts with nothing but what is committed in CLAUDE.md.
2. For your teammates. Each developer's auto memory stays on their machine. A new teammate's Claude Code doesn't know what yours learned last month.
3. In your other AI tools. Cursor, Codex and ChatGPT keep their own memory. A decision made in Claude Code doesn't reach them.
4. As the index grows. Only the first 200 lines of MEMORY.md load at startup. As it grows, older notes can fall outside what Claude sees.

And one more: if neither you nor Claude writes a decision down, no file has it, so the next session can't know it.

What forgetting looks like

On Monday, you and Claude Code agree that new invoice numbers use INV-<ULID> and old numbers never change. The code still says max + 1.

Nothing is broken. The memory just isn't where the work is.

Your options for longer-lasting Claude Code memory

Add persistent memory with Membase

Membase is a memory layer for AI agents. It keeps one memory outside any single machine or tool, so Claude Code can save what matters and bring it back in the next session, wherever you work.

What it does differently:

• Recalls on every prompt, automatically. With the Claude Code hooks, relevant memory is added at session start and to every message you send. Claude doesn't have to decide to look.
• Never blocks you. Recall waits up to 10 seconds; if Membase is slow, the hook moves on and the results arrive with your next prompt.
• Saves once, in the background. Each session is saved when it ends, without slowing Claude Code down.
• One memory, everywhere. The same Memory works on every machine. Give each teammate's agent its own key scoped to that Memory, and revoke it any time.
• Every answer has a source. Each search result points back to the session or document it came from.
• Hosted or local. Use the hosted service, or keep memory on your own machine with local mode.
• Fewer tokens. Membase's engine scores 93.1% on LoCoMo while using up to 11x fewer tokens than the full history (our own numbers; see the method).

Set it up in 2 minutes:

1. Sign up at app.membase.com, open Connect > Developer keys and create a key. Create a Memory named after your repo.

2. Add Membase to Claude Code:

   claude mcp add --transport http membase https://api.app.membase.com/mcp-http \
     --header "Authorization: Bearer $MEMBASE_API_KEY"
   

3. For automatic recall on every prompt, install the Claude Code hooks: follow Membase Use Case 01: Claude Code Persistent Memory. The same installer works for Codex CLI and Gemini CLI.

4. Test it: decide something specific, quit, open a new session and ask about it without mentioning it.

Use it alongside CLAUDE.md and auto memory

You don't have to choose. Each layer has its job:

The same Memory also works in Cursor (add the MCP server to .cursor/mcp.json) and in ChatGPT and Claude (connect Membase as a custom connector).

Common mistakes

• Putting everything in CLAUDE.md. Long files are followed less consistently. Keep rules there and let memory hold the rest.
• Running /clear or /compact before saving decisions. Ask Claude to note important decisions first.
• Letting MEMORY.md grow unchecked. Review it now and then so important notes stay in the first 200 lines.
• One memory for every repo. Create one Memory per repository so projects don't mix.

Start building with Membase

• Get an API key: app.membase.com > Connect > Developer keys
• Tutorial: Membase Use Case 01
• MCP server: https://api.app.membase.com/mcp-http
• Docs: docs.membase.com

Membase is in beta and free during the beta.