chenxiaofie-memory-mcp 0.2.0

情景+实体记忆 MCP 服务

Memory MCP Service

English | 中文

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

Features

• Episodes: Dialogue scenes divided by task/function
• Entities: Structured knowledge units (decisions, concepts, preferences, etc.)
• Dual-layer storage: User-level (cross-project) + Project-level (project isolated)
• Real-time cache: Messages are stored in real-time to prevent loss
• Semantic retrieval: Vector-based semantic search

Installation

Windows One-click Installation

Run install.bat file in the project root directory:

install.bat

Mac/Linux One-click Installation

chmod +x install.sh
./install.sh

The installation script will automatically create a Python 3.10 virtual environment (venv310) and install dependencies.

Configure Claude Code

Important

This package depends on chromadb which uses Pydantic V1, not compatible with Python 3.14+.

Required: Use local source code with venv310 virtual environment (Python 3.10).

Add MCP Server

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

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

Manual Configuration File

Edit ~/.claude/settings.json and add:

{
  "mcpServers": {
    "memory-mcp": {
      "command": "C:\\path\\to\\memory-mcp\\venv310\\Scripts\\python.exe",
      "args": ["-m", "src.server"],
      "cwd": "C:\\path\\to\\memory-mcp"
    }
  }
}

Configure Hooks (Optional)

Hooks enable automatic message saving. Once configured, conversations will be saved without manual memory tool calls.

Add the following hooks configuration to ~/.claude/settings.json:

pip install (recommended, works on all platforms):

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

Local source code installation (alternative)

Mac/Linux:

{
  "hooks": {
    "SessionStart": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "/path/to/venv310/bin/python",
        "args": ["/path/to/memory-mcp/session_start.py"]
      }]
    }],
    "UserPromptSubmit": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "/path/to/venv310/bin/python",
        "args": ["/path/to/memory-mcp/auto_save.py"]
      }]
    }],
    "Stop": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "/path/to/venv310/bin/python",
        "args": ["/path/to/memory-mcp/save_response.py"]
      }]
    }],
    "SessionEnd": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "/path/to/venv310/bin/python",
        "args": ["/path/to/memory-mcp/session_end.py"]
      }]
    }]
  }
}

Windows (requires cmd wrapper):

{
  "hooks": {
    "SessionStart": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "cmd",
        "args": ["/c", "C:\\path\\to\\memory-mcp\\venv310\\Scripts\\python.exe", "C:\\path\\to\\memory-mcp\\session_start.py"]
      }]
    }],
    "UserPromptSubmit": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "cmd",
        "args": ["/c", "C:\\path\\to\\memory-mcp\\venv310\\Scripts\\python.exe", "C:\\path\\to\\memory-mcp\\auto_save.py"]
      }]
    }],
    "Stop": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "cmd",
        "args": ["/c", "C:\\path\\to\\memory-mcp\\venv310\\Scripts\\python.exe", "C:\\path\\to\\memory-mcp\\save_response.py"]
      }]
    }],
    "SessionEnd": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "cmd",
        "args": ["/c", "C:\\path\\to\\memory-mcp\\venv310\\Scripts\\python.exe", "C:\\path\\to\\memory-mcp\\session_end.py"]
      }]
    }]
  }
}

Hooks Description:

Hook Name	Purpose	Weight
SessionStart	Create new episode (lightweight JSON ops, no chromadb)	~50ms
UserPromptSubmit	Save user messages + entity detection + memory retrieval	~1-2s
Stop	Save assistant responses	~1s
SessionEnd	Write close signal + remove project trust (no chromadb)	~50ms

Note: SessionStart and SessionEnd hooks are lightweight — they do not import MemoryManager/chromadb to avoid the heavy initialization cost (10-30s). Episode closing and archiving is handled by the background monitor process.

Verify Configuration

claude mcp list

Expected output should show memory-m-mcp: ... - ✓ Connected

Usage

Automatic Mode (With Hooks)

After configuring hooks, conversations are automatically saved without manual operation.

Manual Mode

Manually call memory tools:

# Start a new task
memory_start("Login Function Development", ["auth"])

# Record a decision
memory_add_entity("Decision", "Adopt JWT + Redis solution", "Consider distributed deployment")

# Retrieve history
memory_recall("Login scheme")

# Close task
memory_close_episode("Completed JWT login function development")

Tools List

• memory_start_episode: Start a new episode
• memory_close_episode: Close an episode
• memory_get_current_episode: Get current episode
• memory_add_entity: Add entity
• memory_confirm_entity: Confirm candidate entity
• memory_reject_candidate: Reject candidate
• memory_deprecate_entity: Deprecate entity
• memory_get_pending: Get pending entities
• memory_recall: Comprehensive retrieval
• memory_search_by_type: Search by type
• memory_get_episode_detail: Get episode detail
• memory_list_episodes: List all episodes by time
• memory_stats: Get statistics
• memory_encoder_status: Check encoder status
• memory_cache_message: Manually cache a message
• memory_clear_cache: Clear message cache
• memory_cleanup_messages: Clean up old messages

Entity Types

User-level (cross-project shared)

• Preference: User preferences
• Concept: General concepts
• Habit: Work habits

Project-level (project isolated)

• Decision: Project decisions
• Episode: Development episodes
• File: File descriptions
• Architecture: Architecture designs

Storage Locations

• User-level: ~/.claude-memory/ (Windows: %APPDATA%/claude-memory/)
• Project-level: {project-root}/.claude/memory/

License

MIT License - see LICENSE file for details.