superlocalmemory 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -16,6 +16,41 @@ SuperLocalMemory V2 - Intelligent local memory system for AI coding assistants.
 
 ---
 
+## [2.4.2] - 2026-02-11
+
+**Release Type:** Bug Fix Release
+**Backward Compatible:** Yes
+
+### Fixed
+- **Profile isolation bug in UI dashboard**: Graph nodes and connections were displaying global counts instead of profile-filtered counts. New/empty profiles incorrectly showed data from other profiles. Fixed by adding `JOIN memories` and `WHERE m.profile = ?` filter to graph stats queries in `ui_server.py` (`/api/stats` endpoint, lines 986-990).
+
+---
+
+## [2.4.1] - 2026-02-11
+
+**Release Type:** Hierarchical Clustering & Documentation Release
+**Backward Compatible:** Yes (additive schema changes only)
+
+### Added
+- **Hierarchical Leiden clustering** (`graph_engine.py`): Recursive community detection — large clusters (≥10 members) are automatically sub-divided up to 3 levels deep. E.g., "Python" → "FastAPI" → "Authentication patterns". New `parent_cluster_id` and `depth` columns in `graph_clusters` table
+- **Community summaries** (`graph_engine.py`): TF-IDF structured reports for every cluster — key topics, projects, categories, hierarchy context. Stored in `graph_clusters.summary` column, surfaced in `/api/clusters` endpoint and web dashboard
+- **CLI commands**: `python3 graph_engine.py hierarchical` and `python3 graph_engine.py summaries` for manual runs
+- **Schema migration**: Safe `ALTER TABLE` additions for `summary`, `parent_cluster_id`, `depth` columns — backward compatible with existing databases
+
+### Changed
+- `build_graph()` now automatically runs hierarchical sub-clustering and summary generation after flat Leiden
+- `/api/clusters` endpoint returns `summary`, `parent_cluster_id`, `depth` fields
+- `get_stats()` includes `max_depth` and per-cluster summary/hierarchy data
+- `setup_validator.py` schema updated to include new columns
+
+### Documentation
+- **README.md**: v2.4.0→v2.4.1, added Hierarchical Leiden, Community Summaries, MACLA, Auto-Backup sections
+- **Wiki**: Updated Roadmap, Pattern-Learning-Explained, Knowledge-Graph-Guide, Configuration, Visualization-Dashboard, Footer
+- **Website**: Updated features.astro, comparison.astro, index.astro for v2.4.1 features
+- **`.npmignore`**: Recursive `__pycache__` exclusion patterns
+
+---
+
 ## [2.4.0] - 2026-02-11
 
 **Release Type:** Profile System & Intelligence Release

package/README.md

@@ -130,7 +130,7 @@ npm update -g superlocalmemory
 npm install -g superlocalmemory@latest
 
 # Install specific version
-npm install -g superlocalmemory@2.3.7
+npm install -g superlocalmemory@latest
 ```
 
 **Manual install users:**
@@ -189,6 +189,19 @@ python ~/.claude-memory/ui_server.py
 
 ---
 
+### New in v2.4.1: Hierarchical Clustering, Community Summaries & Auto-Backup
+
+| Feature | Description |
+|---------|-------------|
+| **Hierarchical Leiden** | Recursive community detection — clusters within clusters up to 3 levels. "Python" → "FastAPI" → "Auth patterns" |
+| **Community Summaries** | TF-IDF structured reports per cluster: key topics, projects, categories at a glance |
+| **MACLA Confidence** | Bayesian Beta-Binomial scoring (arXiv:2512.18950) — calibrated confidence, not raw frequency |
+| **Auto-Backup** | Configurable SQLite backups with retention policies, one-click restore from dashboard |
+| **Profile UI** | Create, switch, delete profiles from the web dashboard — full isolation per context |
+| **Profile Isolation** | All API endpoints (graph, clusters, patterns, timeline) scoped to active profile |
+
+---
+
 ## 🔍 Advanced Search
 
 SuperLocalMemory V2.2.0 implements **hybrid search** combining multiple strategies for maximum accuracy.
@@ -433,13 +446,13 @@ Not another simple key-value store. SuperLocalMemory implements **cutting-edge m
 │  6 universal slash-commands for AI assistants               │
 │  Compatible with Claude Code, Continue, Cody                │
 ├─────────────────────────────────────────────────────────────┤
-│  Layer 4: PATTERN LEARNING                                  │
-│  Learns: coding style, preferences, terminology             │
+│  Layer 4: PATTERN LEARNING + MACLA (v2.4.0)                  │
+│  Bayesian Beta-Binomial confidence (arXiv:2512.18950)       │
 │  "You prefer React over Vue" (73% confidence)               │
 ├─────────────────────────────────────────────────────────────┤
-│  Layer 3: KNOWLEDGE GRAPH                                   │
-│  Auto-clusters: "Auth & Tokens", "Performance", "Testing"   │
-│  Discovers relationships you didn't know existed            │
+│  Layer 3: KNOWLEDGE GRAPH + HIERARCHICAL LEIDEN (v2.4.1)    │
+│  Recursive clustering: "Python" → "FastAPI" → "Auth"        │
+│  Community summaries + TF-IDF structured reports            │
 ├─────────────────────────────────────────────────────────────┤
 │  Layer 2: HIERARCHICAL INDEX                                │
 │  Tree structure for fast navigation                         │
@@ -488,6 +501,8 @@ python ~/.claude-memory/pattern_learner.py context 0.5
 
 **Your AI assistant can now match your preferences automatically.**
 
+**MACLA Confidence Scoring (v2.4.0):** Confidence uses a Bayesian Beta-Binomial posterior (Forouzandeh et al., [arXiv:2512.18950](https://arxiv.org/abs/2512.18950)). Pattern-specific priors, log-scaled competition, recency bonus. Range: 0.0–0.95 (hard cap prevents overconfidence).
+
 ### Multi-Profile Support
 
 ```bash
@@ -537,14 +552,21 @@ superlocalmemoryv2:profile create <name>                 # New profile
 superlocalmemoryv2:profile switch <name>                 # Switch context
 
 # Knowledge Graph
-python ~/.claude-memory/graph_engine.py build            # Build graph
+python ~/.claude-memory/graph_engine.py build            # Build graph (+ hierarchical + summaries)
 python ~/.claude-memory/graph_engine.py stats            # View clusters
 python ~/.claude-memory/graph_engine.py related --id 5   # Find related
+python ~/.claude-memory/graph_engine.py hierarchical     # Sub-cluster large communities
+python ~/.claude-memory/graph_engine.py summaries        # Generate cluster summaries
 
 # Pattern Learning
 python ~/.claude-memory/pattern_learner.py update        # Learn patterns
 python ~/.claude-memory/pattern_learner.py context 0.5   # Get identity
 
+# Auto-Backup (v2.4.0)
+python ~/.claude-memory/auto_backup.py backup            # Manual backup
+python ~/.claude-memory/auto_backup.py list              # List backups
+python ~/.claude-memory/auto_backup.py status            # Backup status
+
 # Reset (Use with caution!)
 superlocalmemoryv2:reset soft                            # Clear memories
 superlocalmemoryv2:reset hard --confirm                  # Nuclear option

package/bin/slm

@@ -187,13 +187,13 @@ DOCUMENTATION:
   README: https://github.com/varun369/SuperLocalMemoryV2
   Docs: ~/.claude-memory/docs/
 
-VERSION: 2.3.0-universal
+VERSION: 2.4.1
 EOF
         ;;
 
     version|--version|-v)
         echo "SuperLocalMemory V2 - Universal CLI"
-        echo "Version: 2.3.0-universal"
+        echo "Version: 2.4.1"
         echo "Database: $SLM_DIR/memory.db"
         ;;
 

package/docs/ARCHITECTURE.md

@@ -46,7 +46,7 @@ Simple Storage → Intelligent Organization → Adaptive Learning
 
 ## Universal Integration
 
-**Version 2.3.0-universal** transforms SuperLocalMemory from Claude-Code-only to a universal memory system that works across 16+ IDEs and CLI tools with zero configuration.
+**Version 2.4.1** transforms SuperLocalMemory from Claude-Code-only to a universal memory system that works across 16+ IDEs and CLI tools with zero configuration.
 
 ### Three-Tier Access Architecture
 
@@ -204,7 +204,7 @@ slm graph build           # Knowledge graph
 
 ## 7-Layer Architecture
 
-SuperLocalMemory V2 uses a hierarchical, additive architecture where each layer builds on the previous without replacing it. Version 2.3.0-universal extended the original 4 core layers with 3 universal access layers.
+SuperLocalMemory V2 uses a hierarchical, additive architecture where each layer builds on the previous without replacing it. Version 2.3.0 introduced universal access across 16+ IDEs, and subsequent releases (through 2.4.1) added profiles, hierarchical clustering, and community summaries.
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐

package/docs/CLI-COMMANDS-REFERENCE.md

@@ -2,7 +2,7 @@
 
 **Quick reference for all CLI commands**
 
-**Version 2.3.0-universal** - Universal integration across 16+ IDEs and CLI tools
+**Version 2.4.1** - Universal integration across 16+ IDEs and CLI tools
 
 SuperLocalMemory V2 offers three access methods:
 1. **Universal CLI** - Simple `slm` commands (NEW in v2.1.0)

package/docs/MCP-MANUAL-SETUP.md

@@ -683,7 +683,7 @@ python3 ~/.claude-memory/mcp_server.py
 ```
 ============================================================
 SuperLocalMemory V2 - MCP Server
-Version: 2.3.0-universal
+Version: 2.4.1
 ============================================================
 
 Transport: stdio

package/docs/MCP-TROUBLESHOOTING.md

@@ -15,7 +15,7 @@ python3 ~/.claude-memory/mcp_server.py
 ```
 ============================================================
 SuperLocalMemory V2 - MCP Server
-Version: 2.3.0-universal
+Version: 2.4.1
 ============================================================
 
 Transport: stdio

package/docs/UNIVERSAL-INTEGRATION.md

@@ -1,8 +1,8 @@
 # Universal Integration Guide
 
-**Version:** 2.3.0-universal
+**Version:** 2.4.1
 **Status:** Production Ready
-**Updated:** February 7, 2026
+**Updated:** February 11, 2026
 
 ---
 
@@ -483,6 +483,6 @@ python3 ~/.claude-memory/mcp_server.py --transport http --port 8001
 
 **Questions?** Open an issue: https://github.com/varun369/SuperLocalMemoryV2/issues
 
-**Version:** 2.3.0-universal
+**Version:** 2.4.1
 **Author:** Varun Pratap Bhardwaj
 **License:** MIT

package/mcp_server.py

@@ -711,7 +711,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.3.0-universal", file=sys.stderr)
+    print("Version: 2.4.1", 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.0",
+  "version": "2.4.2",
   "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",
@@ -43,6 +43,7 @@
     "superlocalmemory": "./bin/slm-npm"
   },
   "scripts": {
+    "prepack": "find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null; find . -name '*.pyc' -delete 2>/dev/null; true",
     "postinstall": "node scripts/postinstall.js",
     "preuninstall": "node scripts/preuninstall.js",
     "test": "echo \"Run: npm install -g . && slm status\" && exit 0"

package/src/graph_engine.py

@@ -404,6 +404,293 @@ class ClusterBuilder:
         return name[:100]  # Limit length
 
 
+    def hierarchical_cluster(self, min_subcluster_size: int = 5, max_depth: int = 3) -> Dict[str, any]:
+        """
+        Run recursive Leiden clustering — cluster the clusters.
+
+        Large communities (>= min_subcluster_size * 2) are recursively sub-clustered
+        to reveal finer-grained thematic structure. E.g., "Python" → "FastAPI" → "Auth".
+
+        Args:
+            min_subcluster_size: Minimum members to attempt sub-clustering (default 5)
+            max_depth: Maximum recursion depth (default 3)
+
+        Returns:
+            Dictionary with hierarchical clustering statistics
+        """
+        try:
+            import igraph as ig
+            import leidenalg
+        except ImportError:
+            raise ImportError("python-igraph and leidenalg required. Install: pip install python-igraph leidenalg")
+
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        active_profile = self._get_active_profile()
+
+        try:
+            # Get top-level clusters for this profile that are large enough to sub-cluster
+            cursor.execute('''
+                SELECT cluster_id, COUNT(*) as cnt
+                FROM memories
+                WHERE cluster_id IS NOT NULL AND profile = ?
+                GROUP BY cluster_id
+                HAVING cnt >= ?
+            ''', (active_profile, min_subcluster_size * 2))
+            large_clusters = cursor.fetchall()
+
+            if not large_clusters:
+                logger.info("No clusters large enough for hierarchical decomposition")
+                return {'subclusters_created': 0, 'depth_reached': 0}
+
+            total_subclusters = 0
+            max_depth_reached = 0
+
+            for parent_cid, member_count in large_clusters:
+                subs, depth = self._recursive_subcluster(
+                    conn, cursor, parent_cid, active_profile,
+                    min_subcluster_size, max_depth, current_depth=1
+                )
+                total_subclusters += subs
+                max_depth_reached = max(max_depth_reached, depth)
+
+            conn.commit()
+            logger.info(f"Hierarchical clustering: {total_subclusters} sub-clusters, depth {max_depth_reached}")
+            return {
+                'subclusters_created': total_subclusters,
+                'depth_reached': max_depth_reached,
+                'parent_clusters_processed': len(large_clusters)
+            }
+
+        except Exception as e:
+            logger.error(f"Hierarchical clustering failed: {e}")
+            conn.rollback()
+            return {'subclusters_created': 0, 'error': str(e)}
+        finally:
+            conn.close()
+
+    def _recursive_subcluster(self, conn, cursor, parent_cluster_id: int,
+                               profile: str, min_size: int, max_depth: int,
+                               current_depth: int) -> Tuple[int, int]:
+        """Recursively sub-cluster a community using Leiden."""
+        import igraph as ig
+        import leidenalg
+
+        if current_depth > max_depth:
+            return 0, current_depth - 1
+
+        # Get memory IDs in this cluster
+        cursor.execute('''
+            SELECT id FROM memories
+            WHERE cluster_id = ? AND profile = ?
+        ''', (parent_cluster_id, profile))
+        member_ids = [row[0] for row in cursor.fetchall()]
+
+        if len(member_ids) < min_size * 2:
+            return 0, current_depth - 1
+
+        # Get edges between members of this cluster
+        placeholders = ','.join('?' * len(member_ids))
+        edges = cursor.execute(f'''
+            SELECT source_memory_id, target_memory_id, weight
+            FROM graph_edges
+            WHERE source_memory_id IN ({placeholders})
+              AND target_memory_id IN ({placeholders})
+        ''', member_ids + member_ids).fetchall()
+
+        if len(edges) < 2:
+            return 0, current_depth - 1
+
+        # Build sub-graph
+        id_to_vertex = {mid: idx for idx, mid in enumerate(member_ids)}
+        vertex_to_id = {idx: mid for mid, idx in id_to_vertex.items()}
+
+        g = ig.Graph()
+        g.add_vertices(len(member_ids))
+        edge_list, edge_weights = [], []
+        for src, tgt, w in edges:
+            if src in id_to_vertex and tgt in id_to_vertex:
+                edge_list.append((id_to_vertex[src], id_to_vertex[tgt]))
+                edge_weights.append(w)
+
+        if not edge_list:
+            return 0, current_depth - 1
+
+        g.add_edges(edge_list)
+
+        # Run Leiden with higher resolution for finer communities
+        partition = leidenalg.find_partition(
+            g, leidenalg.ModularityVertexPartition,
+            weights=edge_weights, n_iterations=100, seed=42
+        )
+
+        # Only proceed if Leiden found > 1 community (actual split)
+        non_singleton = [c for c in partition if len(c) >= 2]
+        if len(non_singleton) <= 1:
+            return 0, current_depth - 1
+
+        subclusters_created = 0
+        deepest = current_depth
+
+        # Get parent depth
+        cursor.execute('SELECT depth FROM graph_clusters WHERE id = ?', (parent_cluster_id,))
+        parent_row = cursor.fetchone()
+        parent_depth = parent_row[0] if parent_row else 0
+
+        for community in non_singleton:
+            sub_member_ids = [vertex_to_id[v] for v in community]
+
+            if len(sub_member_ids) < 2:
+                continue
+
+            avg_imp = self._get_avg_importance(cursor, sub_member_ids)
+            cluster_name = self._generate_cluster_name(cursor, sub_member_ids)
+
+            result = cursor.execute('''
+                INSERT INTO graph_clusters (name, member_count, avg_importance, parent_cluster_id, depth)
+                VALUES (?, ?, ?, ?, ?)
+            ''', (cluster_name, len(sub_member_ids), avg_imp, parent_cluster_id, parent_depth + 1))
+
+            sub_cluster_id = result.lastrowid
+
+            # Update memories to point to sub-cluster
+            cursor.executemany('''
+                UPDATE memories SET cluster_id = ? WHERE id = ?
+            ''', [(sub_cluster_id, mid) for mid in sub_member_ids])
+
+            subclusters_created += 1
+            logger.info(f"Sub-cluster {sub_cluster_id} under {parent_cluster_id}: "
+                        f"'{cluster_name}' ({len(sub_member_ids)} members, depth {parent_depth + 1})")
+
+            # Recurse into this sub-cluster if large enough
+            child_subs, child_depth = self._recursive_subcluster(
+                conn, cursor, sub_cluster_id, profile,
+                min_size, max_depth, current_depth + 1
+            )
+            subclusters_created += child_subs
+            deepest = max(deepest, child_depth)
+
+        return subclusters_created, deepest
+
+    def generate_cluster_summaries(self) -> int:
+        """
+        Generate TF-IDF structured summaries for all clusters.
+
+        For each cluster, analyzes member content to produce a human-readable
+        summary describing the cluster's theme, key topics, and scope.
+
+        Returns:
+            Number of clusters with summaries generated
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        active_profile = self._get_active_profile()
+
+        try:
+            # Get all clusters for this profile
+            cursor.execute('''
+                SELECT DISTINCT gc.id, gc.name, gc.member_count
+                FROM graph_clusters gc
+                JOIN memories m ON m.cluster_id = gc.id
+                WHERE m.profile = ?
+            ''', (active_profile,))
+            clusters = cursor.fetchall()
+
+            if not clusters:
+                return 0
+
+            summaries_generated = 0
+
+            for cluster_id, cluster_name, member_count in clusters:
+                summary = self._build_cluster_summary(cursor, cluster_id, active_profile)
+                if summary:
+                    cursor.execute('''
+                        UPDATE graph_clusters SET summary = ?, updated_at = CURRENT_TIMESTAMP
+                        WHERE id = ?
+                    ''', (summary, cluster_id))
+                    summaries_generated += 1
+                    logger.info(f"Summary for cluster {cluster_id} ({cluster_name}): {summary[:80]}...")
+
+            conn.commit()
+            logger.info(f"Generated {summaries_generated} cluster summaries")
+            return summaries_generated
+
+        except Exception as e:
+            logger.error(f"Summary generation failed: {e}")
+            conn.rollback()
+            return 0
+        finally:
+            conn.close()
+
+    def _build_cluster_summary(self, cursor, cluster_id: int, profile: str) -> str:
+        """Build a TF-IDF structured summary for a single cluster."""
+        # Get member content
+        cursor.execute('''
+            SELECT m.content, m.summary, m.tags, m.category, m.project_name
+            FROM memories m
+            WHERE m.cluster_id = ? AND m.profile = ?
+        ''', (cluster_id, profile))
+        members = cursor.fetchall()
+
+        if not members:
+            return ""
+
+        # Collect entities from graph nodes
+        cursor.execute('''
+            SELECT gn.entities
+            FROM graph_nodes gn
+            JOIN memories m ON gn.memory_id = m.id
+            WHERE m.cluster_id = ? AND m.profile = ?
+        ''', (cluster_id, profile))
+        all_entities = []
+        for row in cursor.fetchall():
+            if row[0]:
+                try:
+                    all_entities.extend(json.loads(row[0]))
+                except (json.JSONDecodeError, TypeError):
+                    pass
+
+        # Top entities by frequency (TF-IDF already extracted these)
+        entity_counts = Counter(all_entities)
+        top_entities = [e for e, _ in entity_counts.most_common(5)]
+
+        # Collect unique projects and categories
+        projects = set()
+        categories = set()
+        for m in members:
+            if m[3]:  # category
+                categories.add(m[3])
+            if m[4]:  # project_name
+                projects.add(m[4])
+
+        # Build structured summary
+        parts = []
+
+        # Theme from top entities
+        if top_entities:
+            parts.append(f"Key topics: {', '.join(top_entities[:5])}")
+
+        # Scope
+        if projects:
+            parts.append(f"Projects: {', '.join(sorted(projects)[:3])}")
+        if categories:
+            parts.append(f"Categories: {', '.join(sorted(categories)[:3])}")
+
+        # Size context
+        parts.append(f"{len(members)} memories")
+
+        # Check for hierarchical context
+        cursor.execute('SELECT parent_cluster_id FROM graph_clusters WHERE id = ?', (cluster_id,))
+        parent_row = cursor.fetchone()
+        if parent_row and parent_row[0]:
+            cursor.execute('SELECT name FROM graph_clusters WHERE id = ?', (parent_row[0],))
+            parent_name_row = cursor.fetchone()
+            if parent_name_row:
+                parts.append(f"Sub-cluster of: {parent_name_row[0]}")
+
+        return " | ".join(parts)
+
+
 class ClusterNamer:
     """Enhanced cluster naming with optional LLM support (future)."""
 
@@ -498,13 +785,24 @@ class GraphEngine:
                 id INTEGER PRIMARY KEY AUTOINCREMENT,
                 name TEXT NOT NULL,
                 description TEXT,
+                summary TEXT,
                 member_count INTEGER DEFAULT 0,
                 avg_importance REAL,
+                parent_cluster_id INTEGER,
+                depth INTEGER DEFAULT 0,
                 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY (parent_cluster_id) REFERENCES graph_clusters(id) ON DELETE SET NULL
             )
         ''')
 
+        # Safe column additions for existing databases
+        for col, col_type in [('summary', 'TEXT'), ('parent_cluster_id', 'INTEGER'), ('depth', 'INTEGER DEFAULT 0')]:
+            try:
+                cursor.execute(f'ALTER TABLE graph_clusters ADD COLUMN {col} {col_type}')
+            except sqlite3.OperationalError:
+                pass
+
         # Add cluster_id to memories if not exists
         try:
             cursor.execute('ALTER TABLE memories ADD COLUMN cluster_id INTEGER')
@@ -648,9 +946,16 @@ class GraphEngine:
                 memory_ids, vectors, entities_list
             )
 
-            # Detect communities
+            # Detect communities (flat Leiden)
             clusters_count = self.cluster_builder.detect_communities()
 
+            # Hierarchical sub-clustering on large communities
+            hierarchical_stats = self.cluster_builder.hierarchical_cluster()
+            subclusters = hierarchical_stats.get('subclusters_created', 0)
+
+            # Generate TF-IDF structured summaries for all clusters
+            summaries = self.cluster_builder.generate_cluster_summaries()
+
             elapsed = time.time() - start_time
 
             stats = {
@@ -659,6 +964,9 @@ class GraphEngine:
                 'nodes': len(memory_ids),
                 'edges': edges_count,
                 'clusters': clusters_count,
+                'subclusters': subclusters,
+                'max_depth': hierarchical_stats.get('depth_reached', 0),
+                'summaries_generated': summaries,
                 'time_seconds': round(elapsed, 2)
             }
 
@@ -962,28 +1270,36 @@ class GraphEngine:
                 WHERE cluster_id IS NOT NULL AND profile = ?
             ''', (active_profile,)).fetchone()[0]
 
-            # Cluster breakdown for active profile
+            # Cluster breakdown for active profile (including hierarchy)
             cluster_info = cursor.execute('''
-                SELECT gc.name, gc.member_count, gc.avg_importance
+                SELECT gc.name, gc.member_count, gc.avg_importance,
+                       gc.summary, gc.parent_cluster_id, gc.depth
                 FROM graph_clusters gc
                 WHERE gc.id IN (
                     SELECT DISTINCT cluster_id FROM memories
                     WHERE cluster_id IS NOT NULL AND profile = ?
                 )
-                ORDER BY gc.member_count DESC
-                LIMIT 10
+                ORDER BY gc.depth ASC, gc.member_count DESC
+                LIMIT 20
             ''', (active_profile,)).fetchall()
 
+            # Count hierarchical depth
+            max_depth = max((c[5] or 0 for c in cluster_info), default=0) if cluster_info else 0
+
             return {
                 'profile': active_profile,
                 'nodes': nodes,
                 'edges': edges,
                 'clusters': clusters,
+                'max_depth': max_depth,
                 'top_clusters': [
                     {
                         'name': c[0],
                         'members': c[1],
-                        'avg_importance': round(c[2], 1)
+                        'avg_importance': round(c[2], 1) if c[2] else 5.0,
+                        'summary': c[3],
+                        'parent_cluster_id': c[4],
+                        'depth': c[5] or 0
                     }
                     for c in cluster_info
                 ]
@@ -998,7 +1314,7 @@ def main():
     import argparse
 
     parser = argparse.ArgumentParser(description='GraphEngine - Knowledge Graph Management')
-    parser.add_argument('command', choices=['build', 'stats', 'related', 'cluster'],
+    parser.add_argument('command', choices=['build', 'stats', 'related', 'cluster', 'hierarchical', 'summaries'],
                        help='Command to execute')
     parser.add_argument('--memory-id', type=int, help='Memory ID for related/add commands')
     parser.add_argument('--cluster-id', type=int, help='Cluster ID for cluster command')
@@ -1052,6 +1368,18 @@ def main():
             summary = mem['summary'] or '[No summary]'
             print(f"   {summary[:100]}...")
 
+    elif args.command == 'hierarchical':
+        print("Running hierarchical sub-clustering...")
+        cluster_builder = ClusterBuilder(engine.db_path)
+        stats = cluster_builder.hierarchical_cluster()
+        print(json.dumps(stats, indent=2))
+
+    elif args.command == 'summaries':
+        print("Generating cluster summaries...")
+        cluster_builder = ClusterBuilder(engine.db_path)
+        count = cluster_builder.generate_cluster_summaries()
+        print(f"Generated summaries for {count} clusters")
+
 
 if __name__ == '__main__':
     main()

package/src/memory_store_v2.py

@@ -242,7 +242,7 @@ class MemoryStoreV2:
             'project_url': 'https://github.com/varun369/SuperLocalMemoryV2',
             'license': 'MIT',
             'attribution_required': 'yes',
-            'version': '2.3.0-universal',
+            'version': '2.4.1',
             'architecture_date': '2026-01-15',
             'release_date': '2026-02-07',
             'signature': 'VBPB-SLM-V2-2026-ARCHITECT',

package/src/setup_validator.py

@@ -257,11 +257,18 @@ def initialize_database() -> Tuple[bool, str]:
             CREATE TABLE IF NOT EXISTS graph_clusters (
                 id INTEGER PRIMARY KEY AUTOINCREMENT,
                 cluster_name TEXT,
+                name TEXT,
                 description TEXT,
+                summary TEXT,
                 memory_count INTEGER DEFAULT 0,
+                member_count INTEGER DEFAULT 0,
                 avg_importance REAL DEFAULT 5.0,
                 top_entities TEXT DEFAULT '[]',
-                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+                parent_cluster_id INTEGER,
+                depth INTEGER DEFAULT 0,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY (parent_cluster_id) REFERENCES graph_clusters(id) ON DELETE SET NULL
             )
         ''')
 

package/ui_server.py

@@ -707,22 +707,26 @@ async def get_clusters():
 
         active_profile = get_active_profile()
 
-        # Get cluster statistics
+        # Get cluster statistics with hierarchy and summaries
         cursor.execute("""
             SELECT
-                cluster_id,
+                m.cluster_id,
                 COUNT(*) as member_count,
-                AVG(importance) as avg_importance,
-                MIN(importance) as min_importance,
-                MAX(importance) as max_importance,
-                GROUP_CONCAT(DISTINCT category) as categories,
-                GROUP_CONCAT(DISTINCT project_name) as projects,
-                MIN(created_at) as first_memory,
-                MAX(created_at) as latest_memory
-            FROM memories
-            WHERE cluster_id IS NOT NULL AND profile = ?
-            GROUP BY cluster_id
-            ORDER BY member_count DESC
+                AVG(m.importance) as avg_importance,
+                MIN(m.importance) as min_importance,
+                MAX(m.importance) as max_importance,
+                GROUP_CONCAT(DISTINCT m.category) as categories,
+                GROUP_CONCAT(DISTINCT m.project_name) as projects,
+                MIN(m.created_at) as first_memory,
+                MAX(m.created_at) as latest_memory,
+                gc.summary,
+                gc.parent_cluster_id,
+                gc.depth
+            FROM memories m
+            LEFT JOIN graph_clusters gc ON m.cluster_id = gc.id
+            WHERE m.cluster_id IS NOT NULL AND m.profile = ?
+            GROUP BY m.cluster_id
+            ORDER BY COALESCE(gc.depth, 0) ASC, member_count DESC
         """, (active_profile,))
         clusters = cursor.fetchall()
 
@@ -979,10 +983,18 @@ async def get_stats():
         cursor.execute("SELECT COUNT(DISTINCT cluster_id) as total FROM memories WHERE cluster_id IS NOT NULL AND profile = ?", (active_profile,))
         total_clusters = cursor.fetchone()['total']
 
-        cursor.execute("SELECT COUNT(*) as total FROM graph_nodes")
+        cursor.execute("""
+            SELECT COUNT(*) as total FROM graph_nodes gn
+            JOIN memories m ON gn.memory_id = m.id
+            WHERE m.profile = ?
+        """, (active_profile,))
         total_graph_nodes = cursor.fetchone()['total']
 
-        cursor.execute("SELECT COUNT(*) as total FROM graph_edges")
+        cursor.execute("""
+            SELECT COUNT(*) as total FROM graph_edges ge
+            JOIN memories m ON ge.source_memory_id = m.id
+            WHERE m.profile = ?
+        """, (active_profile,))
         total_graph_edges = cursor.fetchone()['total']
 
         # Category breakdown
@@ -1752,7 +1764,7 @@ if __name__ == "__main__":
         print(f"\n  Port {args.port} in use — using {ui_port} instead\n")
 
     print("=" * 70)
-    print("  SuperLocalMemory V2.3.0 - FastAPI UI Server")
+    print("  SuperLocalMemory V2.4.1 - FastAPI UI Server")
     print("  Copyright (c) 2026 Varun Pratap Bhardwaj")
     print("=" * 70)
     print(f"  Database: {DB_PATH}")