Memory MCP Server

Memory MCP Server

A Model Context Protocol (MCP) server providing dynamic short-term and long-term memory management with Chinese language support.

Overview

This MCP server implements a sophisticated memory system extracted from the GentianAphrodite project, offering:

• Short-term Memory: Keyword-based, time-decayed dynamic memory with relevance scoring
• Long-term Memory: Trigger-based permanent memories with JS code execution for flexible activation
• Chinese Language Support: Built-in jieba segmentation for optimal Chinese text processing
• Multiple Conversations: Isolated memory spaces per conversation ID

Features

Short-term Memory

• 🔍 Keyword Extraction: Uses TF-IDF with jieba for Chinese text
• ⏰ Time Decay: Exponential time decay model for memory relevance
• 📊 Relevance Scoring: Dynamic scoring based on keyword matching, time, and activation history
• 🎲 Smart Selection: Three-tier selection (top relevant, next relevant, random flashback)
• 🧹 Auto Cleanup: Automatic removal of old or irrelevant memories (configurable)

Long-term Memory

• 🎯 Trigger Conditions: JavaScript code execution for flexible memory activation
• 🔒 Sandboxed Execution: Using isolated-vm for secure JS code evaluation
• 🎰 Random Recall: Serendipitous memory activation for context enrichment
• 📝 Context Tracking: Records creation and update contexts

Installation

# Clone or download this directory
cd memory-mcp-server

# Install dependencies
npm install

# Make the server executable (Unix/Linux/Mac)
chmod +x src/index.js

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/absolute/path/to/memory-mcp-server/src/index.js"]
    }
  }
}

With Cursor or other MCP clients

Configure according to your client's MCP server setup instructions, pointing to src/index.js.

Available Tools

Short-term Memory Tools

add_short_term_memory

Add a new short-term memory from conversation messages.

Parameters:

• messages (array): Recent conversation messages with role and content
• conversation_id (string): Unique conversation identifier
• roleWeights (object, optional): Custom weights for different roles

Example:

{
  "messages": [
    {"role": "user", "content": "My birthday is July 17, 1990"},
    {"role": "assistant", "content": "I'll remember that!"}
  ],
  "conversation_id": "user_123",
  "roleWeights": {
    "user": 2.7,
    "assistant": 2.0,
    "system": 1.0
  }
}

search_short_term_memories

Search for relevant memories based on current context.

Parameters:

• recentMessages (array): Recent messages to search against
• conversation_id (string): Current conversation ID
• roleWeights (object, optional): Role weights

Returns: Top relevant, next relevant, and random flashback memories

delete_short_term_memories

Delete memories matching a pattern.

Parameters:

• pattern (string): Keyword or regex pattern (e.g., "/pattern/i")
• conversation_id (string): Conversation ID

get_memory_stats

Get statistics about short-term memories.

cleanup_memories

Manually trigger memory cleanup (removes old/low-relevance memories).

get_frequent_conversation

Get the most frequently mentioned conversation ID.

Long-term Memory Tools

add_long_term_memory

Add a permanent memory with a trigger condition.

Parameters:

• name (string): Unique memory name
• prompt (string): Memory content
• trigger (string): JavaScript code for activation condition
• createdContext (string, optional): Context description
• recentMessages (array, optional): Auto-generate context from messages

Trigger Examples:

// Activate when "birthday" is mentioned
"match_keys(context.messages, ['birthday', '生日'], 'any')"

// Activate on specific date or when mentioned
"match_keys(context.messages, ['anniversary'], 'any') || (new Date().getMonth() === 6 && new Date().getDate() === 17)"

// Multiple keywords required
"match_keys_all(context.messages, ['project', 'deadline'], 'user')"

Available in trigger context:

• context.messages: Recent message array
• context.conversation_id: Current conversation ID
• context.participants: Participant information
• match_keys(messages, keywords, scope, depth): Match any keyword
• match_keys_all(messages, keywords, scope, depth): Match all keywords
• Date, Math, RegExp, JSON: Safe built-in objects

update_long_term_memory

Update an existing long-term memory.

Parameters:

• name (string): Memory name to update
• trigger (string, optional): New trigger condition
• prompt (string, optional): New content
• updatedContext (string, optional): Update context

delete_long_term_memory

Delete a long-term memory by name.

list_long_term_memories

List all long-term memories with basic info.

search_long_term_memories

Search and activate memories based on current context.

Parameters:

• messages (array): Recent conversation messages
• conversation_id (string): Current conversation ID
• participants (object, optional): Participant info

Returns: Activated memories (triggered) and random memories

get_memory_context

Get creation and update context of a specific memory.

Architecture

memory-mcp-server/
├── src/
│   ├── index.js                 # MCP server entry point
│   ├── memory/
│   │   ├── short-term.js        # Short-term memory logic
│   │   ├── long-term.js         # Long-term memory logic
│   │   └── storage.js           # JSON file storage
│   ├── nlp/
│   │   ├── jieba.js             # Chinese segmentation
│   │   └── keywords.js          # Keyword matching
│   ├── triggers/
│   │   └── matcher.js           # JS code execution sandbox
│   └── tools/
│       ├── short-term-tools.js  # Short-term MCP tools
│       └── long-term-tools.js   # Long-term MCP tools
└── data/                        # Memory storage (auto-created)
    └── {conversation_id}/
        ├── short-term-memory.json
        └── long-term-memory.json

Memory Algorithms

Short-term Memory Relevance

relevance = keyword_match_score - time_penalty + memory_score

where:
  keyword_match_score = Σ(current_kw.weight + memory_kw.weight)
  time_penalty = 15 * (1 - e^(-time_diff * 2e-9))
  memory_score = accumulated score from past activations

Selection Strategy

1. Top Relevant (max 2): Highest relevance scores
2. Next Relevant (max 1): Next highest scores
3. Random Flashback (max 2): Weighted random from remaining memories

Filtering:

• Excludes same-conversation memories from last 20 minutes
• Excludes memories within 10 minutes of any selected memory
• Ensures diversity in recalled memories

Cleanup Policy

• Triggers every 24 hours
• Removes memories older than 1 year
• Removes low-relevance memories (score < -5)
• Always keeps at least 512 memories

Development

# Run in development mode with auto-reload
npm run dev

# Run normally
npm start

Security

• Sandboxed Execution: Long-term memory triggers run in vm2 sandbox with timeout protection
• No File System Access: Trigger code cannot access filesystem (sandboxed)
• No Network Access: Trigger code cannot make network requests
• Timeout Protection: 1-second execution timeout prevents infinite loops

Note: vm2 provides good security for most use cases. For maximum security in production environments, consider running the MCP server in a containerized environment with additional restrictions.

Limitations

• Memory storage is file-based (JSON), suitable for moderate usage
• Trigger execution has 1-second timeout
• Each isolated VM has 32MB memory limit
• Chinese text processing optimized (may be less optimal for other languages)

License

MIT

Credits

Extracted and generalized from the GentianAphrodite project.