memory-mcp-server

win10ogod/memory-mcp-server

3.2

If you are the rightful owner of memory-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

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

Tools
11
Resources
0
Prompts
0

Memory MCP Server

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

Memory Server MCP server

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

# 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.json Windows: %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.

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:

{
  "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
  • 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:

// 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
  • 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-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 with caching
│   │   └── modalities.js        # Multimodal attachment handling
│   ├── nlp/
│   │   ├── jieba.js             # Chinese segmentation
│   │   └── keywords.js          # Keyword matching
│   ├── triggers/
│   │   └── matcher.js           # JS code execution sandbox (Node.js vm)
│   ├── tools/
│   │   ├── short-term-tools.js  # Short-term MCP tools
│   │   └── long-term-tools.js   # Long-term MCP tools
│   ├── resources/
│   │   └── index.js             # MCP resources (stats, guides)
│   ├── prompts/
│   │   └── index.js             # MCP prompts (workflows)
│   └── utils/
│       ├── lru-cache.js         # LRU cache for managers
│       └── zod-to-json-schema.js
└── 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 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:

import { createImageModality } from './src/utils/image-processor.js';

const imageMemory = createImageModality({
  uri: 'https://example.com/photo.jpg',
  embedding: [0.1, 0.2, 0.3, ...],  // 512-d vector from CLIP/etc
  tags: ['vacation', 'beach'],
  description: 'Sunset at the beach'
});

// Use in memory creation
await addShortTermMemory(messages, conversationId, {
  modalities: [imageMemory]
});

See 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 for details.

Performance Benchmarks

Performance improvements from the latest enhancements:

FeatureImprovementDetails
Query Caching30-50% fasterCaches 50 most recent queries for 5 minutes
Vector Similarity40-60% fasterPre-computed magnitude caching
Rate LimitingProtection100 requests/minute per conversation
Timeout ProtectionReliabilityAll operations timeout after 5-30s
Data Storage30-40% smallerDeduplication and normalization
Health ChecksProactiveMemory, error rate, cache monitoring
Audit LoggingCompleteAll operations logged with timestamps

Test Results

Run the comprehensive test suite:

node test-improvements.js

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

src/
├── memory/           # Core memory management
│   ├── short-term.js    # Dynamic keyword-based memory
│   ├── long-term.js     # Trigger-based permanent memory
│   └── storage.js       # JSON file persistence
├── tools/            # MCP tool implementations
│   ├── short-term-tools.js
│   ├── long-term-tools.js
│   ├── backup-tools.js     # NEW: Backup/restore
│   └── search-tools.js     # NEW: Advanced search
├── utils/            # Utility modules
│   ├── query-cache.js      # NEW: Query result caching
│   ├── timeout.js          # NEW: Timeout handling
│   ├── logger.js           # NEW: Structured logging
│   └── lru-cache.js        # LRU cache implementation
├── security/         # NEW: Security features
│   ├── rate-limiter.js     # API rate limiting
│   ├── input-validator.js  # Input sanitization
│   └── audit-log.js        # Audit trail logging
├── monitoring/       # NEW: Monitoring features
│   └── metrics.js          # Performance metrics
├── health/           # NEW: Health checks
│   └── index.js            # Health monitoring
├── resources/        # MCP resources
│   └── index.js
└── prompts/          # MCP prompts
    └── index.js

License

BSD-3-Clause license

Credits

Extracted and generalized from the GentianAphrodite project.