English | [简体中文](README.zh-CN.md)
# Memory MCP
An MCP server that provides project memory management for Claude Code.
## Quick Start
### Prerequisites
- Python >= 3.10
- [uv](https://github.com/astral-sh/uv) package manager
- Anthropic API Key (get it from [Anthropic Console](https://console.anthropic.com/))
### Option 1: Install via CLI (Recommended)
**Install directly from GitHub (no download required):**
```bash
# Add to current project (local scope)
claude mcp add memory \
--env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
-- uvx --from git+https://github.com/JerryZhongJ/memory-mcp.git memory-mcp --project $(pwd)
```
### Option 2: Local Development Installation
If you need to modify the source code or contribute to development:
```bash
# 1. Clone the repository
git clone https://github.com/JerryZhongJ/memory-mcp.git
cd memory-mcp
# 2. Install dependencies
uv sync
# 3. Add to Claude Code
claude mcp add memory \
--env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
-- uv --directory /path/to/memory-mcp run memory-mcp --project $(pwd)
```
### Verify Installation
After configuration, Claude Code will automatically load the server. You can verify with:
```bash
# List all configured MCP servers
claude mcp list
# Use /mcp command in Claude Code to check server status
```
### Manage Server
```bash
# Remove server
claude mcp remove memory
# View server details
claude mcp get memory
```
## How It Works
- Memories are stored as Markdown files in the project's `.memories` directory
- Uses intelligent keyword matching and retrieval
- LLM automatically decides whether to create new memories or update existing ones
- Automatically validates content size and relevance
- Frontend-backend separation architecture with automatic backend lifecycle management
## Configuring CLAUDE.md
To help Claude better use this MCP service, it's recommended to create a `.claude/CLAUDE.md` file in your project with the following usage rules:
````markdown
# Project Memory Management Rules
## ⚠️ Mandatory Rules (Must Be Strictly Followed)
### 1. Query Memory Before Starting Tasks
**Every time you receive a user question, the first step must be to use `recall_memory_tool` to query relevant information.**
Do not rely on judgment to decide whether to query. Any question may be related to existing memories.
### 2. Save New Information Immediately Upon Discovery
**Whenever you obtain valuable new information through investigation, you must immediately use `memorize_memory_tool` to save it.**
Save the information as soon as you discover it, don't wait until after answering the user's question.
**Standard Workflow**:
```
User Question → Query Memory → Investigate Code/Docs → Discover New Info → Save Immediately → Answer User
```
**Important**: Skipping these steps leads to duplicate work, inconsistent answers, and knowledge loss.
````
## License
MIT
