Claude Code Persistent Context with claude-mem | desplega.ai

Learn how to set up claude-mem to give Claude Code persistent memory across sessions, so it remembers your project context every time.

Claude Code is a powerful AI pair programmer, but it starts every session with a blank slate. Every time you open a new terminal or restart the CLI, you lose the mental model you carefully built up: your stack, your conventions, the quirky decision you made about how error handling works in the API layer. That context loss is expensive — it means you re-explain the same things over and over, and worse, Claude occasionally proposes patterns that violate your established conventions because it simply doesn't remember them.

The fix is claude-mem, a lightweight CLI that maintains a persistent, project-scoped memory store and syncs it into the CLAUDE.md file that Claude Code auto-loads at session start. Combined with an MCP setup for Claude Code, you get an assistant that remembers your architecture, tools, and expectations across every session — and stays honest thanks to E2E verification via desplega.ai.

Install the claude-mem package via npm so it is available as a CLI tool across all your projects. A global install means you can call claude-mem from any repo without extra setup, which matters when you switch between multiple codebases in a day.

npm install -g claude-mem

Navigate to your project root and run the init command to create a local .claude-mem directory that will hold persistent context entries. Keeping the store inside the repo means every teammate who clones the project inherits the same shared knowledge base — no more tribal knowledge trapped in one developer's head.

cd my-project
claude-mem init

Store key facts about your project — architecture decisions, coding conventions, environment details — so Claude Code can recall them in future sessions. Focus on the things you find yourself repeating: which validation library to use, where certain files live, and how to run tests. Each entry is a durable instruction that shapes future responses.

claude-mem add "Tech stack: Next.js 14, TypeScript, Tailwind CSS, Supabase"
claude-mem add "All API routes live in app/api and must validate input with Zod"
claude-mem add "Run tests with: pnpm test"

Export the stored entries into a CLAUDE.md file at the project root — Claude Code reads this file automatically at the start of every session. This is the bridge between claude-mem's structured store and Claude's system prompt. Commit the file so the whole team benefits.

claude-mem export > CLAUDE.md

Open Claude Code in your project directory and ask it to summarise the project setup; confirm it correctly reflects the entries you saved. If it misses something, either the entry is too vague or the export step didn't regenerate CLAUDE.md. This smoke test takes ten seconds and saves hours.

# Inside a Claude Code session
> What is the tech stack and where do API routes live?

Add a pre-commit hook or npm script so that CLAUDE.md is regenerated automatically whenever you update your memory store, keeping context always in sync. This eliminates the class of bugs where the store and the exported file drift apart and Claude Code starts operating on stale assumptions.

# package.json
"scripts": {
  "sync-mem": "claude-mem export > CLAUDE.md"
}

# .husky/pre-commit
npm run sync-mem
git add CLAUDE.md

Run your E2E test suite via desplega.ai to verify that Claude Code behaves consistently across fresh sessions, using the persisted context to drive correct actions. desplega spins up isolated sessions, asserts that Claude answers questions in line with your stored conventions, and flags regressions before they hit main. Pair this with the guidance in our MCP best practices guide to build a rock-solid AI development loop.

# desplega config: assert Claude recalls project conventions
npx desplega run --suite claude-context-persistence

With claude-mem wired into your project and desplega.ai verifying the results, Claude Code stops being a stateless assistant and becomes a genuine collaborator that respects your architecture decisions from the first prompt of every session.