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)

• 🖼️ Image Memory: Optional image embeddings for visual similarity search

Long-term Memory

• 🎯 Trigger Conditions: JavaScript code execution for flexible memory activation

• 🔒 Sandboxed Execution: Using Node.js built-in vm module for secure JS code evaluation

• 🎰 Random Recall: Serendipitous memory activation for context enrichment

• 📝 Context Tracking: Records creation and update contexts

• 🖼️ Multimodal Support: Images, audio, and custom embeddings

Data Optimization

• 📉 Space Saving: 30-40% reduction in storage size

• 🔄 Auto Deduplication: Removes duplicate keywords and images

• ⏱️ Timestamp Normalization: Unified timestamp format (ISO 8601)

• 🗜️ Smart Compression: Eliminates redundant attachments field

Performance & Reliability (NEW!)

• ⚡ Query Caching: 30-50% faster searches with intelligent result caching

• ⏱️ Timeout Protection: Prevents long-running operations from blocking the server

• 🚦 Rate Limiting: Protects against API abuse (100 requests/minute per conversation)

• 🛡️ Input Validation: Comprehensive sanitization and validation of all inputs

• 📝 Structured Logging: JSON-formatted logs for easy parsing and monitoring

• 📊 Performance Metrics: Real-time metrics collection (latency, error rates, cache hits)

• 💚 Health Monitoring: Built-in health checks for proactive issue detection

• 🔍 Audit Logging: Complete audit trail of all operations for compliance

• 🔄 Graceful Shutdown: Ensures all pending writes complete before shutdown

New Features (NEW!)

• 💾 Backup & Restore: Export and import entire memory databases

  • backup_memories: Create timestamped backups with metadata

  • restore_memories: Restore from backup with merge or overwrite modes

  • list_backups: Browse available backup files

  • delete_backup: Clean up old backups

• 🔎 Advanced Search: Powerful search with flexible filtering

  • search_memories: Search with keywords, date ranges, score filters

  • analyze_memory_patterns: Statistical analysis and insights

  • Support for sorting by relevance, score, or timestamp

  • Search across short-term, long-term, or both memory types

• 📈 System Monitoring: Real-time server monitoring tools

  • health_check: Get server health status and diagnostics

  • get_metrics: View performance metrics (P50/P95/P99 latency, error rates)

  • get_cache_stats: Monitor query cache hit rates

Installation

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

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

With Cursor or other MCP clients

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

MCP Features

This server implements the full Model Context Protocol specification with:

• Tools: 13 tools for memory management

• Resources: 4 resources for system inspection

• Prompts: 4 prompt templates for common memory tasks

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:

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

• conversation_id (string, optional): Conversation ID to store the memory under (defaults to "default")

• createdContext (string, optional): Context description

• recentMessages (array, optional): Auto-generate context from messages

Trigger Examples:

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

• conversation_id (string, optional): Conversation ID that owns the memory

• updatedContext (string, optional): Update context

delete_long_term_memory

Delete a long-term memory by name.

Parameters:

• name (string): Memory name to delete

• conversation_id (string, optional): Conversation ID that owns the memory

list_long_term_memories

List all long-term memories with basic info.

Parameters:

• conversation_id (string, optional): Conversation ID to inspect (defaults to "default")

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.

Parameters:

• name (string): Memory name to inspect

• conversation_id (string, optional): Conversation ID that owns the memory

Available Resources

MCP resources allow AI to inspect the memory system state:

memory://stats/overview

System-wide overview and health status.

Returns:

• Total conversation count

• System health status

• Available features

memory://conversations/list

List all conversations with memory statistics.

Returns:

• Conversation IDs

• Short-term memory counts

• Long-term memory counts

memory://stats/conversation/{id}

Detailed statistics for a specific conversation.

Parameters:

• {id}: Conversation ID to inspect

Returns:

• Short-term memory: total, scores, age ranges

• Long-term memory: total, update counts, timestamps

memory://guide/best-practices

Comprehensive guide on using the memory system effectively.

Returns:

• Best practices for short-term and long-term memory

• Trigger condition examples

• Multimodal support guidelines

• Common usage patterns

Available Prompts

MCP prompts provide guided workflows for common tasks:

remember-user-info

Store important user information in long-term memory.

Arguments:

• info_type (required): Type of information (preference, birthday, fact, etc.)

• information (required): The information to remember

• conversation_id (optional): Target conversation ID

Guides AI to:

1. Create appropriate memory name

2. Generate relevant trigger conditions

3. Use add_long_term_memory tool

recall-context

Search for relevant memories based on current conversation.

Arguments:

• current_topic (required): Current topic or question

• conversation_id (optional): Conversation to search

Guides AI to:

1. Search short-term memories for recent context

2. Search long-term memories for permanent facts

3. Consider keyword relevance and time decay

create-reminder

Create a conditional reminder that activates based on context or date.

Arguments:

• reminder_content (required): What to remind about

• trigger_condition (required): When to trigger (keywords or date)

• conversation_id (optional): Target conversation

Guides AI to:

1. Convert natural language conditions to JavaScript

2. Create date-based or keyword-based triggers

3. Use add_long_term_memory with proper trigger

analyze-conversation

Analyze conversation history and suggest what should be remembered.

Arguments:

• conversation_id (required): Conversation to analyze

Guides AI to:

1. Get current memory statistics

2. Identify important information types

3. Categorize for short-term vs long-term storage

4. Create appropriate memory entries

Architecture

Memory Algorithms

Short-term Memory Relevance

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

Security

• Sandboxed Execution: Long-term memory triggers run in Node.js built-in vm module 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

• Secure Context: Only safe built-in objects are exposed to trigger code

Note: The built-in vm module provides good isolation 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

• Manager instances cached with LRU (max 100 conversations, 30-min idle timeout)

• Chinese text processing optimized (may be less optimal for other languages)

Performance Optimizations

• Write Caching: Delayed writes with 1-second batching to reduce disk I/O

• Directory Caching: Directory existence checks are cached to avoid repeated file system calls

• LRU Manager Cache: Automatic cleanup of inactive conversation managers prevents memory leaks

• Retry Logic: File operations automatically retry with exponential backoff on transient errors

• Graceful Shutdown: Pending writes are flushed and resources cleaned up on shutdown signals

• Data Deduplication: Automatic removal of duplicate images and keywords (30-40% space savings)

• Timestamp Normalization: Unified timestamp format eliminates redundancy

Image Memory Features

The server includes optional image memory capabilities:

• Image Modalities: Store images with memories using embeddings, tags, and descriptions

• Similarity Search: Find visually similar memories using cosine similarity on embeddings

• Auto Deduplication: Automatically detect and remove duplicate images (URL or content hash)

• Flexible Embeddings: Support for CLIP, ResNet, or custom image embeddings

• Base64 Support: Handle both URLs and data URI images

Example:

See docs/IMAGE_MEMORY.md for detailed guide.

Data Optimization

Built-in data optimization reduces storage by 30-40%:

• Timestamp Normalization: time_stamp/timeStamp/timestamp → timestamp (ISO 8601)

• Remove Redundancy: attachments field removed (use modalities only)

• Keyword Deduplication: Case-insensitive merge with max weight retention

• Image Deduplication: Remove duplicate images based on URI or content hash

All optimizations are applied automatically during storage. See docs/DATA_OPTIMIZATION.md for details.

Performance Benchmarks

Performance improvements from the latest enhancements:

Test Results

Run the comprehensive test suite:

Expected output: 36 tests pass covering:

• Query caching (4 tests)

• Timeout handling (3 tests)

• Rate limiting (5 tests)

• Input validation (8 tests)

• Structured logging (3 tests)

• Performance metrics (6 tests)

• Health checks (4 tests)

• Audit logging (3 tests)

Architecture

License

BSD-3-Clause license

Credits

Extracted and generalized from the GentianAphrodite project.