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

mcp_sqlite_memory_bank/semantic.py

@@ -21,7 +21,9 @@ except ImportError:
     SENTENCE_TRANSFORMERS_AVAILABLE = False
     SentenceTransformer = None  # type: ignore
     util = None  # type: ignore
-    logging.warning("sentence-transformers not available. Install with: pip install sentence-transformers")
+    logging.warning(
+        "sentence-transformers not available. Install with: pip install sentence-transformers"
+    )
 
 try:
     import torch
@@ -58,7 +60,7 @@ class SemanticSearchEngine:
             )
 
     @property
-    def model(self):
+    def model(self) -> Any:
         """Lazy load the sentence transformer model."""
         if self._model is None:
             if not SENTENCE_TRANSFORMERS_AVAILABLE or SentenceTransformer is None:
@@ -124,7 +126,9 @@ class SemanticSearchEngine:
 
         try:
             embeddings = self.model.encode(
-                valid_texts, convert_to_tensor=False, show_progress_bar=len(valid_texts) > 10
+                valid_texts,
+                convert_to_tensor=False,
+                show_progress_bar=len(valid_texts) > 10,
             )
             return [emb.tolist() for emb in embeddings]
         except Exception as e:
@@ -193,7 +197,12 @@ class SemanticSearchEngine:
             return []
 
         # Use efficient torch/sentence-transformers if available
-        if TORCH_AVAILABLE and torch is not None and SENTENCE_TRANSFORMERS_AVAILABLE and util is not None:
+        if (
+            TORCH_AVAILABLE
+            and torch is not None
+            and SENTENCE_TRANSFORMERS_AVAILABLE
+            and util is not None
+        ):
             try:
                 # Convert to tensors
                 query_tensor = torch.tensor(query_embedding).unsqueeze(0)
@@ -291,6 +300,10 @@ class SemanticSearchEngine:
                 original_idx = valid_indices[candidate_idx]
                 row = content_data[original_idx].copy()
 
+                # Remove embedding data to avoid polluting LLM responses
+                if embedding_column in row:
+                    del row[embedding_column]
+
                 # Add similarity score
                 row["similarity_score"] = round(similarity_score, 3)
 
@@ -344,10 +357,9 @@ class SemanticSearchEngine:
             semantic_weight /= total_weight
             text_weight /= total_weight
 
-        # Get semantic search results
-        semantic_results = self.semantic_search(
-            query, content_data, embedding_column, similarity_threshold=0.3, top_k=top_k * 2  # Get more for reranking
-        )
+        # Use the provided content_data as semantic results (already filtered by database)
+        # The content_data passed here should already be the semantic search results
+        semantic_results = content_data.copy() if content_data else []
 
         # Add text matching scores
         query_lower = query.lower()
@@ -373,7 +385,7 @@ class SemanticSearchEngine:
 
         return semantic_results[:top_k]
 
-    def clear_cache(self):
+    def clear_cache(self) -> None:
         """Clear the embedding cache."""
         self._embedding_cache.clear()
         logging.info("Semantic search cache cleared")
@@ -392,13 +404,13 @@ def get_semantic_engine(model_name: str = "all-MiniLM-L6-v2") -> SemanticSearchE
             if not SENTENCE_TRANSFORMERS_AVAILABLE:
                 raise ValueError("Sentence transformers not available for semantic search")
             _semantic_engine = SemanticSearchEngine(model_name)
-        
+
         # Verify the engine is properly initialized
-        if not hasattr(_semantic_engine, 'hybrid_search'):
+        if not hasattr(_semantic_engine, "hybrid_search"):
             raise ValueError("Semantic engine missing hybrid_search method")
-            
+
         return _semantic_engine
-        
+
     except Exception as e:
         raise DatabaseError(f"Failed to initialize semantic engine: {e}")
 

mcp_sqlite_memory_bank/server.py

@@ -43,14 +43,25 @@ Each tool is designed for explicit, discoverable use by LLMs and agents:
 Author: Robert Meisner
 """
 
+from .tools.discovery import (
+    intelligent_discovery as intelligent_discovery_impl,
+    discovery_templates as discovery_templates_impl,
+    discover_relationships as discover_relationships_impl,
+)
+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 os
-import re
 import logging
 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,
@@ -265,6 +276,40 @@ def create_row(table_name: str, data: Dict[str, Any]) -> ToolResponse:
     return cast(CreateRowResponse, get_database(DB_PATH).insert_row(table_name, data))
 
 
+@mcp.tool
+@catch_errors
+def upsert_memory(table_name: str, data: Dict[str, Any], match_columns: List[str]) -> ToolResponse:
+    """
+    🔄 **SMART MEMORY UPSERT** - Prevent duplicates and maintain data consistency!
+
+    Update existing records or create new ones based on matching columns.
+    This is the preferred method for memory management as it prevents duplicates.
+
+    Args:
+        table_name (str): Table to upsert into
+        data (Dict[str, Any]): Data to upsert (column-value pairs)
+        match_columns (List[str]): Columns to use for finding existing records
+
+    Returns:
+        ToolResponse: On success: {"success": True, "action": "updated"|"created", "id": rowid}
+                     On error: {"success": False, "error": str, "category": str, "details": dict}
+
+    Examples:
+        >>> upsert_memory('technical_decisions',
+        ...     {'decision_name': 'API Design', 'chosen_approach': 'REST'},
+        ...     ['decision_name'])
+        {"success": True, "action": "updated", "id": 15, "rows_affected": 1}
+
+    FastMCP Tool Info:
+        - **PREVENTS DUPLICATES**: Automatically updates existing records instead of creating duplicates
+        - **SMART MATCHING**: Uses specified columns to find existing records
+        - **EFFICIENT MEMORY MANAGEMENT**: Ideal for agent memory patterns
+        - **CLEAR FEEDBACK**: Returns whether record was created or updated
+        - **PERFECT FOR AGENTS**: Handles the common "update or create" pattern automatically
+    """
+    return basic.upsert_memory(table_name, data, match_columns)
+
+
 @mcp.tool
 @catch_errors
 def read_rows(table_name: str, where: Optional[Dict[str, Any]] = None) -> ToolResponse:
@@ -293,7 +338,9 @@ def read_rows(table_name: str, where: Optional[Dict[str, Any]] = None) -> ToolRe
 
 @mcp.tool
 @catch_errors
-def update_rows(table_name: str, data: Dict[str, Any], where: Optional[Dict[str, Any]] = None) -> ToolResponse:
+def update_rows(
+    table_name: str, data: Dict[str, Any], where: Optional[Dict[str, Any]] = None
+) -> ToolResponse:
     """
     Update rows in any table in the SQLite Memory Bank for Copilot/AI agents, matching the WHERE clause.
 
@@ -349,7 +396,10 @@ def delete_rows(table_name: str, where: Optional[Dict[str, Any]] = None) -> Tool
 @mcp.tool
 @catch_errors
 def run_select_query(
-    table_name: str, columns: Optional[List[str]] = None, where: Optional[Dict[str, Any]] = None, limit: int = 100
+    table_name: str,
+    columns: Optional[List[str]] = None,
+    where: Optional[Dict[str, Any]] = None,
+    limit: int = 100,
 ) -> ToolResponse:
     """
     Run a safe SELECT query on a table in the SQLite memory bank.
@@ -374,7 +424,10 @@ def run_select_query(
         - Only SELECT queries are allowed (no arbitrary SQL)
         - Default limit of 100 rows prevents memory issues
     """
-    return cast(SelectQueryResponse, get_database(DB_PATH).select_query(table_name, columns, where, limit))
+    return cast(
+        SelectQueryResponse,
+        get_database(DB_PATH).select_query(table_name, columns, where, limit),
+    )
 
 
 @mcp.tool
@@ -400,24 +453,12 @@ def list_all_columns() -> ToolResponse:
 
 
 # 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,
-)
+# Import the implementation functions from discovery module
 
 # --- MCP Tool Definitions (Required in main server.py for FastMCP) ---
 
+
 @mcp.tool
 @catch_errors
 def search_content(
@@ -455,7 +496,7 @@ def search_content(
 
 
 @mcp.tool
-@catch_errors  
+@catch_errors
 def explore_tables(
     pattern: Optional[str] = None,
     include_row_counts: bool = True,
@@ -656,7 +697,7 @@ def embedding_stats(
 
     FastMCP Tool Info:
         - Shows how much content is ready for semantic search
-        - Helps identify tables that need embedding generation  
+        - Helps identify tables that need embedding generation
         - Provides embedding dimension info for debugging
         - Useful for monitoring semantic search capabilities
     """
@@ -808,6 +849,7 @@ def find_related(
 
 # --- Advanced Discovery Tools for SQLite Memory Bank ---
 
+
 @mcp.tool
 @catch_errors
 def intelligent_discovery(
@@ -825,14 +867,14 @@ def intelligent_discovery(
     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  
+            - "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  
+            - "moderate": Balanced analysis with actionable recommendations
             - "comprehensive": Deep dive with detailed analysis
         agent_id (Optional[str]): Agent identifier for learning discovery patterns
 
@@ -861,8 +903,7 @@ def intelligent_discovery(
 @mcp.tool
 @catch_errors
 def discovery_templates(
-    template_type: str = "first_time_exploration",
-    customize_for: Optional[str] = None
+    template_type: str = "first_time_exploration", customize_for: Optional[str] = None
 ) -> ToolResponse:
     """
     📋 **DISCOVERY TEMPLATES** - Pre-built exploration workflows for common scenarios!
@@ -895,7 +936,7 @@ def discovery_templates(
         }}
 
     FastMCP Tool Info:
-        - **PROVEN WORKFLOWS**: Battle-tested discovery sequences  
+        - **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
@@ -907,8 +948,12 @@ def discovery_templates(
 @catch_errors
 def discover_relationships(
     table_name: Optional[str] = None,
-    relationship_types: List[str] = ["foreign_keys", "semantic_similarity", "temporal_patterns"],
-    similarity_threshold: float = 0.6
+    relationship_types: List[str] = [
+        "foreign_keys",
+        "semantic_similarity",
+        "temporal_patterns",
+    ],
+    similarity_threshold: float = 0.6,
 ) -> ToolResponse:
     """
     🔗 **RELATIONSHIP DISCOVERY** - Find hidden connections in your data!
@@ -983,12 +1028,13 @@ __all__ = [
     "app",
     "mcp",
     "create_table",
-    "drop_table", 
+    "drop_table",
     "rename_table",
     "list_tables",
     "describe_table",
     "list_all_columns",
     "create_row",
+    "upsert_memory",
     "read_rows",
     "update_rows",
     "delete_rows",
@@ -1008,7 +1054,10 @@ __all__ = [
 def mcp_server():
     """Entry point for MCP stdio server (for uvx and package installations)."""
     # Configure logging for MCP server
-    logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
 
     # Log startup information
     logging.info(f"Starting SQLite Memory Bank MCP server with database at {DB_PATH}")
@@ -1040,12 +1089,20 @@ def main():
     print(f"Database path: {DB_PATH}")
     print("Available at: http://localhost:8000/docs")
 
-    uvicorn.run("mcp_sqlite_memory_bank.server:app", host=args.host, port=args.port, reload=args.reload)
+    uvicorn.run(
+        "mcp_sqlite_memory_bank.server:app",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+    )
 
 
 if __name__ == "__main__":
     # Configure logging
-    logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
 
     # Log startup information
     logging.info(f"Starting SQLite Memory Bank with database at {DB_PATH}")
@@ -1085,3 +1142,88 @@ _get_content_health_score_impl = analytics.get_content_health_score
 _intelligent_discovery_impl = intelligent_discovery_impl
 _discovery_templates_impl = discovery_templates_impl
 _discover_relationships_impl = discover_relationships_impl
+
+
+@mcp.tool
+@catch_errors
+def batch_create_memories(
+    table_name: str,
+    data_list: List[Dict[str, Any]],
+    match_columns: Optional[List[str]] = None,
+    use_upsert: bool = True,
+) -> ToolResponse:
+    """
+    🚀 **BATCH MEMORY CREATION** - Efficiently add multiple memories at once!
+
+    Create multiple memory records in a single operation with optional duplicate prevention.
+    Much faster than creating records one by one.
+
+    Args:
+        table_name (str): Table to insert records into
+        data_list (List[Dict[str, Any]]): List of memory records to create
+        match_columns (Optional[List[str]]): Columns to use for duplicate detection (if use_upsert=True)
+        use_upsert (bool): Whether to use upsert logic to prevent duplicates (default: True)
+
+    Returns:
+        ToolResponse: On success: {"success": True, "created": int, "updated": int, "failed": int}
+                     On error: {"success": False, "error": str, "category": str, "details": dict}
+
+    Examples:
+        >>> batch_create_memories('technical_decisions', [
+        ...     {'decision_name': 'API Design', 'chosen_approach': 'REST'},
+        ...     {'decision_name': 'Database Choice', 'chosen_approach': 'SQLite'},
+        ...     {'decision_name': 'Frontend Framework', 'chosen_approach': 'React'}
+        ... ], match_columns=['decision_name'])
+        {"success": True, "created": 2, "updated": 1, "failed": 0, "total_processed": 3}
+
+    FastMCP Tool Info:
+        - **EFFICIENT**: Process multiple records in one operation
+        - **SMART DEDUPLICATION**: Optional upsert logic prevents duplicates
+        - **DETAILED FEEDBACK**: Returns counts for created, updated, and failed records
+        - **PARTIAL SUCCESS**: Continues processing even if some records fail
+        - **PERFECT FOR BULK IMPORTS**: Ideal for importing knowledge bases or datasets
+    """
+    return basic.batch_create_memories(table_name, data_list, match_columns, use_upsert)
+
+
+@mcp.tool
+@catch_errors
+def batch_delete_memories(
+    table_name: str, where_conditions: List[Dict[str, Any]], match_all: bool = False
+) -> ToolResponse:
+    """
+    🗑️ **BATCH MEMORY DELETION** - Efficiently delete multiple memories at once!
+
+    Delete multiple memory records in a single operation with flexible matching conditions.
+    Much faster than deleting records one by one.
+
+    Args:
+        table_name (str): Table to delete records from
+        where_conditions (List[Dict[str, Any]]): List of WHERE conditions for deletion
+        match_all (bool): If True, delete records matching ALL conditions; if False, delete records matching ANY condition (default: False)
+
+    Returns:
+        ToolResponse: On success: {"success": True, "deleted": int, "failed": int}
+                     On error: {"success": False, "error": str, "category": str, "details": dict}
+
+    Examples:
+        >>> batch_delete_memories('technical_decisions', [
+        ...     {'decision_name': 'Old Decision 1'},
+        ...     {'decision_name': 'Old Decision 2'},
+        ...     {'id': 42}
+        ... ])
+        {"success": True, "deleted": 3, "failed": 0, "total_conditions": 3}
+
+        >>> batch_delete_memories('notes', [
+        ...     {'category': 'temp', 'created_date': '2024-01-01'}
+        ... ], match_all=True)
+        {"success": True, "deleted": 15, "failed": 0}  # Deletes notes that are BOTH temp AND from that date
+
+    FastMCP Tool Info:
+        - **EFFICIENT**: Process multiple deletions in one operation
+        - **FLEXIBLE MATCHING**: Support both OR logic (any condition) and AND logic (all conditions)
+        - **DETAILED FEEDBACK**: Returns counts and per-condition results
+        - **PARTIAL SUCCESS**: Continues processing even if some deletions fail
+        - **SAFE**: Uses parameterized queries to prevent SQL injection
+    """
+    return basic.batch_delete_memories(table_name, where_conditions, match_all)

mcp_sqlite_memory_bank/tools/__init__.py

@@ -3,7 +3,7 @@ Tools module for SQLite Memory Bank MCP server.
 
 This module organizes the various MCP tools into logical categories:
 - analytics: Content analysis and health assessment tools
-- search: Intelligent search and discovery tools  
+- search: Intelligent search and discovery tools
 - discovery: Advanced exploration and relationship discovery tools
 - basic: Core CRUD operations and table management
 """
@@ -45,35 +45,32 @@ from .basic import (
 
 __all__ = [
     # Analytics tools
-    'analyze_memory_patterns',
-    'get_content_health_score',
-    
+    "analyze_memory_patterns",
+    "get_content_health_score",
     # Search tools
-    'search_content',
-    'explore_tables',
-    'add_embeddings',
-    'semantic_search',
-    'find_related',
-    'smart_search',
-    'embedding_stats',
-    'auto_semantic_search',
-    'auto_smart_search',
-    
+    "search_content",
+    "explore_tables",
+    "add_embeddings",
+    "semantic_search",
+    "find_related",
+    "smart_search",
+    "embedding_stats",
+    "auto_semantic_search",
+    "auto_smart_search",
     # Discovery tools
-    'intelligent_discovery',
-    'discovery_templates',
-    'discover_relationships',
-    
+    "intelligent_discovery",
+    "discovery_templates",
+    "discover_relationships",
     # Basic tools
-    'create_table',
-    'list_tables', 
-    'describe_table',
-    'drop_table',
-    'rename_table',
-    'create_row',
-    'read_rows',
-    'update_rows',
-    'delete_rows',
-    'run_select_query',
-    'list_all_columns',
+    "create_table",
+    "list_tables",
+    "describe_table",
+    "drop_table",
+    "rename_table",
+    "create_row",
+    "read_rows",
+    "update_rows",
+    "delete_rows",
+    "run_select_query",
+    "list_all_columns",
 ]