What is the difference between CLAUDE.md and memory.md in Claude Code?

CLAUDE.md is a file you write with rules and project instructions, and it loads into every session. memory.md is created by Claude Code's auto memory feature as an index of notes it takes about your feedback, linking to separate topic files. Both work best when kept short and used as pointers to detail elsewhere.

How long should a CLAUDE.md file be?

The video's rule of thumb is under 200 lines. Everything in it loads every session, so long material such as style guides or client lists belongs in separate files that CLAUDE.md references. That keeps the always-loaded context small and leaves room for the task.

Should Claude Code memory be injected by a hook or searched through an MCP tool?

A hook injects memory automatically, so it never depends on the model remembering to search, but it adds text to every prompt. An MCP tool only spends context when the model calls it, but the model may not call it. A common compromise is to inject a small index and expose full search as a tool.

All video notes

Video notes · Claude Code memory

Every Claude Code Memory System Compared (So You Don't Have To)

Video by Simon Scrapes on YouTube · 41 min · uploaded April 2026

Notes and analysis by BrainTube, written from the video. Not affiliated with Simon Scrapes. Watch on YouTube

In short

The video sorts Claude Code memory tools into six levels, from the built-in CLAUDE.md and auto memory up to a shared Postgres store that any AI tool can query. Its core frame, that every system differs only in where memory is stored and how it gets into context, is correct and useful. It never measures retrieval quality, and it underplays the cost of injecting memory into every prompt.

The argument

The claim is that the crowded list of memory tools is not a list of rivals. Each answers the same question, how Claude Code gets the right context at the right time, with a different storage choice and a different retrieval path. Most people should stop early: use CLAUDE.md and auto memory well, add a session hook that loads a small index, and only move to semantic search or verbatim recall when notes grow past what keyword lookup handles. The last two levels change the goal. They are about building a knowledge base from what you read and watch, and about sharing one memory across Claude, ChatGPT, Cursor and other tools. The creator says he runs the first three levels together in his own setup.

Key ideas, with timestamps

1:03
Storage and retrieval are the only variables
Before any tool appears, he sets up two axes: where memory lives (markdown files, vectors, local disk or cloud) and how Claude gets hold of it (always loaded, searched on demand, or injected by a hook). Every later level is placed on these two axes, which makes the comparison easy to follow.
2:36
Keep CLAUDE.md small and use it as an index
CLAUDE.md loads into every session, and nested files inherit from parent folders with the local file winning on conflicts. His rule of thumb is to keep it under 200 lines and move long material such as a brand voice guide into separate files it points to. He ties this to context rot, the drop in recall as more text is loaded.
3:38
Auto memory already writes an index for you
Running the /memory command opens a per-project auto memory folder. Inside, memory.md is a table of contents that links to separate feedback files, such as one about project structure. An empty folder shows nothing, which proves the notes are written in the background per project.
7:51
Level two: a structured folder plus a hook
Building on a prompt from Pavel Huryn and an article by John Connolly, he adds memory rules to CLAUDE.md, creates general, domain and tool files, and registers a pre-tool-use hook that injects the memory.md index before the first tool call. At 15:36 a reorganize memory pass deletes 13 empty files, trims six sessions and closes nine stale threads.
17:40
Level three: daily notes and semantic search
When general.md grows too large and keyword search stops finding things, he moves to the OpenClaw memory layout: a long-term memory.md, one daily note per date, and an optional dreaming pass that promotes recurring items. MemSearch, a plugin from Zilliz, ports that layout to Claude Code and uses a UserPromptSubmit hook to inject the top three semantic matches into every prompt.
23:16
Hook injection versus an MCP tool
He passes on Claude-Mem mainly because it is MCP-based, so Claude has to decide to call the search tool, while MemSearch pushes matches in automatically. This push versus pull distinction is the most practical point in the video, even if he treats it as a clear win for push.
23:46
Level four: verbatim recall with MemPalace
MemPalace keeps conversations word for word in a local Chroma vector store plus a SQL store of entities, filed into wings, rooms and drawers with a compact symbolic index. Hooks file sessions on session end and before compaction, and a mine command indexes past sessions. He repeats the project's claim of the top published benchmark score, with an "apparently" that is worth keeping.
35:08
Levels five and six leave Claude Code
Level five is Karpathy's LLM Wiki pattern: a raw folder Claude only reads and a wiki folder it fully maintains, viewed in Obsidian. Level six is Nate Jones's Open Brain, one Supabase Postgres table of text, embeddings and tags behind an MCP server, so Claude, ChatGPT and Cursor read the same store. He names Recall and Mem0 as hosted alternatives and objects that your data lives on their servers.

What it gets right

The storage and retrieval frame is the right way to judge any memory tool, and most comparison videos skip it. Once you ask "where does this live and what puts it into context", the tools stop looking like a confusing list and start looking like trade-offs.

The advice on CLAUDE.md is sound. A file that loads every session should hold rules and pointers, not reference documents. Treating memory.md and CLAUDE.md as indexes, with detail in separate files, is the same pattern good documentation uses, and it keeps the always-loaded cost small.

His recommendation to stop at level two for most people is also honest. Many creators push the most complex tool. He says plainly that a structured folder and one hook covers most solo users, and that you should only climb a level when you hit a specific failure, such as Claude missing an answer you know is in your notes.

What it leaves out

No measurement. Each level is justified by a symptom, never by a test. The one benchmark mentioned is a project's own claim. Before you adopt semantic search, write ten questions whose answers you know are in your notes and check how many each setup gets right.
The cost of always injecting. Pushing the top three matches into every prompt fixes the case where Claude forgets to search, but it also adds loosely related text to prompts that did not need it. That is the context rot he warns about at 3:06. Pull through an MCP tool is slower to trigger but only spends context when asked. Many setups use both: a small injected index plus a search tool.
What gets captured. Hooks that file every session on end or before compaction will also store API keys, client data and wrong turns. None of the levels discuss redaction or how to delete a memory that turned out to be false.
Knowledge versus operations. He dismisses the LLM Wiki pattern for business use, but much operational work depends on things you read. Decisions about a client's landing page are informed by research. The two kinds of memory are better linked than kept apart.
Moving targets. Plugin names, install commands and the unreleased Kairos daemon he describes at 5:44 are all as of the video's April 2026 upload. Check each repo before following the steps.

How this applies to memory across AI tools

Levels one to four are tied to one machine and one client. The video only reaches portability at level six, and it frames that as a heavy setup. The underlying idea is simpler: put memory behind an MCP server and every client can query the same store. That is what an MCP memory server does.

For the reading and watching side that level five covers, BrainTube saves YouTube videos with their transcripts, articles, PDFs and podcasts into one compiled knowledge base and exposes it as an MCP server, so Claude, ChatGPT, Cursor and other MCP clients can search it. That can sit next to a local CLAUDE.md and hook setup rather than replace it: project rules stay in the repo, and research lives in one shared place. For more on keeping one store across clients, see persistent AI memory across tools.

Who should watch it

Watch it if you use Claude Code daily and keep repeating context it should know, or if you are choosing between MemSearch, Claude-Mem, MemPalace and a hosted service. Beginners get the most from 1:33 to 6:15 (CLAUDE.md, auto memory, the 200-line rule) and the summary at 39:18. If you already have a working CLAUDE.md, start at 6:15 for the hook setup and 17:40 for semantic search. Skip it if you work mainly outside Claude Code or want benchmarks, since the video compares designs, not results.

Frequently asked

What is the difference between CLAUDE.md and memory.md in Claude Code?: CLAUDE.md is a file you write with rules and project instructions, and it loads into every session. memory.md is created by Claude Code's auto memory feature as an index of notes it takes about your feedback, linking to separate topic files. Both work best when kept short and used as pointers to detail elsewhere.
How long should a CLAUDE.md file be?: The video's rule of thumb is under 200 lines. Everything in it loads every session, so long material such as style guides or client lists belongs in separate files that CLAUDE.md references. That keeps the always-loaded context small and leaves room for the task.
Should Claude Code memory be injected by a hook or searched through an MCP tool?: A hook injects memory automatically, so it never depends on the model remembering to search, but it adds text to every prompt. An MCP tool only spends context when the model calls it, but the model may not call it. A common compromise is to inject a small index and expose full search as a tool.

Keep videos like this one searchable

BrainTube saves YouTube videos with their transcripts into one compiled knowledge base that Claude, ChatGPT, Cursor and other MCP clients can search.

Start free

Every Claude Code Memory System Compared (So You Don't Have To)

In short

The argument

Key ideas, with timestamps

Storage and retrieval are the only variables

Keep CLAUDE.md small and use it as an index

Auto memory already writes an index for you

Level two: a structured folder plus a hook

Level three: daily notes and semantic search

Hook injection versus an MCP tool

Level four: verbatim recall with MemPalace

Levels five and six leave Claude Code