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
attachmentsfield
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 metadatarestore_memories: Restore from backup with merge or overwrite modeslist_backups: Browse available backup filesdelete_backup: Clean up old backups
-
🔎 Advanced Search: Powerful search with flexible filtering
search_memories: Search with keywords, date ranges, score filtersanalyze_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 diagnosticsget_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 contentconversation_id(string): Unique conversation identifierroleWeights(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 againstconversation_id(string): Current conversation IDroleWeights(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 nameprompt(string): Memory contenttrigger(string): JavaScript code for activation conditionconversation_id(string, optional): Conversation ID to store the memory under (defaults to "default")createdContext(string, optional): Context descriptionrecentMessages(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 arraycontext.conversation_id: Current conversation IDcontext.participants: Participant informationmatch_keys(messages, keywords, scope, depth): Match any keywordmatch_keys_all(messages, keywords, scope, depth): Match all keywordsDate,Math,RegExp,JSON: Safe built-in objects
update_long_term_memory
Update an existing long-term memory.
Parameters:
name(string): Memory name to updatetrigger(string, optional): New trigger conditionprompt(string, optional): New contentconversation_id(string, optional): Conversation ID that owns the memoryupdatedContext(string, optional): Update context
delete_long_term_memory
Delete a long-term memory by name.
Parameters:
name(string): Memory name to deleteconversation_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 messagesconversation_id(string): Current conversation IDparticipants(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 inspectconversation_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 rememberconversation_id(optional): Target conversation ID
Guides AI to:
- Create appropriate memory name
- Generate relevant trigger conditions
- Use add_long_term_memory tool
recall-context
Search for relevant memories based on current conversation.
Arguments:
current_topic(required): Current topic or questionconversation_id(optional): Conversation to search
Guides AI to:
- Search short-term memories for recent context
- Search long-term memories for permanent facts
- 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 abouttrigger_condition(required): When to trigger (keywords or date)conversation_id(optional): Target conversation
Guides AI to:
- Convert natural language conditions to JavaScript
- Create date-based or keyword-based triggers
- 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:
- Get current memory statistics
- Identify important information types
- Categorize for short-term vs long-term storage
- 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
- Top Relevant (max 2): Highest relevance scores
- Next Relevant (max 1): Next highest scores
- 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
vmmodule 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
vmmodule 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 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:
attachmentsfield removed (usemodalitiesonly) - 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:
| 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:
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.