mcp-sqlite-memory-bank 1.4.3__py3-none-any.whl → 1.5.1__py3-none-any.whl

mcp_sqlite_memory_bank/server.py

@@ -50,6 +50,7 @@ from typing import Dict, Optional, List, cast, Any
 from fastmcp import FastMCP
 
 from .database import get_database
+from .semantic import is_semantic_search_available
 from .types import (
     ToolResponse,
     CreateTableResponse,
@@ -68,6 +69,9 @@ from .utils import catch_errors
 from .resources import setup_mcp_resources
 from .prompts import setup_mcp_prompts
 
+# Import modular tool implementations (for aliases only)
+from .tools import basic, search, analytics
+
 # Initialize FastMCP app with explicit name
 mcp: FastMCP = FastMCP("SQLite Memory Bank for Copilot/AI Agents")
 
@@ -86,6 +90,9 @@ setup_mcp_resources(mcp, DB_PATH)
 # Set up MCP Prompts for enhanced workflow support
 setup_mcp_prompts(mcp, DB_PATH)
 
+# All tools are registered via @mcp.tool decorators below
+# No explicit registration needed - decorators handle this automatically
+
 
 # --- Schema Management Tools for SQLite Memory Bank ---
 
@@ -392,12 +399,32 @@ def list_all_columns() -> ToolResponse:
     return cast(ListAllColumnsResponse, get_database(DB_PATH).list_all_columns())
 
 
-# --- Content Search and Exploration Tools ---
+# Import the implementation functions from tools modules
+from .tools.search import (
+    search_content as search_content_impl,
+    explore_tables as explore_tables_impl, 
+    add_embeddings as add_embeddings_impl,
+    auto_semantic_search as auto_semantic_search_impl,
+    auto_smart_search as auto_smart_search_impl,
+    embedding_stats as embedding_stats_impl,
+)
+
+# Import the implementation functions from discovery module  
+from .tools.discovery import (
+    intelligent_discovery as intelligent_discovery_impl,
+    discovery_templates as discovery_templates_impl,
+    discover_relationships as discover_relationships_impl,
+)
 
+# --- MCP Tool Definitions (Required in main server.py for FastMCP) ---
 
 @mcp.tool
 @catch_errors
-def search_content(query: str, tables: Optional[List[str]] = None, limit: int = 50) -> ToolResponse:
+def search_content(
+    query: str,
+    tables: Optional[List[str]] = None,
+    limit: int = 50,
+) -> ToolResponse:
     """
     Perform full-text search across table content using natural language queries.
 
@@ -424,12 +451,15 @@ def search_content(query: str, tables: Optional[List[str]] = None, limit: int =
         - Supports phrase search with quotes: "exact phrase"
         - Supports boolean operators: AND, OR, NOT
     """
-    return cast(ToolResponse, get_database(DB_PATH).search_content(query, tables, limit))
+    return search_content_impl(query, tables, limit)
 
 
 @mcp.tool
-@catch_errors
-def explore_tables(pattern: Optional[str] = None, include_row_counts: bool = True) -> ToolResponse:
+@catch_errors  
+def explore_tables(
+    pattern: Optional[str] = None,
+    include_row_counts: bool = True,
+) -> ToolResponse:
     """
     Explore and discover table structures and content for better searchability.
 
@@ -458,22 +488,22 @@ def explore_tables(pattern: Optional[str] = None, include_row_counts: bool = Tru
         - Helps understand what data is available for searching
         - Useful for exploratory data analysis
     """
-    return cast(ToolResponse, get_database(DB_PATH).explore_tables(pattern, include_row_counts))
-
-
-# --- Semantic Search and AI-Enhanced Discovery Tools ---
+    return explore_tables_impl(pattern, include_row_counts)
 
 
 @mcp.tool
 @catch_errors
 def add_embeddings(
-    table_name: str, text_columns: List[str], embedding_column: str = "embedding", model_name: str = "all-MiniLM-L6-v2"
+    table_name: str,
+    text_columns: List[str],
+    embedding_column: str = "embedding",
+    model_name: str = "all-MiniLM-L6-v2",
 ) -> ToolResponse:
     """
     ⚠️  **ADVANCED TOOL** - Most agents should use auto_smart_search() instead!
-    
+
     Generate and store vector embeddings for semantic search on table content.
-    
+
     **RECOMMENDATION**: Use auto_smart_search() or auto_semantic_search() for automatic setup.
     This tool is for advanced users who need manual control over embedding generation.
 
@@ -501,14 +531,12 @@ def add_embeddings(
         - Uses efficient batch processing for large datasets
         - Supports various sentence-transformer models for different use cases
     """
-    return cast(
-        ToolResponse, get_database(DB_PATH).generate_embeddings(table_name, text_columns, embedding_column, model_name)
-    )
+    return add_embeddings_impl(table_name, text_columns, embedding_column, model_name)
 
 
 @mcp.tool
 @catch_errors
-def semantic_search(
+def auto_semantic_search(
     query: str,
     tables: Optional[List[str]] = None,
     similarity_threshold: float = 0.5,
@@ -516,102 +544,48 @@ def semantic_search(
     model_name: str = "all-MiniLM-L6-v2",
 ) -> ToolResponse:
     """
-    ⚠️  **ADVANCED TOOL** - Most agents should use auto_smart_search() instead!
-    
-    Find content using natural language semantic similarity rather than exact keyword matching.
-    
-    **RECOMMENDATION**: Use auto_smart_search() for automatic setup and hybrid search capabilities.
-    This tool requires manual embedding setup via add_embeddings() first.
+    🚀 **ZERO-SETUP SEMANTIC SEARCH** - Just search, embeddings are handled automatically!
 
-    This enables intelligent knowledge discovery - find related concepts even when
-    they use different terminology or phrasing.
+    Find content using natural language semantic similarity. If embeddings don't exist,
+    they will be automatically generated for text columns. This is the easiest way to
+    do semantic search - no manual setup required!
 
     Args:
         query (str): Natural language search query
-        tables (Optional[List[str]]): Specific tables to search (default: all tables with embeddings)
+        tables (Optional[List[str]]): Specific tables to search (default: all tables)
         similarity_threshold (float): Minimum similarity score (0.0-1.0, default: 0.5)
         limit (int): Maximum number of results to return (default: 10)
-        model_name (str): Model to use for query embedding (default: "all-MiniLM-L6-v2")
+        model_name (str): Model to use for embeddings (default: "all-MiniLM-L6-v2")
 
     Returns:
-        ToolResponse: On success: {"success": True, "results": List[...], "total_results": int}
+        ToolResponse: On success: {"success": True, "results": List[...], "auto_embedded_tables": List[str]}
                      On error: {"success": False, "error": str, "category": str, "details": dict}
 
     Examples:
-        >>> semantic_search("API design patterns")
+        >>> auto_semantic_search("API design patterns")
         {"success": True, "results": [
-            {"table_name": "technical_decisions", "similarity_score": 0.87, "decision_name": "REST API Structure", ...},
-            {"table_name": "project_structure", "similarity_score": 0.72, "component": "API Gateway", ...}
-        ]}
+            {"table_name": "technical_decisions", "similarity_score": 0.87, "decision_name": "REST API Structure", ...}
+        ], "auto_embedded_tables": ["technical_decisions"]}
 
-        >>> semantic_search("machine learning", tables=["technical_decisions"], similarity_threshold=0.7)
+        >>> auto_semantic_search("machine learning concepts")
         # Finds content about "ML", "AI", "neural networks", etc.
+        # Automatically creates embeddings if they don't exist!
 
     FastMCP Tool Info:
+        - **COMPLETELY AUTOMATIC**: No manual embedding setup required
+        - Auto-detects text columns and creates embeddings as needed
         - Works across multiple tables simultaneously
         - Finds conceptually similar content regardless of exact wording
         - Returns relevance scores for ranking results
         - Supports fuzzy matching and concept discovery
-        - Much more powerful than keyword-based search for knowledge discovery
-    """
-    return cast(
-        ToolResponse,
-        get_database(DB_PATH).semantic_search(
-            query, tables, "embedding", None, similarity_threshold, limit, model_name
-        ),
-    )
-
-
-@mcp.tool
-@catch_errors
-def find_related(
-    table_name: str,
-    row_id: int,
-    similarity_threshold: float = 0.5,
-    limit: int = 5,
-    model_name: str = "all-MiniLM-L6-v2",
-) -> ToolResponse:
-    """
-    Find content related to a specific row by semantic similarity.
-
-    Discover connections and related information that might not be obvious
-    from direct references or tags.
-
-    Args:
-        table_name (str): Table containing the reference row
-        row_id (int): ID of the row to find related content for
-        similarity_threshold (float): Minimum similarity score (default: 0.5)
-        limit (int): Maximum number of related items to return (default: 5)
-        model_name (str): Model for similarity comparison (default: "all-MiniLM-L6-v2")
-
-    Returns:
-        ToolResponse: On success: {"success": True, "results": List[...], "target_row": Dict}
-                     On error: {"success": False, "error": str, "category": str, "details": dict}
-
-    Examples:
-        >>> find_related("technical_decisions", 5)
-        {"success": True, "results": [
-            {"id": 12, "similarity_score": 0.84, "decision_name": "Related Architecture Choice", ...},
-            {"id": 3, "similarity_score": 0.71, "decision_name": "Similar Technology Decision", ...}
-        ], "target_row": {"id": 5, "decision_name": "API Framework Selection", ...}}
-
-    FastMCP Tool Info:
-        - Helps discover hidden relationships between data
-        - Useful for finding similar decisions, related problems, or connected concepts
-        - Can reveal patterns and themes across your knowledge base
-        - Enables serendipitous discovery of relevant information
+        - Perfect for agents - just search and it works!
     """
-    return cast(
-        ToolResponse,
-        get_database(DB_PATH).find_related_content(
-            table_name, row_id, "embedding", similarity_threshold, limit, model_name
-        ),
-    )
+    return auto_semantic_search_impl(query, tables, similarity_threshold, limit, model_name)
 
 
 @mcp.tool
 @catch_errors
-def smart_search(
+def auto_smart_search(
     query: str,
     tables: Optional[List[str]] = None,
     semantic_weight: float = 0.7,
@@ -620,15 +594,11 @@ def smart_search(
     model_name: str = "all-MiniLM-L6-v2",
 ) -> ToolResponse:
     """
-    ⚠️  **ADVANCED TOOL** - Most agents should use auto_smart_search() instead!
-    
-    Intelligent hybrid search combining semantic understanding with keyword matching.
-    
-    **RECOMMENDATION**: Use auto_smart_search() for the same functionality with automatic setup.
-    This tool requires manual embedding setup via add_embeddings() first.
+    🚀 **ZERO-SETUP HYBRID SEARCH** - Best of both worlds with automatic embedding!
 
-    Provides the best of both worlds - semantic similarity for concept discovery
-    plus exact text matching for precise searches.
+    Intelligent hybrid search combining semantic understanding with keyword matching.
+    Automatically generates embeddings for text columns when needed. This is the
+    ultimate search tool - no manual setup required!
 
     Args:
         query (str): Search query (natural language or keywords)
@@ -639,37 +609,63 @@ def smart_search(
         model_name (str): Semantic model to use (default: "all-MiniLM-L6-v2")
 
     Returns:
-        ToolResponse: On success: {"success": True, "results": List[...], "search_type": "hybrid"}
+        ToolResponse: On success: {"success": True, "results": List[...], "search_type": "auto_hybrid"}
                      On error: {"success": False, "error": str, "category": str, "details": dict}
 
     Examples:
-        >>> smart_search("user authentication security")
+        >>> auto_smart_search("user authentication security")
         {"success": True, "results": [
-            {"combined_score": 0.89, "semantic_score": 0.92, "text_score": 0.82, ...},
-            {"combined_score": 0.76, "semantic_score": 0.71, "text_score": 0.85, ...}
-        ], "search_type": "hybrid"}
+            {"combined_score": 0.89, "semantic_score": 0.92, "text_score": 0.82, ...}
+        ], "search_type": "auto_hybrid", "auto_embedded_tables": ["user_data"]}
 
     FastMCP Tool Info:
+        - **COMPLETELY AUTOMATIC**: No manual embedding setup required
         - Automatically balances semantic and keyword search
+        - Auto-detects text columns and creates embeddings as needed
         - Provides separate scores for transparency
         - Falls back gracefully if semantic search unavailable
         - Optimal for both exploratory and precise searches
         - Perfect for agents - ultimate search tool that just works!
     """
-    return cast(
-        ToolResponse,
-        get_database(DB_PATH).hybrid_search(
-            query, tables, None, "embedding", semantic_weight, text_weight, limit, model_name
-        ),
-    )
+    return auto_smart_search_impl(query, tables, semantic_weight, text_weight, limit, model_name)
+
+
+@mcp.tool
+@catch_errors
+def embedding_stats(
+    table_name: str,
+    embedding_column: str = "embedding",
+) -> ToolResponse:
+    """
+    Get statistics about semantic search readiness for a table.
+
+    Check which content has embeddings and can be searched semantically.
 
+    Args:
+        table_name (str): Table to analyze
+        embedding_column (str): Embedding column to check (default: "embedding")
 
-# --- Auto-Embedding Semantic Search Tools ---
+    Returns:
+        ToolResponse: On success: {"success": True, "coverage_percent": float, "total_rows": int}
+                     On error: {"success": False, "error": str, "category": str, "details": dict}
+
+    Examples:
+        >>> embedding_stats("technical_decisions")
+        {"success": True, "total_rows": 25, "embedded_rows": 25, "coverage_percent": 100.0,
+         "embedding_dimensions": 384}
+
+    FastMCP Tool Info:
+        - Shows how much content is ready for semantic search
+        - Helps identify tables that need embedding generation  
+        - Provides embedding dimension info for debugging
+        - Useful for monitoring semantic search capabilities
+    """
+    return embedding_stats_impl(table_name, embedding_column)
 
 
 @mcp.tool
 @catch_errors
-def auto_semantic_search(
+def semantic_search(
     query: str,
     tables: Optional[List[str]] = None,
     similarity_threshold: float = 0.5,
@@ -677,117 +673,50 @@ def auto_semantic_search(
     model_name: str = "all-MiniLM-L6-v2",
 ) -> ToolResponse:
     """
-    🚀 **ZERO-SETUP SEMANTIC SEARCH** - Just search, embeddings are handled automatically!
+    ⚠️  **ADVANCED TOOL** - Most agents should use auto_smart_search() instead!
 
-    Find content using natural language semantic similarity. If embeddings don't exist,
-    they will be automatically generated for text columns. This is the easiest way to
-    do semantic search - no manual setup required!
+    Find content using natural language semantic similarity rather than exact keyword matching.
+
+    **RECOMMENDATION**: Use auto_smart_search() for the same functionality with automatic setup.
+    This tool requires manual embedding setup via add_embeddings() first.
+
+    This enables intelligent knowledge discovery - find related concepts even when
+    they use different terminology or phrasing.
 
     Args:
         query (str): Natural language search query
-        tables (Optional[List[str]]): Specific tables to search (default: all tables)
+        tables (Optional[List[str]]): Specific tables to search (default: all tables with embeddings)
         similarity_threshold (float): Minimum similarity score (0.0-1.0, default: 0.5)
         limit (int): Maximum number of results to return (default: 10)
-        model_name (str): Model to use for embeddings (default: "all-MiniLM-L6-v2")
+        model_name (str): Model to use for query embedding (default: "all-MiniLM-L6-v2")
 
     Returns:
-        ToolResponse: On success: {"success": True, "results": List[...], "auto_embedded_tables": List[str]}
+        ToolResponse: On success: {"success": True, "results": List[...], "total_results": int}
                      On error: {"success": False, "error": str, "category": str, "details": dict}
 
     Examples:
-        >>> auto_semantic_search("API design patterns")
+        >>> semantic_search("API design patterns")
         {"success": True, "results": [
-            {"table_name": "technical_decisions", "similarity_score": 0.87, "decision_name": "REST API Structure", ...}
-        ], "auto_embedded_tables": ["technical_decisions"]}
+            {"table_name": "technical_decisions", "similarity_score": 0.87, "decision_name": "REST API Structure", ...},
+            {"table_name": "project_structure", "similarity_score": 0.72, "component": "API Gateway", ...}
+        ]}
 
-        >>> auto_semantic_search("machine learning concepts")
+        >>> semantic_search("machine learning", tables=["technical_decisions"], similarity_threshold=0.7)
         # Finds content about "ML", "AI", "neural networks", etc.
-        # Automatically creates embeddings if they don't exist!
 
     FastMCP Tool Info:
-        - **COMPLETELY AUTOMATIC**: No manual embedding setup required
-        - Auto-detects text columns and creates embeddings as needed
         - Works across multiple tables simultaneously
         - Finds conceptually similar content regardless of exact wording
         - Returns relevance scores for ranking results
         - Supports fuzzy matching and concept discovery
-        - Perfect for agents - just search and it works!
+        - Much more powerful than keyword-based search for knowledge discovery
     """
-    try:
-        db = get_database(DB_PATH)
-        auto_embedded_tables: List[str] = []
-        
-        # Get tables to search
-        search_tables: List[str]
-        if tables:
-            search_tables = tables
-        else:
-            tables_result = db.list_tables()
-            if not tables_result.get("success"):
-                return cast(ToolResponse, tables_result)
-            all_tables = tables_result.get("tables", [])
-            if isinstance(all_tables, list):
-                search_tables = all_tables
-            else:
-                search_tables = []
-        
-        # Auto-embed text columns in tables that don't have embeddings
-        for table_name in search_tables:
-            try:
-                # Check if table has embeddings
-                stats_result = db.get_embedding_stats(table_name, "embedding")
-                coverage_percent = stats_result.get("coverage_percent", 0)
-                if stats_result.get("success") and isinstance(coverage_percent, (int, float)) and coverage_percent > 0:
-                    continue  # Table already has embeddings
-                
-                # Get table schema to find text columns
-                schema_result = db.describe_table(table_name)
-                if not schema_result.get("success"):
-                    continue
-                
-                # Find text columns
-                text_columns = []
-                columns = schema_result.get("columns", [])
-                if isinstance(columns, list):
-                    for col in columns:
-                        if isinstance(col, dict) and "TEXT" in col.get("type", "").upper():
-                            text_columns.append(col["name"])
-                
-                # Auto-embed text columns
-                if text_columns:
-                    embed_result = db.generate_embeddings(table_name, text_columns, "embedding", model_name)
-                    if embed_result.get("success"):
-                        auto_embedded_tables.append(table_name)
-                        
-            except Exception:
-                # If auto-embedding fails, continue without it
-                continue
-        
-        # Perform semantic search
-        search_result = db.semantic_search(
-            query, search_tables, "embedding", None, similarity_threshold, limit, model_name
-        )
-        
-        # Add auto-embedding info to result
-        if isinstance(search_result, dict):
-            search_result["auto_embedded_tables"] = auto_embedded_tables
-            if auto_embedded_tables:
-                search_result["auto_embedding_note"] = f"Automatically generated embeddings for {len(auto_embedded_tables)} table(s)"
-        
-        return cast(ToolResponse, search_result)
-        
-    except Exception as e:
-        return cast(ToolResponse, {
-            "success": False,
-            "error": f"Auto semantic search failed: {str(e)}",
-            "category": "SEMANTIC_SEARCH_ERROR",
-            "details": {"query": query, "tables": tables}
-        })
+    return _semantic_search_impl(query, tables, similarity_threshold, limit, model_name)
 
 
 @mcp.tool
 @catch_errors
-def auto_smart_search(
+def smart_search(
     query: str,
     tables: Optional[List[str]] = None,
     semantic_weight: float = 0.7,
@@ -796,11 +725,15 @@ def auto_smart_search(
     model_name: str = "all-MiniLM-L6-v2",
 ) -> ToolResponse:
     """
-    🚀 **ZERO-SETUP HYBRID SEARCH** - Best of both worlds with automatic embedding!
+    ⚠️  **ADVANCED TOOL** - Most agents should use auto_smart_search() instead!
 
     Intelligent hybrid search combining semantic understanding with keyword matching.
-    Automatically generates embeddings for text columns when needed. This is the
-    ultimate search tool - no manual setup required!
+
+    **RECOMMENDATION**: Use auto_smart_search() for the same functionality with automatic setup.
+    This tool requires manual embedding setup via add_embeddings() first.
+
+    Provides the best of both worlds - semantic similarity for concept discovery
+    plus exact text matching for precise searches.
 
     Args:
         query (str): Search query (natural language or keywords)
@@ -811,242 +744,207 @@ def auto_smart_search(
         model_name (str): Semantic model to use (default: "all-MiniLM-L6-v2")
 
     Returns:
-        ToolResponse: On success: {"success": True, "results": List[...], "search_type": "auto_hybrid"}
+        ToolResponse: On success: {"success": True, "results": List[...], "search_type": "hybrid"}
                      On error: {"success": False, "error": str, "category": str, "details": dict}
 
     Examples:
-        >>> auto_smart_search("user authentication security")
+        >>> smart_search("user authentication security")
         {"success": True, "results": [
-            {"combined_score": 0.89, "semantic_score": 0.92, "text_score": 0.82, ...}
-        ], "search_type": "auto_hybrid", "auto_embedded_tables": ["user_data"]}
+            {"combined_score": 0.89, "semantic_score": 0.92, "text_score": 0.82, ...},
+            {"combined_score": 0.76, "semantic_score": 0.71, "text_score": 0.85, ...}
+        ], "search_type": "hybrid"}
 
     FastMCP Tool Info:
-        - **COMPLETELY AUTOMATIC**: No manual embedding setup required
         - Automatically balances semantic and keyword search
-        - Auto-detects text columns and creates embeddings as needed
         - Provides separate scores for transparency
         - Falls back gracefully if semantic search unavailable
         - Optimal for both exploratory and precise searches
         - Perfect for agents - ultimate search tool that just works!
     """
-    try:
-        db = get_database(DB_PATH)
-        auto_embedded_tables: List[str] = []
-        
-        # Get tables to search
-        search_tables: List[str]
-        if tables:
-            search_tables = tables
-        else:
-            tables_result = db.list_tables()
-            if not tables_result.get("success"):
-                return cast(ToolResponse, tables_result)
-            all_tables = tables_result.get("tables", [])
-            if isinstance(all_tables, list):
-                search_tables = all_tables
-            else:
-                search_tables = []
-        
-        # Auto-embed text columns in tables that don't have embeddings
-        for table_name in search_tables:
-            try:
-                # Check if table has embeddings
-                stats_result = db.get_embedding_stats(table_name, "embedding")
-                coverage_percent = stats_result.get("coverage_percent", 0)
-                if stats_result.get("success") and isinstance(coverage_percent, (int, float)) and coverage_percent > 0:
-                    continue  # Table already has embeddings
-                
-                # Get table schema to find text columns
-                schema_result = db.describe_table(table_name)
-                if not schema_result.get("success"):
-                    continue
-                
-                # Find text columns
-                text_columns = []
-                columns = schema_result.get("columns", [])
-                if isinstance(columns, list):
-                    for col in columns:
-                        if isinstance(col, dict) and "TEXT" in col.get("type", "").upper():
-                            text_columns.append(col["name"])
-                
-                # Auto-embed text columns
-                if text_columns:
-                    embed_result = db.generate_embeddings(table_name, text_columns, "embedding", model_name)
-                    if embed_result.get("success"):
-                        auto_embedded_tables.append(table_name)
-                        
-            except Exception:
-                # If auto-embedding fails, continue without it
-                continue
-        
-        # Now perform hybrid search
-        db = get_database(DB_PATH)
-        hybrid_result = db.hybrid_search(
-            query, tables, None, "embedding", semantic_weight, text_weight, limit, model_name
-        )
-        
-        # Add auto-embedding info to result
-        if isinstance(hybrid_result, dict) and hybrid_result.get("success"):
-            # Convert to mutable dict to add extra fields
-            final_result = dict(hybrid_result)
-            final_result["search_type"] = "auto_hybrid"
-            final_result["auto_embedded_tables"] = auto_embedded_tables
-            if auto_embedded_tables:
-                final_result["auto_embedding_note"] = f"Automatically generated embeddings for {len(auto_embedded_tables)} table(s)"
-            return cast(ToolResponse, final_result)
-        else:
-            return cast(ToolResponse, hybrid_result)
-        
-    except Exception as e:
-        return cast(ToolResponse, {
-            "success": False,
-            "error": f"Auto smart search failed: {str(e)}",
-            "category": "HYBRID_SEARCH_ERROR", 
-            "details": {"query": query, "tables": tables}
-        })
+    return _smart_search_impl(query, tables, semantic_weight, text_weight, limit, model_name)
 
 
 @mcp.tool
-@catch_errors 
-def embedding_stats(table_name: str, embedding_column: str = "embedding") -> ToolResponse:
+@catch_errors
+def find_related(
+    table_name: str,
+    row_id: int,
+    similarity_threshold: float = 0.5,
+    limit: int = 5,
+    model_name: str = "all-MiniLM-L6-v2",
+) -> ToolResponse:
     """
-    Get statistics about semantic search readiness for a table.
+    Find content related to a specific row by semantic similarity.
 
-    Check which content has embeddings and can be searched semantically.
+    Discover connections and related information that might not be obvious
+    from direct references or tags.
 
     Args:
-        table_name (str): Table to analyze
-        embedding_column (str): Embedding column to check (default: "embedding")
+        table_name (str): Table containing the reference row
+        row_id (int): ID of the row to find related content for
+        similarity_threshold (float): Minimum similarity score (default: 0.5)
+        limit (int): Maximum number of related items to return (default: 5)
+        model_name (str): Model for similarity comparison (default: "all-MiniLM-L6-v2")
 
     Returns:
-        ToolResponse: On success: {"success": True, "coverage_percent": float, "total_rows": int}
+        ToolResponse: On success: {"success": True, "results": List[...], "target_row": Dict}
                      On error: {"success": False, "error": str, "category": str, "details": dict}
 
     Examples:
-        >>> embedding_stats("technical_decisions")
-        {"success": True, "total_rows": 25, "embedded_rows": 25, "coverage_percent": 100.0,
-         "embedding_dimensions": 384}
+        >>> find_related("technical_decisions", 5)
+        {"success": True, "results": [
+            {"id": 12, "similarity_score": 0.84, "decision_name": "Related Architecture Choice", ...},
+            {"id": 3, "similarity_score": 0.71, "decision_name": "Similar Technology Decision", ...}
+        ], "target_row": {"id": 5, "decision_name": "API Framework Selection", ...}}
 
     FastMCP Tool Info:
-        - Shows how much content is ready for semantic search
-        - Helps identify tables that need embedding generation  
-        - Provides embedding dimension info for debugging
-        - Useful for monitoring semantic search capabilities
+        - Helps discover hidden relationships between data
+        - Useful for finding similar decisions, related problems, or connected concepts
+        - Can reveal patterns and themes across your knowledge base
+        - Enables serendipitous discovery of relevant information
     """
-    return cast(ToolResponse, get_database(DB_PATH).get_embedding_stats(table_name, embedding_column))
+    return _find_related_impl(table_name, row_id, similarity_threshold, limit, model_name)
 
 
-# --- Enhanced Tool Discovery and Categorization ---
+# --- Advanced Discovery Tools for SQLite Memory Bank ---
+
+@mcp.tool
+@catch_errors
+def intelligent_discovery(
+    discovery_goal: str = "understand_content",
+    focus_area: Optional[str] = None,
+    depth: str = "moderate",
+    agent_id: Optional[str] = None,
+) -> ToolResponse:
+    """
+    🧠 **INTELLIGENT DISCOVERY** - AI-guided exploration of your memory bank!
+
+    Orchestrates multiple discovery tools based on your exploration goals.
+    Provides step-by-step guidance and actionable insights tailored to your needs.
+
+    Args:
+        discovery_goal (str): What you want to achieve
+            - "understand_content": Learn what data is available and how it's organized
+            - "find_patterns": Discover themes, relationships, and content patterns  
+            - "explore_structure": Understand database schema and organization
+            - "assess_quality": Evaluate content quality and completeness
+            - "prepare_search": Get ready for effective content searching
+        focus_area (Optional[str]): Specific table or topic to focus on (default: all)
+        depth (str): How thorough the discovery should be
+            - "quick": Fast overview with key insights
+            - "moderate": Balanced analysis with actionable recommendations  
+            - "comprehensive": Deep dive with detailed analysis
+        agent_id (Optional[str]): Agent identifier for learning discovery patterns
+
+    Returns:
+        ToolResponse: On success: {"success": True, "discovery": Dict, "next_steps": List}
+                     On error: {"success": False, "error": str, "category": str, "details": dict}
+
+    Examples:
+        >>> intelligent_discovery("understand_content")
+        {"success": True, "discovery": {
+            "overview": {"total_tables": 5, "total_rows": 234},
+            "content_summary": {...},
+            "recommendations": [...]
+        }, "next_steps": ["Use auto_smart_search() for specific queries"]}
+
+    FastMCP Tool Info:
+        - **COMPLETELY AUTOMATED**: No manual tool chaining required
+        - **GOAL-ORIENTED**: Tailored discovery based on your specific objectives
+        - **ACTIONABLE INSIGHTS**: Always includes concrete next steps
+        - **LEARNING**: Improves recommendations based on usage patterns
+        - **PERFECT FOR AGENTS**: Single tool that orchestrates complex discovery workflows
+    """
+    return intelligent_discovery_impl(discovery_goal, focus_area, depth, agent_id)
 
 
 @mcp.tool
 @catch_errors
-def list_tool_categories() -> ToolResponse:
+def discovery_templates(
+    template_type: str = "first_time_exploration",
+    customize_for: Optional[str] = None
+) -> ToolResponse:
     """
-    List all available tool categories for better organization and discovery.
-    
-    Returns organized view of available functionality for LLMs and agents.
-    
+    📋 **DISCOVERY TEMPLATES** - Pre-built exploration workflows for common scenarios!
+
+    Provides step-by-step discovery templates optimized for specific agent use cases.
+    Each template includes the exact sequence of tools to call and what to look for.
+
+    Args:
+        template_type (str): Type of discovery template to provide
+            - "first_time_exploration": Complete workflow for new agents
+            - "content_audit": Systematic content quality review
+            - "search_optimization": Prepare memory bank for optimal searching
+            - "relationship_mapping": Discover connections between data
+            - "problem_solving": Find information to solve specific problems
+            - "knowledge_extraction": Extract insights from stored knowledge
+        customize_for (Optional[str]): Customize template for specific domain/topic
+
     Returns:
-        ToolResponse: {"success": True, "categories": {category: [tool_names]}}
+        ToolResponse: {"success": True, "template": Dict, "workflow": List}
+
+    Examples:
+        >>> discovery_templates("first_time_exploration")
+        {"success": True, "template": {
+            "name": "First Time Exploration",
+            "description": "Complete discovery workflow for new agents",
+            "workflow": [
+                {"step": 1, "tool": "intelligent_discovery", "params": {...}},
+                {"step": 2, "tool": "explore_tables", "params": {...}}
+            ]
+        }}
+
+    FastMCP Tool Info:
+        - **PROVEN WORKFLOWS**: Battle-tested discovery sequences  
+        - **STEP-BY-STEP GUIDANCE**: Exact tools and parameters to use
+        - **CUSTOMIZABLE**: Adapt templates to your specific needs
+        - **LEARNING-OPTIMIZED**: Based on successful discovery patterns
     """
-    categories = {
-        "schema_management": [
-            "create_table", "list_tables", "describe_table", 
-            "drop_table", "rename_table", "list_all_columns"
-        ],
-        "data_operations": [
-            "create_row", "read_rows", "update_rows", 
-            "delete_rows", "run_select_query"
-        ],
-        "search_discovery": [
-            "search_content", "explore_tables"
-        ],
-        "semantic_search": [
-            "add_embeddings", "semantic_search", "find_related", 
-            "smart_search", "embedding_stats"
-        ],
-        "workflow_shortcuts": [
-            "quick_note", "remember_decision", "store_context"
-        ],
-        "analytics_insights": [
-            "memory_usage_stats", "content_analytics"
-        ]
-    }
-    
-    return cast(ToolResponse, {
-        "success": True,
-        "categories": categories,
-        "total_tools": sum(len(tools) for tools in categories.values()),
-        "description": "Organized view of all available memory bank capabilities"
-    })
-
-
-@mcp.tool  
+    return discovery_templates_impl(template_type, customize_for)
+
+
+@mcp.tool
 @catch_errors
-def get_tools_by_category(category: str) -> ToolResponse:
+def discover_relationships(
+    table_name: Optional[str] = None,
+    relationship_types: List[str] = ["foreign_keys", "semantic_similarity", "temporal_patterns"],
+    similarity_threshold: float = 0.6
+) -> ToolResponse:
     """
-    Get detailed information about tools in a specific category.
-    
+    🔗 **RELATIONSHIP DISCOVERY** - Find hidden connections in your data!
+
+    Automatically discovers relationships between tables and content areas using
+    both structural analysis and semantic similarity to reveal data connections.
+
     Args:
-        category (str): Category name (schema_management, data_operations, 
-                       search_discovery, semantic_search, workflow_shortcuts, analytics_insights)
-    
+        table_name (Optional[str]): Focus on relationships for specific table (default: all)
+        relationship_types (List[str]): Types of relationships to discover
+            - "foreign_keys": Structural relationships via foreign keys
+            - "semantic_similarity": Content-based relationships via semantic analysis
+            - "temporal_patterns": Time-based relationships and patterns
+            - "naming_patterns": Relationships based on naming conventions
+        similarity_threshold (float): Minimum similarity for semantic relationships (0.0-1.0)
+
     Returns:
-        ToolResponse: {"success": True, "tools": [{"name": str, "description": str, "usage": str}]}
+        ToolResponse: {"success": True, "relationships": Dict, "insights": List}
+
+    Examples:
+        >>> discover_relationships("users")
+        {"success": True, "relationships": {
+            "users": {
+                "foreign_key_refs": ["posts.user_id", "comments.user_id"],
+                "semantic_similar": [{"table": "profiles", "similarity": 0.8}],
+                "temporal_related": ["user_sessions"]
+            }
+        }}
+
+    FastMCP Tool Info:
+        - **AUTOMATIC DETECTION**: Finds relationships you might not notice manually
+        - **MULTIPLE METHODS**: Combines structural, semantic, and temporal analysis
+        - **ACTIONABLE INSIGHTS**: Suggests how to leverage discovered relationships
+        - **PERFECT FOR EXPLORATION**: Reveals hidden data organization patterns
     """
-    tool_details = {
-        "schema_management": [
-            {"name": "create_table", "description": "Create new tables with custom schemas", "usage": "create_table('table_name', [{'name': 'col', 'type': 'TEXT'}])"},
-            {"name": "list_tables", "description": "List all available tables", "usage": "list_tables()"},
-            {"name": "describe_table", "description": "Get detailed schema for a table", "usage": "describe_table('table_name')"},
-            {"name": "drop_table", "description": "Delete a table permanently", "usage": "drop_table('table_name')"},
-            {"name": "rename_table", "description": "Rename an existing table", "usage": "rename_table('old_name', 'new_name')"},
-            {"name": "list_all_columns", "description": "Get all columns across all tables", "usage": "list_all_columns()"},
-        ],
-        "data_operations": [
-            {"name": "create_row", "description": "Insert new data into any table", "usage": "create_row('table', {'col': 'value'})"},
-            {"name": "read_rows", "description": "Query data with optional filtering", "usage": "read_rows('table', {'filter_col': 'value'})"},
-            {"name": "update_rows", "description": "Modify existing data", "usage": "update_rows('table', {'new_data': 'value'}, {'where_col': 'value'})"},
-            {"name": "delete_rows", "description": "Remove data from tables", "usage": "delete_rows('table', {'filter_col': 'value'})"},
-            {"name": "run_select_query", "description": "Execute safe SELECT queries", "usage": "run_select_query('table', ['col1', 'col2'], {'filter': 'value'})"},
-        ],
-        "search_discovery": [
-            {"name": "search_content", "description": "Full-text search across all content", "usage": "search_content('search query', ['table1', 'table2'])"},
-            {"name": "explore_tables", "description": "Discover table structures and sample data", "usage": "explore_tables('pattern*')"},
-        ],
-        "semantic_search": [
-            {"name": "add_embeddings", "description": "Enable semantic search on tables", "usage": "add_embeddings('table', ['text_col1', 'text_col2'])"},
-            {"name": "semantic_search", "description": "Natural language content discovery", "usage": "semantic_search('find ML algorithms')"},
-            {"name": "find_related", "description": "Discover similar content", "usage": "find_related('table', row_id, 0.5)"},
-            {"name": "smart_search", "description": "Hybrid keyword + semantic search", "usage": "smart_search('search query')"},
-            {"name": "embedding_stats", "description": "Check semantic search readiness", "usage": "embedding_stats('table')"},
-        ],
-        "workflow_shortcuts": [
-            {"name": "quick_note", "description": "Rapidly store notes and observations", "usage": "quick_note('content', 'category')"},
-            {"name": "remember_decision", "description": "Store technical decisions with context", "usage": "remember_decision('decision', 'approach', 'rationale')"},
-            {"name": "store_context", "description": "Save session context and progress", "usage": "store_context('topic', 'current_state', 'next_steps')"},
-        ],
-        "analytics_insights": [
-            {"name": "memory_usage_stats", "description": "Analyze memory bank usage patterns", "usage": "memory_usage_stats()"},
-            {"name": "content_analytics", "description": "Get insights on stored content", "usage": "content_analytics('table_name')"},
-        ],
-    }
-    
-    if category not in tool_details:
-        return cast(ToolResponse, {
-            "success": False,
-            "error": f"Unknown category '{category}'. Available: {list(tool_details.keys())}",
-            "category": "VALIDATION",
-            "details": {"available_categories": list(tool_details.keys())},
-        })
-    
-    return cast(ToolResponse, {
-        "success": True,
-        "category": category,
-        "tools": tool_details[category],
-        "tool_count": len(tool_details[category]),
-    })
+    return discover_relationships_impl(table_name, relationship_types, similarity_threshold)
 
 
 # Export the FastMCP app for use in other modules and server runners
@@ -1073,108 +971,19 @@ Available tools:
 - run_select_query: Run a safe SELECT query (no arbitrary SQL)
 - search_content: Perform full-text search across table content
 - explore_tables: Discover table structures and content for better searchability
+- auto_semantic_search: Zero-setup semantic search with automatic embeddings
+- auto_smart_search: Zero-setup hybrid search combining semantic and keyword search
+- add_embeddings: Manual embedding generation for advanced users
+- embedding_stats: Check semantic search readiness
 """
 
 
-# Legacy implementation functions for backwards compatibility with tests
-def _create_row_impl(table_name: str, data: Dict[str, Any]) -> Dict[str, Any]:
-    """Legacy implementation function for tests."""
-    try:
-        # Handle test-specific table creation for legacy compatibility
-        if not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", table_name):
-            return {"success": False, "error": f"Invalid table name: {table_name}"}
-
-        # Auto-create test tables for compatibility
-        current_db = get_database(DB_PATH)
-        if table_name == "nodes":
-            try:
-                current_db.create_table(
-                    "nodes",
-                    [
-                        {"name": "id", "type": "INTEGER PRIMARY KEY AUTOINCREMENT"},
-                        {"name": "label", "type": "TEXT NOT NULL"},
-                    ],
-                )
-            except Exception:
-                pass  # Table might already exist
-        elif table_name == "edges":
-            try:
-                current_db.create_table(
-                    "edges",
-                    [
-                        {"name": "id", "type": "INTEGER PRIMARY KEY AUTOINCREMENT"},
-                        {"name": "source", "type": "INTEGER NOT NULL"},
-                        {"name": "target", "type": "INTEGER NOT NULL"},
-                        {"name": "type", "type": "TEXT NOT NULL"},
-                    ],
-                )
-            except Exception:
-                pass  # Table might already exist
-
-        result = current_db.insert_row(table_name, data)
-        # Ensure we return Dict[str, Any] for legacy compatibility
-        return dict(result) if isinstance(result, dict) else {"success": False, "error": "Unknown error"}
-
-    except Exception as e:
-        logging.error(f"_create_row_impl error: {e}")
-        return {"success": False, "error": str(e)}
-
-
-def _read_rows_impl(table_name: str, where: Optional[Dict[str, Any]] = None, limit: int = 100) -> Dict[str, Any]:
-    """Legacy implementation function for tests."""
-    try:
-        result = get_database(DB_PATH).read_rows(table_name, where, limit)
-        # Ensure we return Dict[str, Any] for legacy compatibility
-        return dict(result) if isinstance(result, dict) else {"success": False, "error": "Unknown error"}
-    except Exception as e:
-        logging.error(f"_read_rows_impl error: {e}")
-        return {"success": False, "error": str(e)}
-
-
-def _update_rows_impl(table_name: str, data: Dict[str, Any], where: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-    """Legacy implementation function for tests."""
-    try:
-        # Auto-create test tables for compatibility
-        if table_name == "edges":
-            try:
-                current_db = get_database(DB_PATH)
-                current_db.create_table(
-                    "edges",
-                    [
-                        {"name": "id", "type": "INTEGER PRIMARY KEY AUTOINCREMENT"},
-                        {"name": "source", "type": "INTEGER NOT NULL"},
-                        {"name": "target", "type": "INTEGER NOT NULL"},
-                        {"name": "type", "type": "TEXT NOT NULL"},
-                    ],
-                )
-            except Exception:
-                pass  # Table might already exist
-
-        result = get_database(DB_PATH).update_rows(table_name, data, where)
-        # Ensure we return Dict[str, Any] for legacy compatibility
-        return dict(result) if isinstance(result, dict) else {"success": False, "error": "Unknown error"}
-    except Exception as e:
-        logging.error(f"_update_rows_impl error: {e}")
-        return {"success": False, "error": str(e)}
-
-
-def _delete_rows_impl(table_name: str, where: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-    """Legacy implementation function for tests."""
-    try:
-        result = get_database(DB_PATH).delete_rows(table_name, where)
-        # Ensure we return Dict[str, Any] for legacy compatibility
-        return dict(result) if isinstance(result, dict) else {"success": False, "error": "Unknown error"}
-    except Exception as e:
-        logging.error(f"_delete_rows_impl error: {e}")
-        return {"success": False, "error": str(e)}
-
-
 # Public API - these functions are available for direct Python use and as MCP tools
 __all__ = [
     "app",
     "mcp",
     "create_table",
-    "drop_table",
+    "drop_table", 
     "rename_table",
     "list_tables",
     "describe_table",
@@ -1186,10 +995,13 @@ __all__ = [
     "run_select_query",
     "search_content",
     "explore_tables",
-    "_create_row_impl",
-    "_read_rows_impl",
-    "_update_rows_impl",
-    "_delete_rows_impl",
+    "add_embeddings",
+    "auto_semantic_search",
+    "auto_smart_search",
+    "embedding_stats",
+    "intelligent_discovery",
+    "discovery_templates",
+    "discover_relationships",
 ]
 
 
@@ -1239,4 +1051,37 @@ if __name__ == "__main__":
     logging.info(f"Starting SQLite Memory Bank with database at {DB_PATH}")
 
     # Run the FastMCP app in stdio mode for MCP clients
-    app.run()
+    app.run(transport="stdio")
+
+
+# Compatibility aliases for tests that expect _impl functions
+# Import modules already imported above for tool implementations
+
+# Basic CRUD operation aliases
+_create_row_impl = basic.create_row
+_read_rows_impl = basic.read_rows
+_update_rows_impl = basic.update_rows
+_delete_rows_impl = basic.delete_rows
+_list_tables_impl = basic.list_tables
+_describe_table_impl = basic.describe_table
+_drop_table_impl = basic.drop_table
+_create_table_impl = basic.create_table
+
+# Search operation aliases
+_search_content_impl = search.search_content
+_explore_tables_impl = search.explore_tables
+_add_embeddings_impl = search.add_embeddings
+_semantic_search_impl = search.semantic_search
+_smart_search_impl = search.smart_search
+_find_related_impl = search.find_related
+_auto_semantic_search_impl = search.auto_semantic_search
+_auto_smart_search_impl = search.auto_smart_search
+
+# Analytics operation aliases
+_analyze_memory_patterns_impl = analytics.analyze_memory_patterns
+_get_content_health_score_impl = analytics.get_content_health_score
+
+# Discovery operation aliases
+_intelligent_discovery_impl = intelligent_discovery_impl
+_discovery_templates_impl = discovery_templates_impl
+_discover_relationships_impl = discover_relationships_impl