How to Give Claude Code Persistent Project Memory
How Claude Code Handles Context
Claude Code reads CLAUDE.md files from three locations at the start of every session: the project root, the user's home directory (~/.claude/CLAUDE.md), and any parent directories above the project. The project-level file provides project-specific context. The home-level file provides personal preferences that apply across all projects. Parent directory files provide context shared across related projects in the same directory tree.
This file hierarchy gives you layered context without duplication. Your global CLAUDE.md might specify your preferred coding style and general conventions. Your project CLAUDE.md specifies the architecture, dependencies, and constraints unique to that project. Claude Code concatenates all of them into the system prompt, so the assistant sees everything simultaneously.
Beyond CLAUDE.md, Claude Code supports MCP (Model Context Protocol) servers that provide tools the assistant can call during a session. An MCP memory server exposes store, recall, and update tools. The assistant calls store when it learns something useful, and recall when it needs context from a previous session. This is how Claude Code's memory grows without anyone manually updating a file.
Step-by-Step Setup
Start with the non-obvious conventions, constraints, and architecture decisions that you find yourself repeating to the assistant. Do not document things the assistant can figure out by reading the code (like "this is a Node.js project"). Focus on the things that would surprise a new developer or that differ from standard practices.
# CLAUDE.md
## Architecture
This is a monorepo with three packages: api (Express), web (Next.js),
and shared (types and utilities). All inter-package imports go through
the shared package, never direct imports between api and web.
## Conventions
- All API responses use the Result<T> wrapper from shared/result.ts.
Never use try/catch for API calls. Use .map() and .mapError() instead.
- Database queries go through the repository pattern. No raw SQL outside
of /api/src/repositories/.
- Test files live next to the code they test, not in a separate test
directory. Named {filename}.test.ts.
## Constraints
- The Stripe API has a 100 requests/second rate limit. All payment
operations must go through the PaymentQueue, not direct API calls.
- The users table has a soft-delete column (deleted_at). All queries
must filter for deleted_at IS NULL unless explicitly querying
deleted records.
## Anti-patterns
- Do not use the ORM's eager loading for the orders table. It causes
N+1 queries because of the polymorphic line_items association.
Use the explicit join in OrderRepository.findWithItems() instead.Create or edit the .mcp.json file in your project root. This tells Claude Code to connect to the memory server at the start of every session. The memory server provides tools that Claude can call to store and retrieve observations.
{
"mcpServers": {
"memory": {
"type": "url",
"url": "https://mcp.adaptiverecall.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}For a global configuration that applies to all projects, add the server to ~/.claude/settings.json instead. This gives Claude memory across every project without per-project configuration. Use namespaces or tags in your memory server to keep project knowledge separate.
Organize the file by category rather than chronologically. Group related conventions together so the assistant sees them as a coherent set of rules rather than a random list. Keep the total length under 3,000 words. If you have more than that, the file is probably including things the assistant can learn from the code itself.
The four categories that provide the most value are:
Conventions that differ from defaults: Import ordering, naming patterns, directory structure, test organization. Only include conventions that deviate from what the framework or language recommends, because the assistant already knows the defaults.
Constraints not visible in code: Rate limits, external API quirks, database columns with hidden semantics, feature flags that control behavior, environment-specific configuration.
Architecture decisions with reasoning: Why you chose this database, why the service is split this way, why certain modules bypass the standard patterns. The reasoning matters because it helps the assistant make consistent decisions in edge cases.
Anti-patterns specific to your codebase: Things that look like they should work but do not. Functions with surprising behavior. Dependencies that conflict. Areas where the standard approach causes problems.
With the MCP memory server connected, use Claude Code normally. When you correct the assistant ("no, we use camelCase for API responses, not snake_case"), the memory server stores that correction. When you explain a constraint ("the CI pipeline does not run integration tests, only unit tests"), it stores the explanation. Over days and weeks, the memory builds a detailed model of your project and preferences.
You do not need to explicitly tell the assistant to remember things, though you can. The memory server's store tool is called automatically when the assistant encounters information it judges to be worth preserving. You can review what has been stored through the memory server's dashboard or by asking Claude "what do you remember about this project."
Once a month, review the memories stored by the MCP server. Remove observations that are outdated (a library was replaced, a convention changed). Promote patterns that have been consistently validated to your CLAUDE.md file, since static context is more reliable than dynamic retrieval for information that every session needs. This pruning keeps the memory system focused on current, accurate knowledge.
What the Memory Server Stores
A well-configured memory server stores several categories of knowledge. Factual observations about the codebase: which service handles authentication, where the deployment scripts live, what the database schema looks like. Developer preferences: preferred variable naming, how much explanation to include in comments, whether to write tests first or last. Correction history: patterns the developer rejected, suggestions that were wrong and why, approaches that do not work in this codebase. Architectural knowledge: how services communicate, what the data flow looks like, where the critical paths are.
Each stored memory should include enough context to be useful in isolation, because the retrieval system surfaces individual memories, not the full conversation where they were created. "Use camelCase for API responses" is less useful than "All API responses use camelCase for JSON keys because the mobile app's deserializer expects it and cannot be changed." The context makes the memory actionable in new situations.
Combining Static and Dynamic Memory
The most effective setup uses CLAUDE.md for the 20% of knowledge that matters in every session and the MCP memory server for the 80% of knowledge that matters only in specific contexts. The CLAUDE.md file should be compact and authoritative: these are the rules, follow them always. The memory server should be expansive and contextual: these are things we have learned, retrieve them when relevant.
Over time, you will notice patterns in what the memory server stores most often. If the same observation appears in memory repeatedly, it belongs in the CLAUDE.md file. If a constraint is important enough that forgetting it causes bugs, promote it to the static file. The memory server is the incubator, the CLAUDE.md file is the graduated, verified knowledge.
Give Claude Code a memory that grows with your project. Adaptive Recall's MCP server stores observations automatically and retrieves them using cognitive scoring for maximum relevance.
Get Started Free