Let Claude keep its own notes with auto memory and /memory

Some knowledge never gets written into a rules file because nobody sits down to write it. Suppose that mid-task you say a sentence like this: “When you touch src/payments/, show me the diff before you commit - I review those myself.” It is a preference, expressed in passing. Your teammates do not need your review step in the shared CLAUDE.md, you will never open an editor to record it, and tomorrow’s session will not have it unless something wrote it down. (The sentence is a constructed example, not a transcript.)

Auto memory is that something: the persistence system where Claude is the author.

Two writers, two systems

Claude Code carries standing knowledge into a session through two systems, split by who writes them:

• CLAUDE.md files: instructions you write, one file per scope (user, project, local, subdirectory), concatenated into the model’s context at launch. The scope lesson covers how they layer.
• Auto memory: notes Claude writes for itself, from your corrections and from what it learns while working in the repo. You do not author it; you audit it.

Auto memory is on by default, and it is selective. It skips anything it can derive from the codebase and anything CLAUDE.md already states, saving only what would help a future session: the correction that cost twenty minutes, the quirk it had to rediscover. When it writes or reads, you see short interface messages such as “Saved 2 memories” or “Recalled 2 memories.”

Where it lives matters. It is per-project, under ~/.claude/projects/<project>/memory/, with the project path derived from the git repository, so worktrees and subdirectories of one repo share a folder. It is machine-local and never reaches a teammate’s checkout. Inside the folder, a MEMORY.md index loads every session; deeper topic files load on demand when a session needs them. The behavior and requirements are documented on the memory reference.

Ask, and choose the destination

You can also hand the agent a fact directly, in plain language. The reply’s shape looks like this. It is illustrative, not captured; the confirmation line follows the documented wording, and the count is whatever it actually saves:

> remember that I review changes to src/payments/ myself before they're committed

  ⎿ Saved 1 memory

There is a deliberate fork in that gesture, and it is the practical heart of this lesson. “Remember X” routes to auto memory, the agent’s own notes on your machine. “Add this to CLAUDE.md” routes to the team-shared rules, a durable rule your whole team inherits through git. Same sentence shape, different destination, so choose on purpose:

• Reach for the rule when the fact is a standing truth your teammates also need: a money convention, a regression-test requirement. Authored, committed, shared.
• Let auto memory hold it when it emerged from working: a preference expressed in passing, a build quirk, a debugging shortcut. Machine-local, agent-curated, no ceremony.

Audit what the agent kept

Agent-written memory is trustworthy only if you can see it. Two commands cover the audit, and they answer different questions.

/memory is the picker for browsing and editing. It lists your memory-file locations across user and project scopes, including entries for files that do not exist yet, and selecting any of them opens it in your editor, creating a selected file first if it was only ever proposed. It carries the auto-memory toggle (saved as autoMemoryEnabled in ~/.claude/settings.json) and an option to open the auto-memory folder at ~/.claude/projects/<project>/memory/.

Everything in that folder is plain markdown you can read, edit, or delete. That is the whole audit posture: an agent writing its own notes can capture something wrong or hold a fact gone stale, so the hygiene you apply to your hand-written rules applies to the files the agent maintains. Read them periodically; prune them.

The second command answers what actually loaded. /context breaks the current session’s window into categories, and the Memory files list shows every rules file present in the session. If a file is missing there, the agent cannot see it. /memory tells you where things live; /context tells you what this session is reading.

Memory is context, not enforcement

Neither system compels anything. Both load as context the model reads and tries to follow. The course’s example payments repo shows the limit in one file: its CLAUDE.md says to use integer cents and never floating point for currency, and src/payments/processor.ts still computes the fee-inclusive total as req.amount * 1.029 in floating point, with the suite green on an assertion of 2056.971. When an outcome must not depend on the model deciding well, you need a hook - a check Claude Code runs automatically at a set moment - and the gate lesson builds one on these exact paths.

Where this leaves you

A project with both systems in place explains itself. Commands, domain facts, and conventions are written once, scoped deliberately, and loaded on their own. An audit on every /init suggestion (the command that drafts CLAUDE.md for a repo) keeps the team file true. Auto memory accumulates what only emerged in flow, and /memory plus /context keep it visible. Every session starts past the basics, with one limit stated plainly: memory informs, and the float in processor.ts is the standing proof.

Knowing the project is half of the problem. The other half is which model the agent brings to a task and how hard it reasons before it acts. A one-string error-message tweak and a concurrency bug should not get the same horsepower, and the models chapter is that lever.