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

npm install

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

node example.js

📋 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

memento-mcp - Core memory functionality
HexTrackr - Integration target project
Model Context Protocol - MCP specification

Enhanced memory management that learns, improves, and remembers.

Memento Protocol Enhanced

Memento Protocol Enhanced

🌟 Features

🔒 Protocol Memory System

🎯 Quality Management

🔍 Enhanced Search (Hybrid Recall)

📖 "Ask the Scribe" Synthesis Reports

🔧 Wrapper Architecture

🚀 Quick Start

Installation

Basic Usage

Run Example

📋 Protocol System

🎯 Quality Management

🔍 Search Strategies

📖 Synthesis Reports

🏗️ Architecture

🔧 Configuration

📊 MCP Server

🛠️ Development

Requirements

Scripts

Adding Protocols

Extending Search

🤝 Integration

With HexTrackr

With Other Projects

🎯 Original Vision

Failure Modes Addressed

Core Innovations

📄 License

🔗 Links

Related Resources

Related MCP Servers

IAC Memory MCP Server

Memory Custom

MCP Server Memory File

Knowledge Graph Memory Server

New MCP Servers

MCP directory API