MCP Memory Service

# Changelog **Recent releases for MCP Memory Service (v8.0.0 and later)** All notable changes to the MCP Memory Service project will be documented in this file. For older releases, see [CHANGELOG-HISTORIC.md](./CHANGELOG-HISTORIC.md). The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ## [8.50.1] - 2025-12-14 ### Fixed - **MCP_EMBEDDING_MODEL Environment Variable Now Respected** (PR #276, fixes #275) - The `MCP_EMBEDDING_MODEL` environment variable was being ignored in server.py during storage initialization - All storage backends (sqlite_vec, hybrid) now correctly use `EMBEDDING_MODEL_NAME` from config - Users can now configure custom embedding models like `paraphrase-multilingual-mpnet-base-v2` - Technical details: Fixed by passing `config.embedding_model` to storage backend constructors - **Installation Script Backend Support Updated** (fixes #273, commit 892212c) - Removed stale ChromaDB references from `--storage-backend` choices (ChromaDB was removed in v8.3.0) - Added missing 'cloudflare' and 'hybrid' options to both installation scripts - Updated help text to reflect current supported backends: sqlite_vec, cloudflare, hybrid - Fixes: `scripts/installation/install.py` and root-level `install.py` ### Added - **i18n Quality Analytics Translations** - Completed translations for quality analytics feature (PR #271) - Added 25 quality strings to Spanish, French, German, Japanese, Korean (125 translations total) - Completes i18n coverage started in PR #270 (English/Chinese) - Languages now fully supported: English, Chinese, Spanish, French, German, Japanese, Korean - Strings added: navigation labels, quality stats/charts, provider settings, help text ## [8.50.0] - 2025-12-09 ### Added - **Fallback Quality Scoring** - DeBERTa primary with MS-MARCO rescue for technical content (resolves prose bias issue) - **Problem Solved**: DeBERTa systematic bias toward prose (0.78-0.92) over technical content (0.48-0.60) - **Solution**: Threshold-based fallback - DeBERTa confident → use DeBERTa, DeBERTa low + MS-MARCO high → rescue with MS-MARCO - **Expected Results**: Technical content 0.70-0.80 (+45-65% improvement), prose 0.82 (no degradation) - **Performance**: ~139ms average (DeBERTa-only: 115ms for ~40% of memories, both models: 155ms for ~60%) - **Configuration**: - `MCP_QUALITY_FALLBACK_ENABLED=true` - Enable fallback mode - `MCP_QUALITY_LOCAL_MODEL="nvidia-quality-classifier-deberta,ms-marco-MiniLM-L-6-v2"` - Specify both models - `MCP_QUALITY_DEBERTA_THRESHOLD=0.6` - DeBERTa confidence threshold (default: 0.6) - `MCP_QUALITY_MSMARCO_THRESHOLD=0.7` - MS-MARCO rescue threshold (default: 0.7) - **Fallback Metadata Tracking** - Extended CSV format for decision transparency - New provider codes: `'fallback_deberta-msmarco': 'fb'`, `'onnx_deberta': 'od'`, `'onnx_msmarco': 'om'` - New decision codes: `'deberta_confident': 'dc'`, `'ms_marco_rescue': 'mr'`, `'both_low': 'bl'` - CSV format extended from 13 to 16 parts: `qs,qp,as,rs,rca,df,cb,ab,qba,qbd,qbr,qbcc,oqbb,dec,dbs,mms` - Backward compatible with old 13-part format - Stores individual model scores (deberta_score, ms_marco_score) for analysis - **Bulk Re-evaluation Script** - Re-score existing memories with fallback approach - Script: `scripts/quality/rescore_fallback.py` - Features: Dry-run mode, decision distribution analysis, threshold tuning support - Reports: Top improvements list, score delta tracking, decision breakdown - Usage: `python scripts/quality/rescore_fallback.py --execute --deberta-threshold 0.6 --msmarco-threshold 0.7` - **Comprehensive Test Suite** - 100% coverage for fallback logic - Test file: `tests/test_fallback_quality.py` - Test classes: FallbackConfiguration, MetadataCodec, FallbackScoringLogic, FallbackPerformance - Validates: Configuration validation, threshold logic, decision paths, metadata encoding/decoding - Performance benchmarks: DeBERTa-only path (<200ms), full fallback path (<500ms) ### Changed - **Quality Evaluator Architecture** - Multi-model support in single evaluator - `QualityEvaluator._onnx_models` dict stores multiple models simultaneously - `_ensure_initialized()` loads both models when fallback enabled - `_score_with_fallback()` implements threshold-based decision logic - `evaluate_quality()` uses fallback when `config.fallback_enabled` and `len(_onnx_models) >= 2` ### Technical Details - **Decision Logic**: ```python # Step 1: Always score with DeBERTa first deberta_score = deberta.score_quality("", content) # Step 2: If DeBERTa confident, use it if deberta_score >= 0.6: return deberta_score # MS-MARCO not consulted # Step 3: DeBERTa low - try MS-MARCO rescue ms_marco_score = ms_marco.score_quality(query, content) if ms_marco_score >= 0.7: return ms_marco_score # Rescue technical content # Step 4: Both agree low quality return deberta_score ``` - **Files Modified** (3): - `src/mcp_memory_service/quality/config.py` - Fallback configuration, threshold validation - `src/mcp_memory_service/quality/ai_evaluator.py` - Multi-model loading, fallback logic - `src/mcp_memory_service/quality/metadata_codec.py` - Provider codes, decision encoding - **Files Created** (2): - `scripts/quality/rescore_fallback.py` - Bulk re-evaluation script - `tests/test_fallback_quality.py` - Comprehensive test suite ### Performance Expectations - **Decision Distribution** (estimated): - DeBERTa confident: ~40% (prose, high-quality content) - Fast path (115ms) - MS-MARCO rescue: ~35% (technical content saved) - Full path (155ms) - Both low: ~25% (garbage, fragments) - Full path (155ms) - **Quality Improvements** (expected): - Technical content: 0.48 → 0.70-0.80 (+45-65%) - Prose content: 0.82 → 0.82 (no degradation) - High quality (≥0.7): 0.4% → 20-30% (50-75x increase) ### Important Discovery - MS-MARCO Limitations (Post-Implementation) **Problem Identified**: MS-MARCO cannot perform absolute quality assessment - MS-MARCO is a **query-document relevance model**, not a quality classifier - Empty query returns 0.000 (no signal) - Generic query ("high quality content") returns 0.000 (no signal) - Self-matching query (content as query) returns 1.000 (100% bias) - Only meaningful related queries work (but introduce bias) **Root Cause**: Cross-encoder architecture requires query-document pairs for relevance ranking, cannot evaluate intrinsic quality **Impact**: Fallback approach as designed is fundamentally incompatible with MS-MARCO's training objective ### Recommended Configuration (Updated After Threshold Testing) **✅ RECOMMENDED: Implicit Signals Only (Technical Corpora)** For technical note corpora (fragments, file paths, abbreviations, task lists): ```bash # Disable AI quality scoring (DeBERTa bias toward prose) export MCP_QUALITY_AI_PROVIDER=none # Quality based on implicit signals (access patterns, recency, retrieval ranking) export MCP_QUALITY_SYSTEM_ENABLED=true export MCP_QUALITY_BOOST_ENABLED=false # Implicit signals only, no AI combination ``` **Why This Works for Technical Content**: - **Access patterns = true quality** - Heavily-used memories are valuable, regardless of prose style - **No prose bias** - File paths, abbreviations, fragments treated fairly - **Simpler** - No model loading, no inference latency - **Self-learning** - Quality improves based on actual usage **Threshold Test Results** (50-sample analysis): - Average DeBERTa score: 0.209 (median: 0.165) - Only 4% scored ≥ 0.6 (good prose) - 72% scored < 0.4 (includes valuable technical fragments!) - Manual inspection: "Garbage" category contained valid technical references **Conclusion**: DeBERTa is trained on Wikipedia/news and systematically under-scores: - File paths and references (`modules/siem/dcr-linux-nginx.tf`) - Technical abbreviations (SAP, SIEM, CLI) - Fragmented notes and lists - Code-adjacent documentation **Alternative for Prose-Heavy Corpora**: DeBERTa with Lower Threshold ```bash # Only use for narrative documentation, blog posts, etc. export MCP_QUALITY_AI_PROVIDER=local export MCP_QUALITY_LOCAL_MODEL=nvidia-quality-classifier-deberta export MCP_QUALITY_DEBERTA_THRESHOLD=0.4 # Or 0.3 for more tolerance ``` **When to Use AI Scoring**: - ✅ Long-form documentation (prose paragraphs) - ✅ Blog posts, articles, tutorials - ✅ Narrative meeting notes - ❌ Technical fragments, file references (use implicit signals) - ❌ Code comments, CLI output (use implicit signals) - ❌ Task lists, tickets (use implicit signals) **⚠️ NOT RECOMMENDED: Fallback Mode** The fallback implementation remains available for experimentation, but MS-MARCO's architecture makes it unsuitable for this use case. Future work may explore alternative rescue strategies (implicit signals, different models). ## [8.49.0] - 2025-12-09 ### Changed - **NVIDIA DeBERTa Quality Classifier** - Replaced MS-MARCO with DeBERTa for absolute quality assessment (resolves #268) - **Model Upgrade**: Changed default from `ms-marco-MiniLM-L-6-v2` (23MB) to `nvidia-quality-classifier-deberta` (450MB) - **Architecture**: 3-class classifier (Low/Medium/High) for query-independent quality evaluation - **Eliminates Self-Matching Bias**: No query needed, evaluates content directly (~25% false positive reduction) - **Improved Distribution**: Mean score 0.60-0.70 (vs 0.469), uniform spread (vs bimodal clustering) - **Fewer False Positives**: <5% perfect 1.0 scores (vs 20% with MS-MARCO) - **Performance**: 80-150ms CPU, 20-40ms GPU (CUDA/MPS/DirectML) - ~20% slower but significantly more accurate - **Backward Compatible**: MS-MARCO still available via `MCP_QUALITY_LOCAL_MODEL=ms-marco-MiniLM-L-6-v2` ### Added - **Multi-Model ONNX Architecture** - Support for both classifier and cross-encoder models - Model registry in `src/mcp_memory_service/quality/config.py` with metadata (model type, size, inputs, output classes) - Model-specific scoring logic in `onnx_ranker.py`: softmax for classifiers, sigmoid for cross-encoders - `validate_model_selection()` function to validate user model choices - Environment variable: `MCP_QUALITY_LOCAL_MODEL` to switch between models - **DeBERTa Export Script** - One-time model download and ONNX conversion - Script: `scripts/quality/export_deberta_onnx.py` - Downloads 450MB model from HuggingFace, exports to ONNX format - Caches at: `~/.cache/mcp_memory/onnx_models/nvidia-quality-classifier-deberta/` - Includes test inference for validation - **Migration Script** - Re-evaluate existing memories with DeBERTa - Script: `scripts/quality/migrate_to_deberta.py` - Compares MS-MARCO vs DeBERTa distributions with statistical analysis - Preserves original scores in `quality_migration` metadata for rollback - Tracks score deltas (increases, decreases, stable memories) - Expected time: 10-20 minutes for 4,000-5,000 memories - **Comprehensive Test Suite** - 100+ tests for both models - Test file: `tests/test_deberta_quality.py` - Test classes: ModelRegistry, DeBERTaIntegration, BackwardCompatibility, Performance - Validates: Query-independence, 3-class output mapping, absolute quality scoring - Benchmarks: Inference speed, performance comparison vs MS-MARCO ### Fixed - **Quality Scoring**: Fixed double-softmax bug in ONNX ranker (was applying softmax twice, causing artificially low scores) - **Quality Scoring**: Corrected inverted class label mapping (High=0, Medium=1, Low=2, not [Low, Medium, High]) - **Bulk Evaluation**: Added missing logging import in `scripts/quality/bulk_evaluate_onnx.py` - **Migration Script**: Created optimized `scripts/quality/rescore_deberta.py` using direct SQLite access to avoid network timeouts during bulk re-scoring ### Performance - New content quality scores: 0.749 avg (vs 0.469 baseline, +60% improvement) - High quality identifications: 75.7% (vs 32.2% baseline, 2.4x improvement) - Inference time: 44ms CPU / 20-40ms GPU (expected with CUDA/MPS/DirectML) - Performance ratio: 7.8x slower than MS-MARCO (acceptable for quality gains) ### Documentation - **Memory Quality Guide** - Updated with DeBERTa model comparison and migration guide - Replaced ONNX limitations section with multi-model architecture - Added DeBERTa vs MS-MARCO performance metrics table - Migration instructions and GPU acceleration documentation - Location: `docs/guides/memory-quality-guide.md` - **Configuration Examples** - Added Configuration 9 (DeBERTa recommended setup) - Updated Configuration 1 to reflect DeBERTa as default - Best practices for v8.49.0+ vs v8.48.x (MS-MARCO) - Location: `docs/examples/quality-system-configs.md` - **CLAUDE.md** - Updated with v8.49.0 release notes and configuration examples - Architecture section now lists both DeBERTa (default) and MS-MARCO (legacy) - Configuration section shows DeBERTa as default model - Quality boost now recommended (more accurate with DeBERTa) ### Technical Details - **Files Modified** (3): - `src/mcp_memory_service/quality/config.py` - Model registry, default changed to DeBERTa - `src/mcp_memory_service/quality/onnx_ranker.py` - Multi-model support with classifier/cross-encoder branching - `scripts/quality/bulk_evaluate_onnx.py` - Model type detection for query strategy - **Files Created** (3): - `scripts/quality/export_deberta_onnx.py` - DeBERTa export script - `scripts/quality/migrate_to_deberta.py` - Migration script with statistics - `tests/test_deberta_quality.py` - Comprehensive test suite (100+ tests) - **Key Implementation**: Softmax 3-class scoring ```python # DeBERTa: weighted score from 3-class probabilities score = 0.0 × P(low) + 0.5 × P(medium) + 1.0 × P(high) # MS-MARCO: sigmoid binary score score = 1.0 / (1.0 + exp(-logit)) ``` ## [8.48.4] - 2025-12-08 ### Fixed - **Cloudflare D1 Drift Detection Performance** - Fixed slow/failing queries in hybrid backend drift detection (issue #264) - **Root Cause**: `get_memories_updated_since()` used slow ISO string comparison (`updated_at_iso > ?`) instead of fast numeric comparison - **Fix**: Changed WHERE clause to use indexed `updated_at` column with numeric comparison (`updated_at > ?`) - **Performance Impact**: 10-100x faster queries, eliminates D1 timeout/400 Bad Request errors on large datasets - **Affected Function**: `CloudflareStorage.get_memories_updated_since()` (lines 1638-1667) - **Location**: `src/mcp_memory_service/storage/cloudflare.py` - **Credit**: Root cause analysis by Claude Code workflow (GitHub Actions) ## [8.48.3] - 2025-12-08 ### Fixed - **Code Execution Hook Failure** - Fixed session-start hook falling back to MCP tools instead of using fast Code Execution API - **Root Cause 1**: Invalid `time_filter` parameter passed to `search()` function (API signature only accepts `query`, `limit`, `tags`) - **Root Cause 2**: Python `transformers` library emitted `FutureWarning` to stderr, causing `execSync()` to fail - **Root Cause 3**: Installer used system `python3` instead of detecting venv Python path - **Fix 1**: Removed time_filter parameter from Code Execution queries (line 325 in `claude-hooks/core/session-start.js`) - **Fix 2**: Added `-W ignore` flag to suppress Python warnings during execution (line 359) - **Fix 3**: Updated installer to use `sys.executable` for automatic venv detection (`claude-hooks/install_hooks.py:271-299`) - **Impact**: 75% token reduction per session start (1200-2400 tokens → 300-600 tokens with Code Execution) - **Behavior**: Hook now successfully uses Code Execution API instead of falling back to slower MCP tools - **Documentation**: Added memory with troubleshooting guide for future reference - **Location**: `claude-hooks/core/session-start.js:315-363`, `claude-hooks/install_hooks.py:271-299` ### Changed - **Session-Start Hook Connection Timeout** - Increased quick connection timeout from 2s to 5s - Prevents premature timeout during memory client initialization - Allows more time for HTTP server connection during high-load periods - Location: `~/.claude/hooks/core/session-start.js:750` (user installation) ## [8.48.2] - 2025-12-08 ### Added - **HTTP Server Auto-Start System** - Smart service management with comprehensive health checks - Created `scripts/service/http_server_manager.sh` with 376 lines of robust service management - Orphaned process detection and cleanup (handles stale PIDs from crashes/force kills) - Version mismatch detection (alerts when installed version differs from running version) - Config change detection (monitors .env file modification timestamps, triggers restart on changes) - Hybrid storage initialization wait (10-second timeout ensures storage backends are ready) - Health check with retry logic (3 attempts with 2s intervals before declaring failure) - Commands: `status`, `start`, `stop`, `restart`, `auto-start`, `logs` - Shell integration support (add to ~/.zshrc for automatic startup on terminal launch) - Location: `scripts/service/http_server_manager.sh` - **Session-Start Hook Health Check** - Proactive HTTP server availability monitoring - Added health check warning in `~/.claude/hooks/core/session-start.js` (lines 657-674) - Displays clear error message when HTTP server is unreachable - Provides actionable fix instructions (how to start server, how to enable auto-start) - Detects connection errors: ECONNREFUSED, fetch failed, network errors, timeout - Non-blocking check (warns but doesn't block Claude Code session initialization) - Location: `~/.claude/hooks/core/session-start.js:657-674` ### Fixed - **Time Parser "Last N Periods" Support** - Fixed issue #266 (time expressions not working) - Added new regex pattern `last_n_periods` to match "last N days/weeks/months/years" - Implemented `get_last_n_periods_range(n, period)` function for date calculations - Pattern positioning: Checked BEFORE `last_period` pattern to match more specific expressions first - Properly handles: - "last 3 days" → From 3 days ago 00:00:00 to now - "last 2 weeks" → From 2 weeks ago Monday 00:00:00 to now - "last 1 month" → From 1 month ago first day 00:00:00 to now - "last 5 years" → From 5 years ago Jan 1 00:00:00 to now - Backward compatible with existing "last week", "last month" patterns - Location: `src/mcp_memory_service/utils/time_parser.py` ### Changed - **Hook Configuration Time Windows** - Reverted to "last 3 days" (now works with parser fix) - Applied to `recentTimeWindow` and `fallbackTimeWindow` in hook config - Previously limited to "yesterday" due to parser bug - Now leverages full 3-day context window for better memory recall - Location: `~/.claude/hooks/config.json` ### Technical Details - **HTTP Server Manager Architecture**: - PID tracking via `/tmp/mcp_memory_http.pid` (shared location for orphan detection) - Config fingerprinting via MD5 hash of `.env` file (detects credential/backend changes) - Version extraction from installed package (compares with runtime version) - Log rotation support (tails last 50 lines from `~/.mcp-memory-service/http_server.log`) - SIGTERM graceful shutdown (10s timeout before SIGKILL) - Auto-start function for shell integration (idempotent, safe for rc files) - **Time Parser Improvements**: - Regex pattern: `r'last\s+(\d+)\s+(days?|weeks?|months?|years?)'` - Handles singular/plural forms (day/days, week/weeks, etc.) - Week boundaries: Monday 00:00:00 (ISO 8601 standard) - Month boundaries: First day 00:00:00 (calendar month alignment) - Fallback behavior: Interprets unknown periods as days (defensive programming) - **Testing Coverage**: - HTTP server manager: Tested status/start/stop/restart/auto-start commands - Orphaned process cleanup: Verified detection and cleanup of stale PIDs - Version mismatch: Confirmed detection when installed vs running version differs - Config change detection: Verified restart trigger on .env modification - Time parser: Tested "last 3 days", "last 2 weeks", "last 1 month", "last 5 years" - Backward compatibility: Verified "last week", "last month" still work ## [8.48.1] - 2025-12-08 ### Fixed - **CRITICAL: Service Startup Failure** - Fixed fatal `UnboundLocalError` that prevented v8.48.0 from starting - **Root Cause**: Redundant local `import calendar` statement at line 84 in `src/mcp_memory_service/models/memory.py` - **Python Scoping Issue**: Local import declaration made `calendar` a local variable within `iso_to_float()` function - **Error Location**: Exception handler at line 168 referenced `calendar` before the local import statement was executed - **Impact**: Service entered infinite loop during Cloudflare sync initialization, repeating error every ~100ms - **Symptoms**: Health endpoint unresponsive, dashboard inaccessible, all MCP Memory Service functionality unavailable - **Resolution**: Removed redundant local import (module already imported globally at line 21) - **Severity**: CRITICAL - All v8.48.0 users affected, immediate upgrade required - **Migration**: Drop-in replacement, no configuration changes needed - Location: `src/mcp_memory_service/models/memory.py:84` (removed) ### Technical Details - **Error Message**: `UnboundLocalError: cannot access local variable 'calendar' where it is not associated with a value` - **Frequency**: Repeating continuously (~100ms intervals) during Cloudflare hybrid backend initialization - **Testing**: Service now starts successfully, health endpoint responds correctly, Cloudflare sync completes without errors - **Verification**: No timestamp parsing errors in logs, dashboard accessible at https://localhost:8000 ## [8.48.0] - 2025-12-07 ### Added - **CSV-Based Metadata Compression** - Intelligent metadata compression system for Cloudflare sync operations - Implemented CSV encoding/decoding for quality and consolidation metadata - Achieved 78% size reduction (732B → 159B typical case) - Provider code mapping (onnx_local → ox, groq_llama3_70b → gp, etc.) for 70% reduction in provider field - Metadata size validation (<9.5KB) prevents sync failures before Cloudflare API calls - Transparent compression/decompression in hybrid backend operations - Quality metadata optimizations: - ai_scores history limited to 3 most recent entries (10 → 3) - quality_components removed from sync (debug-only, reconstructible) - Cloudflare-specific field suppression (metadata_source, last_quality_check) - Location: `src/mcp_memory_service/quality/metadata_codec.py` - **Verification Script** - Shell script to verify compression effectiveness - Tests CSV encoding/decoding round-trip accuracy - Measures compression ratios - Validates metadata size under Cloudflare limits - Location: `verify_compression.sh` ### Fixed - **Cloudflare Sync Failures** - Resolved 100% of metadata size limit errors - Problem: Cloudflare D1 10KB metadata limit was exceeded by quality/consolidation metadata - Impact: 1 operation stuck in retry queue with 400 Bad Request errors - Root cause: Uncompressed metadata (ai_scores history, quality_components) exceeded limit - Solution: CSV compression + metadata size validation before sync - Result: 0 sync failures, all operations processing successfully - Locations: `src/mcp_memory_service/storage/hybrid.py` (lines 547-559, 77-119), `src/mcp_memory_service/storage/cloudflare.py` (lines 606-612, 741-747, 830-836, 1474-1480) ### Technical Details - **Compression Architecture**: Phase 1 of 3-phase metadata optimization plan - Phase 1 (COMPLETE): CSV-based compression for quality/consolidation metadata - Phase 2 (AVAILABLE): Binary encoding with struct/msgpack (85-90% reduction target) - Phase 3 (AVAILABLE): Reference-based deduplication for repeated values - **Backward Compatibility**: Fully transparent - automatic compression on write, decompression on read - **Performance Impact**: Negligible (<1ms overhead per operation) - **Testing**: All quality system tests passing, sync queue empty, 3,750 ONNX-scored memories verified ## [8.47.1] - 2025-12-07 ### Fixed - **ONNX Self-Match Bug** - ONNX bulk evaluation was using memory content as its own query, producing artificially inflated scores (~1.0 for all memories) - Root cause: Cross-encoder design requires meaningful query-memory pairs for relevance ranking - Fixed by generating queries from tags/metadata (what memory is *about*) instead of memory content - Result: Realistic quality distribution (avg 0.468 vs 1.000, breakdown: 42.9% high / 3.2% medium / 53.9% low) - Location: `scripts/quality/bulk_evaluate_onnx.py` - **Association Pollution** - System-generated associations and compressed clusters were being evaluated for quality - These memories are structural (not content) and shouldn't receive quality scores - Fixed by filtering memories with type='association' or type='compressed_cluster' - Added belt-and-suspenders check for 'source_memory_hashes' metadata field - Impact: 948 system-generated memories excluded from evaluation - Location: `scripts/quality/bulk_evaluate_onnx.py` - **Sync Queue Overflow** - Queue capacity of 1,000 was overwhelmed by 4,478 updates during bulk ONNX evaluation - Resulted in 278 Cloudflare sync failures (27.8% failure rate) - Fixed by increasing queue size to 2,000 (env: `MCP_HYBRID_QUEUE_SIZE`) - Fixed by increasing batch size to 100 (env: `MCP_HYBRID_BATCH_SIZE`) - Added 5-second timeout with fallback to immediate sync on queue full - Added `wait_for_sync_completion()` method for monitoring bulk operations - Result: 0% sync failure rate during bulk operations - Location: `src/mcp_memory_service/storage/hybrid.py`, `src/mcp_memory_service/config.py` - **Consolidation Hang** - Batch update optimization was missing for relevance score updates - Sequential update_memory() calls caused slowdown during consolidation - Fixed by collecting updates and using single `update_memories_batch()` transaction - Impact: 50-100x speedup for relevance score updates during consolidation - Location: `src/mcp_memory_service/consolidation/consolidator.py` ### Added - **Reset ONNX Scores Script** (`scripts/quality/reset_onnx_scores.py`) - Resets all ONNX quality scores to implicit defaults (0.5) - Pauses hybrid backend sync during reset, resumes after completion - Preserves timestamps (doesn't change created_at/updated_at) - Progress reporting every 500 memories - Use case: Recover from bad ONNX evaluation (self-match bug) - **Enhanced Bulk Evaluate Script** (`scripts/quality/bulk_evaluate_onnx.py`) - Added association filtering (skip system-generated memories) - Added sync monitoring with queue size reporting - Added wait_for_sync_completion() call to prevent premature exit - Enhanced progress reporting with sync stats - Proper pause/resume for hybrid backend sync ### Changed - **ONNX Configuration Defaults** - Updated for better bulk operation support - `HYBRID_QUEUE_SIZE`: 1,000 → 2,000 (default, configurable via env) - `HYBRID_BATCH_SIZE`: 50 → 100 (default, configurable via env) - Backward compatible: `HYBRID_MAX_QUEUE_SIZE` still supported (legacy) - **Hybrid Backend Sync** - Enhanced pause/resume state tracking - Added `_sync_paused` flag to prevent enqueuing during pause (v8.47.1) - Fixed race condition where operations were enqueued while sync was paused - Ensures operations are not lost during consolidation or bulk updates ### Documentation - **ONNX Limitations** - Added critical warning to CLAUDE.md - Documented that ONNX ranker (ms-marco-MiniLM-L-6-v2) is a cross-encoder - Clarified it scores query-memory relevance, not absolute quality - Explained why self-matching queries produce artificially high scores - Added system-generated memory exclusion rationale ## [8.47.0] - 2025-12-06 ### Added - **Association-Based Quality Boost** - Memories with many connections automatically receive quality score boosts during consolidation - Well-connected memories (≥5 connections by default) get 20% quality boost - Leverages network effect: frequently referenced memories are likely more valuable - Configurable via environment variables: `MCP_CONSOLIDATION_QUALITY_BOOST_ENABLED`, `MCP_CONSOLIDATION_MIN_CONNECTIONS_FOR_BOOST`, `MCP_CONSOLIDATION_QUALITY_BOOST_FACTOR` - Valid boost factor range: 1.0-2.0 (default: 1.2 = 20% boost) - Quality scores capped at 1.0 to prevent over-promotion - Full metadata persistence with audit trail (connection count, original scores, boost date, boost reason) - Impact: Boosted quality affects relevance scoring (~4% increase) and retention tier (can move from medium to high retention) - Location: `src/mcp_memory_service/consolidation/decay.py` - **Quality Boost Metadata Tracking** - Complete audit trail for all quality boosts applied during consolidation - `quality_boost_applied`: Boolean flag indicating boost was applied - `quality_boost_date`: ISO timestamp of when boost occurred - `quality_boost_reason`: Always "association_connections" for this release - `quality_boost_connection_count`: Number of connections that triggered the boost - `original_quality_before_boost`: Preserved original quality score for analysis - **Configuration Variables** - Three new environment variables with validation - `MCP_CONSOLIDATION_QUALITY_BOOST_ENABLED` (default: true) - Master toggle - `MCP_CONSOLIDATION_MIN_CONNECTIONS_FOR_BOOST` (default: 5, range: 1-100) - Minimum connections required - `MCP_CONSOLIDATION_QUALITY_BOOST_FACTOR` (default: 1.2, range: 1.0-2.0) - Boost multiplier ### Changed - **Exponential Decay Calculation** - Enhanced to include association-based quality boost - Quality boost applied before quality multiplier calculation - Debug logging for each boost application - Info logging when persisting boosted scores to memory metadata - Preserved original quality score in RelevanceScore metadata for comparison - **Memory Relevance Metadata** - Extended to include quality boost tracking - `update_memory_relevance_metadata()` now persists boosted quality scores - Automatic quality score update if boost was applied - Metadata fields added: `quality_boost_applied`, `quality_boost_date`, `quality_boost_reason`, etc. ### Documentation - Added comprehensive feature guide: `docs/features/association-quality-boost.md` - Configuration examples (conservative, balanced, aggressive) - Impact on memory lifecycle (relevance, retention, forgetting resistance) - Use cases (knowledge graphs, code documentation, research notes) - Monitoring and troubleshooting guides - Performance impact analysis (negligible computational cost) - Future enhancement roadmap (connection quality analysis, temporal decay, bidirectional boost) - Updated `CLAUDE.md` with v8.47.0 release information - Added association-based quality boost to consolidation features list - Added configuration examples with environment variables - Updated version summary at top of file ### Tests - Added 5 comprehensive test cases in `tests/consolidation/test_decay.py` - `test_association_quality_boost_enabled`: Validates boost increases scores - `test_association_quality_boost_threshold`: Confirms minimum connection enforcement - `test_association_quality_boost_caps_at_one`: Verifies quality cap at 1.0 - `test_association_quality_boost_disabled`: Tests feature disable functionality - `test_association_quality_boost_persists_to_memory`: Validates metadata persistence - All tests use monkeypatch for configuration override - 100% test pass rate (5/5 new tests, 17/18 total consolidation tests) ### Technical Details - Feature enabled by default to provide immediate value - Boost calculation time: ~5-10 microseconds per memory (negligible overhead) - Memory overhead: ~200 bytes per boosted memory (5 metadata fields) - No measurable impact on consolidation duration - Integration point: `ExponentialDecayCalculator._calculate_memory_relevance()` - Quality boost applied BEFORE quality multiplier calculation in relevance scoring - Boost only applied if: enabled, connection count ≥ threshold, boost would increase score - Future-proof: `MCP_CONSOLIDATION_MIN_CONNECTED_QUALITY` reserved for Phase 2 (connection quality analysis) ## [8.46.3] - 2025-12-06 ### Fixed - **Quality Score Persistence in Hybrid Backend** - Fixed ONNX quality scores not persisting to Cloudflare in hybrid storage backend - Scores remained at default 0.5 instead of evaluated ~1.0 values - Root cause: `/api/quality/evaluate` endpoint was passing entire `memory.metadata` dict to `update_memory_metadata()` - Cloudflare backend expects quality fields wrapped in 'metadata' key, not as top-level fields - **Metadata Normalization for Cloudflare** - Added `_normalize_metadata_for_cloudflare()` helper function - Separates Cloudflare-recognized top-level keys (metadata, memory_type, tags, timestamps) from custom metadata fields - Wraps custom fields in 'metadata' key as expected by Cloudflare D1 backend - Only wraps if not already wrapped (idempotent operation) - **Quality API Metadata Handling** - Modified `/api/quality/evaluate` endpoint to extract only quality-related fields - Now passes only: quality_score, quality_provider, ai_scores, quality_components - Prevents accidental metadata overwrites from passing entire metadata dict - Added detailed logging for troubleshooting persistence issues - **Hybrid Backend Sync Operation** - Enhanced `SyncOperation` dataclass with `preserve_timestamps` flag - Ensures timestamp preservation through background sync queue - Passes flag to Cloudflare backend during update operations - Maintains temporal consistency across hybrid backends ### Technical Details - Affects only hybrid backend with Cloudflare secondary storage - SQLite-vec primary storage was working correctly (scores persisted locally) - Issue manifested during background sync to Cloudflare D1 - Verification: Search results now show quality scores of 1.000 instead of 0.500 ## [8.46.2] - 2025-12-06 ### Fixed - **Session-Start Hook Crash** - Added missing `queryMemoriesByTagsAndTime()` function to HTTP memory client - Hook was calling undefined function, causing "is not a function" error on session start - Implemented client-side tag filtering on time-based search results - Works with both HTTP and MCP protocols - Enables users to use session-start hooks without crashes - **Hook Installer Warnings Eliminated** - Removed confusing package import warnings during installation - Created `_version.py` to isolate version metadata from main package - Updated `install_hooks.py` to read version from `pyproject.toml` (avoids heavy imports) - Warnings appeared because importing `mcp_memory_service` loaded sqlite-vec/sentence_transformers dependencies - Provides clean installation experience without misleading warnings ### Technical Details - Root cause (session-start): `memory-client.js` missing function implementation for combined tag+time queries - Root cause (installer warnings): Hook installer imported main package for version detection, triggering model initialization warnings - Fix applies to all platforms (Windows, macOS, Linux) ## [8.46.1] - 2025-12-06 ### Fixed - **Windows Hooks Installer Encoding** - Fixed `'charmap' codec can't encode character` error when running `install_hooks.py` on Windows - Added UTF-8 console configuration (CP65001) at script startup - Reconfigured stdout/stderr with `encoding='utf-8', errors='replace'` - Added explicit `encoding='utf-8'` to all JSON file read/write operations - Added `ensure_ascii=False` to `json.dump()` for proper Unicode handling ### Technical Details - Root cause: Windows console default encoding (CP1252) doesn't support Unicode emojis (✅, ⚠️, etc.) - Fix applies to all Windows systems regardless of console code page setting ## [8.46.0] - 2025-12-06 ### Added - **Quality System + Hooks Integration** - Complete 3-phase integration of AI quality scoring into memory awareness hooks: - **Phase 1**: Hooks read `backendQuality` from memory metadata (20% weight in scoring) - **Phase 2**: Session-end hook triggers async `/api/quality/memories/{hash}/evaluate` endpoint - **Phase 3**: Quality-boosted search with `quality_boost` and `quality_weight` parameters - **`POST /api/quality/memories/{hash}/evaluate`** - New endpoint to trigger AI-based quality evaluation - Uses multi-tier system (ONNX local → Groq → Gemini → Implicit) - Returns quality_score, quality_provider, ai_score, evaluation_time_ms - Performance: ~355ms with ONNX ranker - **Quality-Boosted Search** - Added `quality_boost` and `quality_weight` to `/api/search` - Over-fetches 3x results, reranks with composite score - Formula: `(1-weight)*semantic + weight*quality` - Returns `search_type: "semantic_quality_boost"` with score breakdown - **Hook Integration Functions** - `calculateBackendQuality()` in `memory-scorer.js` extracts quality_score from metadata - `triggerQualityEvaluation()` in `session-end.js` for async scoring - `queryMemories()` in `memory-client.js` supports `qualityBoost` option ### Changed - Updated hook scoring weights: timeDecay (20%), tagRelevance (30%), contentRelevance (10%), contentQuality (20%), backendQuality (20%) ### Technical Details - Hook evaluation: Non-blocking with 10s timeout, graceful fallback on failure - Requires Memory Quality System (v8.45.0+) to be enabled ## [8.45.3] - 2025-12-06 ### Fixed - **ONNX Ranker Model Export** - Fixed broken model download URL (404 from HuggingFace) by implementing automatic model export from transformers to ONNX format on first use - **Offline Mode Support** - Added `local_files_only=True` support for air-gapped/offline environments using cached HuggingFace models - **Tokenizer Loading** - Fixed tokenizer initialization to load from exported pretrained files instead of broken archive ### Changed - Replaced failing `onnx.tar.gz` download approach with dynamic export from `cross-encoder/ms-marco-MiniLM-L-6-v2` via transformers - Model now exports to `~/.cache/mcp_memory/onnx_models/ms-marco-MiniLM-L-6-v2/model.onnx` on first initialization - Added graceful fallback: tries `local_files_only` first, then online download if not cached ### Technical Details - Performance: 7-16ms per memory scoring on CPU (CPUExecutionProvider) - Model size: ~23MB exported ONNX model - Dependencies: Requires `transformers`, `torch`, `onnxruntime`, `onnx` packages ## [8.45.2] - 2025-12-06 ### Fixed - **Dashboard Dark Mode Consistency** - Fixed dark mode regression where form controls, select elements, and view buttons had white/light backgrounds in dark mode - **Global Dark Mode CSS** - Added comprehensive `.form-control` and `.form-select` dark mode overrides ensuring consistency across all 7 dashboard tabs (Dashboard, Search, Browse, Documents, Manage, Analytics, Quality) - **Quality Tab Chart Contrast** - Improved chart readability in dark mode with proper `var(--neutral-400)` backgrounds and visible grid lines - **Chart.js Dark Mode Support** - Added dynamic Chart.js color configuration in `applyTheme()` function with light text (#f9fafb) and proper legend colors - **Quality Distribution Chart** - Updated `renderQualityDistributionChart()` with dynamic text/grid colors for dark mode - **Quality Provider Chart** - Updated `renderQualityProviderChart()` with dark mode-aware legend colors ### Changed - Enhanced `.view-btn` dark mode styles with proper hover states for better user interaction ## [8.45.1] - 2025-12-05 ### Fixed - **Quality System HTTP API** - Fixed router configuration causing 404 errors on all `/api/quality/*` endpoints (missing `/api/quality` prefix in app.py router inclusion) - **Quality Distribution MCP Tool** - Corrected storage method call from non-existent `search_all_memories()` to `get_all_memories()` in server.py quality distribution handler - **HTTP API Tests** - Replaced synchronous `TestClient` with async `httpx.AsyncClient` to fix SQLite thread safety issues in quality system tests - **Distribution Endpoint** - Fixed storage retrieval logic in quality.py and removed unnecessary dict-to-Memory conversions ### Added - **Dependencies** - Added `pytest-benchmark` for performance testing support - **Dependencies** - Added `onnxruntime` as optional dependency for ONNX model support ### Testing - All 27 functional tests passing - ONNX tests properly skip when model unavailable (expected behavior) - Zero errors in test suite ## [8.45.0] - 2025-12-05 ### Added - **Memory Quality System** - AI-driven automatic quality scoring (Issue #260, Memento-inspired design) - Local SLM via ONNX (ms-marco-MiniLM-L-6-v2, 23MB) as Tier 1 (primary, default) - Multi-tier fallback chain: Local SLM → Groq API → Gemini API → Implicit signals - Zero cost, full privacy, offline-capable with local SLM - 50-100ms latency (CPU), 10-20ms (GPU with CUDA/MPS/DirectML) - Cross-platform: Windows (CUDA/DirectML), macOS (MPS), Linux (CUDA/ROCm) - **Quality-Based Memory Management** - Quality-based forgetting: High (≥0.7) preserved 365 days, Medium (0.5-0.7) 180 days, Low (<0.5) 30-90 days - Quality-weighted decay: High-quality memories decay 3x slower than low-quality - Quality-boosted search: 0.7×semantic + 0.3×quality reranking (opt-in via `MCP_QUALITY_BOOST_ENABLED`) - Adaptive retention based on access patterns and user feedback - **MCP Tools** (4 new tools for quality management) - `rate_memory` - Manual quality rating with thumbs up/down/neutral (-1/0/1) - `get_memory_quality` - Retrieve quality metrics (score, provider, confidence, access stats) - `analyze_quality_distribution` - System-wide analytics (distribution, provider breakdown, trends) - `retrieve_with_quality_boost` - Quality-boosted semantic search with reranking - **HTTP API Endpoints** (4 new REST endpoints) - POST `/api/quality/memories/{hash}/rate` - Rate memory quality manually - GET `/api/quality/memories/{hash}` - Get quality metrics for specific memory - GET `/api/quality/distribution` - Distribution statistics (high/medium/low counts) - GET `/api/quality/trends` - Time series quality analysis (weekly/monthly trends) - **Dashboard UI Enhancements** - Quality badges on all memory cards (color-coded by tier: green/yellow/red/gray) - Analytics view with distribution charts (bar chart for counts, pie chart for providers) - Provider breakdown visualization (local/groq/gemini/implicit usage statistics) - Top/bottom performers lists (highest and lowest quality memories) - Settings panel for quality configuration (enable/disable, provider selection, boost weight) - i18n support for quality UI elements (English + Chinese translations) - **Configuration** (10 new environment variables) - `MCP_QUALITY_SYSTEM_ENABLED` - Master toggle (default: true) - `MCP_QUALITY_AI_PROVIDER` - Provider selection (local/groq/gemini/auto/none, default: local) - `MCP_QUALITY_LOCAL_MODEL` - ONNX model name (default: ms-marco-MiniLM-L-6-v2) - `MCP_QUALITY_LOCAL_DEVICE` - Device selection (auto/cpu/cuda/mps/directml, default: auto) - `MCP_QUALITY_BOOST_ENABLED` - Enable quality-boosted search (default: false, opt-in) - `MCP_QUALITY_BOOST_WEIGHT` - Quality weight 0.0-1.0 (default: 0.3) - `MCP_QUALITY_RETENTION_HIGH` - High-quality retention days (default: 365) - `MCP_QUALITY_RETENTION_MEDIUM` - Medium-quality retention days (default: 180) - `MCP_QUALITY_RETENTION_LOW_MIN` - Low-quality minimum retention (default: 30) - `MCP_QUALITY_RETENTION_LOW_MAX` - Low-quality maximum retention (default: 90) ### Changed - **Memory Model** - Extended with quality properties (backward compatible) - Added `quality_score`, `quality_provider`, `quality_confidence`, `quality_calculated_at` - Added `access_count` and `last_accessed_at` for usage tracking - Existing memories work without modification (quality calculated on first access) - **Storage Backends** - Enhanced with access pattern tracking - SQLite-Vec: Tracks access_count and last_accessed_at on retrieval - Cloudflare: Tracks access_count and last_accessed_at on retrieval - Both backends support quality-boosted search (opt-in) - **Consolidation System** - Integrated quality scores for intelligent retention - Forgetting module uses quality scores for retention decisions - Decay module applies quality-weighted decay (high-quality decays slower) - Association discovery prioritizes high-quality memories - **Search System** - Optional quality-based reranking - Default: Pure semantic search (0% quality influence) - Opt-in: Quality-boosted search (70% semantic + 30% quality) - Configurable boost weight via `MCP_QUALITY_BOOST_WEIGHT` ### Documentation - Comprehensive user guide: `/Users/hkr/Documents/GitHub/mcp-memory-service/docs/guides/memory-quality-guide.md` - Setup and configuration (local SLM, cloud APIs, hybrid mode) - Usage examples (MCP tools, HTTP API, Dashboard UI) - Performance benchmarks (latency, accuracy, cost analysis) - Troubleshooting guide (common issues, diagnostics) - CLAUDE.md updated with quality system section - Configuration examples for all deployment scenarios - Migration notes for existing users (zero breaking changes) ### Performance - **Quality Calculation Overhead**: <10ms per memory (non-blocking async) - **Search Latency with Boost**: <100ms total (semantic search + quality reranking) - **Local SLM Inference**: 50-100ms CPU, 10-20ms GPU (CUDA/MPS/DirectML) - **Async Background Scoring**: Non-blocking, queued processing for new memories - **Model Size**: 23MB ONNX (ms-marco-MiniLM-L-6-v2) ### Testing - 25 unit tests for quality scoring (`tests/test_quality_system.py`) - 6 integration tests for consolidation (`tests/test_quality_integration.py`) - Test pass rate: 67% (22/33 tests passing) - Known issues: 4 HTTP API tests (non-critical, fix scheduled for v8.45.1) ### Known Issues - 4 HTTP API tests failing (non-critical, development environment only): - `test_analyze_quality_distribution_mcp_tool` - Storage retrieval edge case - `test_rate_memory_http_endpoint` - HTTP 404 (routing configuration) - `test_get_quality_http_endpoint` - HTTP 404 (routing configuration) - `test_distribution_http_endpoint` - HTTP 500 (async handling) - Fix scheduled for v8.45.1 patch release - Production functionality unaffected (manual testing validates all features work correctly) ### Migration Notes - **No breaking changes** - Quality system is opt-in and backward compatible - **Existing users**: System works as before, quality scoring happens automatically in background - **To enable quality-boosted search**: Set `MCP_QUALITY_BOOST_ENABLED=true` in configuration - **To use cloud APIs**: Set API keys (GROQ_API_KEY/GEMINI_API_KEY) and `MCP_QUALITY_AI_PROVIDER=auto` - **To disable quality system**: Set `MCP_QUALITY_SYSTEM_ENABLED=false` (not recommended) ### Success Metrics (Phase 1 Targets) - Target: >40% improvement in retrieval precision (to be measured with usage data) - Target: >95% local SLM usage (Tier 1, zero cost) - Target: <100ms search latency with quality boost - Target: $0 monthly cost (local SLM default, no external API calls) ## [8.44.0] - 2025-11-30 ### Added - **Multi-Language Expansion** - Added 5 new languages to dashboard i18n system (commit a7d0ba7) - 🇯🇵 **Japanese (日本語)** - 359 translation keys, complete UI coverage - 🇰🇷 **Korean (한국어)** - 359 translation keys, complete UI coverage - 🇩🇪 **German (Deutsch)** - 359 translation keys, complete UI coverage - 🇫🇷 **French (Français)** - 359 translation keys, complete UI coverage - 🇪🇸 **Spanish (Español)** - 359 translation keys, complete UI coverage - All translations professionally validated (key parity, interpolation syntax, JSON structure) - **Complete i18n Coverage** - Extended translation support to all UI elements (+57 keys: 304 → 359) - Search results view: headers, view buttons, empty states - Browse by Tags view: title, subtitle, filter controls - Memory Details Modal: all buttons and labels - Add Memory Modal: complete form field coverage - Settings Modal: preferences, system info, backup sections - Loading states and connection status indicators - Memory Viewer Modal: all interactive elements - ~80 data-i18n attributes added to index.html for automatic translation ### Fixed - **Dark Mode Language Dropdown** - Fixed styling inconsistencies in dark mode (commit a7d0ba7) - Added proper background colors for dropdown items - Fixed hover state styling (translucent white overlay) - Fixed active language highlighting - Improved contrast and readability in dark theme ### Changed - **Translation Key Structure** - Expanded from 304 to 359 keys per language - Maintains backward compatibility with existing translations - English (en.json) and Chinese (zh.json) updated to match new structure - Consistent key naming conventions across all languages ## [8.43.0] - 2025-11-30 ### Added - **Frontend Internationalization** - Complete i18n support for dashboard with English and Chinese translations (PR #256, thanks @amm10090!) - Language toggle switcher in header with 🌐 icon - 300+ translation keys in `en.json` and `zh.json` - Automatic language detection (localStorage > browser language > English) - Dynamic translation of all UI elements, placeholders, tooltips - English fallback for missing keys - **Enhanced Claude Branch Automation** - Integrated quality checks before PR creation - New file-level quality validation utility (`scripts/pr/run_quality_checks_on_files.sh`, 286 lines) - Groq API primary (fast, 200-300ms), Gemini CLI fallback - Code complexity analysis (blocks >8, warns 7-8) - Security vulnerability scan (SQL injection, XSS, command injection, path traversal, secrets) - Conditional PR creation (blocks if security issues detected) - GitHub Actions annotations for inline feedback - Machine-parseable output format for CI/CD integration ### Changed - **i18n Performance Optimization** - Reduced DOM traversal overhead (4 separate calls → single unified traversal) ### Fixed - **Translation Accuracy** - Removed incorrect translation wrapping for backend error messages - **Translation Completeness** - Added missing `{reason}` placeholder to error translations ## [8.42.1] - 2025-11-29 ### Fixed - **MCP Resource Handler AttributeError** - Fixed `AttributeError: 'AnyUrl' object has no attribute 'startswith'` in `handle_read_resource` function (issue #254) - Added automatic URI string conversion at function start to handle both plain strings and Pydantic AnyUrl objects - MCP SDK may pass AnyUrl objects instead of strings, causing AttributeError when using `.startswith()` method - Fix converts AnyUrl to string using `str()` before processing, maintaining backward compatibility ## [8.42.0] - 2025-11-27 ### Added - **Visible Memory Injection Display** - Users now see injected memories at session start (commit TBD) - Added `showInjectedMemories` config option to display top 3 memories with relevance scores - Shows memory age (e.g., "2 days ago"), tags, and relevance scores - Formatted with colored output box for clear visibility - Helps users understand what context the AI assistant is using - Configurable via `~/.claude/hooks/config.json` ### Changed - **Session-End Hook Quality Improvements** - Raised quality thresholds to prevent generic boilerplate (commit TBD) - Increased `minSessionLength` from 100 → 200 characters (requires more substantial content) - Increased `minConfidence` from 0.1 → 0.5 (requires 5+ meaningful items vs 1+) - Added optional LLM-powered session summarizer using Gemini CLI - New files: `llm-session-summarizer.js` utility and `session-end-llm.js` core hook - Prevents low-quality memories like "User asked Claude to review code" from polluting database - Database cleaned from 3352 → 3185 memories (167 generic entries removed) ### Fixed - **Duplicate MCP Fallback Messages** - Fixed duplicate "MCP Fallback → Using standard MCP tools" log messages (commit TBD) - Added module-level flag to track if fallback message was already logged - Message now appears once per session instead of once per query - Improved session start hook output clarity ### Performance - **Configuration Improvements** - Better defaults for session analysis - Enabled relevance scores in context formatting - Improved memory scoring to prioritize quality over recency for generic content - Session-end hook re-enabled with improved quality gates ## [8.41.2] - 2025-11-27 ### Fixed - **Hook Installer Utility File Deployment** - Installer now copies ALL utility files instead of hardcoded lists (commit 557be0e) - **BREAKING**: Previous installer only copied 8/14 basic utilities and 5/14 enhanced utilities - Updated files like `memory-scorer.js` and `context-formatter.js` were not deployed with `--natural-triggers` flag - Replaced hardcoded file lists with glob pattern (`*.js`) to automatically include all utility files - Ensures v8.41.0/v8.41.1 project affinity filtering fixes get properly deployed - Future utility file additions automatically included without manual list maintenance - **Impact**: Users running `python install_hooks.py --natural-triggers` now get all 14 utility files, preventing stale hooks ## [8.41.1] - 2025-11-27 ### Fixed - **Context Formatter Memory Sorting** - Memories now sorted by recency within each category (commit 2ede2a8) - Added sorting by `created_at_iso` (descending) after grouping memories into categories - Ensures most recent memories appear first in each section for better context relevance - Applied in `context-formatter.js` after category grouping logic - Improves user experience by prioritizing newest information in memory context ## [8.41.0] - 2025-11-27 ### Fixed - **Session Start Hook Reliability** - Improved session start hook reliability and memory filtering (commit 924962a) - **Error Suppression**: Suppressed Code Execution ModuleNotFoundError spam - Added `suppressErrors: true` to Code Execution call configuration - Eliminates console noise from module import errors during session start - **Clean Output**: Removed duplicate "Injected Memory Context" output - Removed duplicate stdout console.log that caused double messages - Session start output now cleaner and easier to read - **Memory Filtering**: Added project affinity scoring to prevent cross-project memory pollution - New `calculateProjectAffinity()` function in `memory-scorer.js` - Hard filters out memories without project tag when in a project context - Soft scoring penalty (0.3x) for memories from different projects - Prevents Azure/Terraform memories from appearing in mcp-memory-service context - **Classification Fix**: Session summaries no longer misclassified as "Current Problems" - Excludes `session`, `session-summary`, and `session-end` memory types from problem classification - Prevents confusion between historical session notes and actual current issues - **Path Display**: "Unknown location" now shows actual path via `process.cwd()` fallback - When git repository detection fails, uses `process.cwd()` instead of "Unknown location" - Provides better context awareness even in non-git directories ## [8.40.0] - 2025-11-27 ### Added - **Session Start Version Display** - Automatic version information display during session startup (commit f2f7d2b, fixes #250) - **Version Checker Utility**: New `version-checker.js` utility in `claude-hooks/utilities/` - Reads local version from `src/mcp_memory_service/__init__.py` - Fetches latest published version from PyPI API - Compares versions and displays status labels (published/development/outdated) - Configurable timeout for PyPI API requests - **Session Start Integration**: Version information now appears automatically during session initialization - Displays format: `📦 Version → X.Y.Z (local) • PyPI: X.Y.Z` - Shows after storage backend information - Provides immediate visibility into version status - **Testing**: Includes `test_version_checker.js` for utility validation - **Benefits**: - Quick version verification without manual checks - Early detection of outdated installations - Improved development workflow transparency - Helps users stay current with latest features and fixes ## [8.39.1] - 2025-11-27 ### Fixed - **Dashboard Analytics Bugs** - Fixed three critical bugs in the analytics section (commit c898a72, fixes #253) - **Top Tags filtering**: Now correctly filters tags by selected timeframe (7d/30d/90d) - Implemented time-based filtering using `get_memories_by_time_range()` - Counts tags only from memories within the selected period - Maintains backward compatibility with all storage backends - **Recent Activity display**: Bars now show percentage distribution - Enhanced display to show both count and percentage of total - Tooltip includes both absolute count and percentage - Activity count label shows percentage (e.g., '42 (23.5%)') - **Storage Report field mismatches**: Fixed "undefined chars" display - Fixed field name: `size_kb` instead of `size` - Fixed field name: `preview` instead of `content_preview` - Fixed date parsing: `created_at` is ISO string, not timestamp - Added null safety and proper size display (KB with bytes fallback) ## [8.39.0] - 2025-11-26 ### Performance - **Analytics date-range filtering**: Moved from application layer to storage layer for 10x performance improvement (#238) - Added `get_memories_by_time_range()` to Cloudflare backend with D1 database filtering - Updated memory growth endpoint to use database-layer queries instead of fetching all memories - **Performance gains**: - Reduced data transfer: 50MB → 1.5MB (97% reduction for 10,000 memories) - Response time (SQLite-vec): ~500ms → ~50ms (10x improvement) - Response time (Cloudflare): ~2-3s → ~200ms (10-15x improvement) - **Scalability**: Now handles databases with >10,000 memories efficiently - **Benefits**: Pushes filtering to database WHERE clauses, leverages indexes on `created_at` ## [8.38.1] - 2025-11-26 ### Fixed - **HTTP MCP Transport: JSON-RPC 2.0 Compliance** - Fixed critical bug where HTTP MCP responses violated JSON-RPC 2.0 specification (PR #249, fixes #236) - **Problem**: FastAPI ignored Pydantic's `ConfigDict(exclude_none=True)` when directly returning models, causing responses to include null fields (`"error": null` in success, `"result": null` in errors) - **Impact**: Claude Code/Desktop rejected all HTTP MCP communications due to spec violation - **Solution**: Wrapped all `MCPResponse` returns in `JSONResponse` with explicit `.model_dump(exclude_none=True)` serialization - **Verification**: - Success responses now contain ONLY: `jsonrpc`, `id`, `result` - Error responses now contain ONLY: `jsonrpc`, `id`, `error` - **Testing**: Validated with curl commands against all 5 MCP endpoint response paths - **Credits**: @timkjr (Tim Knauff) for identifying root cause and implementing proper fix ## [8.38.0] - 2025-11-25 ### Improved - **Code Quality: Phase 2b Duplicate Consolidation COMPLETE** - Eliminated ~176-186 lines of duplicate code (issue #246) - **Document chunk processing consolidation (Group 3)**: - Extracted `process_document_chunk()` helper function from duplicate implementations - Consolidated chunk_text/chunk_size/chunk_overlap pattern across document ingestion tools - 2 occurrences reduced to 1 canonical implementation with consistent metadata handling - **MCP response parsing consolidation (Group 3)**: - Extracted `parse_mcp_response()` helper for isError/error/content pattern - Standardized error handling across MCP tool invocations - 2 occurrences reduced to 1 canonical implementation - **Cache statistics logging consolidation (Group 5)**: - Extracted `log_cache_statistics()` helper for storage/service cache metrics - Standardized cache performance logging format (hits, misses, hit rates) - 2 occurrences reduced to 1 canonical implementation with consistent percentage formatting - **Winter season boundary logic consolidation (Group 7)**: - Extracted `is_winter_boundary_case()` helper for cross-year winter season handling - Centralized December-January transition logic (Dec 21 - Mar 20 spans years) - 2 occurrences reduced to 1 canonical implementation - **Test tempfile setup consolidation (Groups 10, 11)**: - Extracted `create_test_document()` helper for pytest tmp_path fixture patterns - Standardized temporary file creation across document ingestion tests - 6 occurrences reduced to 2 canonical implementations (PDF, DOCX variants) - **MCP server configuration consolidation (Phase 2b-3)**: - Consolidated duplicate server config sections in install.py and scripts/installation/install.py - Unified JSON serialization logic for mcpServers configuration blocks - Improved maintainability through shared configuration structure - **User input prompt consolidation (Phase 2b-2)**: - Extracted shared prompt logic for backend selection and configuration - Standardized input validation patterns across installation scripts - Reduced code duplication in interactive installation workflows - **Additional GPU detection consolidation (Phase 2b-1)**: - Completed GPU platform detection consolidation from Phase 2a - Refined helper function extraction for test_gpu_platform() and related utilities - Enhanced configuration-driven GPU detection architecture - **Consolidation Summary**: - Total duplicate code eliminated: ~176-186 lines across 10 consolidation commits - Functions/patterns consolidated: 10+ duplicate implementations → canonical versions - Strategic deference: 5 groups intentionally skipped (high-risk/low-benefit per session analysis) - Code maintainability: Enhanced through focused helper methods and consistent patterns - 100% backward compatibility maintained (no breaking changes) - Test coverage: 100% maintained across all consolidations ### Code Quality - **Phase 2b Duplicate Consolidation**: 10 consolidation commits addressing multiple duplication groups - **Duplication Score**: Reduced from 5.5% (Phase 2a baseline) to estimated 4.5-4.7% - **Complexity Reduction**: Helper extraction pattern applied consistently across codebase - **Expected Impact**: - Duplication Score: Approaching <3% target with strategic consolidation - Complexity Score: Improved through helper function extraction - Overall Health Score: Strong progress toward 75+ target - **Remaining Work**: 5 duplication groups intentionally deferred (high-risk backend logic, low-benefit shared imports) - **Related**: Issue #246 Phase 2b (Duplicate Consolidation Strategy COMPLETE) ## [8.37.0] - 2025-11-24 ### Improved - **Code Quality: Phase 2a Duplicate Consolidation COMPLETE** - Eliminated 5 duplicate high-complexity functions (issue #246) - **detect_gpu() consolidation (3 duplicates → 1 canonical)**: - Consolidated ROOT install.py::detect_gpu() (119 lines, complexity 30) with refactored scripts/installation/install.py version (187 lines, configuration-driven) - Refactored scripts/validation/verify_environment.py::EnvironmentVerifier.detect_gpu() (123 lines, complexity 27) to use helper-based architecture - Final canonical implementation in install.py: GPU_PLATFORM_CHECKS config dict + test_gpu_platform() helper + CUDA_VERSION_PARSER - Impact: -4% high-complexity functions (27 → 26), improved maintainability - **verify_installation() consolidation (2 duplicates → 1 canonical)**: - Replaced scripts/installation/install.py simplified version with canonical ROOT install.py implementation - Added tokenizers check for ONNX dependencies, safer DirectML version handling - Improved error messaging and user guidance - **Consolidation Summary**: - Total duplicate functions eliminated: 5 (3x detect_gpu + 2x verify_installation) - High-complexity functions reduced: 27 → 24 (-11%) - Code maintainability improved through focused helper methods and configuration-driven design - 100% backward compatibility maintained (no breaking changes) ### Code Quality - **Phase 2a Duplicate Consolidation**: 5 of 5 target functions consolidated (100% complete) - **High-Complexity Functions**: Reduced from 27 to 24 (-11%) - **Complexity Reduction**: Configuration-driven patterns replace monolithic if/elif chains - **Expected Impact**: - Duplication Score: Reduced toward <3% target - Complexity Score: Improved through helper extraction - Overall Health Score: On track for 75+ target - **Related**: Issue #246 Phase 2a (Duplicate Consolidation Strategy COMPLETE) ## [8.36.1] - 2025-11-24 ### Fixed - **CRITICAL**: HTTP server crash on v8.36.0 startup - forward reference error in analytics.py (issue #247) - Added `from __future__ import annotations` to enable forward references in type hints - Added `Tuple` to typing imports for Python 3.9 compatibility - Impact: Unblocks all v8.36.0 users experiencing startup failures - Root cause: PR #244 refactoring introduced forward references without future annotations import - Fix verified: HTTP server starts successfully, all 10 analytics routes registered ## [8.36.0] - 2025-11-24 ### Improved - **Code Quality: Phase 2 COMPLETE - 100% of Target Achieved** - Refactored final 7 functions, -19 complexity points (issue #240 PR #244) - **consolidator.py (-8 points)**: - `consolidate()`: 12 → 8 - Introduced SyncPauseContext for cleaner sync state management + extracted `check_horizon_requirements()` helper - `_get_memories_for_horizon()`: 10 → 8 - Replaced conditional logic with data-driven HORIZON_CONFIGS dict lookup - **analytics.py (-8 points)**: - `get_tag_usage_analytics()`: 10 → 6 - Extracted `fetch_storage_stats()` and `calculate_tag_statistics()` helpers (40+ lines) - `get_activity_breakdown()`: 9 → 7 - Extracted `calculate_activity_time_ranges()` helper (70+ lines) - `get_memory_type_distribution()`: 9 → 7 - Extracted `aggregate_type_statistics()` helper - **install.py (-2 points)**: - `detect_gpu()`: 10 → 8 - Data-driven GPU_PLATFORM_CHECKS dict + extracted `test_gpu_platform()` helper - **cloudflare.py (-1 point)**: - `get_memory_timestamps()`: 9 → 8 - Extracted `_fetch_d1_timestamps()` method for D1 query logic - **Gemini Review Improvements (5 iterations)**: - **Critical Fixes**: - Fixed timezone bug: `datetime.now()` → `datetime.now(timezone.utc)` in consolidator - Fixed analytics double-counting: proper use of `count_all_memories()` - CUDA/ROCm robustness: try all detection paths before failing - **Quality Improvements**: - Modernized deprecated APIs: `pkg_resources` → `importlib.metadata`, `universal_newlines` → `text=True` - Enhanced error logging with `exc_info=True` for better debugging - Improved code consistency and structure across all refactored functions ### Code Quality - **Phase 2 Complete**: 10 of 10 functions refactored (100%) - **Complexity Reduction**: -39 of -39 points achieved (100% of target) - **Total Batches**: - v8.34.0 (PR #242): `analytics.py::get_memory_growth()` (-5 points) - v8.35.0 (PR #243): `install.py::configure_paths()`, `cloudflare.py::_search_by_tags_internal()` (-15 points) - v8.36.0 (PR #244): Remaining 7 functions (-19 points) - **Expected Impact**: - Complexity Score: 40 → 51+ (+11 points, exceeded +10 target) - Overall Health Score: 63 → 68-72 (Grade B achieved!) - **Related**: Issue #240 Phase 2 (100% COMPLETE), Phase 1: v8.33.0 (dead code removal, +5-9 health points) ## [8.35.0] - 2025-11-24 ### Improved - **Code Quality: Phase 2 Batch 1 Complete** - Refactored 2 high-priority functions (issue #240 PR #243) - **install.py::configure_paths()**: Complexity reduced from 15 → 5 (-10 points) - Extracted 4 helper functions for better separation of concerns - Main function reduced from 80 → ~30 lines - Improved testability and maintainability - **cloudflare.py::_search_by_tags_internal()**: Complexity reduced from 13 → 8 (-5 points) - Extracted 3 helper functions for tag normalization and query building - Method reduced from 75 → ~45 lines - Better code organization - **Gemini Review Improvements**: - Dynamic PROJECT_ROOT detection in scripts - Specific exception handling (OSError, IOError, PermissionError) - Portable documentation paths ### Code Quality - **Phase 2 Progress**: 3 of 10 functions refactored (30% complete) - **Complexity Reduction**: -20 points achieved of -39 point target (51% of target) - **Remaining Work**: 7 functions with implementation plans ready - **Overall Health**: On track for 75+ target score ## [8.34.0] - 2025-11-24 ### Improved - **Code Quality: Phase 2 Complexity Reduction** - Refactored `analytics.py::get_memory_growth()` function (issue #240 Phase 2) - Complexity reduced from 11 → 6-7 (-4 to -5 points, exceeding -3 point target) - Introduced PeriodType Enum for type-safe period validation - Data-driven period configuration with PERIOD_CONFIGS dict - Data-driven label formatting with PERIOD_LABEL_FORMATTERS dict - Improved maintainability and extensibility for analytics endpoints ### Code Quality - Phase 2 Progress: 1 of 10 functions refactored - Complexity Score: Estimated +1 point improvement (partial Phase 2) - Overall Health: On track for 70+ target ## [8.33.0] - 2025-11-24 ### Fixed - **Critical Installation Bug**: Fixed early return in `install.py` that prevented Claude Desktop MCP configuration from executing (issue #240 Phase 1) - 77 lines of Claude Desktop setup code now properly runs during installation - Users will now get automatic MCP server configuration when running `install.py` - Bug was at line 1358 - early `return False` in exception handler made lines 1360-1436 unreachable - Resolves all 27 pyscn dead code violations identified in issue #240 Phase 1 ### Improved - Modernized `install.py` with pathlib throughout (via Gemini Code Assist automated review) - Specific exception handling (OSError, PermissionError, JSONDecodeError) instead of bare `except` - Fixed Windows `memory_wrapper.py` path resolution bug (now uses `resolve()` for absolute paths) - Added config structure validation to prevent TypeError on malformed JSON - Import optimization and better error messages - Code structure improvements from 10+ Gemini Code Assist review iterations ### Code Quality - **Dead Code Score**: 70 → 85-90 (projected +15-20 points from removing 27 violations) - **Overall Health Score**: 63 → 68-72 (projected +5-9 points) - All improvements applied via automated Gemini PR review workflow ## [8.32.0] - 2025-11-24 ### Added - **pyscn Static Analysis Integration**: Multi-layer quality workflow with comprehensive static analysis - New `scripts/pr/run_pyscn_analysis.sh` for PR-time analysis with health score thresholds (blocks <50) - New `scripts/quality/track_pyscn_metrics.sh` for historical metrics tracking (CSV storage) - New `scripts/quality/weekly_quality_review.sh` for automated weekly reviews with regression detection - Enhanced `scripts/pr/quality_gate.sh` with `--with-pyscn` flag for comprehensive checks - Three-layer quality strategy: Pre-commit (Groq/Gemini LLM) → PR Gate (standard + pyscn) → Periodic (weekly) - 6 comprehensive metrics: cyclomatic complexity, dead code, duplication, coupling, dependencies, architecture - Health score thresholds: <50 (blocker), 50-69 (action required), 70-84 (good), 85+ (excellent) - Complete documentation in `docs/development/code-quality-workflow.md` (651 lines) - Integration guide in `.claude/agents/code-quality-guard.md` - Updated `CLAUDE.md` with "Code Quality Monitoring" section ## [8.31.0] - 2025-11-23 ### Added - **Revolutionary Batch Update Performance** - Memory consolidation now 21,428x faster with new batch update API (#241) - **Performance Improvement**: 300 seconds → 0.014 seconds for 500 memory batch updates (21,428x speedup) - **Consolidation Workflow**: Complete consolidation time reduced from 5+ minutes to <1 second for 500 memories - **New API Method**: `update_memories_batch()` in storage backends for atomic batch operations - **Implementation**: - **SQLite Backend**: Single transaction with executemany for 21,428x speedup - **Cloudflare Backend**: Parallel batch updates with proper vectorize sync - **Hybrid Backend**: Optimized dual-backend batch sync with queue processing - **Backward Compatible**: Existing single-update code paths continue working - **Real-world Impact**: Memory consolidation that previously took 5+ minutes now completes in <1 second - **Files Modified**: - `src/mcp_memory_service/storage/sqlite_vec.py` (lines 542-571): Batch update implementation - `src/mcp_memory_service/storage/cloudflare.py` (lines 673-728): Cloudflare batch updates - `src/mcp_memory_service/storage/hybrid.py` (lines 772-822): Hybrid backend batch sync - `src/mcp_memory_service/consolidation/service.py` (line 472): Using batch update in consolidation ### Performance - **Memory Consolidation**: 21,428x faster batch metadata updates (300s → 0.014s for 500 memories) - **Consolidation Workflow**: Complete workflow time reduced from 5+ minutes to <1 second for 500 memories - **Database Efficiency**: Single transaction instead of 500 individual updates with commit overhead ## [8.30.0] - 2025-11-23 ### Added - **Adaptive Chart Granularity** - Analytics charts now use semantically appropriate time intervals for better trend visualization - **Last Month view**: Changed from 3-day intervals to weekly aggregation for clearer monthly trends - **Last Year view**: Uses monthly aggregation for annual overview - **Human-readable labels**: Charts display clear interval formatting: - Daily view: "Nov 15" format - Weekly aggregation: "Week of Nov 15" format - Monthly aggregation: "November 2024" format - **Improved UX**: Better semantic alignment between time period and chart granularity - **Files Modified**: `src/mcp_memory_service/web/api/analytics.py` (lines 307-345), `src/mcp_memory_service/web/static/app.js` (line 3661) ### Fixed - **CRITICAL: Interval Aggregation Bug** - Multi-day intervals (weekly, monthly) now correctly aggregate across entire period - **Problem**: Intervals were only counting memories from the first day of the interval, not the entire period - **Impact**: Analytics showed wildly inaccurate data (e.g., 0 memories instead of 427 for Oct 24-30 week) - **Root Cause**: `strftime` format in date grouping only used the first timestamp, not the interval's date range - **Solution**: Updated aggregation logic to properly filter and count all memories within each interval - **Files Modified**: `src/mcp_memory_service/web/api/analytics.py` (lines 242-267) - **CRITICAL: Data Sampling Bug** - Analytics now fetch complete historical data with proper date range filtering - **Problem**: API only fetched 1,000 most recent memories, missing historical data for longer time periods - **Impact**: Charts showed incomplete or missing data for older time ranges - **Solution**: Increased fetch limit to 10,000 memories with proper `created_at >= start_date` filtering - **Files Modified**: `src/mcp_memory_service/web/api/analytics.py` (lines 56-62) - **Performance**: Maintains fast response times (<200ms) even with larger dataset ### Changed - **Analytics API**: Improved data fetching with larger limits and proper date filtering for accurate historical analysis ## [8.29.0] - 2025-11-23 ### Added - **Dashboard Quick Actions: Sync Controls Widget** - Compact, real-time sync management for hybrid backend users (#234, fixes #233) - **Real-time sync status indicator**: Visual states for synced/syncing/pending/error/paused with color-coded icons - **Pause/Resume controls**: Safely pause background sync for database maintenance or offline work - **Force sync button**: Manual trigger for immediate synchronization - **Sync metrics**: Display last sync time and pending operations count - **Clean layout**: Removed redundant sync status bar between header and body, moved to sidebar widget - **Backend-aware**: Widget automatically hides for sqlite-vec only users (hybrid-specific feature) - **API endpoints**: - `POST /api/sync/pause` - Pause background sync - `POST /api/sync/resume` - Resume background sync - **Hybrid backend methods**: Added `pause_sync()` and `resume_sync()` for sync control - **Automatic Scheduled Backup System** - Enterprise-grade backup with retention policies and scheduling (#234, fixes #233) - **New backup module**: `src/mcp_memory_service/backup/` with `BackupService` and `BackupScheduler` - **SQLite native backup API**: Uses safe `sqlite3.backup()` to prevent corruption (no file copying) - **Async I/O**: Non-blocking backup operations with `asyncio.to_thread` - **Flexible scheduling**: Hourly, daily, or weekly automatic backups - **Retention policies**: Configurable by days and max backup count - **Dashboard widget**: Backup status, last backup time, manual trigger, backup count, next scheduled time - **Configuration via environment variables**: - `MCP_BACKUP_ENABLED=true` (default: true) - `MCP_BACKUP_INTERVAL=daily` (hourly/daily/weekly, default: daily) - `MCP_BACKUP_RETENTION=7` (days, default: 7) - `MCP_BACKUP_MAX_COUNT=10` (max backups, default: 10) - **API endpoints**: - `GET /api/backup/status` - Get backup status and scheduler info - `POST /api/backup/now` - Trigger manual backup - `GET /api/backup/list` - List available backups with metadata - **Security**: OAuth protection on backup endpoints, no file path exposure in responses - **Safari compatibility**: Improved event listener handling with lazy initialization ### Changed - **Quick Actions Layout**: Moved sync controls from top status bar to sidebar widget for cleaner, more accessible UI - **Sync State Persistence**: Pause state is now preserved during force sync operations - **Dashboard Feedback**: Added toast notifications for sync and backup operations ### Fixed - **Sync Button Click Events**: Resolved DOM timing issues with lazy event listeners for reliable button interactions - **Spinner Animation**: Fixed syncing state visual feedback with proper CSS animations - **Security**: Removed file path exposure from backup API responses (used backup IDs instead) ## [8.28.1] - 2025-11-22 ### Fixed - **CRITICAL: HTTP MCP Transport JSON-RPC 2.0 Compliance** - Fixed protocol violation causing Claude Code rejection (#236) - **Problem**: HTTP MCP server returned `"error": null` in successful responses, violating JSON-RPC 2.0 spec which requires successful responses to OMIT the error field entirely (not include it as null) - **Impact**: Claude Code's strict schema validation rejected all HTTP MCP responses with "Unrecognized key(s) in object: 'error'" errors, making HTTP transport completely unusable - **Root Cause**: MCPResponse Pydantic model included both `result` and `error` fields in all responses, serializing null values - **Solution**: - Added `ConfigDict(exclude_none=True)` to MCPResponse model to exclude null fields from serialization - Updated docstring to document JSON-RPC 2.0 compliance requirements - Replaced deprecated `.dict()` with `.model_dump()` for Pydantic V2 compatibility - Moved json import to top of file per PEP 8 style guidelines - **Files Modified**: - `src/mcp_memory_service/web/api/mcp.py` - Added ConfigDict, updated serialization - **Affected Users**: All users attempting to use HTTP MCP transport with Claude Code or other strict JSON-RPC 2.0 clients - **Testing**: Verified successful responses exclude `error` field and error responses exclude `result` field - **Credits**: Thanks to @timkjr for identifying the issue and providing the fix ## [8.28.0] - 2025-11-21 ### Added - **Cloudflare Tag Filtering** - AND/OR operations for tag searches with unified API contracts (#228) - Added `search_by_tags(tags, operation, time_start, time_end)` to the storage base class and implemented it across SQLite, Cloudflare, Hybrid, and HTTP client backends - Normalized Cloudflare SQL to use `GROUP BY` + `HAVING COUNT(DISTINCT ...)` for AND semantics while supporting optional time ranges - Introduced `get_all_tags_with_counts()` for Cloudflare to power analytics dashboards without extra queries ### Changed - **Tag Filtering Behavior** - `get_all_memories(tags=...)` now performs exact tag comparisons with AND logic instead of substring OR matching, and hybrid storage exposes the same `operation` parameter for parity across backends. ## [8.27.2] - 2025-11-18 ### Fixed - **Memory Type Loss During Cloudflare-to-SQLite Sync** - Fixed `memory_type` not being preserved in sync script - **Problem**: `scripts/sync/sync_memory_backends.py` did not extract or pass `memory_type` when syncing from Cloudflare to SQLite-vec - **Impact**: All memories synced via `--direction cf-to-sqlite` showed as "untyped" (100%) in dashboard analytics - **Root Cause**: Missing `memory_type` field in both memory dict extraction and Memory object creation - **Solution**: - Added `memory_type` to memory dictionary extraction from source - Added `memory_type` and `updated_at` parameters when creating Memory objects for target storage - **Files Modified**: - `scripts/sync/sync_memory_backends.py` - Added memory_type and updated_at handling - **Affected Users**: Users who ran `python scripts/sync/sync_memory_backends.py --direction cf-to-sqlite` - **Recovery**: Re-run sync from Cloudflare to restore memory types (Cloudflare preserves original types) ## [8.27.1] - 2025-11-18 ### Fixed - **CRITICAL: Timestamp Regression Bug** - Fixed `created_at` timestamps being reset during metadata sync - **Problem**: Bidirectional sync and drift detection (v8.25.0-v8.27.0) incorrectly reset `created_at` timestamps to current time during metadata updates - **Impact**: All memories synced from Cloudflare → SQLite-vec appeared "just created", destroying historical timestamp data - **Root Cause**: `preserve_timestamps=False` parameter reset **both** `created_at` and `updated_at`, when it should only update `updated_at` - **Solution**: - Modified `update_memory_metadata()` to preserve `created_at` from source memory during sync - Hybrid storage now passes all 4 timestamp fields (`created_at`, `created_at_iso`, `updated_at`, `updated_at_iso`) during drift detection - Cloudflare storage updated to handle timestamps consistently with SQLite-vec - **Files Modified**: - `src/mcp_memory_service/storage/sqlite_vec.py:1389-1406` - Fixed timestamp handling logic - `src/mcp_memory_service/storage/hybrid.py:625-637, 935-947` - Pass source timestamps during sync - `src/mcp_memory_service/storage/cloudflare.py:833-864` - Consistent timestamp handling - **Tests Added**: `tests/test_timestamp_preservation.py` - Comprehensive test suite with 7 tests covering: - Timestamp preservation with `preserve_timestamps=True` - Regression test for `created_at` preservation without source timestamps - Drift detection scenario - Multiple sync operations - Initial memory storage - **Recovery Tools**: - `scripts/validation/validate_timestamp_integrity.py` - Detect timestamp anomalies - `scripts/maintenance/recover_timestamps_from_cloudflare.py` - Restore corrupted timestamps from Cloudflare - **Affected Versions**: v8.25.0 (drift detection), v8.27.0 (bidirectional sync) - **Affected Users**: Hybrid backend users who experienced automatic drift detection or initial sync - **Data Recovery**: If using hybrid backend and Cloudflare has correct timestamps, run recovery script: ```bash # Preview recovery python scripts/maintenance/recover_timestamps_from_cloudflare.py --dry-run # Apply recovery python scripts/maintenance/recover_timestamps_from_cloudflare.py --apply ``` ### Changed - **Timestamp Handling Semantics** - Clarified `preserve_timestamps` parameter behavior: - `preserve_timestamps=True` (default): Only updates `updated_at` to current time, preserves `created_at` - `preserve_timestamps=False`: Uses timestamps from `updates` dict if provided, otherwise preserves existing `created_at` - **Never** resets `created_at` to current time (this was the bug) ### Added - **Timestamp Integrity Validation** - New script to detect timestamp anomalies: ```bash python scripts/validation/validate_timestamp_integrity.py ``` - Checks for impossible timestamps (`created_at > updated_at`) - Detects suspicious timestamp clusters (bulk reset indicators) - Analyzes timestamp distribution for anomalies - Provides detailed statistics and warnings ## [8.27.0] - 2025-11-17 ### Added - **Hybrid Storage Sync Performance Optimization** - Dramatic initial sync speed improvement (3-5x faster) - **Performance Metrics**: - **Before**: ~5.5 memories/second (8 minutes for 2,619 memories) - **After**: ~15-30 memories/second (1.5-3 minutes for 2,619 memories) - **3-5x faster** initial sync from Cloudflare to local SQLite - **Optimizations**: - **Bulk Existence Check**: `get_all_content_hashes()` method eliminates 2,619 individual DB queries - **Parallel Processing**: `asyncio.gather()` with Semaphore(15) for concurrent memory processing - **Larger Batch Sizes**: Increased from 100 to 500 memories per Cloudflare API call (5x fewer requests) - **Files Modified**: - `src/mcp_memory_service/storage/sqlite_vec.py` - Added `get_all_content_hashes()` method (lines 1208-1227) - `src/mcp_memory_service/storage/hybrid.py` - Parallel sync implementation (lines 859-921) - `scripts/benchmarks/benchmark_hybrid_sync.py` - Performance validation script - **Backward Compatibility**: Zero breaking changes, transparent optimization for all sync operations - **Use Case**: Users with large memory databases (1000+ memories) will see significantly faster initial sync times ### Changed - **Hybrid Initial Sync Architecture** - Refactored sync loop for better performance - O(1) hash lookups instead of O(n) individual queries - Concurrent processing with controlled parallelism (15 simultaneous operations) - Reduced Cloudflare API overhead with larger batches (6 API calls vs 27) - Maintains full drift detection and metadata synchronization capabilities ### Fixed - **Duplicate Sync Queue Architecture** - Resolved inefficient dual-sync issue - **Problem**: MCP server and HTTP server each created separate HybridStorage instances with independent sync queues - **Impact**: Duplicate sync work, potential race conditions, memory not immediately visible across servers - **Solution**: New `MCP_HYBRID_SYNC_OWNER` configuration to control which process handles Cloudflare sync - **Configuration Options**: - `"http"` - HTTP server only handles sync (recommended - avoids duplicate work) - `"mcp"` - MCP server only handles sync - `"both"` - Both servers sync independently (default for backward compatibility) - **Files Modified**: - `src/mcp_memory_service/config.py` - Added `HYBRID_SYNC_OWNER` configuration (lines 424-427) - `src/mcp_memory_service/storage/factory.py` - Server-type aware storage creation (lines 76-110) - `src/mcp_memory_service/mcp_server.py` - Pass server_type="mcp" (line 143) - `src/mcp_memory_service/web/dependencies.py` - Pass server_type="http" (line 65) - **Migration Guide**: ```bash # Recommended: Set HTTP server as sync owner to eliminate duplicate sync export MCP_HYBRID_SYNC_OWNER=http ``` - **Backward Compatibility**: Defaults to "both" (existing behavior), no breaking changes ### Performance - **Benchmark Results** (`python scripts/benchmarks/benchmark_hybrid_sync.py`): - Bulk hash loading: 2,619 hashes loaded in ~100ms (vs ~13,000ms for individual queries) - Parallel processing: 15x concurrency reduces CPU idle time - Batch size optimization: 78% reduction in API calls (27 → 6 for 2,619 memories) - Combined speedup: 3-5x faster initial sync ## [8.26.0] - 2025-11-16 ### Added - **Global MCP Server Caching** - Revolutionary performance improvement for MCP tools (PR #227) - **Performance Metrics**: - **534,628x faster** on cache hits (1,810ms → 0.01ms per MCP tool call) - **99.9996% latency reduction** for cached operations - **90%+ cache hit rate** in normal usage patterns - **MCP tools now 41x faster** than HTTP API after warm-up - **New MCP Tool**: `get_cache_stats` - Real-time cache performance monitoring - Track hits/misses, hit rate percentage - Monitor storage and service cache sizes - View initialization time statistics (avg/min/max) - **Infrastructure**: - Global cache structures: `_STORAGE_CACHE`, `_MEMORY_SERVICE_CACHE`, `_CACHE_STATS` - Thread-safe concurrent access via `asyncio.Lock` - Automatic cleanup on server shutdown (no memory leaks) - **Files Modified**: - `src/mcp_memory_service/server.py` - Production MCP server caching - `src/mcp_memory_service/mcp_server.py` - FastMCP server caching - `src/mcp_memory_service/utils/cache_manager.py` - New cache management utilities - `scripts/benchmarks/benchmark_server_caching.py` - Cache effectiveness validation - **Backward Compatibility**: Zero breaking changes, transparent caching for all MCP clients - **Use Case**: MCP tools in Claude Desktop and Claude Code are now the fastest method for memory operations ### Changed - **Code Quality Improvements** - Gemini Code Assist review implementation (PR #227) - Eliminated code duplication across `server.py` and `mcp_server.py` - Created shared `CacheManager.calculate_stats()` utility for statistics - Enhanced PEP 8 compliance with proper naming conventions - Added comprehensive inline documentation for cache implementation ### Fixed - **Security Vulnerability** - Removed unsafe `eval()` usage in benchmark script (PR #227) - Replaced `eval(stats_str)` with safe `json.loads()` for parsing cache statistics - Eliminated arbitrary code execution risk in development tools - Improved benchmark script robustness ### Performance - **Benchmark Results** (10 consecutive MCP tool calls): - First Call (Cache Miss): ~2,485ms - Cached Calls Average: ~0.01ms - Speedup Factor: 534,628x - Cache Hit Rate: 90% - **Impact**: MCP tools are now the recommended method for Claude Desktop and Claude Code users - **Technical Details**: - Caches persist across stateless HTTP calls - Storage instances keyed by "{backend}:{path}" - MemoryService instances keyed by storage ID - Lazy initialization preserved to prevent startup hangs ### Documentation - Updated Wiki: 05-Performance-Optimization.md with cache architecture - Added cache monitoring guide using `get_cache_stats` tool - Performance comparison tables now show MCP as fastest method ## [8.25.2] - 2025-11-16 ### Changed - **Drift Detection Script Refactoring** - Improved code maintainability in `check_drift.py` (PR #226) - **Refactored**: Cloudflare config dictionary construction to use dictionary comprehension - **Improvement**: Separated configuration keys list from transformation logic - **Benefit**: Easier to maintain and modify configuration keys - **Code Quality**: More Pythonic, cleaner, and more readable - **Impact**: No functional changes, pure code quality improvement - **File Modified**: `scripts/sync/check_drift.py` - **Credit**: Implements Gemini code review suggestions from PR #224 ## [8.25.1] - 2025-11-16 ### Fixed - **Drift Detection Script Initialization** - Corrected critical bugs in `check_drift.py` (PR #224) - **Bug 1**: Fixed incorrect config attribute `SQLITE_DB_PATH` → `SQLITE_VEC_PATH` in AppConfig - **Bug 2**: Added missing `cloudflare_config` parameter to HybridMemoryStorage initialization - **Impact**: Script was completely broken for Cloudflare/Hybrid backends - now initializes successfully - **Error prevented**: `AttributeError: 'AppConfig' object has no attribute 'SQLITE_DB_PATH'` - **File Modified**: `scripts/sync/check_drift.py` - **Severity**: High - Script was non-functional for users with hybrid or cloudflare backends - **CI Test Infrastructure** - Added HuggingFace model caching to prevent network-related test failures (PR #225) - **Root Cause**: GitHub Actions runners cannot access huggingface.co during test runs - **Solution**: Implemented `actions/cache@v3` for `~/.cache/huggingface` directory - **Pre-download step**: Downloads `all-MiniLM-L6-v2` model after dependency installation - **Impact**: Fixes all future PR test failures caused by model download restrictions - **Cache Strategy**: Key includes `pyproject.toml` hash for dependency tracking - **Performance**: First run downloads model, subsequent runs use cache - **File Modified**: `.github/workflows/main.yml` ### Technical Details - **PR #224**: Drift detection script now properly initializes Cloudflare backend with all required parameters (api_token, account_id, d1_database_id, vectorize_index) - **PR #225**: CI environment now caches embedding models, eliminating network dependency during test execution - **Testing**: Both fixes validated in PR test runs - drift detection now works, tests pass consistently ## [8.25.0] - 2025-11-15 ### Added - **Hybrid Backend Drift Detection** - Automatic metadata synchronization using `updated_at` timestamps (issue #202) - **Bidirectional awareness**: Detects metadata changes on either backend (SQLite-vec ↔ Cloudflare) - **Periodic drift checks**: Configurable interval via `MCP_HYBRID_DRIFT_CHECK_INTERVAL` (default: 1 hour) - **"Newer timestamp wins" conflict resolution**: Prevents data loss during metadata updates - **Dry-run support**: Preview changes via `python scripts/sync/check_drift.py` - **New configuration variables**: - `MCP_HYBRID_SYNC_UPDATES` - Enable metadata sync (default: true) - `MCP_HYBRID_DRIFT_CHECK_INTERVAL` - Seconds between drift checks (default: 3600) - `MCP_HYBRID_DRIFT_BATCH_SIZE` - Memories to check per scan (default: 100) - **New methods**: - `BackgroundSyncService._detect_and_sync_drift()` - Core drift detection logic with dry-run mode - `CloudflareStorage.get_memories_updated_since()` - Query memories by update timestamp - **Enhanced initial sync**: Now detects and syncs metadata drift for existing memories ### Fixed - **Issue #202** - Hybrid backend now syncs metadata updates (tags, types, custom fields) - Previous behavior only detected missing memories, ignoring metadata changes - Prevented silent data loss when memories updated on one backend but not synced - Tag fixes in Cloudflare now properly propagate to local SQLite - Metadata updates no longer diverge between backends ### Changed - Initial sync (`_perform_initial_sync`) now compares timestamps for existing memories - Periodic sync includes drift detection checks at configurable intervals - Sync statistics tracking expanded with drift detection metrics ### Technical Details - **Files Modified**: - `src/mcp_memory_service/config.py` - Added 3 configuration variables - `src/mcp_memory_service/storage/hybrid.py` - Drift detection implementation (~150 lines) - `src/mcp_memory_service/storage/cloudflare.py` - Added `get_memories_updated_since()` method - `scripts/sync/check_drift.py` - New dry-run validation script - **Architecture**: Timestamp-based drift detection with 1-second clock skew tolerance - **Performance**: Non-blocking async operations, configurable batch sizes - **Safety**: Opt-in feature, dry-run mode, comprehensive audit logging ## [8.24.4] - 2025-11-15 ### Changed - **Code Quality Improvements** - Applied Gemini Code Assist review suggestions (issue #180) - **documents.py:87** - Replaced chained `.replace()` calls with `re.sub()` for path separator sanitization - **app.js:751-762** - Cached DOM elements in setProcessingMode to reduce query overhead - **app.js:551-553, 778-780** - Cached upload option elements to optimize handleDocumentUpload - **index.html:357, 570** - Fixed indentation consistency for closing `</div>` tags - Performance impact: Minor - reduced DOM query overhead - Breaking changes: None ### Technical Details - **Files Modified**: `src/mcp_memory_service/web/api/documents.py`, `src/mcp_memory_service/web/static/app.js`, `src/mcp_memory_service/web/static/index.html` - **Code Quality**: Regex-based sanitization more scalable, DOM element caching reduces redundant queries - **Commit**: ffc6246 - refactor: code quality improvements from Gemini review (issue #180) ## [8.24.3] - 2025-11-15 ### Fixed - **GitHub Release Manager Agent** - Resolved systematic version history omission in README.md (commit ccf959a) - Fixed agent behavior that was omitting previous versions from "Previous Releases" section - Added v8.24.1 to Previous Releases list (was missing despite being valid release) - Enhanced agent instructions with CRITICAL section for maintaining version history integrity - Added quality assurance checklist item to prevent future omissions - Root cause: Agent was replacing entire Previous Releases section instead of prepending new version ### Added - **Test Coverage for Tag+Time Filtering** - Comprehensive test suite for issue #216 (commit ebff282) - 10 unit tests passing across SQLite-vec, Cloudflare, and Hybrid backends - Validates PR #215 functionality (tag+time filtering to fix semantic over-filtering bug #214) - Tests verify memories can be retrieved using both tag criteria AND time range filters - API integration tests created (with known threading issues documented for future fix) - Ensures regression prevention for semantic search over-filtering bug ### Changed - GitHub release workflow now more reliable with enhanced agent guardrails - Test suite provides better coverage for multi-filter memory retrieval scenarios ### Technical Details - **Files Modified**: - `.claude/agents/github-release-manager.md` - Added CRITICAL section for Previous Releases maintenance - `tests/test_time_filtering.py` - 10 new unit tests for tag+time filtering - `tests/integration/test_api_time_search.py` - API integration tests (threading issues documented) - **Test Execution**: All 10 unit tests passing, API tests have known threading limitations - **Impact**: Prevents version history loss in future releases, ensures tag+time filtering remains functional ## [8.24.2] - 2025-11-15 ### Fixed - **CI/CD Workflow Infrastructure** - Development Setup Validation workflow fixes (issue #217 related) - Fixed bash errexit handling in workflow tests - prevents premature exit on intentional test failures - Corrected exit code capture using EXIT_CODE=0 and || EXIT_CODE=$? pattern - All 5 workflow tests now passing: version consistency, pre-commit hooks, server warnings, developer prompts, docs accuracy - Root cause: bash runs with -e flag (errexit), which exits immediately when commands return non-zero exit codes - Tests intentionally run check_dev_setup.py expecting exit code 1, but bash was exiting before capture - Commits: b4f9a5a, d1bcd67 ### Changed - Workflow tests can now properly validate that the development setup validator correctly detects problems - Exit code capture no longer uses "|| true" pattern (was making all commands return 0) ### Technical Details - **Files Modified**: .github/workflows/dev-setup-validation.yml - **Pattern Change**: - Before: `python script.py || true` (always returns 0, breaks exit code testing) - After: `EXIT_CODE=0; python script.py || EXIT_CODE=$?` (captures actual exit code, prevents bash exit) - **Test Jobs**: All 5 jobs in dev-setup-validation workflow now pass consistently - **Context**: Part of test infrastructure improvement efforts (issue #217) ## [8.24.1] - 2025-11-15 ### Fixed - **Test Infrastructure Failures** - Resolved 27 pre-existing test failures (issue #217) - Fixed async fixture incompatibility in 6 test files (19+ failures) - Corrected missing imports (MCPMemoryServer → MemoryServer, removed MemoryMetadata) - Added missing content_hash parameter to Memory() instantiations - Updated hardcoded version strings (6.3.0 → 8.24.0) - Improved test pass rate from 63% to 71% (412/584 tests passing) - Execution: Automated via amp-bridge agent ### Changed - Test suite now has cleaner baseline for detecting new regressions - All async test fixtures now use @pytest_asyncio.fixture decorator ### Technical Details - **Automated Fix**: Used amp-bridge agent for pattern-based refactoring - **Execution Time**: ~15 minutes (vs 1-2 hours manual) - **Files Modified**: 11 test files across tests/ and tests/integration/ - **Root Causes**: Test infrastructure issues, not code bugs - **Remaining Failures**: 172 failures remain (backend config, performance, actual bugs) ## [8.24.0] - 2025-11-12 ### Added - **PyPI Publishing Automation** - Package now available via `pip install mcp-memory-service` - **Workflow Automation**: Configured GitHub Actions workflow to automatically publish to PyPI on tag pushes - **Installation Simplification**: Users can now install directly via `pip install mcp-memory-service` or `uv pip install mcp-memory-service` - **Accessibility**: Resolves installation barriers for users without git access or familiarity - **Token Configuration**: Secured with `PYPI_TOKEN` GitHub secret for automated publishing - **Quality Gates**: Publishes only after successful test suite execution ### Changed - **Distribution Method**: Added PyPI as primary distribution channel alongside GitHub releases - **Installation Documentation**: Updated guides to include pip-based installation as recommended method ### Technical Details - **Files Modified**: - `.github/workflows/publish.yml` - NEW workflow for automated PyPI publishing - GitHub repository secrets - Added `PYPI_TOKEN` for authentication - **Trigger**: Workflow runs automatically on git tag creation (pattern: `v*.*.*`) - **Build System**: Uses Hatchling build backend with `python-semantic-release` ### Migration Notes - **For New Users**: Preferred installation is now `pip install mcp-memory-service` - **For Existing Users**: No action required - git-based installation continues to work - **For Contributors**: Tag creation now triggers PyPI publishing automatically ## [8.23.1] - 2025-11-10 ### Fixed - **Stale Virtual Environment Prevention System** - Comprehensive 6-layer strategy to prevent "stale venv vs source code" version mismatches - **Root Cause**: MCP servers load from site-packages, not source files. System restart doesn't help - it relaunches with same stale package - **Impact**: Prevented issue that caused v8.23.0 tag validation bug to persist despite v8.22.2 fix (source showed v8.23.0 while venv had v8.5.3) ### Added - **Phase 1: Automated Detection** - New `scripts/validation/check_dev_setup.py` - Validates source/venv version consistency, detects editable installs - Enhanced `scripts/hooks/pre-commit` - Blocks commits when venv is stale, provides actionable error messages - Added CLAUDE.md development setup section with explicit `pip install -e .` guidance - **Phase 2: Runtime Warnings** - Added `check_version_consistency()` function in `src/mcp_memory_service/server.py` - Server startup warnings when version mismatch detected (source vs package) - Updated README.md developer section with editable install instructions - Enhanced `docs/development/ai-agent-instructions.md` with proper setup commands - **Phase 3: Interactive Onboarding** - Enhanced `scripts/installation/install.py` with developer detection (checks for git repo) - Interactive prompt guides developers to use `pip install -e .` for editable installs - New CI/CD workflow `.github/workflows/dev-setup-validation.yml` with 5 comprehensive test jobs: 1. Version consistency validation 2. Pre-commit hook functionality 3. Server startup warnings 4. Interactive developer prompts 5. Documentation accuracy checks ### Changed - **Developer Workflow**: Developers now automatically guided to use `pip install -e .` for proper setup - **Pre-commit Hook**: Now validates venv consistency before allowing commits - **Installation Process**: Detects developer mode and provides targeted guidance ### Technical Details - **6-Layer Prevention System**: 1. **Development**: Pre-commit hook blocks bad commits, detection script validates setup 2. **Runtime**: Server startup warnings catch edge cases 3. **Documentation**: CLAUDE.md, README.md, ai-agent-instructions.md all updated 4. **Automation**: check_dev_setup.py, pre-commit hook, CI/CD workflow 5. **Interactive**: install.py prompts developers for editable install 6. **Testing**: CI/CD workflow with 5 comprehensive test jobs - **Files Modified**: - `scripts/validation/check_dev_setup.py` - NEW automated detection script - `scripts/hooks/pre-commit` - Enhanced with venv validation - `CLAUDE.md` - Added development setup guidance - `src/mcp_memory_service/server.py` - Added runtime version check - `README.md` - Updated developer section - `docs/development/ai-agent-instructions.md` - Updated setup commands - `scripts/installation/install.py` - Added developer detection - `.github/workflows/dev-setup-validation.yml` - NEW CI/CD validation ### Migration Notes - **For Developers**: Run `pip install -e .` to install in editable mode (will be prompted by install.py) - **For Users**: No action required - prevention system is transparent for production use - **Pre-commit Hook**: Automatically installed during `install.py`, validates on every commit ### Commits Included - `670fb74` - Phase 1: Automated detection (check_dev_setup.py, pre-commit hook, CLAUDE.md) - `9537259` - Phase 2: Runtime warnings (server.py) + developer documentation - `a17bcc7` - Phase 3: Interactive onboarding (install.py) + CI/CD validation