Claude Code Settings and Memory Guide

Claude Code has two important configuration layers: memory, which gives Claude persistent context, and settings, which control behavior such as permissions, tools, hooks, plugins, and environment details. When used well, they turn repeated reminders into a stable coding workflow. When used poorly, they create stale context and hidden risk.

This guide explains how to use CLAUDE.md, auto memory, project settings, local settings, permission rules, and hooks without overcomplicating your first Claude Code setup.

Quick Answer

Use CLAUDE.md for concise project instructions that should load into every Claude Code session: package manager, test commands, architecture notes, coding standards, and files to avoid. Use auto memory for learned patterns and preferences Claude discovers over time. Use settings for behavior and permissions, not long prose.

Keep three ideas separate:

1. CLAUDE.md guides Claude with context.
2. Settings configure Claude Code behavior.
3. Hooks enforce rules at lifecycle points.

Memory is not a security boundary. If an action must be blocked, use permission rules or a hook.

CLAUDE.md vs Auto Memory

Anthropic's memory docs describe two complementary systems:

1. CLAUDE.md files: instructions you write.
2. Auto memory: notes Claude writes based on corrections, patterns, and preferences.

Both load at the start of conversations, but they are not the same.

Use CLAUDE.md for stable rules:

1. Package manager.
2. Build command.
3. Test command.
4. Project layout.
5. Style conventions.
6. Review expectations.
7. Generated directories to avoid.

Use auto memory for recurring learnings:

1. Debugging insights Claude discovered.
2. Project-specific patterns that were corrected during work.
3. Preferences that emerged from repeated feedback.
4. Commands Claude learned while working in the repository.

Do not store secrets, tokens, private credentials, one-off debugging output, or long documentation dumps in either system.

A Good Starter CLAUDE.md

Start small:

# CLAUDE.md

Use pnpm for this repository.

Common commands:
- pnpm lint
- pnpm test
- pnpm build

Before finishing a code change, run the closest relevant check.
If you cannot run a check, explain why.

Do not edit generated files:
- .next/
- dist/
- coverage/
- node_modules/

Keep patches small and summarize risk before handing off.

This is better than a long policy document because it is specific and easy for Claude to apply. The official memory docs note that concise, well-structured instructions are followed more consistently.

When To Add Memory

Add to CLAUDE.md when:

1. Claude makes the same mistake twice.
2. A review catches something Claude should know next time.
3. You keep typing the same correction.
4. A new teammate would need the same project context.

Do not add a rule because it was useful once. Temporary instructions belong in the prompt. Durable repository behavior belongs in CLAUDE.md.

If a rule only applies to one file type or directory, use a more specific instruction surface rather than bloating the root file.

Settings Scopes

Claude Code settings use multiple scopes. The practical model is:

1. Managed settings: organization or machine policy, highest priority.
2. Command-line arguments: temporary overrides for one session.
3. Local project settings: your personal settings for one repo.
4. Project settings: shared repository settings committed to git.
5. User settings: your defaults across projects.

Use project settings for team behavior that should be shared. Use local settings for personal workflow preferences that should not be committed. Use user settings for tools and preferences you want everywhere. Managed settings are for policy that should not be overridden.

Permissions

Claude Code permissions should match the risk of the task. The official permissions docs describe a precedence model where deny rules win over allow rules. That is the right mental model: if a tool or command is dangerous, block it at the strongest appropriate scope.

Examples of useful restrictions:

1. Ask before running broad shell commands.
2. Deny edits to generated directories.
3. Deny commands that modify production infrastructure.
4. Allow common read-only inspection commands.
5. Allow narrow test commands that the project uses daily.

Do not rely on a sentence in CLAUDE.md to block destructive actions. Use permissions or hooks when the boundary matters.

Hooks

Hooks run at specific points in Claude Code's lifecycle. Use them when you need automation around tool use or session events.

Good hook use cases:

1. Format files after edits.
2. Block edits to protected files.
3. Notify you when Claude needs input.
4. Re-inject context after compaction.
5. Audit configuration changes.
6. Run a lightweight check before handoff.

Hooks are more mechanical than memory. If you need enforcement, use a hook. If you need context, use memory.

Project vs Local Settings

Use project settings for shared team defaults:

1. Recommended tools.
2. Shared permission policy.
3. Team hooks.
4. Plugins or MCP servers the repository expects.

Use local settings for private preferences:

1. Your notification behavior.
2. Your personal shortcuts.
3. Local-only paths.
4. Machine-specific tools.
5. Temporary experiments.

Do not commit personal credentials or local machine paths into shared project settings.

How This Compares To Codex AGENTS.md

Codex uses AGENTS.md as its durable repository guidance file. Claude Code uses CLAUDE.md and auto memory for persistent context, with settings and hooks for behavior control.

The workflow idea is similar: do not keep repeating package manager, test command, and generated-file rules in every prompt. Put stable rules near the codebase so the agent starts with the right operating manual.

For the Codex version, see the Codex AGENTS.md Guide.

A Safe Team Setup

For a small team, start with:

1. A short repository CLAUDE.md.
2. Shared project settings only for non-sensitive team defaults.
3. Local settings for personal preferences.
4. Permission rules that deny risky tools or paths.
5. One or two hooks that enforce obvious mechanical rules.
6. A review habit that checks diffs and verification output.

Do not start with a giant configuration system. Let real workflow pain tell you what needs to become durable.

Debugging Bad Behavior

If Claude ignores an instruction, check:

1. Is the instruction loaded in the current session?
2. Is it too vague?
3. Is it buried in a long file?
4. Does another setting override it?
5. Should it be a permission rule or hook instead of memory?
6. Is the prompt asking for behavior that conflicts with the memory?

Memory is context. It improves behavior, but it is not absolute enforcement.

Common Mistakes

The first mistake is writing a long CLAUDE.md before using Claude Code on real tasks. Start with the few rules that actually change output.

The second mistake is storing secrets in memory or settings. Keep credentials out of agent-readable files.

The third mistake is using memory as a policy engine. Use permissions and hooks when the rule must be enforced.

The fourth mistake is committing local settings. Personal preferences and machine-specific paths should stay local.

The fifth mistake is never pruning memory. Old project facts become misleading when packages, test commands, or architecture change.

Best Setup Checklist

Before relying on Claude Code heavily, confirm:

1. CLAUDE.md is short and specific.
2. Test and build commands are current.
3. Generated directories are listed clearly.
4. Local settings are not committed.
5. Project settings contain only team-safe defaults.
6. Risky tools or commands are denied at the right scope.
7. Hooks enforce only rules that need enforcement.
8. Secrets are not stored in memory, settings, or prompts.
9. The first few tasks produce small, reviewable diffs.
10. The final answer always includes verification.

Bottom Line

Claude Code settings and memory are most useful when they reduce repeated instructions without hiding risk. Use CLAUDE.md for concise project context, auto memory for learned patterns, settings for behavior, permissions for boundaries, and hooks for enforcement.

If you are still learning the tool, keep the setup small. A clear prompt, a short CLAUDE.md, and a real verification command will improve results more than a large configuration file.

Related AI Coding Agent Tutorials

• Claude Code Quick Start
• Claude Code CLI Tutorial
• Claude Code VS Code Tutorial
• Claude Code GitHub Actions Guide
• Claude Code MCP Guide
• Claude Code Hooks Guide
• Claude Code Subagents Guide
• Claude Code Skills and Slash Commands Guide
• Claude Code Plugins Guide
• Claude Code Agent Teams Guide
• Codex vs Claude Code
• Codex AGENTS.md Guide
• Codex Permissions and Sandbox Guide
• Codex CLI Tutorial
• Codex Quick Start

Official References

• Claude Code memory
• Claude Code settings
• Claude Code permissions
• Claude Code hooks
• Claude Code overview