# 🧠 claude-memory-mcp

> Give Claude (and any MCP client) a **persistent long-term memory**. 100% local, no API key, no cloud.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-compatible-6E56CF.svg)](https://modelcontextprotocol.io)
[![Node](https://img.shields.io/badge/node-%3E%3D18-3C873A.svg)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://www.typescriptlang.org)

LLMs forget everything the moment a conversation ends. `claude-memory-mcp` is a tiny
[Model Context Protocol](https://modelcontextprotocol.io) server that gives your assistant
a durable memory it can write to and search across sessions — so you stop re-explaining
your preferences, your stack, and your decisions every single time.

Everything runs **on your machine**. Memories live in a local SQLite file, and semantic
search uses a local embedding model (`all-MiniLM-L6-v2`) that runs in-process. **No API key.
No data leaves your computer.**

---

## ✨ Features

- **Persistent memory** across sessions, backed by a single SQLite file you own.
- **Semantic search** — recall by meaning, not just keywords, via local embeddings.
- **Zero API keys / fully offline** after the first model download.
- **Works with any MCP client** — Claude Desktop, Claude Code, Cursor, and more.
- **Four simple tools**: `save_memory`, `search_memory`, `list_memories`, `delete_memory`.
- **Tiny & hackable** — a few hundred lines of TypeScript.

## 🚀 Quick start

### Claude Desktop

Add this to your `claude_desktop_config.json`
(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,
Windows: `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "claude-memory-mcp"],
      "env": {
        "MEMORY_DB_PATH": "~/.claude-memory/memories.db"
      }
    }
  }
}
```

Restart Claude Desktop. You'll see the memory tools appear in the tools menu.

### Claude Code

```bash
claude mcp add memory -- npx -y claude-memory-mcp
```

### From source

```bash
git clone https://github.com/<you>/claude-memory-mcp.git
cd claude-memory-mcp
npm install
npm run build
node dist/index.js   # speaks MCP over stdio
```

## 🛠️ Tools

| Tool | Description |
|------|-------------|
| `save_memory(content, tags?)` | Store a durable fact, preference, or decision. |
| `search_memory(query, limit?, min_score?)` | Semantic search over everything you've saved. |
| `list_memories(limit?, tag?)` | Browse recent memories, optionally by tag. |
| `delete_memory(id)` | Remove a memory by id. |

### Example prompts

- "Remember that I prefer TypeScript with 2-space indentation." → `save_memory`
- "What do you know about my coding preferences?" → `search_memory`
- "List everything tagged `project-x`." → `list_memories`

## ⚙️ Configuration

| Env var | Default | Description |
|---------|---------|-------------|
| `MEMORY_DB_PATH` | `~/.claude-memory/memories.db` | Where the SQLite database is stored. |
| `MEMORY_EMBED_MODEL` | `Xenova/all-MiniLM-L6-v2` | Local embedding model (any `@xenova/transformers` feature-extraction model). |

## 🧩 How it works

1. `save_memory` embeds the text with a local MiniLM model and stores the text, tags, and
   vector in SQLite.
2. `search_memory` embeds your query and ranks stored memories by cosine similarity — all
   in-process, no network calls.
3. The database is a plain SQLite file, so it's easy to back up, inspect, or sync yourself.

The first run downloads the embedding model (~25 MB) and caches it locally; every run after
that is fully offline.

## 🔒 Privacy

Your memories never leave your machine. There is no telemetry and no external API. Delete
the database file to wipe everything.

## 🤝 Contributing

Issues and PRs welcome! This project is intentionally small — good first issues include
new storage backends, memory expiry/TTL, and export/import commands.

## 📄 License

MIT — see [LICENSE](./LICENSE).