superlocalmemory 2.4.2 → 2.5.1

package/mcp_server.py

@@ -46,6 +46,14 @@ except ImportError as e:
     print(f"Ensure SuperLocalMemory V2 is installed at {MEMORY_DIR}", file=sys.stderr)
     sys.exit(1)
 
+# Agent Registry + Provenance (v2.5+)
+try:
+    from agent_registry import AgentRegistry
+    from provenance_tracker import ProvenanceTracker
+    PROVENANCE_AVAILABLE = True
+except ImportError:
+    PROVENANCE_AVAILABLE = False
+
 # Parse command line arguments early (needed for port in constructor)
 import argparse as _argparse
 _parser = _argparse.ArgumentParser(add_help=False)
@@ -63,6 +71,80 @@ mcp = FastMCP(
 # Database path
 DB_PATH = MEMORY_DIR / "memory.db"
 
+# ============================================================================
+# Shared singleton instances (v2.5 — fixes per-call instantiation overhead)
+# All MCP tool handlers share one MemoryStoreV2 instance instead of creating
+# a new one per call. This means one ConnectionManager, one TF-IDF vectorizer,
+# one write queue — shared across all concurrent MCP requests.
+# ============================================================================
+
+_store = None
+_graph_engine = None
+_pattern_learner = None
+
+
+def get_store() -> MemoryStoreV2:
+    """Get or create the shared MemoryStoreV2 singleton."""
+    global _store
+    if _store is None:
+        _store = MemoryStoreV2(DB_PATH)
+    return _store
+
+
+def get_graph_engine() -> GraphEngine:
+    """Get or create the shared GraphEngine singleton."""
+    global _graph_engine
+    if _graph_engine is None:
+        _graph_engine = GraphEngine(DB_PATH)
+    return _graph_engine
+
+
+def get_pattern_learner() -> PatternLearner:
+    """Get or create the shared PatternLearner singleton."""
+    global _pattern_learner
+    if _pattern_learner is None:
+        _pattern_learner = PatternLearner(DB_PATH)
+    return _pattern_learner
+
+
+_agent_registry = None
+_provenance_tracker = None
+
+
+def get_agent_registry():
+    """Get shared AgentRegistry singleton (v2.5+). Returns None if unavailable."""
+    global _agent_registry
+    if not PROVENANCE_AVAILABLE:
+        return None
+    if _agent_registry is None:
+        _agent_registry = AgentRegistry.get_instance(DB_PATH)
+    return _agent_registry
+
+
+def get_provenance_tracker():
+    """Get shared ProvenanceTracker singleton (v2.5+). Returns None if unavailable."""
+    global _provenance_tracker
+    if not PROVENANCE_AVAILABLE:
+        return None
+    if _provenance_tracker is None:
+        _provenance_tracker = ProvenanceTracker.get_instance(DB_PATH)
+    return _provenance_tracker
+
+
+def _register_mcp_agent(agent_name: str = "mcp-client"):
+    """Register the calling MCP agent and record activity. Non-blocking."""
+    registry = get_agent_registry()
+    if registry:
+        try:
+            registry.register_agent(
+                agent_id=f"mcp:{agent_name}",
+                agent_name=agent_name,
+                protocol="mcp",
+            )
+        except Exception:
+            pass
+
+
 # ============================================================================
 # MCP TOOLS (Functions callable by AI)
 # ============================================================================
@@ -103,8 +185,11 @@ async def remember(
         remember("JWT auth with refresh tokens", tags="security,auth", importance=8)
     """
     try:
+        # Register MCP agent (v2.5 — agent tracking)
+        _register_mcp_agent()
+
         # Use existing MemoryStoreV2 class (no duplicate logic)
-        store = MemoryStoreV2(DB_PATH)
+        store = get_store()
 
         # Call existing add_memory method
         memory_id = store.add_memory(
@@ -114,6 +199,22 @@ async def remember(
             importance=importance
         )
 
+        # Record provenance (v2.5 — who created this memory)
+        prov = get_provenance_tracker()
+        if prov:
+            try:
+                prov.record_provenance(memory_id, created_by="mcp:client", source_protocol="mcp")
+            except Exception:
+                pass
+
+        # Track write in agent registry
+        registry = get_agent_registry()
+        if registry:
+            try:
+                registry.record_write("mcp:mcp-client")
+            except Exception:
+                pass
+
         # Format response
         preview = content[:100] + "..." if len(content) > 100 else content
 
@@ -174,7 +275,7 @@ async def recall(
     """
     try:
         # Use existing MemoryStoreV2 class
-        store = MemoryStoreV2(DB_PATH)
+        store = get_store()
 
         # Call existing search method
         results = store.search(query, limit=limit)
@@ -223,7 +324,7 @@ async def list_recent(limit: int = 10) -> dict:
     """
     try:
         # Use existing MemoryStoreV2 class
-        store = MemoryStoreV2(DB_PATH)
+        store = get_store()
 
         # Call existing list_all method
         memories = store.list_all(limit=limit)
@@ -263,7 +364,7 @@ async def get_status() -> dict:
     """
     try:
         # Use existing MemoryStoreV2 class
-        store = MemoryStoreV2(DB_PATH)
+        store = get_store()
 
         # Call existing get_stats method
         stats = store.get_stats()
@@ -303,7 +404,7 @@ async def build_graph() -> dict:
     """
     try:
         # Use existing GraphEngine class
-        engine = GraphEngine(DB_PATH)
+        engine = get_graph_engine()
 
         # Call existing build_graph method
         stats = engine.build_graph()
@@ -461,7 +562,7 @@ async def search(query: str) -> dict:
         {"results": [{"id": str, "title": str, "text": str, "url": str}]}
     """
     try:
-        store = MemoryStoreV2(DB_PATH)
+        store = get_store()
         raw_results = store.search(query, limit=20)
 
         results = []
@@ -504,7 +605,7 @@ async def fetch(id: str) -> dict:
         {"id": str, "title": str, "text": str, "url": str, "metadata": dict|null}
     """
     try:
-        store = MemoryStoreV2(DB_PATH)
+        store = get_store()
         mem = store.get_by_id(int(id))
 
         if not mem:
@@ -549,7 +650,7 @@ async def get_recent_memories_resource(limit: str) -> str:
     Usage: memory://recent/10
     """
     try:
-        store = MemoryStoreV2(DB_PATH)
+        store = get_store()
         memories = store.list_all(limit=int(limit))
         return json.dumps(memories, indent=2)
     except Exception as e:
@@ -564,7 +665,7 @@ async def get_stats_resource() -> str:
     Usage: memory://stats
     """
     try:
-        store = MemoryStoreV2(DB_PATH)
+        store = get_store()
         stats = store.get_stats()
         return json.dumps(stats, indent=2)
     except Exception as e:
@@ -579,7 +680,7 @@ async def get_clusters_resource() -> str:
     Usage: memory://graph/clusters
     """
     try:
-        engine = GraphEngine(DB_PATH)
+        engine = get_graph_engine()
         stats = engine.get_stats()
         clusters = stats.get('clusters', [])
         return json.dumps(clusters, indent=2)
@@ -595,7 +696,7 @@ async def get_coding_identity_resource() -> str:
     Usage: memory://patterns/identity
     """
     try:
-        learner = PatternLearner(DB_PATH)
+        learner = get_pattern_learner()
         patterns = learner.get_identity_context(min_confidence=0.5)
         return json.dumps(patterns, indent=2)
     except Exception as e:
@@ -615,7 +716,7 @@ async def coding_identity_prompt() -> str:
     based on learned preferences and patterns.
     """
     try:
-        learner = PatternLearner(DB_PATH)
+        learner = get_pattern_learner()
         patterns = learner.get_identity_context(min_confidence=0.6)
 
         if not patterns:
@@ -656,7 +757,7 @@ async def project_context_prompt(project_name: str) -> str:
         Formatted prompt with relevant project memories
     """
     try:
-        store = MemoryStoreV2(DB_PATH)
+        store = get_store()
 
         # Search for project-related memories
         memories = store.search(f"project:{project_name}", limit=20)
@@ -711,7 +812,7 @@ if __name__ == "__main__":
     # Print startup message to stderr (stdout is used for MCP protocol)
     print("=" * 60, file=sys.stderr)
     print("SuperLocalMemory V2 - MCP Server", file=sys.stderr)
-    print("Version: 2.4.1", file=sys.stderr)
+    print("Version: 2.5.0", file=sys.stderr)
     print("=" * 60, file=sys.stderr)
     print("Created by: Varun Pratap Bhardwaj (Solution Architect)", file=sys.stderr)
     print("Repository: https://github.com/varun369/SuperLocalMemoryV2", file=sys.stderr)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "2.4.2",
+  "version": "2.5.1",
   "description": "Your AI Finally Remembers You - Local-first intelligent memory system for AI assistants. Works with Claude, Cursor, Windsurf, VS Code/Copilot, Codex, and 16+ AI tools. 100% local, zero cloud dependencies.",
   "keywords": [
     "ai-memory",
@@ -98,5 +98,8 @@
     "year": "2026",
     "github": "https://github.com/varun369",
     "required": "Attribution notice must be preserved in all copies and derivative works"
+  },
+  "dependencies": {
+    "docx": "^9.5.1"
   }
 }

package/scripts/generate-thumbnails.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""
+SuperLocalMemory V2 - Thumbnail Generator
+Copyright (c) 2026 Varun Pratap Bhardwaj
+Licensed under MIT License
+
+Generates optimized thumbnail versions of all screenshots.
+- Size: 320×180px (16:9 ratio)
+- Format: PNG (for wiki/docs) and WebP (for website)
+- Quality: High enough to recognize content
+- File size: < 50KB per thumbnail
+"""
+
+import os
+import json
+from pathlib import Path
+from PIL import Image, ImageFilter, ImageOps
+from datetime import datetime
+
+# Configuration
+SCREENSHOT_DIR = Path(__file__).parent.parent / "assets" / "screenshots"
+THUMBNAIL_DIR = Path(__file__).parent.parent / "assets" / "thumbnails"
+THUMBNAIL_SIZE = (320, 180)  # 16:9 ratio
+QUALITY_PNG = 95
+QUALITY_WEBP = 85
+MAX_FILESIZE = 50 * 1024  # 50KB
+
+# Category mapping based on filename patterns
+CATEGORY_MAP = {
+    "overview": "dashboard",
+    "timeline": "timeline",
+    "agents": "agents",
+    "patterns": "patterns",
+    "clusters": "clusters",
+    "memories": "memories",
+    "graph": "graph",
+    "filtered": "search",
+    "live-events": "events",
+}
+
+def get_category(filename):
+    """Extract category from filename."""
+    for pattern, category in CATEGORY_MAP.items():
+        if pattern in filename.lower():
+            return category
+    return "general"
+
+def get_title(filename):
+    """Generate human-readable title from filename."""
+    # Remove extensions and convert dashes/underscores to spaces
+    name = Path(filename).stem
+    # Remove 'dashboard-' prefix if present
+    if name.startswith("dashboard-"):
+        name = name[9:]
+    # Remove '-dark' suffix
+    name = name.replace("-dark", "")
+    # Convert to title case
+    return " ".join(word.capitalize() for word in name.split("-"))
+
+def get_description(filename, category):
+    """Generate description based on filename and category."""
+    descriptions = {
+        "overview": "Main dashboard with memory statistics and knowledge graph overview",
+        "timeline": "Chronological timeline of all stored memories and events",
+        "agents": "Agent connections and activity tracking",
+        "patterns": "Learned coding patterns and user preferences",
+        "clusters": "Knowledge graph clusters and relationships",
+        "memories": "Detailed memory list with search and filtering",
+        "graph": "Interactive knowledge graph visualization",
+        "search": "Advanced memory search and filtering interface",
+        "events": "Real-time live event stream from memory operations",
+    }
+    is_dark = "-dark" in filename.lower()
+    base_desc = descriptions.get(category, "Dashboard interface")
+    if is_dark:
+        base_desc += " (dark mode)"
+    return base_desc
+
+def resize_and_crop(image, target_size):
+    """
+    Resize image to target size while maintaining aspect ratio.
+    Crops if necessary to achieve exact dimensions.
+    """
+    img_ratio = image.width / image.height
+    target_ratio = target_size[0] / target_size[1]
+
+    if img_ratio > target_ratio:
+        # Image is wider, crop width
+        new_height = target_size[1]
+        new_width = int(new_height * img_ratio)
+        resized = image.resize((new_width, new_height), Image.Resampling.LANCZOS)
+        left = (resized.width - target_size[0]) // 2
+        return resized.crop((left, 0, left + target_size[0], target_size[1]))
+    else:
+        # Image is taller, crop height
+        new_width = target_size[0]
+        new_height = int(new_width / img_ratio)
+        resized = image.resize((new_width, new_height), Image.Resampling.LANCZOS)
+        top = (resized.height - target_size[1]) // 2
+        return resized.crop((0, top, target_size[0], top + target_size[1]))
+
+def apply_sharpening(image):
+    """Apply subtle sharpening to enhance detail."""
+    # Use UNSHARP_MASK equivalent with subtle settings
+    return image.filter(ImageFilter.UnsharpMask(radius=1, percent=100, threshold=3))
+
+def generate_thumbnail(source_path, dest_dir, metadata):
+    """Generate PNG and WebP thumbnails for a single source image."""
+    try:
+        # Open image
+        with Image.open(source_path) as img:
+            # Convert RGBA to RGB if necessary (for PNG/WebP)
+            if img.mode == "RGBA":
+                background = Image.new("RGB", img.size, (255, 255, 255))
+                background.paste(img, mask=img.split()[3])
+                img = background
+            elif img.mode != "RGB":
+                img = img.convert("RGB")
+
+            # Resize and crop
+            thumbnail = resize_and_crop(img, THUMBNAIL_SIZE)
+
+            # Apply sharpening
+            thumbnail = apply_sharpening(thumbnail)
+
+            filename = source_path.stem
+
+            # Save PNG version
+            png_path = dest_dir / f"{filename}-thumb.png"
+            thumbnail.save(png_path, "PNG", quality=QUALITY_PNG, optimize=True)
+            png_size = png_path.stat().st_size
+
+            # Save WebP version
+            webp_path = dest_dir / f"{filename}-thumb.webp"
+            thumbnail.save(webp_path, "WEBP", quality=QUALITY_WEBP, method=6)
+            webp_size = webp_path.stat().st_size
+
+            # Check file sizes
+            if png_size > MAX_FILESIZE:
+                print(f"⚠️  PNG {filename}: {png_size/1024:.1f}KB (exceeds limit)")
+            if webp_size > MAX_FILESIZE:
+                print(f"⚠️  WebP {filename}: {webp_size/1024:.1f}KB (exceeds limit)")
+
+            print(f"✓ {filename}")
+            print(f"  PNG: {png_size/1024:.1f}KB | WebP: {webp_size/1024:.1f}KB")
+
+            # Store metadata
+            category = get_category(filename)
+            metadata[filename] = {
+                "title": get_title(filename),
+                "description": get_description(source_path.name, category),
+                "category": category,
+                "full_image": f"../screenshots/dashboard/{source_path.name}",
+                "thumbnail_png": f"{filename}-thumb.png",
+                "thumbnail_webp": f"{filename}-thumb.webp",
+                "created": datetime.now().isoformat(),
+                "original_size": f"{img.width}×{img.height}",
+                "thumbnail_size": f"{THUMBNAIL_SIZE[0]}×{THUMBNAIL_SIZE[1]}",
+                "png_size_kb": round(png_size / 1024, 2),
+                "webp_size_kb": round(webp_size / 1024, 2),
+            }
+            return True
+    except Exception as e:
+        print(f"✗ {source_path.name}: {str(e)}")
+        return False
+
+def main():
+    """Generate all thumbnails."""
+    # Ensure thumbnail directory exists
+    THUMBNAIL_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Verify screenshot directory exists
+    if not SCREENSHOT_DIR.exists():
+        print(f"Error: Screenshot directory not found: {SCREENSHOT_DIR}")
+        return 1
+
+    # Find all images in screenshot directory
+    image_extensions = {".png", ".jpg", ".jpeg", ".webp"}
+    sources = sorted([
+        f for f in SCREENSHOT_DIR.glob("**/*")
+        if f.is_file() and f.suffix.lower() in image_extensions and not f.name.startswith(".")
+    ])
+
+    if not sources:
+        print(f"No images found in {SCREENSHOT_DIR}")
+        return 1
+
+    print(f"Found {len(sources)} images in {SCREENSHOT_DIR}")
+    print(f"Generating thumbnails to {THUMBNAIL_DIR}\n")
+
+    metadata = {}
+    successful = 0
+    failed = 0
+
+    for source in sources:
+        if generate_thumbnail(source, THUMBNAIL_DIR, metadata):
+            successful += 1
+        else:
+            failed += 1
+
+    # Save metadata index
+    index_path = THUMBNAIL_DIR / "index.json"
+    with open(index_path, "w") as f:
+        json.dump(metadata, f, indent=2, sort_keys=True)
+    print(f"\n✓ Saved metadata index to {index_path}")
+
+    # Print summary
+    print(f"\n{'='*60}")
+    print(f"Summary:")
+    print(f"  Total processed: {len(sources)}")
+    print(f"  Successful: {successful}")
+    print(f"  Failed: {failed}")
+    print(f"  PNG thumbnails: {len(list(THUMBNAIL_DIR.glob('*-thumb.png')))}")
+    print(f"  WebP thumbnails: {len(list(THUMBNAIL_DIR.glob('*-thumb.webp')))}")
+    print(f"  Total size: {sum(f.stat().st_size for f in THUMBNAIL_DIR.glob('*-thumb.*')) / 1024:.1f}KB")
+
+    return 0 if failed == 0 else 1
+
+if __name__ == "__main__":
+    exit(main())