Claude Memory MCP

Persistent memory for Claude across sessions — works with VS Code, Claude Desktop, and any MCP client.

---

Why This Exists

Claude doesn't remember previous conversations. Every new session starts fresh.

This MCP server gives Claude persistent memory:

• 💾 Save important context, decisions, discoveries
• 🔍 Search past conversations with full-text search
• 🔄 Recall what happened in previous sessions
• 📝 Sync with CLAUDE.md for project-specific context
• 🌐 Works everywhere — VS Code, Claude Desktop, terminal

---

Quick Start

1. Install

# Clone the repository
git clone https://github.com/YOUR_USERNAME/claude-memory-mcp.git
cd claude-memory-mcp

# Install dependencies
npm install

# Build
npm run build

2. Configure Your MCP Client

VS Code with Claude Extension

Add to your VS Code settings.json (Cmd/Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"):

{
  "claude.mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/absolute/path/to/claude-memory-mcp/dist/server.js"]
    }
  }
}

Claude Desktop (Mac)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/absolute/path/to/claude-memory-mcp/dist/server.js"]
    }
  }
}

Claude Desktop (Windows)

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["C:\\path\\to\\claude-memory-mcp\\dist\\server.js"]
    }
  }
}

3. Restart Your Client

Restart VS Code or Claude Desktop. Claude now has memory tools available!

---

Available Tools

Tool	Description
memory_save	Save something to remember
memory_search	Search past memories (full-text)
memory_get	Get full details by memory IDs
memory_timeline	See context around a memory
memory_list_sessions	List recent sessions
memory_recall_session	Get all memories from a session
memory_context	Get relevant context for current task
memory_checkpoint	Save state and sync to CLAUDE.md
memory_stats	View memory statistics
memory_delete	Delete a memory

---

Memory Types

When saving memories, use these types for better organization:

Type	Use For	Example
discovery	Key insights	"The API requires OAuth2 refresh tokens"
decision	Choices made	"Using PostgreSQL over MongoDB because..."
bug	Issues and fixes	"Fixed race condition by adding mutex"
todo	Tasks for later	"Need to add rate limiting"
context	Project setup	"This is a Next.js 14 app with App Router"
research	Research findings	"Benchmarks show Redis is 3x faster"
checkpoint	Session state	Auto-generated on checkpoint
note	General notes	Anything else

---

Usage Examples

Saving Memories

You: "Remember that the API rate limit is 100 requests per minute"

Claude: [uses memory_save]
✅ Saved memory #1
Type: discovery
Tags: api, rate-limit

Searching

You: "What did we figure out about authentication?"

Claude: [uses memory_search with query="authentication"]
Found 3 memories:

#12 [bug] 2024-01-15
Fixed auth token not refreshing - needed to add...

#8 [decision] 2024-01-14  
Using JWT with refresh tokens because...

#5 [discovery] 2024-01-13
Auth service requires specific headers...

Getting Full Context

You: "Show me the full details of memory #12"

Claude: [uses memory_get with ids=[12]]
## Memory #12
**Type:** bug
**Date:** 2024-01-15
**Tags:** auth, token, refresh

The authentication token wasn't refreshing properly...
[full content shown]

Session Recall

You: "What did we work on yesterday?"

Claude: [uses memory_list_sessions with days=1]
Recent sessions:

**a1b2c3d4** | 2024-01-15 | 12 memories | my-project
Fixed authentication bugs and added rate limiting

**e5f6g7h8** | 2024-01-15 | 8 memories | my-project
Set up project structure and database

Checkpoint & Sync

You: "Let's checkpoint this session"

Claude: [uses memory_checkpoint]
✅ Checkpoint saved (#45)
📝 Synced to ./CLAUDE.md

---

CLAUDE.md Integration

The server can sync memories to a CLAUDE.md file in your project. This file:

1. Persists even without the MCP server
2. Gets loaded by Claude automatically (in Claude Code)
3. Contains your project rules + auto-updated memory

Example CLAUDE.md

# CLAUDE.md

## Project Overview
E-commerce API built with Node.js and PostgreSQL.

## Rules
- Always run tests before committing
- Use TypeScript strict mode
- Follow REST conventions

## 🧠 Memory (Auto-Updated)

<!-- MEMORY_SYNC_START -->
_Last synced: 2024-01-15T10:30:00Z_

### Recent Sessions
- **2024-01-15**: Fixed auth bugs, added rate limiting (12 memories)
- **2024-01-14**: Database schema design (8 memories)

### Key Discoveries
- API rate limit is 100 req/min
- Auth service requires X-API-Version header

### Decisions Made
- Using PostgreSQL for ACID compliance
- JWT with refresh tokens for auth
<!-- MEMORY_SYNC_END -->

---

Configuration

Environment variables:

Variable	Default	Description
MEMORY_DIR	~/.claude-memory	Where to store the database
MEMORY_DB	memory.db	Database filename
MEMORY_PROJECT	Auto-detected	Current project name
MEMORY_MAX_RESULTS	20	Default search limit
MEMORY_LOG_LEVEL	info	Logging level

---

Data Storage

All data is stored locally in ~/.claude-memory/:

~/.claude-memory/
├── memory.db          # SQLite database with FTS5
└── memory.db-wal      # Write-ahead log (auto-managed)

---

How It Works

┌─────────────────────────────────────┐
│  Claude (VS Code / Desktop / CLI)   │
│                                     │
│  "Remember the API rate limit"      │
└─────────────────┬───────────────────┘
                  │
                  │ MCP Protocol (stdio)
                  │
                  ▼
┌─────────────────────────────────────┐
│  claude-memory-mcp Server           │
│  ├── memory_save                    │
│  ├── memory_search                  │
│  ├── memory_get                     │
│  └── memory_checkpoint              │
│                                     │
│  SQLite + FTS5 (full-text search)   │
└─────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│  ~/.claude-memory/memory.db         │
└─────────────────────────────────────┘

---

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode (rebuild on changes)
npm run dev

# Clean build artifacts
npm run clean

---

Troubleshooting

Server not connecting

1. Check the path in your config is absolute
2. Ensure Node.js 18+ is installed: node --version
3. Run npm run build to compile TypeScript
4. Try running manually: node dist/server.js

Search not finding results

1. Check spelling in search query
2. Try broader search terms
3. Use memory_stats to verify data exists

CLAUDE.md not syncing

1. Check write permissions on project directory
2. Run memory_checkpoint explicitly
3. Check for error messages in response

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

---

License

MIT — Use it however you want.

---

Credits

Inspired by:

• claude-mem — Claude Code plugin for persistent memory
• mem0 — Memory layer for LLMs

Built for the Claude community. 🧠