# 🧠 Claude Memory MCP

A lightweight **Model Context Protocol (MCP) server** that gives Claude Desktop persistent memory across conversations. It stores, summarizes, and retrieves conversation history so Claude always remembers your context.

---

## ✨ Features

| Feature | Description |
|---|---|
| **Persistent Memory** | Saves every conversation turn to a local `memory.json` file |
| **Auto-Summarization** | Automatically compresses history after 10 turns to keep context lean |
| **Fast Context Loading** | Returns summary + last 3 turns on demand — no bloat |
| **One-command Setup** | Powered by `uv` — no virtualenv juggling needed |
| **Zero Latency** | Runs locally over stdio — no network calls |

---

## 🛠️ Tools Exposed

| Tool | Description |
|---|---|
| `get_context` | Load compressed memory (summary + last 3 turns). Call at the **start** of every conversation. |
| `save_turn` | Save one conversation turn. Call **after** every AI response. |
| `clear_memory` | Wipe all stored memory and start fresh. |

---

## 🚀 Quick Start

### Prerequisites
- Python 3.13+
- [`uv`](https://docs.astral.sh/uv/) installed

### 1. Clone & Install

```bash
git clone https://github.com/adeeljames/claude-memory-mcp.git
cd claude-memory-mcp
uv sync
```

### 2. Run the MCP Server (for testing)

```bash
uv run python server.py
```

### 3. Add to Claude Desktop

Open your Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the following under `mcpServers`:

```json
{
  "mcpServers": {
    "memory-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/claude-mcp-optimize",
        "python",
        "server.py"
      ]
    }
  }
}
```

> Replace `/absolute/path/to/claude-mcp-optimize` with the actual path on your machine.

Restart Claude Desktop — the `memory-mcp` server will appear in your tools list.

---

## 📁 Project Structure

```
claude-memory-mcp/
├── server.py           # MCP server — all tools defined here
├── memory.json         # Runtime memory file (auto-created, gitignored)
├── pyproject.toml      # uv project config & dependencies
├── uv.lock             # Locked dependency graph
└── README.md           # You are here
```

---

## ⚙️ How It Works

```
Claude Desktop ──stdio──► server.py ──► memory.json
                                          │
                         ┌────────────────┘
                         │
                    get_context()     → returns summary + last 3 turns
                    save_turn()       → appends to history, triggers summary at 10 turns
                    clear_memory()    → resets everything
```

---

## 🔧 Dependencies

| Package | Purpose |
|---|---|
| `mcp>=1.26.0` | Model Context Protocol SDK |

All dependencies are managed by `uv` and pinned in `uv.lock`.

---

## 📄 License

MIT — free to use, modify, and share.

---

Made with love by **[@muhammadadeelai](https://github.com/adeeljames)**