Claude Code Session Memory: CLAUDE.md & More [2026]

April 13, 2026—5 min read

Claude Code is stateless between sessions. Close a chat and open a new one—Claude has no memory of your previous work, decisions, or conventions. This is by design (each session gets a fresh 1M token context window). But you can give Claude institutional memory three ways: 1) CLAUDE.md files in your repo, 2) the /memory command and memory files, and 3) keeping sessions lean so context lasts longer (via Token Limits compression). Together these mean Claude carries real knowledge across days of work.

Claude Code does not store conversation history between sessions. Every new session is a blank slate. This is a feature—you get a fresh context window—but it means you have to re-explain your project, conventions, and gotchas to Claude in every session. The fix is not to make Claude remember, but to encode knowledge in files that Claude reads automatically.

Approach 1: CLAUDE.md files (the best approach)

Create a CLAUDE.md file in your project root. Claude Code loads this file automatically at the start of every session. Use it to encode your project context: coding conventions, architecture decisions, gotchas, tools, required environment variables, and common commands.

Example CLAUDE.md structure:

# Project Context ## Architecture - Backend: Next.js API routes (src/app/api) - Database: Postgres via Prisma - Frontend: React hooks, Tailwind CSS ## Conventions - Type strict mode enabled - No Vite—use Next.js build - Commit message format: "type: description" (fix, feat, docs, refactor) ## Common Gotchas - Database migrations require `npm run migrate` - Build fails if TypeScript errors exist—run `npm run type-check` first - CSS is Tailwind only, no custom CSS files ## Running Locally - Start dev: `npm run dev` - Build: `npm run build` - Test: `npm run test`

Claude Code reads CLAUDE.md automatically at the start of every session. The file serves as a permanent knowledge base that does not reset between sessions.

Approach 2: /memory command and memory files

Claude Code has a built-in /memory command. Type /memory add "key" "value" to store a fact that Claude retains within a session. Type /memory list to see all stored facts. This helps within a single session but does not persist across sessions.

Use /memory for temporary context: "This is a payment integration task" or "User is on the auth module refactor". When you start a new session and need that context, re-enter it with /memory add again.

Approach 3: Keep sessions lean with compression

The longer a session runs without hitting the token limit, the more context Claude retains from your conversation. Install Token Limits to compress tool outputs 60-90%. A typical 3-hour session that would normally hit limits (forcing a restart) can now run 8-10 hours. More session time = more context retention within that session.

This does not make Claude remember across sessions, but it extends individual sessions so you have more uninterrupted time with continuous context.

Recommended approach: Combine all three

  1. Create CLAUDE.md in your repo root with architecture, conventions, and gotchas
  2. Install Token Limits so sessions last longer and you retain more context within them
  3. Use /memory during a session for temporary, task-specific context
  4. At end of session, note important discoveries or decisions in CLAUDE.md for the next session

What goes in CLAUDE.md

  • ✓Architecture: Tech stack, folder structure, key entry points
  • ✓Conventions: Code style, naming, commit formats, branch patterns
  • ✓Gotchas: Known issues, common build failures, environment setup quirks
  • ✓Commands: How to run tests, build, deploy, migrate database
  • ✓Required vars: Environment variables, API keys, config locations
  • ✓Context: Domain knowledge, business logic, why decisions were made

Example: A real CLAUDE.md

# Token Limits Project ## Stack - Next.js (TypeScript strict) - Prisma ORM → Postgres - Stripe for payments, Resend for email ## Where things live - Website: src/app (Next.js app router) - Proxy: client/index.ts (runs locally, intercepts API) - MCP server: mcp-server/index.ts ## Key Commands - Build binaries: /build-client (all platforms) - Rebuild MCP: /build-mcp (after mcp-server changes) - Type check: npx tsc --noEmit - Deploy: railway up (after binaries uploaded to R2) ## Gotchas - Binaries in R2 CDN, NOT in git - NEVER deploy without /upload-binaries first - Prisma migrations require DATABASE_URL - MCP manifest is in mcpb ZIP, update when server changes

Encode your project knowledge once, use it forever

CLAUDE.md files give Claude permanent context about your project. Combined with Token Limits compression, you get days-long sessions with continuous context. Create one file, solve context amnesia across all future sessions.

Get Token LimitsView Setup Guide

FAQ

Does Claude Code automatically find CLAUDE.md?

Yes. Claude Code looks for CLAUDE.md in your repo root at the start of each session. Create it once and it loads automatically.

Can I have multiple CLAUDE.md files?

You can create CLAUDE.md in subdirectories for context-specific info (e.g., src/CLAUDE.md for frontend context). Claude reads the most relevant one for your current task.

Should I commit CLAUDE.md to git?

Yes. CLAUDE.md is documentation for your project. Commit it so all developers (and Claude) see the same conventions and architecture.

Does /memory persist across Claude Code sessions?

No. /memory is session-only. Use it for temporary context within a session. Use CLAUDE.md for permanent, cross-session knowledge.

Can CLAUDE.md replace watching token usage?

No. CLAUDE.md reduces how much context you have to re-explain. Token Limits extends how long sessions last. Use both.

← Back to blog