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:

1. Noise Accumulation: Filters low-quality information
2. Confidence Erosion: Tracks reliability over time
3. Retrieval Brittleness: Multiple search strategies for robustness
4. Temporal Confusion: Time-aware relevance scoring
5. Context Loss: Preserves rich metadata and relationships
6. 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:

1. Multi-Strategy Search: Finds relevant memories using all search approaches
2. Quality Filtering: Removes low-confidence or irrelevant results
3. Insight Extraction: Identifies patterns and key information
4. Coherent Synthesis: Combines findings into readable summaries
5. 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

1. Create YAML file in protocols/ directory
2. Define triggers, conditions, and actions
3. 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

1. LLM compliance is unreliable → Protocol enforcement outside LLM
2. Noisy memories from keyword scraping → Two-stage filtering
3. Memory bloat & drift → Freshness decay + archival tiers
4. Conflicting protocols → Priority and scope management
5. Identity & grounding issues → Stable IDs and linkage
6. 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.