Memento Protocol Enhanced
An enhanced wrapper around memento-mcp that adds sophisticated memory management capabilities inspired by the original ChatGPT memory design concepts.
🌟 Features
🔒 Protocol Memory System
- Rule Enforcement Outside LLM: Protocols are enforced deterministically, not subject to model forgetfulness
- YAML Configuration: Easy-to-edit protocol definitions
- Auto Git Backup: Automatic version control before file modifications
- Extensible Actions: Git operations, file system actions, API calls
🎯 Quality Management
- Two-Stage Filtering: Heuristic + LLM validation for accuracy
- Confidence Scoring: Tracks reliability of memories
- Freshness Decay: Automatic aging and archival of old memories
- Archival Tiers: Hot/Warm/Cold storage based on usage and age
🔍 Enhanced Search (Hybrid Recall)
- Multiple Strategies: Semantic vector, keyword matching, temporal relevance, confidence weighting
- Hybrid Scoring: Combines multiple search approaches for better results
- Quality Filtering: Filters results by confidence and relevance thresholds
- Search Metadata: Detailed information about search process and results
📖 "Ask the Scribe" Synthesis Reports
- Memory Synthesis: Combines related memories into coherent summaries
- Insight Extraction: Identifies key patterns and connections
- Confidence Tracking: Rates the reliability of synthesized information
- Query-Focused: Tailored responses to specific questions
🔧 Wrapper Architecture
- Preserves Compatibility: Works as a drop-in replacement for memento-mcp
- Upstream Safe: Doesn't fork memento-mcp, wraps it instead
- Optional Features: All enhancements can be enabled/disabled
- Graceful Fallbacks: Falls back to basic functionality if enhancements fail
🚀 Quick Start
Installation
Basic Usage
const { MementoWrapper } = require('./src/memento-wrapper');
// Initialize with all enhancements
const memento = new MementoWrapper({
enableProtocols: true,
enableQualityManagement: true,
enableEnhancedSearch: true
});
await memento.initializeComponents();
// Create entities with protocol enforcement
await memento.createEntity('MyProject', 'project');
// Add observations with quality scoring
await memento.addObservation(
'MyProject',
'Implemented enhanced memory wrapper with protocol enforcement',
{ category: 'development', priority: 'high' }
);
// Enhanced search with hybrid strategies
const results = await memento.searchMemories('memory wrapper architecture');
// Generate synthesis reports
const synthesis = await memento.generateSynthesisReport(
'What are the key features of this memory system?'
);
Run Example
📋 Protocol System
Protocols are defined in YAML files and enforce rules automatically:
# protocols/backup-before-write.yaml
name: backup-before-write
description: Auto git backup before file modifications
priority: 90
triggers:
tools: ['writeFile', 'applyPatch', 'refactor']
conditions:
- field: 'args.path'
operator: 'exists'
actions:
- type: 'git'
operation: 'add'
args: ['.']
- type: 'git'
operation: 'commit'
args: ['-m', 'Auto backup before ${context.toolName}']
🎯 Quality Management
The quality system addresses six failure modes identified in basic memory systems:
- Noise Accumulation: Filters low-quality information
- Confidence Erosion: Tracks reliability over time
- Retrieval Brittleness: Multiple search strategies for robustness
- Temporal Confusion: Time-aware relevance scoring
- Context Loss: Preserves rich metadata and relationships
- Scale Degradation: Efficient archival and tier management
🔍 Search Strategies
The hybrid search system combines multiple approaches:
- Semantic Vector: Embedding-based similarity search
- Keyword Matching: Exact term matching with scoring
- Temporal Relevance: Recent memories weighted higher
- Confidence Weighted: High-confidence memories prioritized
📖 Synthesis Reports
"Ask the Scribe" generates comprehensive reports by:
- Multi-Strategy Search: Finds relevant memories using all search approaches
- Quality Filtering: Removes low-confidence or irrelevant results
- Insight Extraction: Identifies patterns and key information
- Coherent Synthesis: Combines findings into readable summaries
- Confidence Rating: Provides reliability assessment
🏗️ Architecture
The wrapper is built in distinct layers:
┌─────────────────────────┐
│ MCP Server Layer │ ← Tool handlers, protocol middleware
├─────────────────────────┤
│ Memento Wrapper │ ← Main integration layer
├─────────────────────────┤
│ ┌─────────────────────┐│
│ │ Protocol Engine ││ ← Rule enforcement
│ ├─────────────────────┤│
│ │ Quality Manager ││ ← Scoring, filtering, archival
│ ├─────────────────────┤│
│ │ Enhanced Search ││ ← Hybrid search strategies
│ └─────────────────────┘│
├─────────────────────────┤
│ memento-mcp │ ← Core functionality (unchanged)
└─────────────────────────┘
🔧 Configuration
const memento = new MementoWrapper({
// Protocol settings
enableProtocols: true,
protocolsPath: './protocols',
// Quality management
enableQualityManagement: true,
qualityThresholds: {
minConfidence: 0.3,
freshnessPeriod: 30, // days
maxArchiveAge: 90 // days
},
// Search configuration
enableEnhancedSearch: true,
searchOptions: {
hybridWeight: 0.7,
maxResults: 20,
strategies: [
'semantic_vector',
'keyword_matching',
'temporal_relevance',
'confidence_weighted'
]
}
});
📊 MCP Server
The package includes a complete MCP server implementation:
# Start the MCP server
npm start
# Available tools:
# - memory_search_enhanced: Enhanced search with hybrid strategies
# - memory_get_full: Retrieve complete memory graph
# - protocol_enforce: Manual protocol enforcement
# - protocol_list: List available protocols
# - scribe_report: Generate synthesis reports
🛠️ Development
Requirements
- Node.js 18+
- Git (for protocol auto-backup)
Scripts
npm start # Start MCP server
npm test # Run tests (when implemented)
npm run example # Run usage example
Adding Protocols
- Create YAML file in
protocols/ directory - Define triggers, conditions, and actions
- Protocol engine loads automatically
Extending Search
Add new search strategies in src/enhanced-search/index.js:
async executeSearchStrategy(strategy, query, options) {
switch (strategy) {
case 'your_new_strategy':
return this.yourNewStrategySearch(query, options);
// ...
}
}
🤝 Integration
With HexTrackr
This wrapper was designed for integration with HexTrackr but works standalone:
// In HexTrackr project
const { MementoWrapper } = require('memento-protocol-enhanced');
const memento = new MementoWrapper(/* config */);
// Use as drop-in replacement for memento-mcp
await memento.createEntity('HexTrackr Feature', 'feature');
With Other Projects
The wrapper preserves full memento-mcp compatibility:
// Existing memento-mcp code works unchanged
const memento = new MementoWrapper();
await memento.searchMemories('query'); // Enhanced automatically
🎯 Original Vision
This implementation realizes the original ChatGPT memory design vision:
"Some of our improvements with how we handle the searching and the semantics might actually be an improvement" - User feedback
The wrapper addresses fundamental limitations in basic memory systems while maintaining simplicity and compatibility.
Failure Modes Addressed
- LLM compliance is unreliable → Protocol enforcement outside LLM
- Noisy memories from keyword scraping → Two-stage filtering
- Memory bloat & drift → Freshness decay + archival tiers
- Conflicting protocols → Priority and scope management
- Identity & grounding issues → Stable IDs and linkage
- Security & PII sprawl → Secret scrubbing and access controls
Core Innovations
- Hybrid Recall: Symbolic (SQL-like) + Vector (semantic) + Raw transcripts
- Protocol Memory: Rules enforced deterministically, not stored as "memories"
- Quality Pipeline: Heuristics → LLM validation → Confidence scoring
- Archival Strategy: Hot/warm/cold tiers based on adjusted confidence
📄 License
MIT License - see LICENSE file for details.
🔗 Links
Enhanced memory management that learns, improves, and remembers.