How Claude Code Retains Project Context: CLAUDE.md and Auto Memory Explained

ArticleAnthropicResource

Anthropic outlines the memory architecture of Claude Code. Because every session starts with a clean context window, the CLI tool relies on two complementary systems: user-defined CLAUDE.md files for explicit instructions and an auto memory feature that records learnings from user feedback.

Key points

  1. Dual memory model: CLAUDE.md holds deliberate developer instructions, while auto memory stores learnings and patterns Claude derives automatically (up to 200 lines or 25 KB).
  2. Hierarchical scoping: Rules can be placed at the system/org level, personal user level (~/.claude/CLAUDE.md), repo root, or gitignored locally (CLAUDE.local.md).
  3. Context rather than enforcement: Instructions guide model behaviour as context; deterministic blocking of actions requires PreToolUse hooks.
  4. Instruction best practices: Anthropic advises keeping files under 200 lines, using clear markdown formatting, and providing concrete, verifiable rules.
  5. Imports and tool migration: Files support @-syntax imports up to four hops deep, while /init and /import commands allow importing rules from AGENTS.md, Cursor, Copilot, and other agent configs.

Why it matters

Persistent project context is essential for AI coding agents to follow repository standards without requiring repetitive manual prompting. Understanding how Claude Code handles scope, memory imports, and token limits helps engineering teams establish reliable coding practices across distributed projects.

Analysis

Anthropic makes a clean architectural distinction between explicit guidelines and dynamic session notes. Since CLAUDE.md content directly consumes context window tokens, the documentation encourages concise scoping and path-based rules. The inclusion of approval prompts for external imports also demonstrates a conscious approach to security, preventing shared repositories from arbitrarily pulling files from the user's wider system into the prompt context.

Mentioned links

Found in

Summary generated by AI (Gemini 3.8 Flash, 27 September 2026). It may contain errors – the original source is authoritative.

Related entries

Similar in content, found by the AI search.

  • Article:Rui Sousa, Luis Sousa

    Tutorial: Building a CLAUDE.md File for Claude Code

    Rui and Luis Sousa share an approach to loading permanent business context into Claude Code via a root CLAUDE.md file, eliminating the need to repeatedly explain business details in every new session.

    AI & LLMs· Tutorial

  • Article:Anthropic

    Extending Claude Code with Skills: Architecture and Best Practices

    Anthropic details the skills system for Claude Code. Developers can encapsulate recurring procedures and workflows inside SKILL.md files built on the open Agent Skills standard, supporting dynamic context injection and subagent delegation.

    AI & LLMs· Tool

  • Repository:thedotmack/claude-mem

    claude-mem: Persistent Cross-Session Memory for AI Agents

    The open-source project claude-mem (now also branded as Grok Mem) captures agent activity during active sessions, compresses it with AI, and injects relevant context back into future runs.

    93.1kstarsJavaScript

    AI & LLMs· Tool

  • Link:Anthropic

    Anthropic Claude Code: Agentic Coding in the Terminal and IDEs

    Anthropic introduces Claude Code, an AI coding agent designed for the terminal, IDEs, web, and Slack. The tool maps codebases using agentic search, applies multi-file edits, runs tests, and creates pull requests directly within the developer's environment.

    AI & LLMs· Tool

  • Repository:anthropics/claude-code

    Claude Code: Terminal-Based Agentic Coding Tool

    Claude Code by Anthropic is an agentic coding tool that operates in the terminal. It understands codebases, executes routine development tasks, explains complex code, and handles Git workflows using natural language commands.

    144.1kstarsPython

    AI & LLMs· Tool

Back to the knowledge base

Let's talk about your project

Get in touch

Locations

  • Mattersburg
    Johann Nepomuk Bergerstraße 7/2/14
    7210 Mattersburg, Austria
  • Vienna
    Ungargasse 64-66/3/404
    1030 Wien, Austria

Parts of this content were created with the assistance of AI.