How to give Claude Code persistent memory across projects

You're mid-way through a complex refactor. Claude Code knows your codebase intimately — the database schema quirks, the reason you picked that unconventional error handling pattern, the three things you tried before landing on the current approach. Then you close the terminal.

The next morning, you open Claude Code and it's back to zero. You spend the first twenty minutes re-explaining the context before you can do any real work.

This is the session-reset problem. It's not a bug in Claude Code — it's an architectural constraint. Claude Code's context lives in the current session. When the session ends, most of it goes with it. This post covers exactly what Claude Code gives you out of the box for memory persistence, where those tools run into their limits, and how to extend them with a proper memory layer.

What Claude Code gives you out of the box

Claude Code has two built-in mechanisms for persisting context across sessions.

CLAUDE.md files

CLAUDE.md files are loaded automatically at the start of every session. They're plain Markdown — you write your project conventions, architectural decisions, and preferences once, and Claude Code reads them every time.

There are four scopes:

• User (~/.claude/CLAUDE.md) — applies to every project on your machine. Good for personal preferences like "always prefer TypeScript strict mode" or "I use Neovim, format commands accordingly."
• Project (CLAUDE.md in the repo root) — checked into git, shared with the whole team. The standard place for project conventions.
• Local (.claude/CLAUDE.md) — not checked in. Personal overrides for a specific project.
• Enterprise — managed policies applied at the organization level.

A well-written project CLAUDE.md looks something like this:

# Project conventions

- TypeScript strict mode is enabled. Never use `any`.
- We use Tailwind for all styling. No inline styles, no CSS modules.
- Tests live next to source files: `foo.ts` → `foo.test.ts`
- All API routes require authentication middleware unless explicitly marked public.
- Database: PostgreSQL via Prisma. Never write raw SQL.
- Error handling: always use the `AppError` class from `src/lib/errors.ts`.

This is genuinely useful. Claude Code reads it at session start and stays aligned with your conventions without you having to repeat them.

Auto memory (MEMORY.md)

Beyond CLAUDE.md, Claude Code automatically captures important context during sessions into a MEMORY.md file. This lives at ~/.claude/projects/<project-path>/MEMORY.md — per-machine, per-project.

When Claude Code notices something worth remembering (a decision you made, a pattern it should know about), it writes it there. That content is loaded back in future sessions.

This is where the useful-but-limited part comes in. Auto memory has a 200-line cap. On a simple project, that's fine. On anything with real complexity — multiple services, months of history, significant architectural evolution — you'll hit it.

Where the limits are

Both tools are useful. Neither is sufficient on its own for a serious, long-running project.

The 200-line ceiling is real. Auto memory fills up. When it does, older context gets dropped. The things that got pushed out might be exactly what you need today.

It's per-machine. Auto memory lives in ~/.claude/ on your local filesystem. Switch to your laptop, log in from a remote machine, or hand a task off to a teammate — none of that memory travels with you.

No cross-project context. Solutions you discovered in one project don't surface when you hit the same problem in another. Consider a concrete example: you spent two hours debugging a CORS preflight issue caused by a missing Vary header in your Express middleware. You wrote a note in that project's CLAUDE.md. Three months later, you hit the identical issue in a different repo. Claude Code has no idea you've seen this before.

CLAUDE.md is static text, not a knowledge base. It doesn't grow with your project. It can't answer "what did we decide about error handling last month?" — you'd have to know where to look and what to look for.

Team memory doesn't exist natively. CLAUDE.md is shared, but it's static. Auto memory is individual — your teammate's Claude Code doesn't have your debugging sessions. There's no mechanism for the team's accumulated knowledge to flow between developers.

Past sessions don't resurface automatically. When the same bug recurs, Claude Code won't recall your prior investigation unless you explicitly paste it in.

Adding persistent memory with MemNexus

MemNexus connects to Claude Code via MCP (Model Context Protocol), giving it access to a searchable, structured memory store that persists across sessions, machines, and projects.

Setup takes about a minute:

npm install -g @memnexus-ai/cli
mx auth login --api-key YOUR_API_KEY
mx setup claude-code

mx setup claude-code configures the MCP server connection, sets up your CLAUDE.md with session-start instructions, and installs CommitContext — a hook that automatically captures context from your git commits into your memory store. Once configured, Claude Code can read from and write to your memory store as part of normal conversation — no special commands required.

Usage patterns

1. Automatic context loading at session start

mx setup claude-code adds a session-start instruction to your CLAUDE.md automatically. When you open Claude Code, it searches your memory store for relevant history — prior decisions, resolved bugs, architectural notes — and loads them into context. The 200-line limit doesn't apply here because MemNexus retrieves semantically relevant content rather than dumping everything.

2. Saving debugging sessions while they're fresh

After resolving something non-obvious, tell Claude Code to save it:

"Save a memory about this fix — the connection pool was being instantiated per-request instead of at module load time. We saw this as intermittent timeout errors under load."

Next time you see similar symptoms — in this project or another — that memory surfaces when Claude Code searches for relevant context. The fix you found isn't locked in a git commit message that nobody reads. It's searchable knowledge.

3. Cross-project knowledge retrieval

This is the scenario that's hard to replicate any other way. You're in a new project and you ask Claude Code about connection handling patterns. MemNexus returns context from a different repo where you worked through the same problem last quarter — the specific approach that worked, the one that didn't, and why.

Your accumulated experience across projects becomes reusable instead of siloed.

The combination that works

CLAUDE.md and MemNexus serve different roles and work best together:

• CLAUDE.md holds stable, team-wide conventions that belong in version control — TypeScript config, coding standards, project structure.
• MemNexus holds the dynamic, growing knowledge that accumulates over time — debugging history, architectural decisions with their reasoning, patterns discovered across projects.

Neither replaces the other. CLAUDE.md is what you'd put in a team wiki. MemNexus is what you'd want to happen if every debugging session, every resolved ambiguity, and every hard-won decision got automatically indexed and made searchable.

Using a different AI coding tool?

The same MCP-based approach works across the AI coding assistant ecosystem:

• How to Give Cursor Persistent Memory Across Sessions — adding persistent memory to Cursor
• How to Give Windsurf Persistent Memory Across Sessions — adding persistent memory to Cascade
• GitHub Copilot Memory: How to Make Copilot Remember Your Project — persistent context for Copilot Chat

---

MemNexus is currently in invite-only preview. If you use Claude Code seriously and want your context to actually persist, request access at memnexus.ai/waitlist. If you're already using Claude Projects and wondering how MemNexus fits in, see MemNexus vs Claude Projects.