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. <a href="https://glama.ai/mcp/servers/@win10ogod/memory-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@win10ogod/memory-mcp-server/badge" alt="Memory Server MCP server" /> </a> ## 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 ```bash # 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` ```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:** ```json { "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:** ```javascript // 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 ```bash # 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:** ```javascript 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 [docs/IMAGE_MEMORY.md](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](docs/DATA_OPTIMIZATION.md) for details. ## Performance Benchmarks Performance improvements from the latest enhancements: | Feature | Improvement | Details | |---------|-------------|---------| | Query Caching | 30-50% faster | Caches 50 most recent queries for 5 minutes | | Vector Similarity | 40-60% faster | Pre-computed magnitude caching | | Rate Limiting | Protection | 100 requests/minute per conversation | | Timeout Protection | Reliability | All operations timeout after 5-30s | | Data Storage | 30-40% smaller | Deduplication and normalization | | Health Checks | Proactive | Memory, error rate, cache monitoring | | Audit Logging | Complete | All operations logged with timestamps | ### Test Results Run the comprehensive test suite: ```bash 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](https://github.com/steve02081504/GentianAphrodite) project.