Deep Dive into Claude Code’s Three Configuration Systems: settings.json / CLAUDE.md / memory

Introduction

Claude Code provides three separate configuration mechanisms, each with distinct scopes, loading logic and maintenance patterns. Many developers treat them interchangeably, which often leads to subtle and costly mistakes. Writing rules into settings.json will produce no effect. Putting runtime parameters into CLAUDE.md bloats the conversation context. Storing static facts inside memory may trigger incorrect inference. This article clarifies the core positioning of each component, explains loading sequence, practical syntax, common pitfalls, and how to combine them properly for production-grade agent workflows.

The three systems operate at different layers and do not replace one another.

• settings.json: Runtime environment configuration, read by the program.
• CLAUDE.md: Human-authored project specification, read by the AI.
• memory: Cross-session knowledge storage, written and indexed automatically by the AI.

The most frequently misunderstood trait is the load-once semantic of settings.json. Any modification applied after startup will not take effect until a full restart. Editing and reloading the chat window alone cannot activate changes inside this file.

1. settings.json – Program Runtime Configuration

1.1 Core Scope

settings.json defines environment variables, permissions, tool hooks and UI display parameters for Claude Code. It is consumed by the application runtime rather than interpreted by the LLM. The model itself cannot directly read the file content; the parsed configuration injects into the program environment before the agent session starts.

1.2 File Override Hierarchy

Configuration cascades across global, project and local instance levels. Later entries override earlier ones.

1. Global ~/.claude/settings.json: Shared across all workspaces. Stores token endpoints, proxy settings, language preference and model selection.
2. Project-level .claude/settings.json: Committed into Git. Defines team-shared hooks, tool permissions and repository-wide command allowlist.
3. Project .claude/settings.local.json: Personal local override. Excluded from version control, for private environment variables and custom shell commands.

1.3 Main Configuration Sections

env: Environment Injection

This block injects environment variables into the shell context used by Claude Code. Values here override UI input selections, which explains why modifying UI proxy settings may fail after restart. Developers can verify injected variables via env | grep -i anthropic.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://xxx.xxx/anthropic",
    "ANTHROPIC_API_KEY": "xxxx",
    "API_TIMEOUT_MS": "60000",
    "API_PROXY": "http://127.0.0.1:7890"
  }
}

permissions: Command Allow / Deny Rules

Permission rules control shell execution behavior. The allow array contains approved commands that run without repeated confirmation, improving workflow speed. The deny block has higher priority and blocks risky operations unconditionally.

{
  "permissions": {
    "allow": [
      "bash -c ls",
      "git diff",
      "cat *"
    ],
    "deny": [
      "rm -rf",
      "curl | bash"
    ]
  }
}

hooks: Tool Lifecycle Triggers

Hooks execute custom scripts before or after tool invocations. Typical use cases include automatic code formatting, lint checks and status reporting after file writes.

statusLine: Custom Status Rendering

This section customizes the bottom status bar. It can display active model name, Git branch, context token consumption percentage and other runtime metrics.

1.4 Key Features & Common Bugs

• One-time loading: The file parses only at startup. Live edits do not apply in an ongoing session. A full restart of Claude Code is required.
• Silent failure on malformed JSON: Syntax errors will make the entire config ignored without explicit warning. Always validate JSON before saving.
• Version control practice: Global and project settings files are tracked by Git, while settings.local.json stays local and uncommitted.

2. CLAUDE.md – Project Specification for AI

2.1 Scope

CLAUDE.md is human-written instruction text loaded fully into the LLM context at the beginning of every conversation. It defines coding conventions, architectural constraints, test requirements and repository rules that the agent must obey. The AI reads and follows these rules, while the program runtime does not parse this file.

A recommended maintenance pattern is splitting large monolithic CLAUDE.md into rule files under ./claude/rules/. Group specifications by topic: logging standards, tech stack constraints, database rules and API contract rules. Modular files simplify incremental updates instead of maintaining a thousands-line single document.

2.2 What to Write

Add enforceable rules that the AI cannot infer merely by reading source code. The test standard: if the AI may produce working code violating team agreements, write the constraint here.
Examples of enforceable constraints:

• Layered architecture restrictions: facade, service, dao, mapper layering and cross-layer prohibition.
• Mandatory code style, import ordering and logging field schema.
• Test requirements: every change must supply unit tests.
• Change workflow: OpenAPI spec changes must update corresponding implementation and test files.

2.3 What Not to Write

Avoid redundant information already visible in codebase. Do not record temporary local environment details such as personal proxy addresses, local ports or one-off setup notes. Those environment settings belong inside settings.json, not CLAUDE.md.

2.4 Critical Performance Constraint

CLAUDE.md loads in full for every new chat session. Longer documents consume more context window capacity and reduce available space for task content. Rule documents should remain high-density. Focus on hard constraints rather than descriptive background explanation or optional suggestions. Concise rules carry stronger weight than verbose prose.

3. memory – Cross-Conversational Memory

3.1 Scope

Memory stores observations recorded by the AI automatically. It solves repeated context reintroduction across separate chat sessions.
The difference compared with CLAUDE.md:

• CLAUDE.md: Static human-authored rules that never change during conversation.
• memory: AI-written factual observations, learned from task execution history.

3.2 Index and Body Two-Tier Architecture

Memory adopts an index + body design. The index (usually around 4KB) loads fully each session. The full body (often up to 100KB) loads selectively only when relevant hooks trigger. This design reduces token overhead versus loading all records unconditionally like CLAUDE.md.

Each memory entry includes metadata, conclusion, reasoning trace and relevance hooks. Hooks act as conditional triggers to decide whether to pull the full memory body into context. Vague hook descriptions cause false negatives, preventing relevant memories from loading.

3.4 Four Memory Entry Types

1. userhook: User preference, workflow habit and confirmed operating steps. Must include reasoning explaining why this rule applies.
2. project: Project-specific constraints, code patterns and fixed repository conventions.
3. feedback: Past failure summaries and fixes learned from prior task attempts.
4. reference: External documents, URLs, ticket IDs and specification links.

3.5 Important Traits

Memory records a snapshot at write time. It is not real-time state tracking. Facts stored in memory may become outdated after code refactoring or configuration changes. The agent treats memory entries as historical observations instead of live file inspection results.

3.6 What Should Not Be Saved

Do not duplicate information already present in source code, Git history or CLAUDE.md. Memory should capture lessons that would otherwise require repeated human explanation. A simple filtering test: will this fact save repeated questions three months later? If not, skip recording it.

4. Comparative Summary & Decision Tree

4.1 Core Comparison Table

Item	settings.json	CLAUDE.md	memory
Reader	Program runtime	AI LLM	AI LLM
Author	Human	Human	AI (human can request deletion)
Load timing	Load once on startup; restart required to apply edits	Full load every new conversation	Index always loaded; body lazy loaded by hook match
Version control	Project file committed; local override ignored	Tracked in Git	Not tracked
Content type	Environment variables, permissions, hooks	Project coding rules and architecture specs	Historical observations and lessons

4.2 Decision Logic for Placement

• Environment variables, shell allowlist and runtime parameters → settings.json.
• Permanent team coding standards and architecture rules → CLAUDE.md.
• Lessons learned, project observations and repeated pitfalls → memory.

4.3 Boundary Examples

1. Proxy configuration: belongs in settings.json env section. Placing proxy info in CLAUDE.md wastes context tokens.
2. Database connection rule: permanent architecture constraint, write to CLAUDE.md.
3. Past failure: "This repository cannot use raw MySQL client without connection pooling" → store as memory entry.

5. Practical Implementation Guidance

5.1 Best Practices for settings.json

Separate global shared configuration and project-specific rules. Use settings.local.json exclusively for private local overrides.
Validation workflow after edits:

1. Create backup before modification.
2. Validate JSON syntax.
3. Restart Claude Code fully.
4. Print environment variables to verify injection.

Permission design principle: deny rules take priority. Start from minimal allowlist and expand command scope gradually. Audit permission logs after execution.

5.2 CLAUDE.md Maintenance

Split rule sets into multiple topic files rather than a single giant markdown document. Each rule must define consequences of violation. Remove obsolete rules periodically, as outdated rules increase context cost and confuse the agent. Keep mandatory constraints inside this document.

5.3 Memory Maintenance

Memory should be actively curated rather than left to fully automatic recording. Developers can explicitly request memory write or deletion. Write precise hook conditions for selective loading. Periodically inspect indexes, merge duplicate records and archive expired observations.

5.4 Combined Workflow

The standard production workflow: define permanent rules in CLAUDE.md, configure runtime environment via settings.json, and let memory accumulate task lessons. Periodically review and clean memory records. In agent development workflows, developers may route LLM traffic through 4sapi, an API gateway to manage multi-model endpoints and request routing.

6. Troubleshooting Common Failures

• Environment proxy not working: Check env section inside settings.json, verify injection with env command, restart agent.
• AI ignores architecture rules: Confirm rules exist in CLAUDE.md, check document length and clarity of constraints.
• Repeated mistakes on solved problems: Validate memory hooks, ensure relevant memory entries load when matching tasks start.
• Changes to config have no effect: The most common root cause is editing settings.json without restarting the entire Claude Code process.

Conclusion

The three configuration systems of Claude Code divide responsibilities clearly. settings.json controls the execution environment of the agent program. CLAUDE.md delivers static project rules to the LLM on every session launch. Memory stores historical observations with lazy loading, reducing repeated context setup. Misplacing configuration content creates performance loss, security risk and unexpected agent behavior. Mastering their loading semantics and boundaries is essential for reliable code agent deployment. When building multi-model agent systems, developers can simplify endpoint management through unified gateway services.

International access: https://4sapi.com
Domestic access: https://4sapi.cn