Claude Code Memory System

Deep dive into the file pathways, caching models, and local directories that compose the memory engine for Claude Code.

1. The Local Config Directory (~/.claude)

At startup, Claude Code initializes a persistent global configuration drawer in the developer's user home directory: ~/.claude/. This drawer holds all workspace tokens, credentials, settings, and globally whitelisted skills.

Inside this folder, you will find:

~/.claude/settings.json: Environment preferences like editor commands, auto-approve configurations, and telemetry toggles.
~/.claude/CLAUDE.md: The global rules configuration. Rules defined here apply to every directory where you start a Claude Code session.
~/.claude/skills/: A subdirectory containing custom bash scripts that Claude Code has learned to perform tasks.

2. Project-Scoped Cache (.claude)

When initialized inside a workspace, Claude Code creates a hidden folder inside the project root: .claude/.

This directory serves as the project's **scratchpad memory**. It caches index structures, tracks previous commands, and caches the dependency graph of your workspace so it doesn't need to rebuild them on every turn.

Tip: Keep .claude/ out of Version Control

Since .claude/ stores local user cache details and session histories specific to your machine, you should add it to your project's .gitignore:

.claude/
.claude_session

3. Custom Skills System

Skills are executable scripts stored inside either the global or project-scoped config folders.

When you tell Claude Code "Learn how to do X", it writes a small script carrying the exact execution sequence. The next time you ask it to run that task, it doesn't try to draft a new script from scratch — it simply runs the whitelisted script stored inside its skills drawer.

4. Global config.json Structure

For advanced developers who hook up MCP servers or custom environments, the ~/.claude/config.json file contains the primary layout:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    },
    "memory-server": {
      "command": "node",
      "args": ["/path/to/mcp-memory/dist/index.js"]
    }
  }
}