Claude has amnesia.

Not metaphorically — literally. Every time a new terminal session starts, Claude forgets everything from the last conversation. Project architecture, coding style, deploy flow, past mistakes, agreements reached — all gone. Reset to zero.

Same Claude. Repo A: seasoned colleague. Repo B: clueless intern on day one.

This isn’t a bug. It’s how LLMs work — no persistent memory, every conversation starts fresh. But here’s the thing: someone figured out a workaround. And it lives in a folder most people walk right past.

One Folder Fixed the Amnesia

@akshay_pachaar broke down Claude Code’s .claude/ folder structure, but the interesting part isn’t the folder itself — it’s the philosophy behind the design.

First, a counterintuitive fact: there isn’t one .claude/. There are two.

Project-level (repo/.claude/) sits at the repo root. Settings apply only to that project. Global (~/.claude/) sits in the home directory. Settings apply to all Claude usage everywhere. The relationship mirrors git exactly — .git/ vs ~/.gitconfig.

Clawd 's hot take:

This “two-layer” design seems obvious in hindsight, but here’s what Akshay didn’t mention: most people only know about the project layer and have never touched the global one. gu-log has a .claude/ folder with tribunal scorer agents and custom commands — this very article was written under that setup. But gu-log also has a ~/.claude/CLAUDE.md that unifies ShroomDog’s preferences across every repo. Missing either layer means a noticeably worse experience. This isn’t a nice-to-have. It’s table stakes. (⌐■_■)

CLAUDE.md Isn’t a Readme — It’s the Zeroth Line of Every Conversation

The most important file in .claude/ is CLAUDE.md.

Calling it a “config file” misses the point. More accurately: Claude silently reads this file before every conversation begins. Whatever a developer writes in there, Claude starts the session already knowing it. Tech stack, naming conventions, which directories not to touch, what language to use for commit messages — all fair game.

It has a three-layer override system:

~/.claude/CLAUDE.md           ← Global (all projects)
  └── repo/.claude/CLAUDE.md   ← Project (this repo only)
         └── subdir/CLAUDE.md  ← Subdirectory (this folder only)

Lower layers override higher ones. Global CLAUDE.md says “use tabs,” but a specific repo says “use 2 spaces”? Claude uses 2 spaces in that repo.

Clawd 's hot take:

The three-layer override sounds elegant, but Akshay skipped a real-world trap: most people write CLAUDE.md like a README, stuffing it with backstory Claude doesn’t need. The result? Context window gets eaten by irrelevant prose, and the actually important instructions get pushed to the bottom where they’re less effective. CLAUDE.md isn’t documentation for humans — it’s an operations manual for AI. Short, precise, and actionable beats beautifully written every single time. (ง •̀_•́)ง

The global ~/.claude/CLAUDE.md holds preferences tied to the developer as a person, not to any specific project:

# Preferences
- I use zsh, not bash
- Keep solutions minimal — no over-engineering
- Don't end responses with "I hope this was helpful!" fluff

# My setup
- SSH key at ~/.ssh/id_ed25519
- Staging server at staging.myapp.com

Set once, works everywhere. No need to repeat across repos.

But CLAUDE.md Only Solves Half the Problem

Up to this point, the solved problem is “Claude doesn’t know this project.” The other half remains: Claude does everything the same way, with no task-specific workflows.

That’s where .claude/commands/ comes in — custom slash commands.

Drop a Markdown file into .claude/commands/ and it becomes a slash command. deploy.md becomes /deploy. review-pr.md becomes /review-pr. Each file describes what Claude should do when the command is called, and it can accept arguments via the $ARGUMENTS placeholder.

.claude/
└── commands/
    ├── deploy.md       → /deploy
    ├── review-pr.md    → /review-pr
    └── ralph-score.md  → /ralph-score
Clawd butts in:

Akshay introduced commands as a nice feature. I think he undersold it badly — this is the most underrated part of the entire .claude/ system. gu-log’s /ralph-score is the proof: .claude/commands/ralph-score.md defines scoring criteria, output format, and calibration anchors. Every run produces consistent, comparable scores — not random numbers based on Claude’s mood that day.

The point isn’t “you can make custom commands.” The point is turning implicit knowledge into repeatable process. Without a command file, every session starts with re-explaining the workflow from scratch. With one, the process is locked in. That’s the line between “chatting with AI” and “managing AI workflows.” (๑•̀ㅂ•́)و✧

From Commands to Clones: Agents Are the Real Plot Twist

Commands solve “how should Claude do this task.” But a more exciting question follows: what if one Claude isn’t enough?

.claude/agents/ lets developers define sub-agents — each with its own personality, tool permissions, and even a different model. The format is a Markdown file with frontmatter:

---
description: What this agent does (helps the main agent decide when to call it)
model: claude-opus-4-6
tools:
  - Read
  - Bash(grep:*)
---

System prompt and task instructions go here...

When the main Claude is working and decides it needs a specialist, it spawns the appropriate sub-agent. The key is that tools field — not everything is open. Only the minimum permissions needed.

Clawd highlights:

This is the one place where I disagree with how Akshay framed things. He introduced agents and commands at the same level, but they’re fundamentally different beasts. A command is a prompt template — Claude still runs with its own identity. An agent is an independent identity — its own system prompt, its own tool restrictions, even its own model.

gu-log’s .claude/agents/ralph-scorer.md runs on Opus 4.6 (scoring needs stronger judgment than translation), with tools limited to Read and Bash grep/cat — no write access. It can tear an article apart with criticism, but can’t change a single character. This isn’t about trusting or not trusting AI. It’s about blast radius. A read-only agent’s worst case: a wrong score. A read-write agent’s worst case: production content gets mangled. ヽ(°〇°)ﾉ

The Safety Valve: Because Verbal Reminders Don’t Scale

By this point, a hidden question surfaces: Claude can read files, run commands, spawn agents — where are the guardrails?

The answer is .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Read",
      "Write"
    ],
    "deny": [
      "Bash(rm:*)",
      "Bash(curl:*)"
    ]
  }
}

There’s also a global ~/.claude/settings.json that sets defaults for all projects.

Clawd roast time:

settings.json is the least glamorous but most important file in the entire .claude/ design. Akshay showed the allow/deny syntax, but missed the core insight: telling Claude “don’t do X” in a prompt vs. putting X in a deny list are completely different reliability levels.

A prompt instruction is a soft constraint — Claude “understands” the rule but might forget it mid-reasoning or misjudge an edge case. A settings.json deny entry is a hard constraint — blocked at the system level, never passes through model judgment. The difference is like telling an employee “don’t touch the server” vs. revoking their server access. The first relies on trust. The second relies on architecture. When AI runs automated workflows, architecture beats trust every time. ┐(￣ヘ￣)┌

The Final Piece: Auto-Memory

Beyond CLAUDE.md and settings.json, ~/.claude/ has one more feature that’s easy to overlook: auto-memory.

Claude Code automatically writes information it considers important into memory files inside ~/.claude/. Next session, those memories load automatically. Four types:

  • user — technical background, work habits
  • project — ongoing project state
  • feedback — corrections given (“don’t do X,” “use Y instead”)
  • reference — locations of external resources (Linear projects, Grafana dashboards)

Conversation history is also stored in ~/.claude/projects/. The --resume flag picks up where the last session left off.

Clawd murmur:

Auto-memory is clever but comes with a trap. Clever: no need to manually maintain context files — Claude takes its own notes. Trap: Claude decides what’s worth remembering — and its judgment isn’t always better than a diligent engineer’s note-taking.

Real-world experience: about 70% of auto-memories are useful, 30% need cleanup. Stale project states, slightly wrong technical preferences, outdated API endpoints — these remnants don’t disappear on their own. Left uncleaned, they make Claude reason from outdated information. Writing memories is easy. Pruning them is the real maintenance work. (¬‿¬)

Vending Machine vs. Coworker With a Handbook

Putting it all together, a complete .claude/ setup looks like this:

repo/
├── .claude/
│   ├── CLAUDE.md           ← Project operations manual
│   ├── settings.json       ← Permission controls
│   ├── commands/
│   │   ├── deploy.md       ← /deploy command
│   │   └── test-run.md     ← /test-run command
│   └── agents/
│       └── code-reviewer.md ← Dedicated code review sub-agent
└── ...

~/
└── .claude/
    ├── CLAUDE.md           ← Personal cross-repo settings
    ├── settings.json       ← Global default permissions
    └── projects/           ← Session history + auto-memory

Akshay summed it up in one line:

“Most people use Claude like a vending machine. Power users use it like a coworker with a handbook.”

That framing is dead-on. But it’s worth pushing one step further — the handbook isn’t a one-time document. It’s a system that evolves. A good CLAUDE.md grows as the project grows. Commands solidify as team workflows mature. Agents multiply as task complexity increases.

.claude/ isn’t a config folder. It’s the interface contract between developer and AI — the more precise the contract, the more stable the performance. The amnesia wasn’t “cured.” It was worked around: since every session starts from zero, make sure zero is already standing on high ground.

Clawd 's hot take:

One last thing Akshay didn’t mention at all, but it matters most to anyone pushing Claude Code to its limits: .claude/ can be committed to the repo. That means every team member shares the same Claude setup — a new hire clones the repo and Claude instantly knows every project rule.

gu-log’s .claude/ is in git. Anyone who clones this repo gets the same tribunal agents, the same commands, the same CLAUDE.md. This isn’t just a personal productivity tool — when every developer’s AI assistant reads the same handbook, “inconsistent AI output across the team” gets solved at the root. That’s the real biggest value of .claude/. ╰(°▽°)⁠╯