How to Add Persistent Memory to Claude Code with MCP

The Problem: Claude Code Forgets Everything

You spend 45 minutes explaining your project architecture to Claude Code. You walk it through the folder structure, the naming conventions, the database schema, the reason you chose Postgres over MongoDB, and the three edge cases that caused production incidents last quarter. Claude Code nails the task. You close the terminal.

The next morning, you open a new session. Claude Code has no idea who you are. It does not know your project. It does not know your conventions. It does not know about the edge cases. You are starting from zero.

This is the single biggest friction point in working with AI coding assistants in 2026. The models are powerful enough to understand complex codebases. They can write production-quality code, debug race conditions, and refactor legacy systems. But they cannot remember. Every session is an isolated conversation that dies when you close the window.

The cost of this is real. You re-explain the same context repeatedly. You lose nuance that took multiple sessions to build. The AI makes suggestions you already rejected last week because it has no memory of that decision. Over days and weeks, the accumulated re-onboarding time adds up to hours of wasted effort.

There is a fix for this, and it takes less than 30 seconds to set up.

What is MCP (Model Context Protocol)?

Before jumping into the solution, a quick primer on the technology that makes it possible. Model Context Protocol (MCP) is an open standard created by Anthropic that lets AI assistants connect to external tools and data sources. Think of it as a USB port for AI: a standardized way to plug in new capabilities without modifying the model itself.

MCP works through a client-server architecture. The AI assistant (Claude Code, Cursor, Windsurf, or any MCP-compatible client) acts as the client. External programs called MCP servers provide tools the AI can call. When you connect an MCP server, the AI gains access to new functions it can invoke during a conversation.

For example, an MCP server could give the AI the ability to query a database, read from a CRM, or -- relevant to this article -- store and retrieve persistent memories.

The protocol handles all the communication plumbing. You do not need to write integration code, build APIs, or configure webhooks. You register a server, and the AI can immediately use whatever tools that server exposes.

MCP is supported by Claude Code, Cursor, Windsurf, Cline, and a growing list of AI development tools. If you want to explore what is available, we maintain a guide to the best MCP memory servers with detailed comparisons.

The Solution: mcp-smart-memory

mcp-smart-memory is an npm package that gives Claude Code persistent memory. When connected, Claude Code gains three new tools: the ability to store knowledge, recall it using semantic search, and view statistics about what it has remembered.

The key design decisions that make it practical for daily use:

• 100% local. All memories are stored in a JSON file on your machine. No cloud, no API keys, no external services, no data leaving your computer.
• Zero configuration. One command to install. No config files, no environment variables, no Docker containers.
• TF-IDF semantic search. When Claude Code recalls a memory, it does not do simple keyword matching. It uses TF-IDF (Term Frequency-Inverse Document Frequency) to find semantically relevant results, even if the exact words do not match.
• Categorized storage. Memories are organized by category and tagged for fine-grained retrieval. This means Claude Code can ask for "all architecture decisions" or "debugging patterns for the auth module" and get targeted results.
• Works across projects. Your memories persist globally, so knowledge learned in one project is available in another when relevant.

Step-by-Step Installation

There are two ways to set up mcp-smart-memory. Both take under 30 seconds.

Option 1: Add Directly to Claude Code (Recommended)

This is the fastest method. Run this single command in your terminal:

claude mcp add memory -- npx mcp-smart-memory

That is it. Claude Code now has persistent memory. The next time you start a conversation, it will have access to memory_store, memory_recall, and memory_stats tools.

Option 2: Install Globally via npm

If you prefer to install the package globally so it is available system-wide (useful if you use multiple MCP clients):

# Install globally
npm install -g mcp-smart-memory

# Then add to Claude Code
claude mcp add memory -- mcp-smart-memory

Verify the Installation

Start a new Claude Code session and ask it to check its available tools. You should see three new memory tools listed. You can also run a quick test:

# In your Claude Code session, ask:
"Store a memory: This project uses TypeScript with strict mode enabled."

# Then in a NEW session, ask:
"What do you remember about TypeScript in this project?"

If Claude Code recalls the TypeScript detail, your memory is working.

How It Works: The Three Core Tools

Once connected, Claude Code has access to three tools it can call at any point during a conversation.

memory_store -- Save Knowledge

This tool writes a piece of knowledge to persistent storage. Each memory has a content field (the actual knowledge), a category (like "architecture", "debugging", or "preferences"), and optional tags for more granular organization.

// What Claude Code does internally when you say
// "Remember that we use PostgreSQL 16 with pgvector for embeddings"

memory_store({
  content: "Project uses PostgreSQL 16 with pgvector extension for vector embeddings. Chosen over MongoDB for ACID compliance and mature ecosystem.",
  category: "architecture",
  tags: ["database", "postgresql", "pgvector", "embeddings"]
})

You do not need to call this tool manually. When you share context that seems worth remembering, Claude Code will store it automatically. You can also explicitly say "remember this" to trigger a store.

memory_recall -- Semantic Search

This tool searches across all stored memories using TF-IDF scoring. It returns the most relevant results based on the query, not just exact keyword matches.

// When Claude Code needs to know about your database setup:

memory_recall({
  query: "database setup and configuration",
  limit: 5
})

// Returns the PostgreSQL memory even though the query
// did not contain "PostgreSQL" or "pgvector"

The search considers term frequency (how often a word appears in a specific memory), inverse document frequency (how unique a word is across all memories), and category weighting. This means highly specific terms like "pgvector" carry more weight than common words like "database".

memory_stats -- Your Knowledge Dashboard

This tool provides an overview of what is stored: total memory count, breakdown by category, storage size, and most frequently tagged topics. It is useful for auditing what Claude Code knows and identifying gaps.

memory_stats()

// Returns:
// Total memories: 47
// Categories: architecture (12), debugging (9), preferences (8), ...
// Top tags: typescript, react, postgresql, auth, api
// Storage: 23 KB

Practical Examples

Here are four real-world scenarios where persistent memory eliminates repeated context-setting.

1. Storing Architecture Decisions

Your project has a specific reason for every technical choice. Without memory, you explain these repeatedly. With memory, you explain once.

You: "We use a monorepo with pnpm workspaces. The API is in packages/api,
the web app in packages/web, and shared types in packages/shared.
We chose this over separate repos because the shared types package
prevents frontend-backend type drift. Remember this."

// Claude Code stores this. In every future session, it knows
// the repo structure and the reasoning behind it.

This is especially valuable for onboarding. If a second developer on your team connects the same memory store, they get the full context of your architectural decisions without reading through months of Slack threads.

2. Remembering Debugging Patterns

Every codebase has recurring failure modes. Memory turns these into institutional knowledge.

You: "When the auth middleware returns a 401 on valid tokens,
it is almost always because the JWT_SECRET env var is not
loaded. The .env file must be in packages/api, not the root.
We have hit this three times. Remember this pattern."

// Next time this issue surfaces, Claude Code checks memory
// before suggesting generic debugging steps.

3. Tracking Preferences and Conventions

Code style preferences, formatting standards, naming conventions, commit message formats -- these are the things you tell every AI assistant repeatedly. Memory stores them once.

You: "Our conventions: use barrel exports (index.ts) in every directory.
Component files are PascalCase. Utility files are camelCase.
We use Zod for all runtime validation, never io-ts.
Tests go in __tests__ next to the source file, not in a
separate test directory."

// Claude Code follows these conventions in every future session
// without being reminded.

4. Building a Knowledge Base Over Time

The most powerful use of persistent memory is not any single stored fact -- it is the accumulation of knowledge over weeks and months. After 50 sessions, Claude Code has absorbed your project's architecture, your team's conventions, the bugs you have fixed, the refactors you have planned, and the decisions you have deferred. It becomes a genuine project knowledge base that grows every time you code.

You can browse your stored memories at any time by asking Claude Code to run memory_stats or by inspecting the local JSON file directly.

TF-IDF vs Vector Embeddings: Why TF-IDF Works

If you are familiar with AI memory systems, you might wonder why mcp-smart-memory uses TF-IDF instead of vector embeddings. Both are valid approaches, but they make different trade-offs. For a comprehensive comparison of available options, see our guide to MCP memory servers.

Advanced: soul-mcp for Identity and Reflection

If you want to go beyond basic memory into something more structured, soul-mcp builds on the same foundation with additional capabilities:

• Identity persistence. The AI develops a consistent working style and personality across sessions, maintaining continuity in how it approaches problems.
• Reflection. The AI can evaluate its own past decisions and learn from mistakes, storing meta-knowledge about what approaches worked and what did not.
• Pattern recognition. Automatic detection of recurring themes across stored memories, surfacing connections you might not have noticed.
• Evaluation. Built-in tools to assess the quality and relevance of stored memories, keeping the knowledge base clean over time.

soul-mcp includes 6 tools total: the 3 core memory tools plus memory_patterns, memory_suggest, and memory_evaluate. The core tools are free. The advanced tools are available with a Smart Memory Pro license.

This is particularly relevant for developers who use Claude Code as a long-running pair programming partner. Over time, the AI builds up not just knowledge of your project, but an understanding of how you prefer to solve problems.

5 Tips for Getting the Most Out of AI Memory

1. Be explicit about what to remember

While Claude Code will proactively store important context, you get better results when you explicitly flag high-value knowledge. Phrases like "remember this decision" or "store this pattern" signal that the information is worth persisting. The more intentional you are about what gets stored, the more useful recall becomes.

2. Use categories consistently

Stick to a small set of categories: architecture, debugging, preferences, conventions, decisions. Consistent categorization makes recall more precise because Claude Code can filter by category when searching. If your categories are random ("stuff", "important", "misc"), the search has nothing useful to filter on.

3. Store the "why", not just the "what"

Storing "we use PostgreSQL" is less valuable than storing "we chose PostgreSQL over MongoDB because we need ACID transactions for payment processing and the pgvector extension for our embedding search feature." The reasoning is what prevents Claude Code from suggesting alternatives you already evaluated and rejected.

4. Review and prune periodically

Run memory_stats every few weeks to see what is accumulated. If you have migrated from React to Svelte, the old React conventions are now noise. Ask Claude Code to remove outdated memories. A clean memory store with 30 relevant entries outperforms a bloated one with 300 entries where half are stale.

5. Combine with project-level context files

Memory works best alongside structured context files like CLAUDE.md or .cursorrules. Use the context file for stable, project-wide rules (formatting, linting, directory structure). Use memory for evolving knowledge (debugging patterns, decision history, learned preferences). The two complement each other: the context file is the constitution, memory is the case law. You can use our free developer tools like the JSON formatter to inspect and validate memory export files if you ever need to audit the raw data.

Frequently Asked Questions

Does Claude Code have persistent memory?

Claude Code does not have built-in persistent memory across sessions. Each new conversation starts with a blank context. However, you can add persistent memory by connecting an MCP memory server like mcp-smart-memory. This gives Claude Code the ability to store and recall knowledge across sessions using tools like memory_store and memory_recall.

What is an MCP memory server?

An MCP memory server is an external tool that connects to AI coding assistants like Claude Code, Cursor, or Windsurf through the Model Context Protocol. It provides persistent storage for knowledge, context, and patterns. The AI can write to and read from this memory store, allowing it to remember information across separate conversations and sessions.

How do I install mcp-smart-memory for Claude Code?

Run a single command in your terminal: claude mcp add memory -- npx mcp-smart-memory. This registers the memory server with Claude Code. No API keys, no cloud accounts, and no configuration files are needed. The server stores all data locally in a JSON file on your machine. You can also install it globally with npm install -g mcp-smart-memory.

Is my data sent to the cloud when using mcp-smart-memory?

No. mcp-smart-memory is 100% local. All memories are stored in a JSON file on your machine. There are no API calls, no cloud services, and no external dependencies. The TF-IDF semantic search runs entirely in your local Node.js process. Your project knowledge, architecture decisions, and debugging notes never leave your computer.

What is the difference between TF-IDF and vector embeddings for AI memory?

TF-IDF (Term Frequency-Inverse Document Frequency) is a statistical method that scores relevance based on word frequency. It works locally, requires zero configuration, and performs well when the vocabulary is consistent -- which is typical for developer notes and project documentation. Vector embeddings use neural networks to capture semantic meaning, which can handle synonyms and paraphrases better, but they require an API key or a local model, add latency, and introduce external dependencies. For most developer use cases, TF-IDF provides accurate recall with no setup overhead.

Your AI Should Learn and Grow With You

The gap between what AI coding assistants can do and what they remember is the biggest bottleneck in the developer experience today. The models understand complex systems. They write solid code. They debug intricate issues. But without memory, every session starts from scratch, and you pay the re-onboarding cost every single time.

Persistent memory changes the dynamic entirely. Instead of an assistant you re-train daily, you get a collaborator that accumulates knowledge about your project, your patterns, and your preferences. It gets more useful the longer you work with it, not less.

The setup takes one command. The storage is local and private. The search is fast and relevant. There is no good reason not to try it.

claude mcp add memory -- npx mcp-smart-memory

Run that, start a session, and tell Claude Code something worth remembering. Tomorrow, ask it what it knows. The difference speaks for itself.