Context and Memory
How Claude Code builds working context and persistent memory
Understand the difference between session context, CLAUDE.md instructions, MEMORY.md indexing, and relevance-based memory recall.
Session context and persistent memory are different systems
Claude Code separates working context from persistent memory. Session context is what the current turn sees immediately. Memory is what can survive into future conversations.
That distinction matters because not every useful fact belongs in a persistent store.
- Git status and current date are session context.
- Discovered CLAUDE.md instructions are session context.
- Typed memory files are long-lived persistence.
CLAUDE.md is loaded as user-level operating guidance
Claude Code walks for CLAUDE.md-style instruction files unless the relevant environment or mode settings disable that behavior.
Those instructions are treated as collaboration guidance for the current project, not as a generic profile for all future conversations.
- Bare mode changes discovery behavior.
- Explicit add-dir behavior is treated differently from automatic discovery.
- Loaded CLAUDE.md content is cached for the session.
MEMORY.md is an index, not the memory itself
The memory system expects a file-based directory with a special entrypoint file called MEMORY.md.
MEMORY.md is intentionally kept concise and acts as an index into richer topic files rather than a dumping ground for long notes.
- Memory files have typed frontmatter.
- The index has size limits and truncation warnings.
- The system encourages semantic organization rather than chronological dumping.
Relevant memories are selected, not blindly loaded
Claude Code scans memory headers and then uses a side-query to select only the memories likely to help with the current user request.
This keeps memory recall selective instead of flooding the conversation with every saved fact.
- Selection is capped to a small number of high-confidence files.
- Already-surfaced memories are filtered to avoid waste.
- Tool reference memories can be deprioritized if the tool is already active in the session.
Learn next
These guides are adjacent to the current topic and make the learning path easier to follow.
Agents and Plan Mode
How Claude Code separates planning, coordination, and delegated execution
Understand the difference between the main thread, plan mode, coordinator behavior, and constrained sub-agents.
CLAUDE.md vs MEMORY.md
Two persistence layers with different jobs
A clear comparison between repository-scoped collaboration instructions and persistent memory files intended to survive across future conversations.
How Claude Code Works
The high-level architecture behind a Claude Code turn
A code-backed explanation of how Claude Code assembles context, runs the agent loop, invokes tools, and keeps long sessions moving.
Related resources
These directory entries connect the concept guide to concrete tools, docs, and integrations.
Next.js CLAUDE.md Template
Comprehensive CLAUDE.md for Next.js App Router projects
Production-ready CLAUDE.md template for Next.js projects using the App Router. Covers project structure, routing conventions, data fetching patterns, server components vs client components, and deployment to Vercel.
TypeScript Monorepo CLAUDE.md Template
CLAUDE.md for Turborepo/Nx monorepo projects
CLAUDE.md template designed for TypeScript monorepo projects using Turborepo or Nx. Covers workspace structure, shared packages, build pipelines, dependency management, and cross-package development patterns.
Claude Code Best Practices
Community-driven best practices for Claude Code
Collection of best practices learned from real-world Claude Code usage. Covers CLAUDE.md optimization, effective prompting, workflow organization, and common pitfalls to avoid. Continuously updated by the community.
Memory MCP Server
Persistent memory and knowledge graph for Claude conversations
Official MCP server providing persistent memory capabilities. Store and retrieve information across conversations using a knowledge graph structure. Enables Claude to remember context, facts, and relationships between sessions.