PluginBench
MCP Server
Maintained
MIT

io.github.chenxiaofie/memory-mcp MCP Server

io.github.chenxiaofie/memory-mcp

Persistent memory for Claude Code—automatically saves conversations and recalls relevant context across sessions.

RepositoryRegistry
How to choose

What this kind of tool is for

  • Create, search, or update items in a notes, docs, or tasks service from your agent.
  • Turn a meeting transcript or a long document into a structured summary.
  • Keep a daily log or standup digest without leaving the terminal.

How to compare servers like this

Service scope:
Confirm the tool covers the exact service and surfaces (pages, tasks, calendars) you need.
Auth model:
See whether it uses an API token you control and what permissions that token grants.
Read vs write:
Start with read-only workflows; give write access only after the first results look right.
Maintenance signal:
For anything tied to a third-party API, prefer tools that track that API's changes.

This page carries your copy-paste config: pick your MCP client in the install section on this page and use the copy button.

What is the io.github.chenxiaofie/memory-mcp MCP server?

The Memory MCP Service is a persistent memory system for Claude Code that automatically saves conversation context and retrieves relevant history across sessions. It uses semantic search and entity extraction to maintain project-level and user-level knowledge, so Claude always has the background it needs for informed decisions.

This MCP server adds long-term memory to Claude Code by automatically capturing conversations, decisions, and preferences. It stores episodes (conversation sessions) and entities (key knowledge like decisions, architecture, preferences) in a vector database, then injects relevant past context into new sessions via semantic search. Useful for multi-session projects where Claude needs continuity and context.

How to install io.github.chenxiaofie/memory-mcp

Copy-paste configuration for popular MCP clients.

transport: stdio
Config generated by PluginBench — verify against the source before use.
Environment / auth
  • CLAUDE_PROJECT_ROOT

    项目根目录路径

~/Library/Application Support/Claude/claude_desktop_config.json
JSON config
{
  "mcpServers": {
    "memory-mcp": {
      "command": "uvx",
      "args": [
        "chenxiaofie-memory-mcp"
      ],
      "env": {
        "CLAUDE_PROJECT_ROOT": "<YOUR_CLAUDE_PROJECT_ROOT>"
      }
    }
  }
}

Tools & capabilities

Tools this server exposes to the agent.

  • memory_start_episode — Start a new episode for a conversation session
  • memory_close_episode — Close and archive the current episode
  • memory_get_current_episode — Get the currently active episode
  • memory_add_entity — Add a knowledge entity (Decision, Architecture, File, Preference, Concept, or Habit)
  • memory_confirm_entity — Confirm a detected entity candidate
  • memory_reject_candidate — Reject a false entity detection
  • memory_deprecate_entity — Mark an entity as outdated
  • memory_get_pending — List pending entity candidates for review
  • memory_recall — Semantic search across episodes and entities
  • memory_search_by_type — Search entities by type
  • memory_get_episode_detail — Get full details of a specific episode
  • 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

Use cases

  • Maintain project context across multiple Claude Code sessions without manual recap
  • Automatically recall past decisions and architecture choices when working on related tasks
  • Track personal preferences and work habits that apply across different projects
  • Search conversation history semantically to find relevant past discussions and solutions
  • Build a knowledge base of technical decisions and entity relationships for long-running projects

io.github.chenxiaofie/memory-mcp MCP server FAQ

What is the Memory MCP Service?

It's an MCP server that gives Claude Code persistent memory by automatically saving conversations and retrieving relevant context from past sessions using semantic search.

Is it free?

Yes, it's open-source under the MIT License and available on PyPI.

How do I install it in Claude Code?

Run `claude mcp add memory-mcp -s user -- uvx --from chenxiaofie-memory-mcp memory-mcp` after installing the vector model with `uvx --from chenxiaofie-memory-mcp memory-mcp-init`.

Do I need to configure anything?

Optionally add hooks to `~/.claude/settings.json` for fully automatic saving; without hooks you can call memory tools manually.

What Python versions are supported?

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

Where is memory stored?

User-level memory in `~/.claude-memory/` (shared across projects) and project-level memory in `{project-root}/.claude/memory/` (isolated per project).

README (reference)

Source of truth, from the repository.

Memory MCP Service

PyPI version Python License: MIT

<!-- mcp-name: io.github.chenxiaofie/memory-mcp -->

English | 中文

A persistent memory MCP service for Claude Code. Automatically saves conversations and retrieves relevant history across sessions.

What it does: Every time you chat with Claude Code, your conversation context (decisions, preferences, key discussions) is saved and automatically recalled in future sessions — so Claude always has the background it needs. Memory recall demo - retrieving past session history

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.

How It Works

Session Start ──► Create Episode ──► Monitor Process (background)
                                          │
User Message  ──► Save Message ──► Recall Related Memories ──► Inject Context
                                          │
Claude Reply  ──► Save Response           │
                                          │
Session End   ──► Close Signal ──► Archive Episode + Generate Summary
  • 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

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")

Hooks Reference

HookWhat it doesTiming
SessionStartCreates a new episode~50ms
UserPromptSubmitSaves user message + retrieves related memories~1-2s
StopSaves assistant response~1s
SessionEndSignals episode closure~50ms

Tools Reference

ToolDescription
memory_start_episodeStart a new episode
memory_close_episodeClose and archive current episode
memory_get_current_episodeGet current active episode
memory_add_entityAdd a knowledge entity
memory_confirm_entityConfirm a detected entity candidate
memory_reject_candidateReject a false detection
memory_deprecate_entityMark an entity as outdated
memory_get_pendingList pending entity candidates
memory_recallSemantic search across episodes and entities
memory_search_by_typeSearch entities by type
memory_get_episode_detailGet full episode details
memory_list_episodesList all episodes chronologically
memory_statsGet system statistics
memory_encoder_statusCheck vector encoder status
memory_cache_messageManually cache a message
memory_clear_cacheClear message cache
memory_cleanup_messagesClean up old cached messages

Entity Types

TypeLevelDescription
DecisionProjectTechnical decisions for this project
ArchitectureProjectArchitecture designs
FileProjectImportant file descriptions
PreferenceUserPersonal preferences (shared across projects)
ConceptUserGeneral concepts
HabitUserWork habits

Storage Locations

  • User-level: ~/.claude-memory/
  • Project-level: {project-root}/.claude/memory/
<details> <summary>Alternative: Install from source</summary>

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
</details>

Author

陈佳俊 (Jiajun Chen) — front-end engineer based in Hangzhou, China. GitHub @chenxiaofie · feifeichen1999@gmail.com

本项目由陈佳俊(GitHub: chenxiaofie)开发并维护。

License

MIT License - see LICENSE file for details.

Related MCP servers

Search and book luxury villa rentals across Europe with real-time availability and pricing.

View repository →

Home appliance MCP: CPSC recall lookup, lifespan, maintenance, repair-or-replace, energy cost.

0
JavaScript
MIT
View repository →

Debt payoff calculator: snowball vs avalanche, minimum payment trap, extra-payment impact.

0
JavaScript
MIT
View repository →

Read accesso mobile ticket links: orders, admissions, barcodes and Google Wallet passes.

0
TypeScript
MIT
View repository →

AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.

0
JavaScript
View repository →

Recommend and inspect AI SaaS apps from the TrueAI catalog (1,600+ apps) by need, name or URL.

0
Python
MIT
View repository →