Memory MCP

A persistent memory MCP service designed for Claude Code, which can automatically save conversation histories and intelligently retrieve relevant contexts in subsequent conversations, achieving memory continuity across sessions.

Knowledge management and memory Developer tools #Memory service #Conversation history #Intelligent retrieval #MCP tool .Python

rating : 2.5 points

downloads : 6.2K

update time : 2026-03-12

Open Site

What is the Memory MCP Service?

The Memory MCP Service is an intelligent memory system specifically designed for Claude Code. It acts like an assistant that never forgets, automatically recording every conversation you have with Claude and intelligently recalling relevant histories in future conversations. Whether you're developing a project, learning new knowledge, or making plans, it ensures that Claude always understands your background and preferences.

How to use the Memory MCP Service?

It's very simple to use: After installation, configure the automatic hook, and then all conversations will be automatically saved and retrieved. You can also manually call the memory tool to record specific information or search the history. The system supports two storage methods: user - level (shared across projects) and project - level (isolated).

Applicable scenarios

It is suitable for scenarios that require context continuity, such as long - term project development, continuous learning, and complex problem - solving. It is particularly suitable for users such as developers, researchers, and students who need to interact with AI assistants multiple times.

Main features

Automatically save conversations

By configuring hooks, the system can automatically save user messages and AI responses without manual operation.

Semantic search and retrieval

Based on vector embedding technology, it can understand the semantic meaning of queries and find the most relevant historical conversations.

Dual - layer storage architecture

User - level storage (sharing preferences and habits across projects) + Project - level storage (project - specific decisions and architectures).

Knowledge entity extraction

Automatically extract key entities (decisions, preferences, concepts, etc.) from conversations to form a structured knowledge base.

Conversation episode management

Each conversation session is recorded as an "episode", including an automatically generated summary and timestamp.

Claude Code hook integration

Deeply integrated with Claude Code's event system, supporting events such as SessionStart and UserPromptSubmit.

Advantages

🚀 Fully automated: No manual operation is required after configuration. Conversations are automatically saved and retrieved.

🧠 Intelligent association: Find the most relevant historical context based on semantic understanding.

📊 Structured storage: Convert conversations into searchable knowledge entities.

🔒 Privacy protection: All data is stored locally and not uploaded to the cloud.

⚡ Fast response: Retrieving relevant memories usually takes 1 - 2 seconds.

🔄 Continuous across sessions: Ensure context continuity for long - term projects.

Limitations

📦 Approximately 400MB of vector models need to be downloaded for the initial installation.

🐍 Requires Python 3.10 - 3.13 and does not support Python 3.14+.

💾 Local storage space increases with the growth of conversations.

🔧 Some technical knowledge is required for initial configuration.

🔄 Only supports Claude Code and does not support other AI assistants.

How to use

Install prerequisite tools

First, install uv (Python package manager), which is a prerequisite tool for running the Memory MCP Service.

Initialize the vector model

Download the necessary vector model files (about 400MB, only need to be downloaded once) when using it for the first time.

Add to Claude Code

Add the Memory MCP Service as an MCP server to Claude Code.

Configure automatic hooks (recommended)

Configure automatic hooks to achieve fully automated memory saving and retrieval. Edit the ~/.claude/settings.json file.

Verify the installation

Check if the Memory MCP Service is successfully connected.

Usage examples

Long - term project development

When developing a web application, each session can recall previous architectural decisions, technology selections, and implementation details.

Learning a new framework

When learning the React framework, the system will remember the concepts you have mastered and common problems you have encountered.

Personal preference recording

Record your code style preferences, such as using 2 - space indents, camelCase for function names, etc.

Frequently Asked Questions

Will the Memory MCP Service save my private data?

How long does the installation take?

How to clean up old memory data?

Which Python versions are supported?

Can it still be used if the hooks are not configured?

What is the accuracy of memory retrieval?

Related resources

GitHub repository

Source code and latest updates

PyPI package page

Python package release page

uv installation guide

Installation instructions for the Python package manager uv

Model Context Protocol documentation

Official documentation of the MCP protocol

Claude Code documentation

Claude Code usage guide

🚀 Memory MCP Service

A persistent memory MCP service for Claude Code. It automatically saves conversations and retrieves relevant history across sessions, providing Claude with the necessary background information for seamless interactions.

🚀 Quick Start

Prerequisites

Install uv (Python package runner):

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Mac/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Requires Python 3.10 - 3.13 (chromadb is not compatible with Python 3.14+).

1. Initialize (First Time Only)

Download the vector model (~400MB, one-time):

uvx --from chenxiaofie-memory-mcp memory-mcp-init

2. Add MCP Server to Claude Code

claude mcp add memory-mcp -s user -- uvx --from chenxiaofie-memory-mcp memory-mcp

3. Configure Hooks (Recommended)

Hooks enable fully automatic message saving. Without hooks, you need to manually call memory tools. Add the following to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [{
      "matcher": ".*",
      "hooks": [{ "type": "command", "command": "uvx --from chenxiaofie-memory-mcp memory-mcp-session-start" }]
    }],
    "UserPromptSubmit": [{
      "matcher": ".*",
      "hooks": [{ "type": "command", "command": "uvx --from chenxiaofie-memory-mcp memory-mcp-auto-save" }]
    }],
    "Stop": [{
      "matcher": ".*",
      "hooks": [{ "type": "command", "command": "uvx --from chenxiaofie-memory-mcp memory-mcp-save-response" }]
    }],
    "SessionEnd": [{
      "matcher": ".*",
      "hooks": [{ "type": "command", "command": "uvx --from chenxiaofie-memory-mcp memory-mcp-session-end" }]
    }]
  }
}

4. Verify

claude mcp list

You should see memory-mcp: ... - ✓ Connected.

That's it! Start a new Claude Code session and your conversations will be automatically saved and recalled.

✨ Features

Episodes: Each conversation session is an "episode" with auto-generated summaries.
Entities: Key knowledge extracted from conversations (decisions, preferences, concepts).
Dual-layer storage: User-level (shared across projects) + Project-level (isolated per project).
Semantic search: Vector-based retrieval finds relevant past context.

💻 Usage Examples

Automatic Mode (With Hooks)

Once hooks are configured, everything is automatic. Claude will see relevant history from past sessions as context.

Manual Mode

You can also call memory tools directly in Claude Code:

# Start a new episode
memory_start_episode("Login Feature Development", ["auth"])

# Record a decision
memory_add_entity("Decision", "Use JWT + Redis", "For distributed deployment")

# Search history
memory_recall("login implementation")

# Close episode
memory_close_episode("Completed JWT login feature")

📚 Documentation

Hooks Reference

Hook	What it does	Timing
SessionStart	Creates a new episode	~50ms
UserPromptSubmit	Saves user message + retrieves related memories	~1 - 2s
Stop	Saves assistant response	~1s
SessionEnd	Signals episode closure	~50ms

Tools Reference

Tool	Description
`memory_start_episode`	Start a new episode
`memory_close_episode`	Close and archive current episode
`memory_get_current_episode`	Get current active episode
`memory_add_entity`	Add a knowledge entity
`memory_confirm_entity`	Confirm a detected entity candidate
`memory_reject_candidate`	Reject a false detection
`memory_deprecate_entity`	Mark an entity as outdated
`memory_get_pending`	List pending entity candidates
`memory_recall`	Semantic search across episodes and entities
`memory_search_by_type`	Search entities by type
`memory_get_episode_detail`	Get full episode details
`memory_list_episodes`	List all episodes chronologically
`memory_stats`	Get system statistics
`memory_encoder_status`	Check vector encoder status
`memory_cache_message`	Manually cache a message
`memory_clear_cache`	Clear message cache
`memory_cleanup_messages`	Clean up old cached messages

Entity Types

Type	Level	Description
`Decision`	Project	Technical decisions for this project
`Architecture`	Project	Architecture designs
`File`	Project	Important file descriptions
`Preference`	User	Personal preferences (shared across projects)
`Concept`	User	General concepts
`Habit`	User	Work habits

Storage Locations

User-level: ~/.claude-memory/
Project-level: {project-root}/.claude/memory/

Alternative: Install from source

If you need to run from source (e.g., for development):

git clone https://github.com/chenxiaofie/memory-mcp.git
cd memory-mcp
# Windows:
install.bat
# Mac/Linux:
chmod +x install.sh && ./install.sh

Then configure MCP server with the venv Python:

# Windows:
claude mcp add memory-mcp -s user -- "C:\path\to\memory-mcp\venv310\Scripts\python.exe" -m memory_mcp.server

# Mac/Linux:
claude mcp add memory-mcp -s user -- /path/to/memory-mcp/venv310/bin/python -m memory_mcp.server