doobidoo/mcp-memory-service v10.8.0

v10.8.0: Hybrid BM25 + Vector Search

on GitHub

🎯 Hybrid BM25 + Vector Search

This release introduces hybrid search combining BM25 keyword matching with vector similarity search, solving the exact match scoring problem where pure vector search scored exact text matches at 60-70% instead of near-100%.

✨ New Features

Hybrid Search (Issue #175, PR #436)

• FTS5-based BM25 keyword search with trigram tokenizer for multilingual support
• Parallel execution of BM25 and vector searches (<15ms typical latency)
• Configurable score fusion weights (default: 30% keyword, 70% semantic)
• Automatic FTS5 index synchronization via database triggers
• Fully backward compatible - existing mode="semantic" searches unchanged
• Comprehensive test suite - 12 tests covering unit, integration, performance
• Performance - <50ms average latency for 100 memories

🔧 Configuration

# Enable hybrid search (default: true)
MCP_HYBRID_SEARCH_ENABLED=true

# Score fusion weights (must sum to ~1.0)
MCP_HYBRID_KEYWORD_WEIGHT=0.3    # BM25 keyword weight
MCP_HYBRID_SEMANTIC_WEIGHT=0.7   # Vector similarity weight

📖 Usage

# Use hybrid search via unified API
result = await storage.search_memories(
    query="OAuth 2.1 authentication",
    mode="hybrid",  # New mode
    limit=5
)

# Or directly
results = await storage.retrieve_hybrid(
    query="exact text to find",
    n_results=10
)

🐛 Bug Fixes

• search_memories() Response Format - Corrected pre-existing bug where search_memories() returned Memory objects instead of dictionaries with similarity_score
• Test Safety - Tests now force sqlite_vec backend to prevent accidental Cloudflare data deletion

📊 Testing

• ✅ All 1,103 tests passing (0 failures)
• ✅ 12/12 new hybrid search tests passing
• ✅ No regressions detected
• ✅ Coverage: 58.36% (above threshold)

🚀 Performance

• Latency: <50ms average for 100 memories
• Storage: Minimal overhead (external content table pattern)
• Execution: BM25 + vector run in parallel
• Reference: AgentKits Memory (sub-10ms latency, 70% token efficiency)

📦 Installation

pip install --upgrade mcp-memory-service

# Or with uv
uv pip install --upgrade mcp-memory-service

🔗 Links

• Issue: #175
• Pull Request: #436
• Documentation: See .env.example for configuration options

🙏 Credits

Inspired by AgentKits Memory implementation. Special thanks to the community for testing and feedback.

Full Changelog: v10.7.2...v10.8.0