headroom.walls.sh · memory

Claude Code memory

CLAUDE.md files and the /memory command give Claude Code persistent context that survives across sessions — project conventions, architecture rules, commands to run.

What memory is for

Claude Code has no built-in recollection between sessions. Every time you open a new session, it starts fresh. Memory files solve this: you write persistent instructions once, and Claude Code reads them at the start of every session in that directory.

This is how you stop re-explaining your stack, your test command, or your commit message format every single time.

CLAUDE.md — the project instructions file

The primary memory mechanism. Create a file called CLAUDE.md in your project root (or any directory Claude Code runs in). Claude Code reads it automatically at session start, before any other context.

# Project: payments-service

## Stack
Node.js 20, Postgres 16, Stripe SDK v14. No ORM — raw SQL via pg.

## Commands
- Test: `npm test` (runs jest, needs Docker for Postgres)
- Lint: `npm run lint` (eslint + prettier)
- Deploy: `railway up` from the repo root

## Conventions
- All money values in cents (integer), never floats
- Use `snake_case` for database columns, `camelCase` for JS
- Commit messages: conventional commits (`feat:`, `fix:`, `chore:`)
- Never commit directly to main — always a branch + PR

## Architecture
- `src/routes/` — Express route handlers (thin, no business logic)
- `src/services/` — business logic
- `src/db/` — SQL query files
- `src/jobs/` — cron workers

Keep it short and factual. Claude Code loads the whole file into context every session — a 200-line CLAUDE.md is fine; a 2000-line one eats context unnecessarily.

Memory scope — where the file lives

Claude Code looks for CLAUDE.md files in a hierarchy, merging all of them:

Project-level CLAUDE.md overrides user-level for conflicting instructions. Subdirectory CLAUDE.md files are loaded when Claude Code operates in that directory.

The /memory slash command

Running /memory in a Claude Code session opens your CLAUDE.md in your editor so you can update it mid-session. Changes take effect immediately — Claude Code re-reads the file before the next message.

/memory

You can also ask Claude Code to add something to memory directly:

Remember: always use async/await, never raw .then() chains in this project

Claude Code will append it to your project's CLAUDE.md (or create the file if it doesn't exist).

What belongs in CLAUDE.md

Good candidates

Commands Claude Code needs to know (npm test, make build, deploy steps). Architecture overview so it doesn't have to re-read the whole codebase every session. Non-obvious conventions — things that aren't clear from reading the code (money in cents, snake_case vs camelCase boundaries). Things Claude Code keeps getting wrong — a short correction at the top of CLAUDE.md is often more reliable than repeating it.

Skip these

Things already obvious from the code (language, framework — Claude Code can see the imports). Long documentation that belongs in README.md. Secrets or API keys — CLAUDE.md may be committed to version control.

Practical CLAUDE.md templates

Minimal (any project)

# CLAUDE.md

## Commands
- Build: `[your build command]`
- Test: `[your test command]`
- Lint: `[your lint command]`

## Key conventions
- [one or two things Claude Code keeps getting wrong]

User-level (~/.claude/CLAUDE.md)

# Personal Claude Code settings

## Response style
- Be concise — no recap of what you just did
- No apologies, no "certainly!", just do the thing
- Prefer editing existing files over creating new ones

## Shell
- I use zsh on macOS, homebrew for packages
- My preferred editor is nvim

Memory and the ~/.claude directory

CLAUDE.md at the user level lives at ~/.claude/CLAUDE.md, in the same directory as Claude Code's other config files. While you're there, ~/.claude/settings.json is where hooks live — including the hook that powers Headroom.

brew install patwalls/tap/headroom

CLAUDE.md and version control

Whether to commit CLAUDE.md to your repo is a team decision. Committed = team-shared conventions, automatically picked up by every contributor. Gitignored = personal workflow notes that don't make sense to share. Many teams commit a project-level CLAUDE.md (team conventions) and gitignore a personal one (CLAUDE.local.md or their own additions to ~/.claude/CLAUDE.md).

→ settings.json reference
→ statusLineHook setup
→ slash commands
→ Claude Code tips