# Auto memory

> Auto memory is a per-repo directory Claude Code writes for itself, outside version control. Only the first 200 lines or 25KB of MEMORY.md load per session.

URL: https://bartlomiejkrupa.dev/notes/auto-memory/
Category: concept | Updated: 2026-10-07
Summary: Auto memory is a per-repo directory Claude Code writes for itself, outside version control. Only the first 200 lines or 25KB of MEMORY.md load per session.

**Auto memory** is a directory Claude Code writes for itself, holding notes it decided were worth keeping: build commands, debugging insights, architecture notes, workflow habits. You do not author it, and it is on by default.

`MEMORY.md` is the index in that directory. **Topic files** are any other markdown beside it (`debugging.md`, `api-conventions.md`) - unlimited in size, and read on demand rather than at startup.

## Where it lives and what loads

| Property | Auto memory | `CLAUDE.md` |
| --- | --- | --- |
| Who writes it | Claude | You |
| Location | `~/.claude/projects/<project>/memory/` | Your repo |
| In version control | No, machine-local | Yes, at project scope |
| Loaded per session | First 200 lines or 25KB of `MEMORY.md` | In full (files over 4 MiB are skipped) |
| Scope | Per repository, shared across worktrees | Project, user, or org |

Two consequences follow from that table. `<project>` is derived from the git repository, not the working directory, so every worktree and subdirectory of one repo shares a single store. And because it is machine-local and never synced, a teammate on the same `CLAUDE.md` runs a differently shaped agent.

The index is the part that silently fails: everything past 200 lines or 25KB stops loading, so a bloated `MEMORY.md` drops its own tail. A write that lands near the limit gets a reminder to compact; a write that lands over it returns an explicit error. It is one line item in the [startup tax](/notes/startup-tax) you pay before typing.

```bash
/memory        # browse the store and open a file
/memory trim   # index over its read limit? drop old entries
/context       # what actually loaded this session
```

## Separate stores

Subagents do not inherit the main conversation's auto memory - see [subagent context isolation](/notes/subagent-context-isolation). A fork is the exception, since it duplicates the current conversation rather than starting fresh. A subagent declaring `memory: user | project | local` gets its own directory (`~/.claude/agent-memory/<name>/`, `.claude/agent-memory/<name>/`, or `.claude/agent-memory-local/<name>/`) under the same index rule.

## Turning it off

```jsonc
{
  "autoMemoryEnabled": false,
  "autoMemoryDirectory": "~/my-memory-dir"
}
```

Both settings work at user or project scope; `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` disables it for one invocation. At project scope `autoMemoryDirectory` is honored only after you accept the workspace trust dialog, the same gate that governs hooks. Disabling auto memory also disables subagent memory - the `memory` field becomes a no-op.

Measured, a rule planted in auto memory held 3/3 when nothing contradicted it and 0/3 when the prompt did - the same score the identical rule posted in `CLAUDE.md`. It is a knowledge layer, not an enforcement one: [knowledge vs rule](/notes/knowledge-vs-rule). Full audit walkthrough and the benchmark: [Claude follows its own memory until you contradict it](/articles/claude-code-auto-memory).

Sources:
- How Claude remembers your project: https://code.claude.com/docs/en/memory
- Create custom subagents: https://code.claude.com/docs/en/sub-agents
- Errors: https://code.claude.com/docs/en/errors
