# Memory Mcp

> A scenario + entity memory MCP service that provides persistent memory capabilities for Claude Code.

- **Type:** MCP server
- **Install:** `agentstack add mcp-chenxiaofie-memory-mcp`
- **Verified:** Pending review
- **Seller:** [chenxiaofie](https://agentstack.voostack.com/s/chenxiaofie)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [chenxiaofie](https://github.com/chenxiaofie)
- **Source:** https://github.com/chenxiaofie/memory-mcp

## Install

```sh
agentstack add mcp-chenxiaofie-memory-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Memory MCP Service

[](https://pypi.org/project/chenxiaofie-memory-mcp/)
[](https://pypi.org/project/chenxiaofie-memory-mcp/)
[](https://opensource.org/licenses/MIT)

[English](README.md) | [中文](README_zh.md)

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.

## Quick Start

### Prerequisites

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python package runner):

```bash
# 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):

```bash
uvx --from chenxiaofie-memory-mcp memory-mcp-init
```

### 2. Add MCP Server to Claude Code

```bash
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`:

```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

```bash
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

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

```bash
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:

```bash
# 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](https://github.com/chenxiaofie) · feifeichen1999@gmail.com

本项目由**陈佳俊**（GitHub: [chenxiaofie](https://github.com/chenxiaofie)）开发并维护。

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [chenxiaofie](https://github.com/chenxiaofie)
- **Source:** [chenxiaofie/memory-mcp](https://github.com/chenxiaofie/memory-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-chenxiaofie-memory-mcp
- Seller: https://agentstack.voostack.com/s/chenxiaofie
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.