Claude Code memory works in two ways: CLAUDE.md files that you write, and auto memory, a folder of notes Claude writes for itself. Both load at the start of every session, and both stay on your machine unless you commit them. At Tokenrip we use the first heavily and keep the second switched off, and this post explains both the mechanics and why we landed there. Docs checked 2026-10-21.
How does Claude Code remember things across sessions?
Every session starts with an empty context window, and two systems carry knowledge forward: CLAUDE.md for instructions you write, and auto memory for what Claude learns from your corrections (Claude Code docs). Both arrive as context, not as enforced rules, so anything that must always happen belongs in a hook. The chat itself doesn't carry over; to reopen a past conversation on the same machine, use claude --continue or claude --resume (sessions).
Claude Code auto memory vs CLAUDE.md: what's the difference?
CLAUDE.md is what you tell Claude, and auto memory is what Claude tells itself.
| CLAUDE.md | Auto memory | |
|---|---|---|
| Who writes it | You | Claude |
| What it holds | Rules, build commands, conventions | Your preferences, corrections, decisions it can't get from the code |
| How much loads | The whole file (aim for under 200 lines) | The first 200 lines or 25KB of the MEMORY.md index; topic files on demand |
| Scope | Organization, user, project or local | One repo and its worktrees, on one machine |
| Default | Always | On, in local sessions |
Claude doesn't save something every session. It keeps what would help a future conversation and skips what it can derive from the code or what CLAUDE.md already says, and you see "Saved 2 memories" or "Recalled 2 memories" when it does (how it works).
Why we turned auto memory off
We ran it, and it wasn't the memory we wanted. The problem wasn't that it forgot things; it remembered too well. It would pull up a rule or a decision from months back and apply it to whatever we were thinking through today, with no sense of whether that decision still held. Old architecture calls showed up in new brainstorms. There's no decay, nothing that says "this was true in June," so every memory gets applied across the board. The second problem was simpler: it's more text in the context window, every session, and we guard that window hard.
From what we've read since, we're not alone, and most people doing serious work with Claude Code leave it off. It's a toggle in /memory, or "autoMemoryEnabled": false in settings, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. What we wanted instead was memory we control, which is what CLAUDE.md turned out to be.
How we set up CLAUDE.md instead
We keep every CLAUDE.md lean, around 150 lines and never over 300, and we use it as a router rather than a rulebook. It holds the basics and then points at other files that carry the detail for a given task. Writing tests? There's a testing guidelines file, and it gets read when that's the work. Claude Code supports this three ways:
- Nested CLAUDE.md files. A CLAUDE.md in a subdirectory loads when Claude works in that folder, so each part of the codebase can carry its own rules (memory docs).
.claude/rules/. A rule file withpathsfrontmatter loads only when Claude touches matching files.- Imports.
@path/to/filein a CLAUDE.md pulls another file in, up to four hops deep.
We also keep AGENTS.md files in the same places, but they're just symlinks to the CLAUDE.md next to them. That works because Codex reads an AGENTS.md in each directory from the repo root down to where it's working, with the nearest one taking priority (Codex docs), and Cursor now reads nested AGENTS.md files in subdirectories too (Cursor docs). One set of rules, three agents, no copies to drift.
Where everything lives, for reference:
- User:
~/.claude/CLAUDE.md, only you, every project. - Project:
./CLAUDE.mdor./.claude/CLAUDE.md, shared through git. - Local:
./CLAUDE.local.md, gitignored, only you, this project. - Managed: a system path IT deploys to every machine.
- Auto memory:
~/.claude/projects/<project>/memory/, aMEMORY.mdindex plus one markdown file per memory. Plain files; edit or delete them any time.
What is the Claude Code memory limit?
The auto memory index loads its first 200 lines or 25KB, whichever comes first, and the rest doesn't (memory docs). Topic files don't count, since Claude reads them only when needed. Near the limit Claude is told to tidy the index; over it, the write succeeds but everything past the line is dropped on the next load. CLAUDE.md has no line cap, but you get a warning at startup and in /status when a file is over the recommended length. We've never hit either limit, and that's the point of keeping things lean.
Why is Claude Code memory not working?
Usually the file didn't load, or the instruction is too vague to follow. Check in this order:
- Run
/contextand look under Memory files. A file missing there is invisible to Claude. - Look for conflicting instructions across files, since Claude may pick one arbitrarily. Make rules specific: "use 2-space indentation", not "format code nicely".
- If a rule vanished after
/compact, it was given only in chat. Put it in the project-root CLAUDE.md, which Claude re-reads from disk after compaction. - If
AGENTS.mdis ignored, a CLAUDE.md on the project path is usually why.
Is Claude Code memory shared across machines, teammates or tools?
Only what you commit. Instructions travel through git, and learned memory, personal files and the state of your work don't. The docs are direct: "Auto memory is machine-local." Claude Code projects, a public beta on Pro and Max, keep project memory that every cloud thread reads, but a project belongs to one user.
| What you need | What Claude Code does natively | Gap |
|---|---|---|
| Rules loaded every session | CLAUDE.md, .claude/rules/, imports |
None for one repo |
| Same rules on a second computer | Project CLAUDE.md, if committed | ~/.claude/CLAUDE.md and auto memory don't travel |
| Teammates get it | Project files through git | Each person's auto memory is private |
| Codex or Cursor read it | AGENTS.md | Nothing shares open tasks or the last session's state |
For one person in one repo, the fix is files on disk: a plan, a context file with decisions and why, a task checklist, and a line in CLAUDE.md saying to read them first and update them before stopping. Files outlast compaction, and anything said only in chat gets summarized with the rest (what survives compaction). It stops working when a second agent, machine or person shows up, because a file can't say "taken," and two agents can start the same next step.
How we share memory across tools: a workspace, not a memory file
Everything that more than one agent needs lives in a Tokenrip workspace, and every agent we run connects to it. Our docs are there, the decisions are pinned, and the open tasks are there. A Grok Bot finds an issue and files a task in the workspace, Claude Code picks it up, and when it's done the result is recorded where the bot can see it. Nothing re-explains the project to the next tool, and nothing stale gets applied by accident, because the record says when and why each decision was made.
Tokenrip doesn't read your CLAUDE.md or auto memory, and it shouldn't; build commands stay in the repo. It's the layer above that: the shared record that CLAUDE.md can't be. To connect Claude Code, paste this into it and it does the setup; you give an email address and a six-digit code.
Connect me to Tokenrip. Fetch https://tokenrip.com/setup?ref=claude-code-memory and follow it.