Auto Memory, Imports & Path-Scoped Rules

Every Claude Code session starts with a fresh context window. Two complementary mechanisms carry knowledge across that gap, and the key to using them well is knowing which is which.

• CLAUDE.md files are instructions you write — coding standards, build commands, architecture. Static, version-controlled, deliberate.
• Auto memory is notes Claude writes itself — build commands it discovered, a debugging insight, a preference you corrected. Dynamic, per-repository, accumulated automatically.

Both load at the start of every conversation, and both are delivered as context, not enforced configuration — Claude reads them and tries to follow them, but compliance is advisory. (For a hard guarantee, a PreToolUse hook is the right tool, not memory.)

The mental model for this whole lesson: static CLAUDE.md is the floor, not the ceiling. Beyond it sit three mechanisms that let memory scale to a large project without bloating context — auto memory (Claude maintains it), @-imports (compose and share files), and .claude/rules/ (load instructions only when relevant).

Auto memory lets Claude accumulate knowledge across sessions without you writing anything. As it works, Claude decides what is worth remembering — a build command, an architecture note, a preference you corrected — and saves it for next time. It does not save something every session; it saves only what would plausibly help a future conversation.

Requirements & default. Auto memory is on by default and requires Claude Code v2.1.59 or later (check with claude --version).

Where it lives. Each project gets its own directory:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # concise index, loaded into every session
├── debugging.md       # detailed notes, loaded on demand
├── api-conventions.md # API decisions, loaded on demand
└── ...                # any other topic files Claude creates

The <project> segment is derived from the git repository, so all worktrees and subdirectories within the same repo share one memory directory. (Outside a git repo, the project root is used.)

What loads when. The first 200 lines of MEMORY.md, or the first 25KB — whichever comes first — load at the start of every conversation. MEMORY.md is an index; Claude keeps it concise by moving detail into topic files like debugging.md, which are not loaded at startup. Claude reads those on demand with its normal file tools when it needs them. (This 200-line / 25KB limit applies only to MEMORY.md — CLAUDE.md files load in full regardless of length.)

It is machine-local. Auto memory is shared across worktrees of the same repo but is not synced across machines or cloud environments. Treat it as a per-machine scratchpad, not a team artifact — for team-shared knowledge, write CLAUDE.md.

When you see "Writing memory" or "Recalled memory" in the interface, Claude is actively reading from or updating this directory. Everything there is plain markdown you can open, edit, or delete.

Auto memory has four control surfaces — a session toggle, a settings key, an env var to kill it outright, and a settings key to relocate it.

Toggle in a session. Run /memory and use the auto memory toggle.

Disable via settings (project settings.json):

{
  "autoMemoryEnabled": false
}

Disable via environment variable (one switch, global to that shell):

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Relocate the storage with autoMemoryDirectory in settings.json. The value must be absolute or start with ~/, and it can be set at any settings scope:

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

Seeding memory yourself. You don't have to wait for Claude to decide. Two ways to add a note directly:

• Prefix a message with # — e.g. # the API tests require a local Redis instance — and it goes into auto memory.
• Just ask in plain language: "remember this: always use pnpm, not npm." Claude saves it to auto memory.

Want it in CLAUDE.md instead (team-shared, version-controlled)? Say so explicitly — "add this to CLAUDE.md" — or edit the file yourself via /memory.

A CLAUDE.md can pull in other files with @path/to/import syntax. The referenced file is expanded and loaded into context at launch, right alongside the CLAUDE.md that imports it.

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md
- personal prefs @~/.claude/my-project-instructions.md

The rules that matter:

• Both relative and absolute paths are allowed. A relative path resolves relative to the importing file, not your working directory.
• Imported files can recursively import other files, up to a maximum depth of 4 hops.
• The first time a project uses external imports, Claude shows an approval dialog listing the files. Decline, and imports stay disabled and the dialog won't reappear. This is the secret-safety gate: an import can't silently slurp in a credentials file.
• Imports help organization, but they do not save context — every imported file still loads at launch. To actually reduce startup context, use path-scoped rules (next section).

The cross-worktree trick. A gitignored CLAUDE.local.md exists only in the worktree where you created it. If you work across multiple worktrees of the same repo and want personal instructions everywhere, don't copy the file around — import one file from your home directory:

# Individual Preferences
- @~/.claude/my-project-instructions.md

Now every worktree's CLAUDE.local.md (or CLAUDE.md) points at the same home-directory source of truth.

Bonus — AGENTS.md. Claude reads CLAUDE.md, not AGENTS.md. If your repo already has an AGENTS.md, put @AGENTS.md at the top of CLAUDE.md so both tools share one set of instructions without duplication.

Imports load everything at launch. Path-scoped rules are how you load instructions only when they're relevant — the single biggest lever for keeping a large project's startup context lean.

Place markdown files in .claude/rules/, one topic per file. They're discovered recursively, so you can nest them:

your-project/
├── .claude/
│   ├── CLAUDE.md           # main project instructions
│   └── rules/
│       ├── code-style.md   # loaded every session (no paths)
│       ├── testing.md
│       └── security.md

The behavior hinges on one frontmatter field — paths:

• A rule with paths frontmatter is conditional: it loads into context only when Claude reads a file matching the glob.
• A rule without paths loads unconditionally at launch, with the same priority as .claude/CLAUDE.md.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

That rule stays out of context until Claude opens a matching src/api/**/*.ts file — then it appears, exactly when it's useful. Glob patterns are flexible, including brace expansion:

Two more layers worth knowing:

• User-level rules in ~/.claude/rules/ apply to every project on your machine. They load before project rules, so project rules win on conflict.
• Symlinks are supported. Maintain one shared rule set and link it into many projects (ln -s ~/shared-claude-rules .claude/rules/shared); circular symlinks are detected and handled.

A good rule of thumb: if an instruction only matters for part of the codebase, it belongs in a path-scoped rule, not in CLAUDE.md.

In a large monorepo, walking up the directory tree can pull in other teams' CLAUDE.md files that are noise for your work. Two tools tame this.

claudeMdExcludes skips specific CLAUDE.md (and rules) files by path or glob. Put it in .claude/settings.local.json to keep the exclusion local to your machine:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Patterns match against absolute paths, and arrays merge across settings layers (user, project, local, managed). One firm limit: managed-policy CLAUDE.md cannot be excluded — org-wide instructions always apply. (For org deployments, the claudeMd key in managed-settings.json can embed CLAUDE.md content directly instead of shipping a separate file.)

/memory is your loaded-files inventory. Run it to:

• List every CLAUDE.md, CLAUDE.local.md, and rules file loaded in the current session — if a file isn't listed, Claude can't see it.
• Toggle auto memory on/off.
• Open the auto memory folder, or any listed file, in your editor.

InstructionsLoaded hook — the debugger. When you can't tell why a rule did or didn't load (path-scoped rules and lazily-loaded subdirectory files are the usual suspects), wire up the InstructionsLoaded hook. It logs exactly which instruction files load, when, and why — the ground truth for diagnosing a rule that silently never fired.