Claude Code Auto‑memory: persistent project memory for evolving preferences, decisions, and references
Claude Code’s Auto-memory stores evolving project context across sessions, preserving preferences, decisions, and references without cluttering CLAUDE.md.
What Auto‑memory Is and Why It Matters
Claude Code’s Auto‑memory is a targeted persistent memory system designed to carry short‑lived, session‑relevant knowledge across interactions without turning your project repository into a living log. Where CLAUDE.md records the stable facts about a project — stack choices, conventions, deployment rules — Auto‑memory captures things that change more rapidly: corrected style preferences, architecture choices made during work, production gotchas, and pointers to resources you return to frequently. The feature is intended to reduce repetitive re‑orientation at the start of each session while keeping that contextual information distinct from versioned project files.
Because Claude normally begins each session without recall, Auto‑memory provides a disciplined place to store details you explicitly decide are worth carrying forward. That selectivity is central to how the system works: Auto‑memory is not an automatic transcript of everything that happened, and it is not a substitute for source control or issue tracking.
How Auto‑memory Stores and Loads Context
Auto‑memory is implemented as a set of Markdown files kept in specific directories. For project‑scoped memory the files live under a per‑project path such as ~/.claude/projects/<project>/memory/. For information that should apply across workspaces, there is a global location at ~/.claude/memory/. At session start Claude reads an index file named MEMORY.md to load the relevant files for that session, and during a session Claude can update those files when instructed.
The system is explicit rather than automatic: Claude will not capture everything by default. Either the user tells Claude to save an item to memory, or the user relies on configured rules that tell Claude when to persist discovered information. The distinction between CLAUDE.md and the memory files is important: CLAUDE.md documents project facts and policies, while memory files document the evolving working relationship and transient project state that are useful across multiple sessions.
The Four Memory Types and When Claude Uses Them
Each memory file begins with frontmatter that declares its type. That type is functional — it determines when and how Claude will consult the file. The four supported types are:
- user — Information about the person you’re working with: role, technical level, and areas of knowledge. Claude uses this to calibrate explanation depth and avoid repeated introductions.
- feedback — Notes about how to approach the work: corrections, validated approaches, and stylistic rules discovered during sessions (for example, “don’t summarize what you just did at the end of messages” or “use a real database in tests, not mocks”).
- project — Statements of current project state such as active decisions, initiatives, and time constraints. These items tend to age quickly and require regular review.
- reference — Pointers to external artifacts and systems you rely on, for example bug trackers or monitoring dashboards (e.g., “pipeline bugs tracked in Linear project INGEST” or a Grafana latency board URL).
Because the file type shapes Claude’s use of the record, choosing the correct frontmatter type is a practical part of keeping memory useful.
Deciding What to Keep and What to Leave Out
Auto‑memory is intentionally not an archive. The guiding rule for what belongs in memory is that the content must be non‑deducible from the repository or existing CLAUDE.md and useful for future sessions. Examples of what the source recommends keeping include:
- A style preference that was confirmed or corrected during a session.
- A production gotcha or invisible constraint discovered while working.
- An active architecture decision that is not yet reflected in code.
- A pointer to an external resource you consult regularly.
Items that do not belong in Auto‑memory are those already visible in files (Claude can read the code), session details better tracked by git commits or issue trackers, in‑progress tasks that are part of the current session, and conventions already documented in CLAUDE.md. The intent is to avoid duplication and to keep memory focused on what would otherwise be lost between sessions.
Project Memory Versus Global Memory: When to Use Each
Auto‑memory provides separate scopes so that context is applied appropriately:
- Project memory (e.g.,
~/.claude/projects/<sanitized-cwd>/memory/) is isolated to a working directory. Opening Claude from a different folder yields a different memory set. This isolation is suitable for preferences and decisions that only make sense for one repository or active project. - Global memory (
~/.claude/memory/) is read in every session across projects. It’s the right place for cross‑cutting preferences such as expected response style or a person’s technical level and general communication conventions.
The practical workflow suggested by the source is to start with project memory and move items to global memory only when the same preference surfaces across multiple projects. Importantly, the guidance is to avoid duplicating entries in both scopes.
Automating Saves with Global Rules in CLAUDE.md
To reduce the friction of saving memories, you can encode a saving policy once in the user‑level CLAUDE.md file at ~/.claude/CLAUDE.md. A representative rule block instructs Claude to persist durable information that appears during a session into the appropriate memory file immediately, for example:
- Preference discovered or corrected →
memory/userormemory/feedback - Approach correction →
memory/feedback - Durable project decision →
memory/project - Pointer to regularly used resource →
memory/reference
The file also emphasizes what not to save: temporary state, in‑progress work, content already in CLAUDE.md, or anything deducible from the code. This “filter” is as important as the trigger: without a clear filter, memory rapidly grows into the same kind of noisy, bloated document that a poorly maintained CLAUDE.md can become.
Maintaining Memory: Audit Prompts and Review
Because project memories can become stale, the source recommends running a periodic audit. The suggested audit prompt walks through each memory file and evaluates:
- Is the content still accurate (checking against the current codebase if necessary)?
- Is the content non‑deducible from code or CLAUDE.md?
- Is the file type correct (user / feedback / project / reference)?
- Is the frontmatter description precise enough?
The audit should also look for global coherence: duplicates, contradictions, stale project memories, and whether MEMORY.md is up to date. The output recommended by the prompt is a table listing File | Issue | Recommended action, after which corrections can be applied. For convenience, the audit prompt itself can be saved as a slash command under .claude/commands/audit-memory.md (project) or ~/.claude/commands/audit-memory.md (global), allowing a single /audit-memory command to initiate the process.
Common Failure Modes and Best Practices
The source identifies a clear failure mode: treating Auto‑memory as a catch‑all storage and dumping every detail into it. When memory has no selection criteria — “trying to put everything in it” — it becomes as ineffective as an overly long CLAUDE.md. Claude will read and process all memory files at session start, and if they contain noisy or outdated items the useful signal can be drowned out by irrelevant data.
Practical best practices drawn from the documented guidance include:
- One file per topic: keep each memory file focused so it’s easy to review and audit.
- Choose types deliberately: frontmatter type controls usage, so prefer precision.
- Start project‑local, promote to global when broadly applicable: avoid duplication.
- Audit regularly: especially project memories that tend to age quickly.
- Use CLAUDE.md rules to automate saves only when the filter prevents over‑logging.
These practices emphasize curation and active maintenance as the keys to keeping Auto‑memory helpful rather than harmful.
How Auto‑memory Fits with Developer Workflows and Tools
Auto‑memory is positioned as a complementary mechanism alongside existing project artifacts. The source explicitly contrasts memory with version control and issue trackers: session details belong in git logs; in‑progress tasks belong to the current session or task manager; and conventions that should be permanent belong in CLAUDE.md. Memory exists for the middle ground — ephemeral but reusable context that doesn’t belong in the codebase.
The system also integrates naturally with developer processes: saving pointers to external systems (bug trackers, dashboards) as reference files makes them discoverable by Claude at session start; feedback entries codify approaches that should be obeyed in future code interactions; and user entries help Claude adapt communication style. The audit workflow can be treated like any other maintenance task in a developer’s routine.
Broader Implications for Teams and Projects
The design principles behind Auto‑memory — selective persistence, scoped contexts, and explicit auditability — imply a shift in how teams might manage ephemeral knowledge. Rather than relying solely on ad‑hoc notes, pull request comments, or personal README fragments, Auto‑memory provides a place to surface transient but consequential information that affects day‑to‑day development: corrected preferences for code formatting, temporary architecture choices being tested, or operational gotchas discovered in production.
However, the utility of that system depends on disciplined curation. Teams that adopt Auto‑memory should pair it with review rituals (the audit prompt is one example) and clear rules about what belongs in project memory versus CLAUDE.md or global memory. Without that discipline, Auto‑memory risks becoming yet another source of stale guidance that misleads rather than assists.
Possible business use cases mentioned or implied by the source include maintaining a lightweight, human‑readable record of non‑code constraints (for example, special operational notes or temporary rollout plans) and providing an on‑ramp to shared preferences so that Claude does not repeatedly re‑learn the same project context. For developer tooling and internal documentation, reference type memory entries create a curated shortcut to external systems that are otherwise discoverable only through search or institutional knowledge.
Operationalizing Auto‑memory in Practice
A practical rollout, according to the source recommendations, looks like this: keep memory files under the per‑project memory directory while you are actively iterating; when a preference or rule recurs across projects, move the entry into the global ~/.claude/memory/; automate saves through ~/.claude/CLAUDE.md rules to avoid manual bookkeeping, but ensure those rules include filters that prevent indiscriminate logging; and schedule regular audits using the provided audit prompt saved as a slash command to surface and correct stale or redundant memory items.
Internal link‑style phrases that are natural to include in documentation and internal tooling in this workflow are things like “project memory,” “audit memory,” “CLAUDE.md rules,” and “reference entries,” which can be converted into navigable internal documentation pages or command entries in a team’s knowledge base.
Auto‑memory, then, is less a passive archive than an active, curated layer of context that sits between immutable project documentation and ephemeral session noise.
Looking ahead, Auto‑memory’s usefulness will depend on teams establishing clear saving and review conventions and treating memory maintenance as part of the development lifecycle; with those practices in place, it can reduce repetitive setup work and preserve the working knowledge that would otherwise vanish between interactions.
