claudekit / guides / memory-tool
[ Guide · Practical · 8 min ]

Getting Started with Auto Memory in Claude Code

published · updated

How Claude Code's auto memory keeps context between sessions. Covers what gets saved automatically, where it's stored, and how to add or edit memories yourself.

Claude Code’s docs call this feature auto memory. It is not the Claude API’s Memory tool, which you use by implementing the memory tool’s file operations in your own application.

What auto memory solves

Re-explaining the same context every session is wasteful. Auto memory saves stable facts about you and your project plus recurring feedback so they’re auto-restored next time.

Storage location

~/.claude/projects/<project>/memory/
├── MEMORY.md           # Index, one line per memory, loaded into every session
├── user_role.md        # One memory
├── feedback_testing.md # One memory
└── ...                 # Any other topic files Claude creates
  • The <project> path is derived from the git repository, so all worktrees and subdirectories within the same repo share one auto memory directory. Outside a git repo, the project root is used instead.
  • To store auto memory in a different location, set autoMemoryDirectory in your settings.json.
  • Auto memory is machine-local. Files are not shared across machines or cloud environments.
  • Claude records the kind of each note as a type field (user, feedback, project, reference) in the memory file’s frontmatter.

How much of MEMORY.md loads

The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation. Content beyond that threshold is not loaded at session start, so Claude keeps MEMORY.md concise by moving detailed notes into separate topic files. If the index goes over a limit, Claude Code returns an error telling Claude to rewrite it. Topic files such as user_role.md aren’t loaded at startup; Claude reads them on demand.

The main conversation’s auto memory isn’t loaded into subagents; the exception is a fork, which inherits the parent conversation. A subagent’s own auto memory, enabled with the subagent memory field, is a separate directory.

What gets auto-saved

user

Your role, expertise, and working preferences.

  • e.g. “Data scientist; currently focused on observability and logging”

feedback

Corrections you give Claude and approaches you confirm.

  • e.g. “Integration tests must hit a real DB, not mocks — last year’s migration regression”

project

Ongoing work, deadlines, and decisions that Claude can’t derive from the code or git history.

  • e.g. “Merge freeze for the mobile release cut starting 2026-03-05”

reference

Where to find information outside the project, such as an issue tracker or dashboard.

  • e.g. “Pipeline bugs tracked in Linear’s INGEST project”

Claude doesn’t save something every session. It decides what’s worth remembering based on whether the information would be useful in a future conversation.

What is NOT saved

  • Anything derivable from the codebase, such as architecture or file paths
  • Change history already in git
  • Debugging fixes (the fix lives in the code)
  • Anything your CLAUDE.md files already say

Add or remove manually

Remember this decision: we use Stripe for payments. PayPal was evaluated but excluded due to Korean entity processing limitations.

Claude saves it to auto memory. To add instructions to CLAUDE.md instead, ask directly, like “add this to CLAUDE.md.”

Remove the Stripe decision memory

Or edit or delete .md files in the memory directory directly.

Inspect and turn off

/memory

The /memory command lists your CLAUDE.md, CLAUDE.local.md, and other memory file locations. It also lets you toggle auto memory on or off and provides an option to open the auto memory folder. Select any file to open it in your editor.

There are three ways to turn it off:

MethodScope
Auto memory toggle in /memorySaves autoMemoryEnabled to ~/.claude/settings.json (all your projects)
"autoMemoryEnabled": false in a project’s settingsThat project
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1Sessions started with that environment variable

Hallmarks of a good memory

  • Non-obvious facts — decisions and background not findable in code
  • Includes the why — why was it decided this way
  • Absolute dates — 2026-05-15 instead of “tomorrow”
  • Concise — one-line index + a short body paragraph

Patterns

Team rules belong in CLAUDE.md

Put team rules like “we always review PR merges in plan mode” in the project CLAUDE.md, not in memory. Auto memory is machine-local and isn’t shared with teammates, and the docs list coding standards and workflows as what CLAUDE.md files are for. Claude treats both as context, not enforced configuration; to block an action regardless of what Claude decides, use a PreToolUse hook (see Writing a Great CLAUDE.md and Automate Workflows with Hooks).

Post-incident notes

After an incident, save lessons like “X migrations are always validated with tool Y” to prevent recurrence.

External system mapping

Save mappings like “design review happens in Figma’s ‘Design QA’ channel” so Claude points you there in related work.

Next steps

§ 10

Frequently Asked Questions

frequently asked
§ 10.1
What is auto memory?
Auto memory is notes Claude writes itself based on your corrections and preferences. It is loaded at the start of every session, so you don't have to re-explain context every time. It is separate from the Memory tool in the Claude API.
§ 10.2
Where are memories stored?
In `~/.claude/projects/<project>/memory/` as markdown files. The `<project>` path is derived from the git repository, so all worktrees and subdirectories within the same repo share one auto memory directory. Set `autoMemoryDirectory` to store it elsewhere.
§ 10.3
What gets saved automatically?
Four kinds of notes: user (your role, expertise, and working preferences), feedback (corrections and approaches you confirm), project (ongoing work, deadlines, and decisions), and reference (where to find information outside the project). Claude skips anything it can derive from the codebase, and anything your CLAUDE.md files already say.
§ 10.4
Can I add or remove memories manually?
Yes. Auto memory files are plain markdown you can edit or delete at any time, and `/memory` opens the auto memory folder. When you ask Claude to remember something, it saves it to auto memory.
§ 10.5
Can I turn auto memory off?
Use the auto memory toggle in `/memory`, which saves `autoMemoryEnabled` to `~/.claude/settings.json`. To turn it off for a single project, set `"autoMemoryEnabled": false` in that project's settings, or set `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`.
§ 10.6
How is this different from the claude-mem plugin?
Auto memory is built into Claude Code. claude-mem is a separate plugin that aggressively compresses session history; use both together for stronger long-context retention.