Memory Management in Claude Code

Starting a new thread on agent memory—beginning with Claude Code’s built-in memory management.

Native memory in CC: https://code.claude.com/docs/en/memory#auto-memory

After reading it, my gut feeling is that if I described building “this kind of system” in an interview, I would never pass.

CC’s native memory is file-system based.

There are two kinds of cross-session persistent memory:

  • Auto memory: Claude automatically saves useful context—project patterns, key commands, preferences. It persists across sessions.
  • CLAUDE.md files: Markdown you write and maintain, with instructions, rules, and preferences for Claude to follow.

Both are loaded into Claude’s context at the start of each session, but auto memory only loads the first 200 lines of its main file.

I don’t think truncation is a great approach…

Layered memory in CC

Organization-wide (all users in the org):

  • Managed policy: IT/DevOps-managed instructions org-wide—coding standards, security, compliance.

Team / project-wide (everyone on the project):

  • Project memory: Shared team instructions—architecture, coding standards, common workflows.
  • Project rules: Modular, topic-specific project rules—language guides, testing norms, API standards.

Personal:

  • Project memory: Personal preferences for a project—sandbox URLs, favorite test data.
  • Auto memory: Project patterns, debugging insights, architecture notes.

What auto memory covers:

  • Project patterns: build commands, testing conventions, style preferences.
  • Debugging insights: fixes for tricky issues, common failure modes.
  • Architecture notes: key files, module relationships, important abstractions.
  • Personal preferences: communication style, workflow habits, tool choices.

I won’t list storage locations—you can read the docs.

  • As mentioned, MEMORY.md only loads the first 200 lines, and Claude Code is instructed to stay concise and move detailed topics into separate topic files.
  • On-demand reads: Files like debugging.md or patterns.md are not loaded at startup. When Claude needs them, it reads them with its normal file tools.
  • Claude reads and writes memory files during a session, so you’ll see memory update as you work.

Claude Code reads memory recursively: from the current working directory it walks up toward / (but not including /), loading any CLAUDE.md or CLAUDE.local.md it finds. That helps in large repos—e.g. you run CC under foo/bar/ while foo/CLAUDE.md and foo/bar/CLAUDE.md both exist.

It also discovers CLAUDE.md files under the current directory subtree. Those are not loaded at startup; they enter context only when Claude reads files in those subtrees.

You can load memory from other directories, edit memory, and use modular rules—I’ll skip the rest.