Content
# memory-mcp 🧠
> **Persistent memory for AI agents — never re-explain your project again**
[](https://www.npmjs.com/package/memory-mcp)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
## The Problem
AI agents like Claude, Cursor, and Cline start every session with a blank slate. They forget your tech stack, coding preferences, project conventions, and everything you explained yesterday. You end up repeating yourself — again and again.
**memory-mcp** solves this by giving your AI agent persistent, searchable memory via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Save once, recall forever.
## Installation
```bash
npm install -g memory-mcp
```
Or run without installing globally:
```bash
npx memory-mcp
```
Memories are stored locally in `~/.memory-mcp/memories.db` (SQLite).
## Usage
### Claude Desktop
Add to your Claude Desktop config:
| OS | Config path |
|----|-------------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux (incl. Kali) | `~/.config/Claude/claude_desktop_config.json` |
```json
{
"mcpServers": {
"memory": {
"command": "memory-mcp"
}
}
}
```
### Cursor
Add to your Cursor MCP settings (`.cursor/mcp.json` or global settings):
```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["memory-mcp"]
}
}
}
```
### Cline
Add to your Cline MCP configuration:
```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["memory-mcp"]
}
}
}
```
Restart your editor or Claude Desktop after updating the config.
## Available Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| `remember` | Save a piece of information to memory | `key` (string), `value` (string), `tags` (optional string) |
| `recall` | Search and retrieve memories by keyword | `query` (string) |
| `forget` | Delete a memory by its key | `key` (string) |
| `list_memories` | List all saved memories | _(none)_ |
## Example Conversation
**You:** Remember that this project uses Next.js 14 with TypeScript and Tailwind CSS.
**Agent** _(calls `remember`)_:
```json
{
"key": "project-stack",
"value": "Next.js 14, TypeScript, Tailwind CSS",
"tags": "stack,frontend"
}
```
→ `Memory saved successfully. Key: project-stack`
---
**You:** What stack are we using?
**Agent** _(calls `recall`)_:
```json
{ "query": "stack" }
```
→ Found 1 memory:
```
Key: project-stack
Value: Next.js 14, TypeScript, Tailwind CSS
Tags: stack,frontend
Updated: 2026-06-26 10:30:00
```
---
**You:** Show me everything you've remembered.
**Agent** _(calls `list_memories`)_:
```
2 memories stored:
Key | Value | Tags | Updated
---------------------------------------------------------------------------
project-stack | Next.js 14, TypeScript, Tailwind.. | stack,frontend| 2026-06-26 10:30:00
user-pref | Prefer functional components | react,style | 2026-06-26 09:15:00
```
---
**You:** Forget the user preference.
**Agent** _(calls `forget`)_:
```json
{ "key": "user-pref" }
```
→ `Memory deleted: user-pref`
## Development
```bash
git clone <repo-url>
cd memory-mcp
npm install
npm run build
npm start
```
For development with hot reload:
```bash
npm run dev
```
## How It Works
- **Storage:** SQLite database at `~/.memory-mcp/memories.db`
- **Transport:** stdio (standard MCP transport for local tools)
- **Upsert:** Saving with an existing key updates the value instead of creating a duplicate
- **Search:** `recall` matches against both keys and values
## License
MIT
