Claude Code Has No Memory. Here's How to Fix That.

Every new Claude Code session starts completely blank. Your repo context, coding conventions, in-progress decisions — gone. Claude asks what you were working on. You explain it again. This isn't a bug; it's how the stateless API works. But it means the tool that's supposed to accelerate you is burning the first ten minutes of every session on re-orientation.

There are three distinct tools for solving this, and most people only know the first one.

CLAUDE.md: the memory file Claude Code reads automatically

CLAUDE.md is a plain text file that Claude Code reads at the start of every session. It's the most reliable form of persistent context because it's just a file — no magic, no configuration, no sync required.

Claude Code checks two locations:

• ~/.claude/CLAUDE.md — global, applies to every project on this machine
• CLAUDE.md at the root of your project — project-specific, typically committed to the repo

Both are read simultaneously. There's no override mechanism — Claude Code synthesizes all context it can find, with more-specific (project-level) instructions generally taking precedence when there's a conflict.

A minimal global CLAUDE.md:

# Preferences

- TypeScript strict mode everywhere. Never disable a strict check without a comment.
- pnpm over npm
- Commit messages: conventional commits (feat/fix/chore/docs)
- Never write comments that restate what the code does
- Tests: prefer integration over mocks; mocks masked a production bug last year
- `pnpm test -- --run` to avoid watch mode when running tests manually

And a project-level one for a Node.js monorepo:

# forgein-platform

Architecture: pnpm monorepo
- apps/web — Next.js App Router (app.forgein.ai)
- apps/api — Express (api.forgein.ai)
- apps/worker — BullMQ jobs
- packages/db — Drizzle ORM (rebuild: `cd packages/db && npm run build` on schema changes)

## Key patterns
- Route groups: (app)/ and (auth)/ — parens excluded from URL paths
- Sidebar width: --sw CSS variable drives both sidebar and main margin simultaneously
- Tier display: isPro gates features, isTeam changes label text only

## Current focus
Stripe Team billing — all 4 price IDs in k8s secret, webhook endpoint needs load test

Claude reads this before it reads anything else. It shapes every response in the session.

What to put in CLAUDE.md — and what to skip

The most common mistake is trying to document the codebase. CLAUDE.md is for things Claude can't derive by reading the files: hidden constraints, team conventions, current focus, anti-patterns to avoid.

Works well:

• Workflow commands: what to run, what flags to use, what ports things start on
• Conventions that aren't enforced by tooling: commit format, PR process, branch naming
• Architecture decisions: the non-obvious reasons a pattern was chosen
• Current focus: what you're actively working on so Claude doesn't suggest conflicting changes
• Explicit anti-patterns: frameworks or approaches you've already decided against

Doesn't work:

• File-by-file documentation (Claude will read the files)
• Exhaustive API references (Claude can grep for them)
• Anything that will be stale in two weeks and you won't remember to update

The right mental model: CLAUDE.md is a briefing document for a contractor who's smart and will read the code. What they need is the non-obvious context that isn't in the files.

The limits of CLAUDE.md

CLAUDE.md is static. You edit it manually. It lives in your repo or at ~/.claude/ and doesn't leave the machine unless you commit it or copy it yourself.

Three gaps follow from this:

• Machine drift — your global CLAUDE.md on your laptop diverges from what's on your work desktop
• Manual maintenance — you have to remember to update it when the project changes
• No accumulation — corrections you make during sessions don't feed back into the file automatically

For solo developers on one machine, manageable. For anyone working across machines or with a team, real friction.

Auto-memory: what Claude Code learns on its own

Claude Code has a built-in auto-memory feature (Settings → Memory). When enabled, Claude surfaces memories worth keeping — corrections you made, preferences you expressed, patterns you established — and writes them to structured files in ~/.claude/projects/<project>/.

These are plain markdown files, same format as CLAUDE.md. The difference is that Claude is writing them as you work, not you writing them upfront. A session where you push back on three suggestions produces three memory files. The next session opens with Claude already knowing those three things.

The weakness is the same as CLAUDE.md: these files live on one machine. They don't roam.

Cloud sync: when one machine isn't enough

If you work across machines, or you want teammates to share context, you need something that bridges sessions at the cloud layer.

This is what forgein does. It syncs your auto-memory files to a cloud store and makes them available in any Claude Code session on any machine. The setup takes about two minutes:

1. Sign up at app.forgein.ai and install the forgein skill into Claude Code (Settings → Skills → add from the forgeinai/forgein registry)
2. /forgein auth — authenticates the CLI, stores the token at ~/.config/forgein/token
3. /forgein mem sync — pushes your local memory files to the cloud

On any other machine: install the skill, authenticate, run /forgein mem sync again. Your memories pull down. New machine, same context as the one you left.

You can also search across all memories in a session with /forgein mem search <query> — useful when you know you captured a decision but can't remember which session it was in.

The practical starting point

In order of ROI:

1. Write a ~/.claude/CLAUDE.md with your global preferences. Language, tooling, commit style, things you hate. Takes fifteen minutes, pays off on the next session.
2. Add a CLAUDE.md at the root of your main project. Commit it. Architecture, commands, current focus.
3. Enable auto-memory in Claude Code settings. Let it accumulate for a week before evaluating.
4. If you work across machines or with a team, set up forgein to sync the accumulated files.

The first two steps alone eliminate most of the re-orientation tax. Steps three and four make the context smarter and portable without any ongoing effort.