# How Claude Code Memory Works: CLAUDE.md, Auto Memory & the # Shortcut > Claude Code remembers through layered files, not magic — the CLAUDE.md hierarchy, the auto memory directory, the # shortcut, and how to keep all of it trustworthy. **Source:** [https://northlabapps.com/blog/claude-code-memory/](https://northlabapps.com/blog/claude-code-memory/) **Published:** 2026-07-04 **Topics:** claude-code, memory, configuration **Author:** NorthLab Apps (https://northlabapps.com) — makers of NorthLab Folders, a privacy-first folders/search/export extension for ChatGPT and Claude --- "Does Claude Code remember anything between sessions?" is the wrong question — it does. The right question is *which of its several memories does what*, because Claude Code's memory isn't one system: it's layered files with different owners, lifetimes, and jobs. Once I understood the layers, the tool stopped feeling forgetful. Here's the map. ## The mental model: memory is files Everything Claude Code "remembers" across sessions lives in Markdown files on your disk. There's no opaque cloud profile. That single fact has three happy consequences: memory is **inspectable** (read the file), **correctable** (edit the file), and **portable** (commit the project parts to git and your whole team's agents share them). The layers, from most intentional to most automatic: ## Layer 1: CLAUDE.md — the rules you write The foundation is the CLAUDE.md hierarchy: `~/.claude/CLAUDE.md` for personal preferences across every project, the repo-root `CLAUDE.md` for project rules (commit this one), and per-subdirectory files for scoped conventions. These load at every session start — they're the closest thing to a permanent system prompt. This layer is *yours*: deliberate, curated, slow-changing. I keep hard rules here ("never commit to main"), commands, and conventions. The full craft of writing one — including what to leave out and why bloat backfires — is in the [complete CLAUDE.md guide](https://northlabapps.com/blog/claude-md-complete-guide/). ## Layer 2: auto memory — the notes Claude keeps for itself The newer layer, and the one that changed daily use most: Claude Code maintains its own per-project memory directory (under `~/.claude`, with a `MEMORY.md` index that's loaded each session). As it works, it can record things it learned — "the staging DB needs the VPN", "this codebase's tests are flaky in CI but not locally", "user prefers PRs without co-author trailers" — and recall them next session without you re-explaining. The distinction from Layer 1 matters: CLAUDE.md is what *you* teach; auto memory is what *it* learns. In practice the agent's notes accumulate the long tail of project trivia you'd never bother writing rules for. Because it's files, you can — and occasionally should — audit it. Stale memories are the failure mode: a note that was true in March and false in July gets recalled with confidence. When Claude acts on something oddly specific and wrong, check its memory directory before assuming the model is confused; delete or correct the entry and the problem stays fixed. ## Layer 3: the session itself (and why it's not memory) Within one session, everything is in context — that's not memory, that's the conversation. It dies with the session (or gets summarized when context runs long). The most common "Claude forgot!" complaint is really this layer: a correction made mid-chat was never persisted anywhere. Which brings us to the shortcut that fixes it. ## The # shortcut: turn corrections into memory in two seconds Start any message with `#` and Claude Code offers to save that instruction to the appropriate memory file. This is the highest-value habit in the whole system: the moment you correct something — "# always run make lint before committing" — spend the two seconds to persist it. The `/memory` command opens the memory files in your editor when you want to curate directly. My workflow reduced to one sentence: **corrections go to `#`, conventions go to CLAUDE.md, and trivia is the agent's job to remember.** ## Keeping the whole system trustworthy Three maintenance habits, learned the annoying way: 1. **Prune on contradiction.** When behavior surprises you, the cause is usually two rules or memories in tension. Find the older one and delete it. 2. **Keep rules short enough to be followed.** Both layers degrade the same way: past a certain size, individual lines lose force. If a rule never prevented a mistake, it's decoration. 3. **Review project memory like code.** The repo CLAUDE.md changes in PRs where teammates can see it; a quarterly skim of the auto memory directory catches drift. ## Where memory ends and enforcement begins Memory is advisory — it shapes what Claude *intends*. When a rule must be unbreakable ("never touch prod config"), that's not a memory problem, that's a permissions problem: deny it mechanically in [settings.json](https://northlabapps.com/blog/claude-code-settings-json/) so intent never enters into it. And when a *workflow* (not a fact) is the thing you keep re-explaining, package it as a [custom slash command](https://northlabapps.com/blog/claude-code-commands-cheat-sheet/) instead. One adjacent note, with the usual disclosure that we build it: the thinking that *precedes* Claude Code sessions — design chats in claude.ai, debugging rubber-ducking in ChatGPT — is a memory system nobody manages. [NorthLab Folders](https://northlabapps.com/folders) gives those conversations local folders and cross-platform search, so "where did I work this out?" has an answer there too. ## Frequently asked questions ### Does Claude Code have memory between sessions? Yes, through files. CLAUDE.md files hold your standing instructions, and Claude Code's auto memory gives the agent a per-project directory (with a MEMORY.md index) where it records facts and lessons it learns while working. New sessions load these automatically — memory is persistent, inspectable, and just Markdown on disk. ### How do I make Claude Code remember something? The fastest way is the # shortcut: start a message with # and Claude Code offers to save that instruction to the right memory file. You can also edit files directly with the /memory command, or simply tell Claude to remember something and it writes it to its memory directory. ### Where is Claude Code's memory stored? All on your machine. Standing instructions live in CLAUDE.md files (~/.claude/CLAUDE.md globally, plus per-project files at the repo root). Auto memory lives in a per-project directory under ~/.claude, with a MEMORY.md index loaded at session start. Nothing about this is a cloud service — you can read and edit every file. ### Why does Claude Code keep forgetting my instructions? Usually one of three causes: the instruction was only ever said in a chat (session context dies with the session — put it in CLAUDE.md), the memory file has grown so bloated the rule is drowning in noise, or the rule contradicts something else in the hierarchy. Short, specific, non-contradictory files get followed.