How to give Claude Code persistent context across sessions

Claude Code is brilliant for exactly one session at a time. Close the terminal and it forgets your architecture, your conventions, and the bug you spent an hour explaining. Next session, you pay the re-explaining tax again.

The fix is layered, not singular. Claude Code has three built-in persistence mechanisms, and there's a fourth layer when you outgrow them. Here's how to set up each one properly.

Layer 1: the repo CLAUDE.md

The foundation. Claude Code reads CLAUDE.md from your project root at the start of every session and treats it as standing instructions.

Bootstrap one with the built-in command:

/init

That generates a starting file from your codebase. Then edit it ruthlessly. A good CLAUDE.md is a briefing, not documentation:

# MyApp

## Commands
- Build: `npm run build` (root — uses turbo)
- Test: `npm test -- --forceExit` (jest hangs without the flag)
- Never run `tsc` with emit in apps/web — stray .js files shadow .tsx sources

## Architecture
- apps/api — Express + Postgres. apps/web — Next.js 14 App Router.
- All API responses use the {success, data, error} envelope.

## Rules
- Semantic Tailwind tokens only — never hardcode colours
- New routes must be added to sitemap.ts

Two principles:

1. Stay under ~100 lines. The file loads in full every session, and adherence measurably drops as it grows — a 400-line file doesn't get you 400 lines of obedience, it gets you the model quietly ignoring some rules. Every line earns its place or gets cut.
2. Write rules and gotchas, not descriptions. "Jest hangs without --forceExit" saves a session. "This project uses Jest for testing" saves nothing.

Commit it to git. Your teammates get the baseline for free when they clone.

Layer 2: the user-level CLAUDE.md

Personal preferences that follow you across every project live in:

~/.claude/CLAUDE.md

This is the place for things that would be noise in a repo file: your preferred commit style, "always explain before running destructive commands," the package manager you insist on. It layers on top of the repo file, so keep the split clean — repo file for project truth, user file for personal taste.

Layer 3: auto memory

Claude Code also maintains its own memory between sessions — a directory of notes it writes for itself, surfaced through an index loaded at startup. You'll see it recall past fixes, project quirks, and decisions without being asked.

Two habits make it useful:

• Feed it. When Claude gets something important right after a struggle, say "remember this" — a one-line instruction like # followed by the fact adds it to memory on the spot.
• Prune it. Memory that's wrong is worse than no memory. Use /memory to open and edit the memory files when you notice stale facts — the index only loads a bounded amount at startup (roughly the first 200 lines), so a bloated, unpruned memory silently truncates.

The limitation to know: auto memory is scoped to you and largely to the project it was learned in. What Claude learns fixing repo A doesn't follow you to repo B, and it never reaches a teammate.

Layer 4: MCP servers — when context outgrows files

Everything above is per-person, per-repo, per-tool. That's fine until one of three things happens:

• Your context outgrows a 100-line file and starts fighting itself
• A second tool enters the workflow (Cursor, Copilot, a chat tab) and needs the same knowledge
• A second person joins and their Claude Code knows none of what yours knows

At that point the fix is architectural: move shared context out of files and into a source Claude Code loads over MCP (Model Context Protocol). Claude Code has first-class MCP support:

claude mcp add <name> <server details>

Any MCP server can supply context — docs servers, internal-wiki bridges, database schemas. The pattern that matters: knowledge lives in one governed place, and every session (yours and your teammates', in Claude Code and beyond) loads it on demand instead of from N drifting copies.

This is the layer Contextium provides: a team workspace of versioned context — knowledge, conventions, project phases, tasks — served over MCP to Claude Code and any other MCP-compatible tool. One setup command:

npx @contextium/mcp-server@latest setup

Teach it once; every teammate's AI arrives briefed. (If you're weighing this against just growing your CLAUDE.md, we wrote up that trade-off honestly: Contextium vs CLAUDE.md.)

The setup that works

Putting it together — the configuration we see work for real teams:

1. Thin repo CLAUDE.md (~50 lines): build commands, hard rules, repo-specific gotchas. Committed to git.
2. User CLAUDE.md: your personal style. Never project facts.
3. Auto memory: fed deliberately ("remember this"), pruned monthly (/memory).
4. Shared context over MCP: everything a second tool or second person needs — architecture, conventions, decisions, project state.

Each layer does one job. The re-explaining tax disappears when the right knowledge lives at the right scope — and the moment you feel yourself pasting the same explanation into a second tool or a teammate's session, that's the signal you've hit the ceiling of files and it's time for layer 4.