Memory System

Claude Code has two memory mechanisms: CLAUDE.md (you write) and auto memory (Claude writes automatically).

CLAUDE.md Files

Markdown files with persistent instructions. Loaded at the start of every session.

Load Order (highest to lowest priority)

1. Managed policy CLAUDE.md (org-wide)
2. User: ~/.claude/CLAUDE.md
3. Project: ./CLAUDE.md or ./.claude/CLAUDE.md
4. Local (gitignored): ./CLAUDE.local.md

Example CLAUDE.md

# My Project

## Build & Test
- Build: `npm run build`
- Test: `npm test`
- Dev server: `npm run dev`
- Lint: `npm run lint` (run before committing)

## Code Style
- TypeScript for all new code
- 2-space indentation
- Named exports only (no default exports)
- Prefer `const` over `let`

## Architecture
- `/src/api` — API handlers (Express routes)
- `/src/components` — React components
- `/src/utils` — Shared utilities
- Database: PostgreSQL, migrations in `/migrations`

## Git Workflow
1. Create branch: `git checkout -b feature/name`
2. Write tests first
3. Implement
4. Commit: `git commit -m "feat: description"`
5. Push and open PR

## Common Pitfalls
- Port 3000 in use: `lsof -i :3000 | awk 'NR>1{print $2}' | xargs kill`
- Tests fail: run `npm install` first
- Build hangs: delete `node_modules` and `.next`, reinstall

Import Syntax

Pull in content from other files with @:

## Architecture
@src/ARCHITECTURE.md

## Build Instructions
@./docs/BUILD.md

## Personal Preferences
@~/.claude/my-preferences.md

Generate with /init

/init    # Claude reads the project and generates a starter CLAUDE.md

Path-Scoped Rules

Rules that only apply to specific file paths. Create .claude/rules/<name>.md:

---
paths:
  - "src/api/**/*.ts"
  - "src/routes/**"
---

# API Development Rules

- All endpoints must validate and sanitize input
- Use the standard error response format: `{ error, code, message }`
- Include OpenAPI JSDoc annotations on every handler
- Return 400 for validation errors, 500 for unexpected errors

When Claude edits a file matching those paths, these rules are automatically included.

Auto Memory

Claude automatically saves learnings to a memory directory and reads them back in future sessions.

Location

~/.claude/projects/<project-hash>/memory/
├── MEMORY.md          # index (loaded every session)
├── debugging.md       # debugging patterns
├── build-issues.md    # build troubleshooting
├── user.md            # user profile info
└── feedback.md        # workflow preferences

View and Edit

/memory               # in-session: view, edit, toggle on/off

Or edit files directly in the memory directory.

Configure

{
  "autoMemoryEnabled": true    // default: true
}

What Claude Saves

• Build commands and error fixes
• Debugging patterns discovered
• Code style and architecture observations
• Your workflow preferences

Memory File Format

---
name: build-issues
description: Known build problems and their fixes
metadata:
  type: project
---

Running `npm test` fails with "module not found" — fix: run `npm install` first.

**Why:** Dependencies go out of sync after git pulls.
**How to apply:** Always suggest `npm install` when tests fail with import errors.

🧠 Quick Recall

• Trick: “CLAUDE.md = you telling Claude; auto memory = Claude telling itself.”
• Both load at session start — not live.

👨‍🏫 Teach It

• Show: add a commit convention → /clear → same ask, better output.
• They’ll trip on: editing CLAUDE.md mid-session and expecting instant effect.

---

Learning path: ⬅ 16-sandboxing-and-security.md · Index · ➡ 18-memory-real-examples.md