Claude Code memory: CLAUDE.md, auto memory and durable context

How does Claude Code memory work?

Claude Code combines project instructions with notes generated from your working preferences. CLAUDE.md is explicit guidance written by a person. Auto memory is Claude’s own record of corrections, preferences and project context it decides are worth carrying forward. The official documentation says both are loaded at the start of every conversation.

Neither system is an authorization or policy engine. Claude treats the files as context, not enforced configuration. Actions that must be blocked regardless of model behavior belong in hooks, permissions and controls outside memory.

What is the difference between CLAUDE.md and auto memory?

CLAUDE.md is for instructions you want Claude to follow, such as build commands, architecture and coding standards. Auto memory is for observations Claude accumulates, such as a repeated correction or a preference inferred from the session. You author one; Claude writes the other.

Use CLAUDE.md when the instruction must be reviewable in Git. Use auto memory for useful observations that are specific to the local working relationship.

What should go in CLAUDE.md?

Put durable, project-specific instructions in CLAUDE.md: build and test commands, architecture boundaries, naming conventions, review expectations and known environment constraints. Write concrete rules such as “Run the API contract test before changing a response schema” instead of broad advice such as “be careful with the API.”

Keep the file focused. The official guidance recommends targeting under 200 lines per CLAUDE.md because longer files consume more context and can reduce adherence. Move file-specific instructions into `.claude/rules` so they load only when Claude works with matching paths.

• Document commands the agent cannot reliably infer from package scripts.
• Name approved boundaries and files that must not be changed without review.
• Record environment constraints that cause failed builds or deployments.
• Remove contradictory or obsolete instructions during every major refactor.
• Keep secrets, credentials and customer data out of all instruction files.

Does Claude Code read AGENTS.md?

Current Claude Code versions can read a repository’s AGENTS.md files in place of CLAUDE.md. This lets a team share one instruction file across coding tools. The exact loading behavior depends on project instruction settings, version and the presence of CLAUDE.md files in the working directory or its parents.

Use AGENTS.md when cross-tool consistency matters, then verify what Claude reports as loaded in the current session. Do not copy the same rules into several files merely to support every tool; duplicated context increases drift and contradictions.

Where does Claude Code auto memory live?

Auto memory is stored under `~/.claude/projects/<project>/memory/MEMORY.md` unless the auto-memory directory is configured elsewhere. It is local to the Claude Code environment, organized by project and shared across worktrees. The index loads at the start of a session, while supporting topic files can be read when needed.

Use `/memory` to inspect and edit what Claude has stored. Audit it after repeated corrections because an inferred preference can become stale, apply to the wrong repository or conflict with a newer instruction file.

cd /path/to/project
claude

# Inside Claude Code
/memory

# In the shell, inspect the local memory directory
find ~/.claude/projects -path '*/memory/MEMORY.md' -maxdepth 4

What are the limits of built-in Claude Code memory?

Built-in memory is optimized for one developer working with a local coding agent. It is not a complete customer-memory service. It does not by itself provide a cross-product memory API, fine-grained tenant retrieval, a shared service for Cursor, Codex and web agents, or a full deletion workflow for derived embeddings and summaries.

The local nature of the default store is also an operational boundary. A different machine, teammate or CI runner does not automatically inherit the same context. A shared repository can carry CLAUDE.md or AGENTS.md, but local auto memory remains personal to the environment unless you deliberately externalize it.

• Local files are not a multi-tenant memory service.
• One developer’s auto memory is not a team knowledge base.
• Instruction files cannot enforce security policy.
• A local store does not synchronize across unrelated harnesses.
• Expiration, correction, export and deletion need explicit product behavior.
• A shared external service needs authentication and scope enforcement.

When should Claude Code use durable external memory?

Add an external memory layer when context must follow a user or team across machines, repositories, Claude Code sessions and other agent harnesses. It becomes necessary when memory needs its own API, provenance, retention rules, audit trail or tenant boundaries that local Markdown files cannot enforce.

Keep local instructions for immediate coding policy and use the external layer for selected durable facts and reviewed project decisions. Do not turn every terminal message into remote memory. Retrieve only the project constraints, accepted decisions and user preferences relevant to the current task.

How should Claude Code memory be corrected and deleted?

Treat instruction files as reviewed code and auto memory as user data. Review CLAUDE.md and AGENTS.md changes in pull requests. Audit local auto memory periodically, remove stale entries and ensure it does not contain secrets, private tokens or unrelated customer information.

For an external memory service, deletion must cover original events, extracted records, summaries, embeddings and copies used by other connected agents. A local `/memory` edit does not delete an external record, and deleting local auto memory does not remove a project decision already synchronized to a shared service.

How do you test Claude Code memory?

Start a fresh session and ask a task that requires a known repository convention. Change the convention, start another session and verify the new instruction wins. Then test path-specific rules in the correct and incorrect directories, a second worktree and a second developer environment.

• Confirm CLAUDE.md or AGENTS.md is visible in `/context`.
• Verify a subdirectory rule loads only within its intended path.
• Change a superseded instruction and test the next session.
• Verify auto memory does not repeat a removed secret or stale preference.
• Repeat the same decision in another harness only when external memory is intended.
• Test deletion across local files and the external service separately.

What is the recommended Claude Code memory architecture?

Use CLAUDE.md or AGENTS.md for explicit repository instructions, `.claude/rules` for path-scoped guidance and auto memory for local learnings. Add an authenticated external memory layer only when the context must cross machines, tools, users or products. Keep policy enforcement in hooks and permissions, not in remembered text.