vector-memory-mcp 1.0.0__py3-none-any.whl

main.py

@@ -0,0 +1,339 @@
+#!/usr/bin/env -S uv run --script
+# -*- coding: utf-8 -*-
+# /// script
+# dependencies = [
+#     "mcp>=0.3.0",
+#     "sqlite-vec>=0.1.6",
+#     "sentence-transformers>=2.2.2"
+# ]
+# requires-python = ">=3.8"
+# ///
+
+"""
+Vector Memory MCP Server - Main Entry Point
+===========================================
+
+A secure, vector-based memory server using sqlite-vec for semantic search.
+Stores and retrieves coding memories, experiences, and knowledge using 
+384-dimensional embeddings generated by sentence-transformers.
+
+Usage:
+    python main.py --working-dir /path/to/project
+
+Memory files stored in: {working_dir}/memory/vector_memory.db
+"""
+
+import sys
+from pathlib import Path
+from typing import Dict, Any
+
+# Add src to path for imports
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+from mcp.server.fastmcp import FastMCP
+
+# Import our modules
+from src.models import Config
+from src.security import validate_working_dir, SecurityError
+from src.memory_store import VectorMemoryStore
+
+
+def get_working_dir() -> Path:
+    """Get working directory from command line arguments"""
+    if len(sys.argv) >= 3 and sys.argv[1] == "--working-dir":
+        return validate_working_dir(sys.argv[2])
+    else:
+        # Default to current directory
+        return validate_working_dir(".")
+
+
+def create_server() -> FastMCP:
+    """Create and configure the MCP server"""
+    
+    # Initialize global memory store
+    try:
+        memory_dir = get_working_dir()
+        db_path = memory_dir / Config.DB_NAME
+        memory_store = VectorMemoryStore(db_path)
+        print(f"Memory database initialized: {db_path}", file=sys.stderr)
+    except Exception as e:
+        print(f"Failed to initialize memory store: {e}", file=sys.stderr)
+        sys.exit(1)
+    
+    # Create FastMCP server
+    mcp = FastMCP(Config.SERVER_NAME)
+    
+    # ===============================================================================
+    # MCP TOOLS IMPLEMENTATION
+    # ===============================================================================
+    
+    @mcp.tool()
+    def store_memory(
+        content: str,
+        category: str = "other",
+        tags: list[str] = None
+    ) -> dict[str, Any]:
+        """
+        Store coding memory with vector embedding for semantic search.
+
+        Args:
+            content: Memory content (max 10K chars)
+            category: code-solution, bug-fix, architecture, learning, tool-usage, debugging, performance, security, other
+            tags: Tags for organization (max 10)
+        """
+        try:
+            if tags is None:
+                tags = []
+            
+            result = memory_store.store_memory(content, category, tags)
+            return result
+            
+        except SecurityError as e:
+            return {
+                "success": False,
+                "error": "Security validation failed",
+                "message": str(e)
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "error": "Storage failed",
+                "message": str(e)
+            }
+    
+    @mcp.tool()
+    def search_memories(
+        query: str,
+        limit: int = 10,
+        category: str = None
+    ) -> dict[str, Any]:
+        """
+        Search memories using semantic similarity (vector search).
+
+        Args:
+            query: Search query
+            limit: Max results (1-50, default 10)
+            category: Optional category filter
+        """
+        try:
+            search_results = memory_store.search_memories(query, limit, category)
+            
+            if not search_results:
+                return {
+                    "success": True,
+                    "results": [],
+                    "message": "No matching memories found. Try different keywords or broader terms."
+                }
+            
+            # Convert SearchResult objects to dictionaries
+            results = [result.to_dict() for result in search_results]
+            
+            return {
+                "success": True,
+                "query": query,
+                "results": results,
+                "count": len(results),
+                "message": f"Found {len(results)} relevant memories"
+            }
+            
+        except SecurityError as e:
+            return {
+                "success": False,
+                "error": "Security validation failed",
+                "message": str(e)
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "error": "Search failed",
+                "message": str(e)
+            }
+    
+    @mcp.tool()
+    def list_recent_memories(limit: int = 10) -> dict[str, Any]:
+        """
+        List recent memories in chronological order.
+
+        Args:
+            limit: Max results (1-50, default 10)
+        """
+        try:
+            limit = min(max(1, limit), Config.MAX_MEMORIES_PER_SEARCH)
+            memories = memory_store.get_recent_memories(limit)
+            
+            # Convert MemoryEntry objects to dictionaries
+            memory_dicts = [memory.to_dict() for memory in memories]
+            
+            return {
+                "success": True,
+                "memories": memory_dicts,
+                "count": len(memory_dicts),
+                "message": f"Retrieved {len(memory_dicts)} recent memories"
+            }
+            
+        except Exception as e:
+            return {
+                "success": False,
+                "error": "Failed to get recent memories",
+                "message": str(e)
+            }
+    
+    @mcp.tool()
+    def get_memory_stats() -> dict[str, Any]:
+        """Get database statistics (total memories, categories, usage, health)."""
+        try:
+            stats = memory_store.get_stats()
+            result = stats.to_dict()
+            result["success"] = True
+            return result
+            
+        except Exception as e:
+            return {
+                "success": False,
+                "error": "Failed to get statistics",
+                "message": str(e)
+            }
+    
+    @mcp.tool()
+    def clear_old_memories(
+        days_old: int = 30,
+        max_to_keep: int = 1000
+    ) -> dict[str, Any]:
+        """
+        Clear old memories to free space (keeps frequently accessed).
+
+        Args:
+            days_old: Min age in days (default 30)
+            max_to_keep: Max total memories (default 1000)
+        """
+        try:
+            if days_old < 1:
+                return {
+                    "success": False,
+                    "error": "Invalid parameter",
+                    "message": "days_old must be at least 1"
+                }
+
+            result = memory_store.clear_old_memories(days_old, max_to_keep)
+            return result
+
+        except SecurityError as e:
+            return {
+                "success": False,
+                "error": "Security validation failed",
+                "message": str(e)
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "error": "Cleanup failed",
+                "message": str(e)
+            }
+
+    @mcp.tool()
+    def get_by_memory_id(memory_id: int) -> dict[str, Any]:
+        """
+        Get specific memory by ID.
+
+        Args:
+            memory_id: Memory ID to retrieve
+        """
+        try:
+            if not isinstance(memory_id, int) or memory_id < 1:
+                return {
+                    "success": False,
+                    "error": "Invalid parameter",
+                    "message": "memory_id must be a positive integer"
+                }
+
+            memory = memory_store.get_memory_by_id(memory_id)
+
+            if memory is None:
+                return {
+                    "success": False,
+                    "error": "Not found",
+                    "message": f"Memory with ID {memory_id} not found"
+                }
+
+            return {
+                "success": True,
+                "memory": memory.to_dict(),
+                "message": "Memory retrieved successfully"
+            }
+
+        except Exception as e:
+            return {
+                "success": False,
+                "error": "Retrieval failed",
+                "message": str(e)
+            }
+
+    @mcp.tool()
+    def delete_by_memory_id(memory_id: int) -> dict[str, Any]:
+        """
+        Delete memory by ID (permanent, cannot be undone).
+
+        Args:
+            memory_id: Memory ID to delete
+        """
+        try:
+            if not isinstance(memory_id, int) or memory_id < 1:
+                return {
+                    "success": False,
+                    "error": "Invalid parameter",
+                    "message": "memory_id must be a positive integer"
+                }
+
+            deleted = memory_store.delete_memory(memory_id)
+
+            if not deleted:
+                return {
+                    "success": False,
+                    "error": "Not found",
+                    "message": f"Memory with ID {memory_id} not found"
+                }
+
+            return {
+                "success": True,
+                "memory_id": memory_id,
+                "message": "Memory deleted successfully from both metadata and vector tables"
+            }
+
+        except Exception as e:
+            return {
+                "success": False,
+                "error": "Deletion failed",
+                "message": str(e)
+            }
+
+    return mcp
+
+
+def main():
+    """Main entry point"""
+    print(f"Starting {Config.SERVER_NAME} v{Config.SERVER_VERSION}", file=sys.stderr)
+    
+    try:
+        # Get working directory info
+        memory_dir = get_working_dir()
+        db_path = memory_dir / Config.DB_NAME
+        
+        print(f"Working directory: {memory_dir.parent}", file=sys.stderr)
+        print(f"Memory database: {db_path}", file=sys.stderr)
+        print(f"Embedding model: {Config.EMBEDDING_MODEL}", file=sys.stderr)
+        print("=" * 50, file=sys.stderr)
+        
+        # Create and run server
+        server = create_server()
+        print("Server ready for connections...", file=sys.stderr)
+        server.run()
+        
+    except KeyboardInterrupt:
+        print("\nServer stopped by user", file=sys.stderr)
+    except Exception as e:
+        print(f"Server failed to start: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

src/__init__.py

@@ -0,0 +1,45 @@
+"""
+Vector Memory MCP Server - Core Package
+=======================================
+
+This package provides vector-based memory capabilities for Claude Desktop
+using sqlite-vec and sentence-transformers.
+
+Modules:
+    models: Data models and type definitions
+    security: Security utilities and validation
+    embeddings: Sentence transformer wrapper (requires sentence-transformers)
+    memory_store: SQLite-vec operations and storage (requires sqlite-vec)
+"""
+
+__version__ = "1.0.0"
+__author__ = "Vector Memory MCP Server"
+
+# Core modules that don't require external dependencies
+from .models import MemoryEntry, MemoryCategory, SearchResult, Config
+from .security import SecurityError, validate_working_dir, sanitize_input
+
+# Optional imports that require external dependencies
+# These are imported lazily to avoid import errors when dependencies aren't available
+
+def get_embedding_model():
+    """Get embedding model (requires sentence-transformers)"""
+    from .embeddings import EmbeddingModel
+    return EmbeddingModel
+
+def get_vector_memory_store():
+    """Get vector memory store (requires sqlite-vec)"""
+    from .memory_store import VectorMemoryStore
+    return VectorMemoryStore
+
+__all__ = [
+    "MemoryEntry",
+    "MemoryCategory", 
+    "SearchResult",
+    "Config",
+    "SecurityError",
+    "validate_working_dir",
+    "sanitize_input",
+    "get_embedding_model",
+    "get_vector_memory_store"
+]

src/embeddings.py

@@ -0,0 +1,235 @@
+"""
+Embeddings Module
+=================
+
+Provides text embedding generation using sentence-transformers.
+Handles model initialization, caching, and vector operations.
+"""
+
+import os
+import sys
+from typing import List, Optional
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+from .models import Config
+from .security import SecurityError
+
+
+class EmbeddingModel:
+    """
+    Wrapper for sentence-transformers model with caching and validation.
+    """
+    
+    def __init__(self, model_name: str = None, cache_dir: str = None):
+        """
+        Initialize embedding model.
+        
+        Args:
+            model_name: Name of the sentence-transformers model
+            cache_dir: Directory to cache the model
+        """
+        self.model_name = model_name or Config.EMBEDDING_MODEL
+        self.cache_dir = cache_dir
+        self.model: Optional[SentenceTransformer] = None
+        self._embedding_dim: Optional[int] = None
+        
+    def _initialize_model(self) -> None:
+        """Initialize the sentence transformer model."""
+        try:
+            # Set cache directory if provided
+            if self.cache_dir:
+                os.environ['SENTENCE_TRANSFORMERS_HOME'] = self.cache_dir
+            
+            print(f"Loading embedding model: {self.model_name}", file=sys.stderr)
+            self.model = SentenceTransformer(self.model_name)
+            
+            # Verify model dimensions
+            test_embedding = self.model.encode(["test"], normalize_embeddings=True)
+            self._embedding_dim = test_embedding.shape[1]
+            
+            if self._embedding_dim != Config.EMBEDDING_DIM:
+                raise ValueError(
+                    f"Model dimension mismatch: expected {Config.EMBEDDING_DIM}, "
+                    f"got {self._embedding_dim}"
+                )
+            
+            print(f"Model loaded successfully. Dimensions: {self._embedding_dim}", file=sys.stderr)
+            
+        except Exception as e:
+            raise RuntimeError(f"Failed to initialize embedding model: {e}")
+    
+    @property
+    def embedding_dim(self) -> int:
+        """Get embedding dimensions."""
+        if self._embedding_dim is None:
+            if self.model is None:
+                self._initialize_model()
+            return self._embedding_dim
+        return self._embedding_dim
+    
+    def encode(self, texts: List[str], normalize: bool = True) -> np.ndarray:
+        """
+        Generate embeddings for a list of texts.
+        
+        Args:
+            texts: List of text strings to encode
+            normalize: Whether to normalize embeddings to unit length
+            
+        Returns:
+            np.ndarray: Array of embeddings with shape (len(texts), embedding_dim)
+            
+        Raises:
+            SecurityError: If input validation fails
+            RuntimeError: If encoding fails
+        """
+        if not isinstance(texts, list):
+            raise SecurityError("Input must be a list of strings")
+        
+        if not texts:
+            raise SecurityError("Input list cannot be empty")
+        
+        # Validate each text
+        for i, text in enumerate(texts):
+            if not isinstance(text, str):
+                raise SecurityError(f"Text at index {i} must be a string")
+            if not text.strip():
+                raise SecurityError(f"Text at index {i} cannot be empty")
+        
+        # Initialize model if needed
+        if self.model is None:
+            self._initialize_model()
+        
+        try:
+            embeddings = self.model.encode(
+                texts,
+                normalize_embeddings=normalize,
+                convert_to_numpy=True
+            )
+            return embeddings
+            
+        except Exception as e:
+            raise RuntimeError(f"Failed to generate embeddings: {e}")
+    
+    def encode_single(self, text: str, normalize: bool = True) -> List[float]:
+        """
+        Generate embedding for a single text.
+        
+        Args:
+            text: Text string to encode
+            normalize: Whether to normalize embedding to unit length
+            
+        Returns:
+            List[float]: Embedding vector as list of floats
+            
+        Raises:
+            SecurityError: If input validation fails
+            RuntimeError: If encoding fails
+        """
+        embeddings = self.encode([text], normalize=normalize)
+        return embeddings[0].tolist()
+    
+    def similarity(self, text1: str, text2: str) -> float:
+        """
+        Calculate cosine similarity between two texts.
+        
+        Args:
+            text1: First text
+            text2: Second text
+            
+        Returns:
+            float: Cosine similarity score (0-1)
+        """
+        embeddings = self.encode([text1, text2], normalize=True)
+        
+        # Cosine similarity with normalized vectors is just dot product
+        similarity = np.dot(embeddings[0], embeddings[1])
+        return float(similarity)
+    
+    def batch_similarity(self, query: str, texts: List[str]) -> List[float]:
+        """
+        Calculate similarity between a query and multiple texts.
+        
+        Args:
+            query: Query text
+            texts: List of texts to compare against
+            
+        Returns:
+            List[float]: Similarity scores for each text
+        """
+        all_texts = [query] + texts
+        embeddings = self.encode(all_texts, normalize=True)
+        
+        query_embedding = embeddings[0]
+        text_embeddings = embeddings[1:]
+        
+        # Calculate dot products (cosine similarity with normalized vectors)
+        similarities = [
+            float(np.dot(query_embedding, text_emb))
+            for text_emb in text_embeddings
+        ]
+        
+        return similarities
+    
+    def get_model_info(self) -> dict:
+        """
+        Get information about the loaded model.
+        
+        Returns:
+            dict: Model information
+        """
+        if self.model is None:
+            self._initialize_model()
+        
+        return {
+            "model_name": self.model_name,
+            "embedding_dimensions": self.embedding_dim,
+            "max_sequence_length": getattr(self.model, 'max_seq_length', 'Unknown'),
+            "device": str(self.model.device) if hasattr(self.model, 'device') else 'Unknown',
+            "cache_dir": self.cache_dir or 'Default'
+        }
+    
+    def validate_embedding(self, embedding: List[float]) -> bool:
+        """
+        Validate that an embedding has the correct dimensions.
+        
+        Args:
+            embedding: Embedding vector to validate
+            
+        Returns:
+            bool: True if valid, False otherwise
+        """
+        return (
+            isinstance(embedding, list) and
+            len(embedding) == self.embedding_dim and
+            all(isinstance(x, (int, float)) for x in embedding)
+        )
+
+
+# Global model instance for efficient reuse
+_global_model: Optional[EmbeddingModel] = None
+
+
+def get_embedding_model(model_name: str = None, cache_dir: str = None) -> EmbeddingModel:
+    """
+    Get global embedding model instance (singleton pattern).
+    
+    Args:
+        model_name: Name of the model (only used on first call)
+        cache_dir: Cache directory (only used on first call)
+        
+    Returns:
+        EmbeddingModel: Global model instance
+    """
+    global _global_model
+    
+    if _global_model is None:
+        _global_model = EmbeddingModel(model_name, cache_dir)
+    
+    return _global_model
+
+
+def reset_embedding_model() -> None:
+    """Reset global model instance (useful for testing)."""
+    global _global_model
+    _global_model = None