Claude Code + MCP: how to give your agent persistent memory (with real code)

Every Claude Code user hits the same wall:

You start a fresh session. Your agent has no idea what you worked on yesterday. No memory of the bug you fixed, the pattern you established, the decision you made.

The agent can think. It can't remember.

Here's how to fix that with MCP (Model Context Protocol) and a simple local memory server.

The problem, concretely

Without persistent memory, Claude Code:

• Doesn't know your coding standards between sessions
• Can't reference previous decisions
• Re-learns your codebase every single session
• Forgets what you asked it NOT to do

You already have CLAUDE.md for project context — but that's static. What you need is dynamic memory that updates as you work.

How MCP memory works

MCP (Model Context Protocol) lets Claude Code call external tools during a session. A memory MCP server exposes two tools:

• remember(key, value) — store something for later
• recall(key) — retrieve it in a future session

Underneath, it's just a SQLite database or a JSON file. The MCP wrapper is what makes Claude aware it can use it.

Set up a local memory MCP server in 10 minutes

1. Install the memory server

# Using the official MCP memory server
npm install -g @modelcontextprotocol/server-memory

Or if you prefer Python:

pip install mcp-memory-server

2. Register it in your .claude/settings.json

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/Users/you/.claude/agent-memory.json"
      }
    }
  }
}

After saving this, restart Claude Code. You'll see the memory tools appear in the tool list.

3. Tell Claude how to use it

Add this to your CLAUDE.md:

## Memory Protocol

At the end of each session:
1. Call memory:save with a summary of what we worked on
2. Include: decisions made, patterns established, things to avoid
3. Start future sessions by calling memory:load to get context

Memory key format: YYYY-MM-DD_projectname

Now Claude will automatically save and load session context.

What to remember (and what not to)

Good things to persist:

{
  "2026-03-29_myproject": {
    "decisions": [
      "Use UUID v7 for all new IDs (time-sortable)",
      "Never use .forEach — use for...of for async safety",
      "Auth middleware must always check rate limit before JWT"
    ],
    "in_progress": "Refactoring payment module — stopped at webhook handler",
    "dont_do": ["Don't suggest Redux — we chose Zustand", "Don't add more npm dependencies without asking"]
  }
}

Bad things to persist:

• Large code blocks (use CLAUDE.md for those)
• API responses (too volatile)
• Anything sensitive (no tokens or passwords in memory)

The shared memory pattern for teams

If your team uses the same Claude API endpoint, you can share memory across developers:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/shared/repo/.claude/team-memory.json"
      }
    }
  }
}

Commit team-memory.json to git. Now everyone shares the same agent memory. Code review decisions, architecture choices, team conventions — all persistent, all shared.

Verify it's working

# Start a Claude Code session and type:
"Remember that we use UUID v7 for all IDs"

# Claude calls memory:save
# Close session, start new one, type:
"What do we use for IDs?"

# Claude calls memory:recall and knows the answer

If the memory tools are registered correctly, you'll see memory:save and memory:recall in the tool use log.

Why this matters for your API costs

With persistent memory, your agent stops re-discovering context every session. That means:

• Fewer tokens burned on re-explaining the codebase
• Fewer back-and-forth clarification rounds
• More direct, useful responses from session start

If you're running this on a Claude API proxy (like the one at simplylouie.com) at $2/month instead of $20/month, you can afford to run memory-powered sessions all day without worrying about usage costs.

The full .claude/ setup so far

For reference, here's what an optimized .claude/ directory looks like:

.claude/
├── settings.json          # MCP servers, permissions, model config
├── CLAUDE.md              # Project memory (static context)
└── commands/
    ├── review.md          # /review slash command
    ├── test.md            # /test slash command  
    └── deploy.md          # /deploy slash command

MCP memory sits outside the project (in ~/.claude/) so it persists across all your projects.

---

Part of an ongoing series on Claude Code configuration. Previous posts covered .claude/settings.json for agents, CLAUDE.md project memory, and custom /commands.