Context & Memory

Claude Code has no memory by default across sessions. These systems fix that.

CLAUDE.md — Your Project Brain

CLAUDE.md is the single most important file in your project. Claude reads it at the start of every conversation. It acts as persistent memory across sessions.

The Full Hierarchy (5 Levels)

Claude Code loads instructions from multiple levels, highest precedence first:

Auto-memory: Claude also stores learned context in ~/.claude/projects/<project>/memory/MEMORY.md.

Recommended Project Structure

your-project/
├── .claude/
│   ├── settings.json       # Auto-accept permissions
│   ├── commands/            # Custom slash commands
│   ├── skills/              # Modular workflow skills
│   └── rules/               # Modular rule files (*.md)
├── CLAUDE.md                # THE MOST IMPORTANT FILE
├── CLAUDE.local.md          # Personal overrides (gitignored)
├── docs/
│   ├── index.md             # Master index
│   ├── architecture.md      # System design
│   └── changelog.md         # Change history
├── .env                     # API keys (never commit)
└── src/                     # Your actual code

Setting Up CLAUDE.md

## Core Rules
1. Read first, answer second — Always read the codebase before making changes.
2. Plan before major changes — Verify the plan with the user first.
3. High-level explanations — Every step, explain what changed and why.
4. Simplicity first — Make every change as simple as possible.
5. Maintain architecture docs — Keep docs/architecture.md updated.

## Documentation Rules
- After every feature: update docs/changelog.md and docs/project_status.md
- After architecture changes: update docs/architecture.md
- After API changes: update docs/api.md

## Autonomy Level
- Skip plan mode — implement directly
- Do not ask for confirmation on file edits
- Only confirm before: destructive git operations, pushing, deleting files
- Run tests automatically after changes

Session Management

The Context Window — Critical Rules

Your context window is like working memory. When it fills up, quality drops.

• Use /compact when context hits 50% (~100K tokens for Opus 4.6’s 200K window)
• Use /clear between unrelated tasks — old irrelevant history wastes tokens
• Never dump all documentation into one file — Claude loads everything in CLAUDE.md at once

Token Economy

Every message sends the entire conversation history plus active tools. Costs compound quickly.

Knowledge & Documentation Setup

Recommended Docs Structure

docs/
├── index.md            # Master map: what each file contains
├── architecture.md     # How the system works end-to-end
├── changelog.md        # History of every significant change
├── project_status.md   # Current state, what works, what's in progress
├── api.md              # API endpoints documentation
└── features/
    ├── auth.md
    ├── payments.md
    └── dashboard.md

The Master Index Pattern

docs/index.md tells Claude where to look so it reads only what’s needed:

# Documentation Index

| File | What it contains | When to read it |
|------|------------------|-----------------|
| architecture.md | System design, data flow | Structural changes |
| changelog.md | History of all changes | Debugging |
| features/auth.md | Auth logic, OAuth | Touching authentication |
| features/payments.md | Stripe integration | Touching billing |

Link this index in CLAUDE.md: Master index: docs/index.md — always check here first.

Subagents

Subagents are specialized AI assistants that run in their own context windows:

Why subagents? Context isolation (work doesn’t bloat your main session), parallel execution, focused toolsets, and independent permissions.

Extended Thinking

Claude Code’s extended thinking is controlled via keyboard toggle, not prompt keywords:

• Toggle: Alt+T (Windows/Linux) or Option+T (macOS)
• Effort levels for Opus 4.6: low, medium, high

Security & Secrets

# Wrong (exposed in chat history):
Set up the database with password=s3cretP@ss!

# Right (secrets stay in .env):
Set up the database using the environment variables from .env