What can you do with this server?

The memory-mcp server provides a persistent memory service for Claude Code, enabling automatic saving, recall, and semantic search of conversation context, decisions, preferences, and knowledge entities across sessions. Episode Management * Start, close, and archive conversation sessions (episodes) with tags and auto-generated summaries * Get the currently active episode, list all historical episodes, or retrieve full details (messages + linked entities) of a specific episode Knowledge Entity Management * Add, confirm, reject, or deprecate knowledge entities of types: Decision, Preference, Concept, Habit, File, or Architecture * List pending auto-detected entity candidates awaiting review Memory Retrieval & Search * Semantic search across all stored episodes and entities using natural language queries * Filter entity searches by type (e.g., all Decisions or Preferences) Message Caching * Manually cache user or assistant messages (with automatic entity detection) * Clear the entire cache or clean up messages older than a specified number of days System & Status * Retrieve system statistics (episodes, entities, etc.) and check vector encoder status Automatic Context Management When configured with Claude Code hooks, it automatically saves messages, recalls relevant memories, and injects context into ongoing conversations. Dual-Layer Storage Supports both user-level (shared across projects) and project-level (isolated per project) memory storage.

How do I use memory-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@memory-mcp recall what we discussed about authentication" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

memory-mcp

by chenxiaofie

Overview Schema Source Related Servers Discussions Admin

Python

Local

Memory MCP Service

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.

Related MCP server: claude-memory-mcp

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

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/

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

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.

Available Tools

9 tools

memory_clear_cacheA

清空消息缓存日志（message_cache.jsonl）。警告：此操作不可逆！

Inputs: confirm (required).

memory_deprecate_entityC

废弃一个过时的实体

Inputs: entity_id (required), superseded_by.

memory_encoder_statusA

查询向量编码器状态。返回编码器是否已就绪，以及哪些操作当前可用。

Inputs: no named parameters.

memory_get_episode_detailA

获取情景详情（包含消息和关联实体）

Inputs: episode_id (required).

memory_get_pendingB

获取所有待确认的实体候选

Inputs: no named parameters.

memory_recallA

综合检索记忆（情景+实体）。【重要】当用户询问'我是谁'、身份信息、个人偏好、历史决策、之前讨论过的内容时，应主动调用此工具检索相关记忆，而不是凭空回答。

Inputs: query (required), top_k, include_deprecated.

memory_reject_candidateB

拒绝一个误判的实体候选

Inputs: candidate_id (required).

memory_search_by_typeC

按类型检索实体

Inputs: entity_type (required), query, top_k.

memory_statsC

获取记忆系统统计信息

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-09-09 18:25 across 9 tools

Disambiguation4/5

各工具目标基本清晰：检索类、候选管理类、系统维护类之间的边界比较明显。不过 memory_recall 与 memory_search_by_type 都是检索入口，存在轻微功能重叠，但描述足以区分综合检索与按类型检索。

Naming Consistency4/5

所有工具统一使用 memory_ 前缀且采用小写和下划线，整体命名风格一致。但 memory_stats 与 memory_encoder_status 是名词式命名，而大多数工具是动词加宾语形式，略有偏差。

Tool Count5/5

9 个工具覆盖检索、候选管理、系统状态和缓存管理，数量处于 3-15 的合理区间，没有冗余的重复工具，范围适中。

Completeness3/5

检索和状态查询较完整，但候选实体管理只有获取待确认和拒绝，缺少确认/接受候选实体的操作，形成流程断点。此外没有显式的实体新增或编辑工具，生命周期覆盖不完整。

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

MemoryRouterA
ai.memoryrouter
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Knowledge & Memory Search
101
https://mcp.memoryrouter.ai/mcp
mcp
ai.butlerbrain
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Knowledge & Memory RAG Systems Workplace & Productivity
2
https://api.butlerbrain.ai/mcp
Maximem SynapA
ai.maximem
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
AI & Machine Learning Knowledge & Memory
4248
https://synap-mcp.maximem.ai/mcp
Motecloud Memory
io.github.motecloud
Cloud-hosted MCP server for durable AI memory
Knowledge & Memory Cloud Platforms
2
https://motecloud.io/mcp

Related MCP Servers

MCP Memory Server
Knowledge & Memory RAG Systems
PlumyCat
A
license
Not graded
quality
D
maintenance
An MCP server that gives Claude persistent memory by storing conversation context, entities, and enabling semantic search across sessions.
Updated a year ago (2025-06-23 22:52 UTC)
34 npm
1
MIT
claude-memory-mcp
Knowledge & Memory Developer Tools
santicalderon
A
license
Not graded
quality
D
maintenance
An MCP server that gives Claude Code cross-session memory persisted to a plain .claude-memory.md file in your repo.
Updated 7 months ago (2026-04-10 14:30 UTC)
MIT
Cortex
Knowledge & Memory Developer Tools
ProductionLineHQ
A
license
Not graded
quality
D
maintenance
Persistent memory MCP server for Claude Code that captures and recalls project context across sessions, eliminating the need to re-explain architecture and decisions daily.
Updated 8 months ago (2026-03-24 00:51 UTC)
73 npm
1
MIT
claude-memory
Knowledge & Memory Search Code Analysis
NathanNorman
A
license
Not graded
quality
C
maintenance
A persistent memory MCP server for Claude Code that enables long-term recall across sessions via hybrid search, code intelligence, and tools for reading/writing memory.
Updated 2 months ago (2026-09-08 22:47 UTC)
20 npm
5
MIT

Memory MCP Service

Quick Start

Prerequisites

1. Initialize (First Time Only)

2. Add MCP Server to Claude Code

3. Configure Hooks (Recommended)

4. Verify

How It Works

Usage

Automatic Mode (With Hooks)

Manual Mode

Hooks Reference

Tools Reference

Entity Types

Storage Locations

Author

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

MCP Memory Server

claude-memory-mcp

Cortex

claude-memory