Claude Code Memory: How Context, History, and Project Knowledge Work (2026)

Quick Answer: Claude Code uses three layers of memory: session context (the current conversation and files), project knowledge (CLAUDE.md, SKILL.md, and config files loaded at startup), and user preferences (stored in ~/.claude/settings.json). Claude does not persist memory between sessions by default, but you can use CLAUDE.md as a persistent memory file that Claude reads on every startup.

Does Claude Code remember things between sessions?

No. Each Claude Code session starts fresh. When you close a session and start a new one, Claude has no memory of what you discussed, what files you changed, or what decisions you made. This is a fundamental design choice, not a bug.

The practical impact: if you spent 30 minutes explaining your project architecture to Claude in one session, you have to explain it again in the next session. Claude won't remember that you prefer Zustand over Redux, that your API uses snake_case, or that you decided to use Postgres instead of MongoDB yesterday.

This is where CLAUDE.md and SKILL.md files become important. They act as persistent memory that loads automatically.

See SKILL.md in action

Doxaflow

by Matthew Ward

$19

finalize

by Alex Shi

$5

Flutter Cross Master

by Pietro Giovanni Vaccarello

$7

Browse all skills

What is CLAUDE.md and how does it work as memory?

CLAUDE.md is a markdown file that Claude Code reads at the start of every session. It sits in your project root or in ~/.claude/CLAUDE.md for global preferences. Whatever you put in this file becomes part of Claude's context before you type anything.

Think of it as a briefing document. Instead of repeating yourself every session, you write it once:

# CLAUDE.md

## Project context
This is a Next.js 15 app with App Router, TypeScript strict mode, Tailwind CSS, and Supabase.
We use Zustand for client state and React Query for server state.
Our API follows REST conventions with snake_case field names.

## Conventions
- All components use named exports, not default exports
- Tests go in __tests__ directories next to the code they test
- We use Prettier with 2-space indent and single quotes
- Error handling uses a custom AppError class in src/lib/errors.ts

## Current priorities
- Migrating from Pages Router to App Router (70% done)
- Adding end-to-end tests with Playwright
- Do not modify anything in src/legacy/ unless explicitly asked

Claude reads this on startup and follows these instructions throughout the session. Update the file as your project evolves and Claude's "memory" stays current.

What is the difference between CLAUDE.md and SKILL.md?

Both are markdown files that Claude reads, but they serve different purposes:

CLAUDE.md is project-specific context. It describes your codebase, conventions, priorities, and preferences. It's unique to your project. You write it yourself.

SKILL.md is a reusable capability. It teaches Claude how to perform a specific task (code review, test generation, commit writing) and works across any project. Skills are portable and shareable.

You can use both. CLAUDE.md tells Claude about your project. SKILL.md files tell Claude how to do specific jobs within your project. Together they give Claude both the context and the capabilities it needs.

For pre-built skills that work alongside your CLAUDE.md, browse Agensi.

How does Claude Code handle context within a session?

During a session, Claude maintains a conversation history and a view of your project files. The context window has a token limit, and as the conversation grows, older messages may fall out of context.

Claude Code manages this by keeping the most relevant information: recent messages, currently open files, and the CLAUDE.md and SKILL.md contents (which stay pinned). When you reference a file, Claude reads it into context. When the conversation gets long, Claude summarizes earlier exchanges to free up space.

Practical tips for managing session context:

Start fresh for new tasks. If you finished a refactoring task and want to move to something unrelated, start a new session. Carrying over context from the old task wastes context window space and can confuse Claude.

Be specific about which files matter. Instead of "look at my project," say "look at src/auth/login.ts and src/middleware/auth.ts." Claude loads only what you point to, keeping context focused.

Use /compact when sessions get long. This summarizes the conversation history to free up context window space. Useful for long coding sessions where you've been going back and forth.

What files does Claude Code read automatically?

When a session starts, Claude Code automatically reads:

1. CLAUDE.md in the project root (if it exists)
2. ~/.claude/CLAUDE.md for global user preferences (if it exists)
3. SKILL.md files in .claude/skills/ (project) and ~/.claude/skills/ (user)
4. Claude Code settings from .claude/settings.json and ~/.claude/settings.json
5. Project configuration files like package.json, tsconfig.json, pyproject.toml (scanned but not deeply read until needed)

Everything else is loaded on demand when you reference it or Claude determines it's relevant to the current task.

How do I make Claude remember decisions across sessions?

The best approach is to update CLAUDE.md as you make decisions. If you and Claude decide to use a specific architecture pattern, add it to CLAUDE.md. If you establish a naming convention, document it there.

Some developers add a "Decisions log" section:

## Decisions log
- 2026-05-15: Switched from REST to tRPC for internal APIs
- 2026-05-10: Using Vitest instead of Jest (faster, native ESM)
- 2026-05-08: All new components use compound pattern with slots

Claude reads this on startup and respects these decisions without you having to re-explain them.

Another approach is to use the /memory command during a session. When Claude learns something important about your project, you can tell it to save a note. These notes persist in your Claude Code configuration and load on subsequent sessions.

Can Claude Code access external memory or databases?

Not natively. But through MCP servers, Claude can connect to external knowledge sources. An MCP server connected to your Notion workspace, your project's wiki, or a documentation database gives Claude access to information beyond what's in the local files.

The Agensi MCP server is one example. It lets Claude search a catalog of skills and suggest relevant ones based on the current task. This is external knowledge that Claude wouldn't have from your project files alone.

For setting up MCP connections, see How MCP and SKILL.md Work Together.

What are common mistakes with Claude Code memory management?

Putting too much in CLAUDE.md. A 2,000-word CLAUDE.md eats context window space on every session. Keep it focused on what Claude actually needs to know: conventions, architecture decisions, and current priorities. Delete information about completed tasks.

Not using CLAUDE.md at all. Every session starts from zero without it. Even a 10-line CLAUDE.md with your stack, formatting preferences, and project structure saves you minutes of explanation on every session.

Expecting Claude to remember between sessions. It won't. If Claude made a mistake you corrected, add the correction to CLAUDE.md so it doesn't repeat it. "Never use default exports in this project" in CLAUDE.md prevents the same mistake across every future session.

Keeping stale information. If CLAUDE.md says "we're migrating to App Router" but the migration finished two weeks ago, Claude will still treat it as in-progress. Review and update CLAUDE.md regularly.

---