meMCP - Memory-Enhanced Model Context Protocol
A persistent memory system for Large Language Models (LLMs) that enables continuous learning and knowledge retention across sessions through the Model Context Protocol (MCP).
Overview
meMCP (Memory-Enhanced Model Context Protocol) is a sophisticated memory management system designed to give LLMs persistent, searchable memory capabilities. Unlike traditional stateless LLM interactions, meMCP allows AI assistants to build cumulative knowledge over time, remember insights from previous conversations, and provide increasingly intelligent responses based on accumulated experience.
Key Features
Persistent Memory
- Facts and insights stored permanently across sessions
- Automatic loading of historical knowledge on startup
- Robust JSON-based storage with corruption prevention
- Atomic write operations to prevent data loss
Semantic Search
- TF-IDF based semantic indexing for intelligent fact retrieval
- Cosine similarity scoring for relevance ranking
- Cross-session search capabilities
- Keyword extraction and document similarity analysis
Quality Assessment
- Multi-dimensional quality scoring system (novelty, generalizability, specificity, validation, impact)
- Configurable scoring weights and thresholds
- Automatic fact classification and prioritization
- Quality-based cleanup and retention policies
Streaming Support
- Efficient handling of large result sets through chunked streaming
- Pause/resume/cancel operations for long-running queries
- Progress tracking and estimated completion times
- Configurable chunk sizes for optimal performance
Modular Architecture
- Separate modules for operations, queries, streaming, and management
- Clean separation of concerns for maintainability
- Backward compatibility with existing integrations
- Easy extension and customization
Architecture
Core Components
SequentialGraphitiIntegration: Main orchestrator that initializes and coordinates all system components.
FactStore: Central storage manager handling fact persistence, indexing, and retrieval with semantic search capabilities.
MemoryTools: Modular MCP tool registration system with four specialized modules:
- MemoryOperations: CRUD operations for facts
- MemoryQueryHandler: Search and retrieval functionality
- MemoryStreamingTools: Large dataset streaming capabilities
- MemoryManagement: Cleanup, backup, and maintenance operations
SemanticIndex: TF-IDF based search engine providing intelligent fact discovery and similarity matching.
FileManager: Robust file I/O system with atomic writes, corruption detection, and automatic recovery.
ConfigurationManager: Flexible configuration system for customizing fact types, scoring weights, and system behavior.
HookManager: Event-driven system for capturing user interactions and processing sequential thinking data.
Data Flow
- Input Processing: User interactions and insights are captured via hooks or direct tool calls
- Quality Assessment: Multi-dimensional scoring evaluates the value and relevance of new information
- Storage: Facts are atomically written to JSON files with semantic indexing
- Retrieval: Semantic search finds relevant facts across all sessions with relevance scoring
- Streaming: Large result sets are delivered in configurable chunks for optimal performance
Storage Structure
~/.mcp_sequential_thinking/
├── graphiti_store/
│ ├── facts/ # Individual fact JSON files
│ ├── indexes/ # Search indexes and metadata
│ └── backups/ # Automatic system backups
└── config/
├── fact-types.json # Fact type definitions
├── scoring-weights.json # Quality scoring configuration
└── settings.json # System settings
Installation
Prerequisites
- Node.js 18+
- npm or yarn package manager
Setup
- Clone the repository:
git clone <repository-url>
cd memcp
- Install dependencies:
npm install
- Initialize the system:
node src/index.js
The system will automatically create the necessary directory structure and configuration files on first run.
MCP Integration
Add to your MCP configuration file (typically mcp_config.json):
{
"mcpServers": {
"memcp": {
"command": "node",
"args": ["src/index.js"],
"cwd": "/path/to/memcp"
}
}
}
Usage
Basic Operations
Store an insight:
await memoryTools.storeInsight({
content: "React useCallback prevents unnecessary re-renders in child components",
type: "verified_pattern",
domain: "react",
tags: ["performance", "hooks"],
context: { framework: "react" }
});
Search for facts:
const results = await factStore.queryFacts({
query: "React performance optimization",
limit: 10,
sortBy: "relevance"
});
Stream large result sets:
const streamId = await streamingManager.createBatchStream(
{ query: "database" },
factStore,
{ chunkSize: 10 }
);
const chunk = await streamingManager.getNextChunk(streamId);
MCP Tools
The system provides comprehensive MCP tools for integration with AI assistants:
memory_store_insight: Store new knowledgememory_query: Search existing factsmemory_update_fact: Modify existing factsmemory_delete_fact: Remove factsmemory_get_stats: System statisticsmemory_get_related: Find related factsmemory_bulk_process: Process multiple insightsmemory_cleanup: Maintenance operationsmemory_stream_query: Start streaming querymemory_stream_next: Get next chunkmemory_stream_status: Check stream statusmemory_stream_cancel: Cancel stream
Configuration
Fact Types: Define custom fact types with priorities and scoring multipliers:
{
"verified_pattern": {
"priority": 10,
"retention_months": 36,
"scoring_multiplier": 1.2,
"keywords": ["proven", "tested", "verified"]
}
}
Scoring Weights: Customize quality assessment dimensions:
{
"novelty": 0.25,
"generalizability": 0.20,
"specificity": 0.20,
"validation": 0.20,
"impact": 0.15
}
System Settings: Adjust operational parameters:
{
"quality_threshold": 60,
"max_facts_per_session": 100,
"retention_check_interval_hours": 24,
"auto_backup": true,
"debug_mode": false
}
Slash Commands
The system provides convenient slash commands for interactive use:
/memconfig: Open configuration interface/remember <insight>: Store new knowledge/recall <query>: Search for facts/insights: View recent high-quality insights
Testing
Run the comprehensive test suite:
# Test core functionality
node test-semantic-search.js
# Test streaming capabilities
node test-streaming.js
# Test modular architecture
node test-modular-memory-tools.js
# Test corruption handling
node test-corruption-fixes.js
# Full system test drive
node test-drive-memcp.js
Performance Characteristics
Storage
- Fact Storage: Individual JSON files for atomic operations
- Indexing: In-memory indexes with periodic persistence
- Search: TF-IDF semantic search with cosine similarity
- Corruption Handling: Automatic detection and recovery
Scalability
- Facts: Tested with 1000+ facts
- Search: Sub-second response times for typical queries
- Streaming: Configurable chunk sizes for large datasets
- Memory: Efficient in-memory indexing with lazy loading
Reliability
- Atomic Writes: Prevents data corruption during writes
- Backup System: Automatic backups with configurable retention
- Error Recovery: Graceful handling of corrupted files
- Data Validation: JSON schema validation for all stored data
Development
Project Structure
src/
├── core/ # Core integration layer
├── storage/ # Data persistence layer
├── indexing/ # Search and semantic indexing
├── streaming/ # Large dataset streaming
├── tools/ # MCP tool implementations
│ └── modules/ # Modular tool components
├── config/ # Configuration management
├── hooks/ # Event handling system
└── processing/ # Data processing pipeline
Adding New Features
- New Fact Types: Add to
config/fact-types.json - Custom Scoring: Implement in
src/processing/QualityScorer.js - Search Enhancements: Extend
src/indexing/SemanticIndex.js - New Tools: Add to appropriate module in
src/tools/modules/
Contributing
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
Troubleshooting
Common Issues
Storage directory not found: The system automatically creates directories on first run. Ensure write permissions to the home directory.
Corrupted JSON files: The system includes automatic corruption detection and repair. Corrupted files are quarantined and restored from backups when possible.
Memory usage: For large fact collections, consider adjusting max_facts_per_session and enabling periodic cleanup.
Search performance: Semantic indexing is rebuilt on startup. For large datasets, consider implementing incremental indexing.
Debug Mode
Enable debug mode in configuration for detailed logging:
{
"debug_mode": true
}
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Built on the Model Context Protocol (MCP) specification
- Uses TF-IDF for semantic search implementation
- Inspired by Sequential-Graphiti memory architecture
- Designed for integration with Claude and other LLM systems