superlocalmemory 2.7.6 → 2.8.0

package/src/search/methods.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Individual search methods (BM25, semantic, graph) for hybrid search.
+"""
+from typing import List, Tuple
+
+
+class SearchMethodsMixin:
+    """
+    Mixin providing individual search method implementations.
+
+    Expects the host class to have:
+        - self.bm25: BM25SearchEngine
+        - self.optimizer: QueryOptimizer
+        - self._tfidf_vectorizer
+        - self._tfidf_vectors
+        - self._memory_ids: list
+        - self._load_graph_engine() method
+        - self.search_bm25() method (for graph seed)
+    """
+
+    def search_bm25(
+        self,
+        query: str,
+        limit: int = 10,
+        score_threshold: float = 0.0
+    ) -> List[Tuple[int, float]]:
+        """
+        Search using BM25 keyword matching.
+
+        Args:
+            query: Search query
+            limit: Maximum results
+            score_threshold: Minimum score threshold
+
+        Returns:
+            List of (memory_id, score) tuples
+        """
+        # Optimize query
+        optimized = self.optimizer.optimize(
+            query,
+            enable_spell_correction=True,
+            enable_expansion=False  # Expansion can hurt precision
+        )
+
+        # Search with BM25
+        results = self.bm25.search(optimized, limit, score_threshold)
+
+        return results
+
+    def search_semantic(
+        self,
+        query: str,
+        limit: int = 10,
+        score_threshold: float = 0.05
+    ) -> List[Tuple[int, float]]:
+        """
+        Search using TF-IDF semantic similarity.
+
+        Args:
+            query: Search query
+            limit: Maximum results
+            score_threshold: Minimum similarity threshold
+
+        Returns:
+            List of (memory_id, score) tuples
+        """
+        if self._tfidf_vectorizer is None or self._tfidf_vectors is None:
+            return []
+
+        try:
+            from sklearn.metrics.pairwise import cosine_similarity
+            import numpy as np
+
+            # Vectorize query
+            query_vec = self._tfidf_vectorizer.transform([query])
+
+            # Calculate similarities
+            similarities = cosine_similarity(query_vec, self._tfidf_vectors).flatten()
+
+            # Get top results above threshold
+            results = []
+            for idx, score in enumerate(similarities):
+                if score >= score_threshold:
+                    memory_id = self._memory_ids[idx]
+                    results.append((memory_id, float(score)))
+
+            # Sort by score and limit
+            results.sort(key=lambda x: x[1], reverse=True)
+            return results[:limit]
+
+        except Exception as e:
+            # Fallback gracefully
+            return []
+
+    def search_graph(
+        self,
+        query: str,
+        limit: int = 10,
+        max_depth: int = 2
+    ) -> List[Tuple[int, float]]:
+        """
+        Search using graph traversal from initial matches.
+
+        Strategy:
+        1. Get seed memories from BM25
+        2. Traverse graph to find related memories
+        3. Score by distance from seed nodes
+
+        Args:
+            query: Search query
+            limit: Maximum results
+            max_depth: Maximum graph traversal depth
+
+        Returns:
+            List of (memory_id, score) tuples
+        """
+        graph = self._load_graph_engine()
+        if graph is None:
+            return []
+
+        # Get seed memories from BM25
+        seed_results = self.search_bm25(query, limit=5)
+        if not seed_results:
+            return []
+
+        seed_ids = [mem_id for mem_id, _ in seed_results]
+
+        # Traverse graph from seed nodes
+        visited = set(seed_ids)
+        results = []
+
+        # BFS traversal
+        queue = [(mem_id, 1.0, 0) for mem_id in seed_ids]  # (id, score, depth)
+
+        while queue and len(results) < limit:
+            current_id, current_score, depth = queue.pop(0)
+
+            if depth > max_depth:
+                continue
+
+            # Add to results
+            if current_id not in [r[0] for r in results]:
+                results.append((current_id, current_score))
+
+            # Get related memories from graph
+            try:
+                related = graph.get_related_memories(current_id, limit=5)
+
+                for rel_id, similarity in related:
+                    if rel_id not in visited:
+                        visited.add(rel_id)
+                        # Decay score by depth
+                        new_score = current_score * similarity * (0.7 ** depth)
+                        queue.append((rel_id, new_score, depth + 1))
+
+            except Exception:
+                # Graph operation failed - skip
+                continue
+
+        return results[:limit]

package/src/search_engine_v2.py

@@ -1,16 +1,14 @@
 #!/usr/bin/env python3
-"""
-SuperLocalMemory V2 - BM25 Search Engine
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""SuperLocalMemory V2 - BM25 Search Engine
 
-Copyright (c) 2026 Varun Pratap Bhardwaj
 Solution Architect & Original Creator
 
-Licensed under MIT License (see LICENSE file)
-Repository: https://github.com/varun369/SuperLocalMemoryV2
+ (see LICENSE file)
 
 ATTRIBUTION REQUIRED: This notice must be preserved in all copies.
 """
-
 """
 BM25 Search Engine - Pure Python Implementation
 

package/src/setup_validator.py

@@ -1,16 +1,11 @@
 #!/usr/bin/env python3
-"""
-SuperLocalMemory V2 - Setup Validator
-Copyright (c) 2026 Varun Pratap Bhardwaj
-Licensed under MIT License
-
-Repository: https://github.com/varun369/SuperLocalMemoryV2
-Author: Varun Pratap Bhardwaj (Solution Architect)
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""SuperLocalMemory V2 - Setup Validator
 
 First-run setup validator that ensures all dependencies are installed
 and the database is properly initialized.
 """
-
 import sys
 import os
 import sqlite3
@@ -41,9 +36,8 @@ def print_banner():
     """Print product banner."""
     print("""
 ╔══════════════════════════════════════════════════════════════╗
-║  SuperLocalMemory V2 - Setup Validator                       ║
-║  by Varun Pratap Bhardwaj                                    ║
-║  https://github.com/varun369/SuperLocalMemoryV2              ║
+║  SuperLocalMemory - Setup Validator                          ║
+║  https://superlocalmemory.com                                ║
 ╚══════════════════════════════════════════════════════════════╝
 """)
 
@@ -338,8 +332,8 @@ def initialize_database() -> Tuple[bool, str]:
         # Add system watermark
         cursor.execute('''
             INSERT OR REPLACE INTO system_metadata (key, value) VALUES
-            ('product', 'SuperLocalMemory V2'),
-            ('author', 'Varun Pratap Bhardwaj'),
+            ('product', 'SuperLocalMemory'),
+            ('website', 'https://superlocalmemory.com'),
             ('repository', 'https://github.com/varun369/SuperLocalMemoryV2'),
             ('license', 'MIT'),
             ('schema_version', '2.0.0')

package/src/subscription_manager.py

@@ -1,16 +1,6 @@
 #!/usr/bin/env python3
-"""
-SuperLocalMemory V2 - Subscription Manager
-Copyright (c) 2026 Varun Pratap Bhardwaj
-Licensed under MIT License
-
-Repository: https://github.com/varun369/SuperLocalMemoryV2
-Author: Varun Pratap Bhardwaj (Solution Architect)
-
-NOTICE: This software is protected by MIT License.
-Attribution must be preserved in all copies or derivatives.
-"""
-
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
 """
 SubscriptionManager — Manages durable and ephemeral event subscriptions.
 

package/src/tree/__init__.py

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Tree — Hierarchical Memory Tree Management.
+
+Composes the TreeManager class from focused mixin modules:
+  - schema.py  : DB initialization and root-node bootstrap
+  - nodes.py   : Node CRUD and count aggregation
+  - queries.py : Read-only tree traversal and statistics
+  - builder.py : Full tree construction from memories table
+"""
+from pathlib import Path
+from typing import Optional
+
+from .schema import TreeSchemaMixin, MEMORY_DIR, DB_PATH
+from .nodes import TreeNodesMixin
+from .queries import TreeQueriesMixin
+from .builder import TreeBuilderMixin
+
+
+class TreeManager(TreeSchemaMixin, TreeNodesMixin, TreeQueriesMixin, TreeBuilderMixin):
+    """
+    Manages hierarchical tree structure for memory navigation.
+
+    Tree Structure:
+        Root
+        +-- Project: NextJS-App
+        |   +-- Category: Frontend
+        |   |   +-- Memory: React Components
+        |   |   +-- Memory: State Management
+        |   +-- Category: Backend
+        |       +-- Memory: API Routes
+        +-- Project: Python-ML
+
+    Materialized Path Format:
+        - Root: "1"
+        - Project: "1.2"
+        - Category: "1.2.3"
+        - Memory: "1.2.3.4"
+
+    Benefits:
+        - Fast subtree queries: WHERE tree_path LIKE '1.2.%'
+        - O(1) depth calculation: count dots in path
+        - O(1) parent lookup: parse path
+        - No recursive CTEs needed
+    """
+
+    def __init__(self, db_path: Optional[Path] = None):
+        """
+        Initialize TreeManager.
+
+        Args:
+            db_path: Optional custom database path
+        """
+        self.db_path = db_path or DB_PATH
+        self._init_db()
+        self.root_id = self._ensure_root()
+
+
+__all__ = ['TreeManager', 'MEMORY_DIR', 'DB_PATH']

package/src/tree/builder.py

@@ -0,0 +1,183 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Tree Builder — Constructs the full tree from the memories table.
+
+Provides TreeBuilderMixin with build_tree, plus the CLI entry point.
+"""
+import sqlite3
+
+
+class TreeBuilderMixin:
+    """Builds the hierarchical tree from flat memory records."""
+
+    def build_tree(self):
+        """
+        Build complete tree structure from memories table.
+
+        Process:
+        1. Clear existing tree (except root)
+        2. Group memories by project
+        3. Group by category within projects
+        4. Link individual memories as leaf nodes
+        5. Update aggregated counts
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Clear existing tree (keep root)
+        cursor.execute('DELETE FROM memory_tree WHERE node_type != ?', ('root',))
+
+        # Step 1: Create project nodes
+        cursor.execute('''
+            SELECT DISTINCT project_path, project_name
+            FROM memories
+            WHERE project_path IS NOT NULL
+            ORDER BY project_path
+        ''')
+        projects = cursor.fetchall()
+
+        project_map = {}  # project_path -> node_id
+
+        for project_path, project_name in projects:
+            name = project_name or project_path.split('/')[-1]
+            node_id = self.add_node('project', name, self.root_id, description=project_path)
+            project_map[project_path] = node_id
+
+        # Step 2: Create category nodes within projects
+        cursor.execute('''
+            SELECT DISTINCT project_path, category
+            FROM memories
+            WHERE project_path IS NOT NULL AND category IS NOT NULL
+            ORDER BY project_path, category
+        ''')
+        categories = cursor.fetchall()
+
+        category_map = {}  # (project_path, category) -> node_id
+
+        for project_path, category in categories:
+            parent_id = project_map.get(project_path)
+            if parent_id:
+                node_id = self.add_node('category', category, parent_id)
+                category_map[(project_path, category)] = node_id
+
+        # Step 3: Link memories as leaf nodes
+        cursor.execute('''
+            SELECT id, content, summary, project_path, category, importance, created_at
+            FROM memories
+            ORDER BY created_at DESC
+        ''')
+        memories = cursor.fetchall()
+
+        for mem_id, content, summary, project_path, category, importance, created_at in memories:
+            # Determine parent node
+            if project_path and category and (project_path, category) in category_map:
+                parent_id = category_map[(project_path, category)]
+            elif project_path and project_path in project_map:
+                parent_id = project_map[project_path]
+            else:
+                parent_id = self.root_id
+
+            # Create memory node
+            name = summary or content[:60].replace('\n', ' ')
+            self.add_node('memory', name, parent_id, memory_id=mem_id, description=content[:200])
+
+        # Step 4: Update aggregated counts
+        self._update_all_counts()
+
+        conn.commit()
+        conn.close()
+
+
+def run_cli():
+    """CLI entry point for tree_manager."""
+    import sys
+    import json
+    from src.tree import TreeManager
+
+    tree_mgr = TreeManager()
+
+    if len(sys.argv) < 2:
+        print("TreeManager CLI")
+        print("\nCommands:")
+        print("  python tree_manager.py build                  # Build tree from memories")
+        print("  python tree_manager.py show [project] [depth] # Show tree structure")
+        print("  python tree_manager.py subtree <node_id>      # Get subtree")
+        print("  python tree_manager.py path <node_id>         # Get path to root")
+        print("  python tree_manager.py stats                  # Show statistics")
+        print("  python tree_manager.py add <type> <name> <parent_id>  # Add node")
+        print("  python tree_manager.py delete <node_id>       # Delete node")
+        sys.exit(0)
+
+    command = sys.argv[1]
+
+    if command == "build":
+        print("Building tree from memories...")
+        tree_mgr.build_tree()
+        stats = tree_mgr.get_stats()
+        print(f"Tree built: {stats['total_nodes']} nodes, {stats['total_memories']} memories")
+
+    elif command == "show":
+        project = sys.argv[2] if len(sys.argv) > 2 else None
+        max_depth = int(sys.argv[3]) if len(sys.argv) > 3 else None
+
+        tree = tree_mgr.get_tree(project, max_depth)
+
+        def print_tree(node, indent=0):
+            if 'error' in node:
+                print(node['error'])
+                return
+
+            prefix = "  " * indent
+            icon = {"root": "\U0001f333", "project": "\U0001f4c1", "category": "\U0001f4c2", "memory": "\U0001f4c4"}.get(node['type'], "\u2022")
+
+            print(f"{prefix}{icon} {node['name']} (id={node['id']}, memories={node['memory_count']})")
+
+            for child in node.get('children', []):
+                print_tree(child, indent + 1)
+
+        print_tree(tree)
+
+    elif command == "subtree" and len(sys.argv) >= 3:
+        node_id = int(sys.argv[2])
+        nodes = tree_mgr.get_subtree(node_id)
+
+        if not nodes:
+            print(f"No subtree found for node {node_id}")
+        else:
+            print(f"Subtree of node {node_id}:")
+            for node in nodes:
+                indent = "  " * (node['depth'] - nodes[0]['depth'] + 1)
+                print(f"{indent}- {node['name']} (id={node['id']})")
+
+    elif command == "path" and len(sys.argv) >= 3:
+        node_id = int(sys.argv[2])
+        path = tree_mgr.get_path_to_root(node_id)
+
+        if not path:
+            print(f"Node {node_id} not found")
+        else:
+            print("Path to root:")
+            print(" > ".join([f"{n['name']} (id={n['id']})" for n in path]))
+
+    elif command == "stats":
+        stats = tree_mgr.get_stats()
+        print(json.dumps(stats, indent=2))
+
+    elif command == "add" and len(sys.argv) >= 5:
+        node_type = sys.argv[2]
+        name = sys.argv[3]
+        parent_id = int(sys.argv[4])
+
+        node_id = tree_mgr.add_node(node_type, name, parent_id)
+        print(f"Node created with ID: {node_id}")
+
+    elif command == "delete" and len(sys.argv) >= 3:
+        node_id = int(sys.argv[2])
+        if tree_mgr.delete_node(node_id):
+            print(f"Node {node_id} deleted")
+        else:
+            print(f"Node {node_id} not found")
+
+    else:
+        print(f"Unknown command: {command}")
+        sys.exit(1)

package/src/tree/nodes.py

@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Tree Nodes — CRUD operations and count aggregation.
+
+Provides TreeNodesMixin with add_node, delete_node, update_counts,
+and internal helper methods for materialized-path management.
+"""
+import sqlite3
+from typing import Optional, Dict, Any
+from datetime import datetime
+
+
+class TreeNodesMixin:
+    """Node CRUD and aggregation logic for the memory tree."""
+
+    def add_node(
+        self,
+        node_type: str,
+        name: str,
+        parent_id: int,
+        description: Optional[str] = None,
+        memory_id: Optional[int] = None
+    ) -> int:
+        """
+        Add a new node to the tree.
+
+        Args:
+            node_type: Type of node ('root', 'project', 'category', 'memory')
+            name: Display name
+            parent_id: Parent node ID
+            description: Optional description
+            memory_id: Link to memories table (for leaf nodes)
+
+        Returns:
+            New node ID
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Get parent path and depth
+        cursor.execute('SELECT tree_path, depth FROM memory_tree WHERE id = ?', (parent_id,))
+        result = cursor.fetchone()
+
+        if not result:
+            raise ValueError(f"Parent node {parent_id} not found")
+
+        parent_path, parent_depth = result
+
+        # Calculate new node position
+        depth = parent_depth + 1
+
+        cursor.execute('''
+            INSERT INTO memory_tree (
+                node_type, name, description,
+                parent_id, tree_path, depth,
+                memory_id, last_updated
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ''', (
+            node_type,
+            name,
+            description,
+            parent_id,
+            '',  # Placeholder, updated below
+            depth,
+            memory_id,
+            datetime.now().isoformat()
+        ))
+
+        node_id = cursor.lastrowid
+
+        # Update tree_path with actual node_id
+        tree_path = f"{parent_path}.{node_id}"
+        cursor.execute('UPDATE memory_tree SET tree_path = ? WHERE id = ?', (tree_path, node_id))
+
+        conn.commit()
+        conn.close()
+
+        return node_id
+
+    def delete_node(self, node_id: int) -> bool:
+        """
+        Delete a node and all its descendants.
+
+        Args:
+            node_id: Node ID to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        if node_id == self.root_id:
+            raise ValueError("Cannot delete root node")
+
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Get tree_path
+        cursor.execute('SELECT tree_path, parent_id FROM memory_tree WHERE id = ?', (node_id,))
+        result = cursor.fetchone()
+
+        if not result:
+            conn.close()
+            return False
+
+        tree_path, parent_id = result
+
+        # Delete node and all descendants (CASCADE handles children)
+        cursor.execute('DELETE FROM memory_tree WHERE id = ? OR tree_path LIKE ?',
+                      (node_id, f"{tree_path}.%"))
+
+        deleted = cursor.rowcount > 0
+        conn.commit()
+        conn.close()
+
+        # Update parent counts
+        if deleted and parent_id:
+            self.update_counts(parent_id)
+
+        return deleted
+
+    def update_counts(self, node_id: int):
+        """
+        Update aggregated counts for a node (memory_count, total_size).
+        Recursively updates all ancestors.
+
+        Args:
+            node_id: Node ID to update
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Get all descendant memory nodes
+        cursor.execute('SELECT tree_path FROM memory_tree WHERE id = ?', (node_id,))
+        result = cursor.fetchone()
+
+        if not result:
+            conn.close()
+            return
+
+        tree_path = result[0]
+
+        # Count memories in subtree
+        cursor.execute('''
+            SELECT COUNT(*), COALESCE(SUM(LENGTH(m.content)), 0)
+            FROM memory_tree t
+            LEFT JOIN memories m ON t.memory_id = m.id
+            WHERE t.tree_path LIKE ? AND t.memory_id IS NOT NULL
+        ''', (f"{tree_path}%",))
+
+        memory_count, total_size = cursor.fetchone()
+
+        # Update node
+        cursor.execute('''
+            UPDATE memory_tree
+            SET memory_count = ?, total_size = ?, last_updated = ?
+            WHERE id = ?
+        ''', (memory_count, total_size, datetime.now().isoformat(), node_id))
+
+        # Update all ancestors
+        path_ids = [int(x) for x in tree_path.split('.')]
+        for ancestor_id in path_ids[:-1]:  # Exclude current node
+            self.update_counts(ancestor_id)
+
+        conn.commit()
+        conn.close()
+
+    def _update_all_counts(self):
+        """Update counts for all nodes (used after build_tree)."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Get all nodes in reverse depth order (leaves first)
+        cursor.execute('''
+            SELECT id FROM memory_tree
+            ORDER BY depth DESC
+        ''')
+
+        node_ids = [row[0] for row in cursor.fetchall()]
+        conn.close()
+
+        # Update each node (will cascade to parents)
+        processed = set()
+        for node_id in node_ids:
+            if node_id not in processed:
+                self.update_counts(node_id)
+                processed.add(node_id)
+
+    def _generate_tree_path(self, parent_path: str, node_id: int) -> str:
+        """Generate tree_path for a new node."""
+        if parent_path:
+            return f"{parent_path}.{node_id}"
+        return str(node_id)
+
+    def _calculate_depth(self, tree_path: str) -> int:
+        """Calculate depth from tree_path (count dots)."""
+        return tree_path.count('.')