superlocalmemory 3.0.16 → 3.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.0.16",
+  "version": "3.0.17",
   "description": "Information-geometric agent memory with mathematical guarantees. 4-channel retrieval, Fisher-Rao similarity, zero-LLM mode, EU AI Act compliant. Works with Claude, Cursor, Windsurf, and 17+ AI tools.",
   "keywords": [
     "ai-memory",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.0.16"
+version = "3.0.17"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "MIT"}

package/src/superlocalmemory/cli/commands.py

@@ -23,6 +23,7 @@ def dispatch(args: Namespace) -> None:
         "provider": cmd_provider,
         "connect": cmd_connect,
         "migrate": cmd_migrate,
+        "list": cmd_list,
         "remember": cmd_remember,
         "recall": cmd_recall,
         "forget": cmd_forget,
@@ -113,6 +114,34 @@ def cmd_migrate(args: Namespace) -> None:
     _migrate(args)
 
 
+def cmd_list(args: Namespace) -> None:
+    """List recent memories chronologically."""
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.core.engine import MemoryEngine
+
+    config = SLMConfig.load()
+    engine = MemoryEngine(config)
+    engine.initialize()
+
+    limit = getattr(args, "limit", 20)
+    facts = engine._db.get_all_facts(engine.profile_id)
+    # Sort by created_at descending, take limit
+    facts.sort(key=lambda f: f.created_at or "", reverse=True)
+    facts = facts[:limit]
+
+    if not facts:
+        print("No memories stored yet.")
+        return
+
+    print(f"Recent memories ({len(facts)}):\n")
+    for i, f in enumerate(facts, 1):
+        date = (f.created_at or "")[:19]
+        ftype_raw = getattr(f, "fact_type", "")
+        ftype = ftype_raw.value if hasattr(ftype_raw, "value") else str(ftype_raw)
+        content = f.content[:100] + ("..." if len(f.content) > 100 else "")
+        print(f"  {i:3d}. [{date}] ({ftype}) {content}")
+
+
 def cmd_remember(args: Namespace) -> None:
     """Store a memory via the engine."""
     from superlocalmemory.core.config import SLMConfig

package/src/superlocalmemory/cli/main.py

@@ -14,73 +14,127 @@ from __future__ import annotations
 import argparse
 import sys
 
+_HELP_EPILOG = """\
+operating modes:
+  Mode A  Local Guardian — Zero cloud, zero LLM. All processing stays on
+          your machine. Full EU AI Act compliance. Best for privacy-first
+          use, air-gapped systems, and regulated environments.
+          Retrieval score: 74.8% on LoCoMo benchmark.
+
+  Mode B  Smart Local — Uses a local Ollama LLM for summarization and
+          enrichment. Data never leaves your network. EU AI Act compliant.
+          Requires: ollama running locally with a model pulled.
+
+  Mode C  Full Power — Uses a cloud LLM (OpenAI, Anthropic, etc.) for
+          maximum accuracy. Best retrieval quality, agentic multi-hop.
+          Retrieval score: 87.7% on LoCoMo benchmark.
+
+quick start:
+  slm setup                   Interactive first-time setup
+  slm remember "some fact"    Store a memory
+  slm recall "search query"   Semantic search across memories
+  slm list -n 20              Show 20 most recent memories
+  slm dashboard               Open web dashboard at localhost:8765
+
+ide integration:
+  slm mcp                     Start MCP server (used by IDEs)
+  slm connect                 Auto-configure all detected IDEs
+  slm connect cursor           Configure a specific IDE
+
+examples:
+  slm remember "Project X uses PostgreSQL 16" --tags "project-x,db"
+  slm recall "which database does project X use"
+  slm list -n 50
+  slm mode a                  Switch to zero-LLM mode
+  slm trace "auth flow"       Recall with per-channel score breakdown
+  slm health                  Check math layer status
+  slm dashboard --port 9000   Dashboard on custom port
+
+documentation:
+  Website:    https://superlocalmemory.com
+  GitHub:     https://github.com/qualixar/superlocalmemory
+  Paper:      https://arxiv.org/abs/2603.14588
+"""
+
 
 def main() -> None:
     """Parse CLI arguments and dispatch to command handlers."""
-    parser = argparse.ArgumentParser(prog="slm", description="SuperLocalMemory V3")
-    sub = parser.add_subparsers(dest="command")
+    try:
+        from importlib.metadata import version as _pkg_version
+        _ver = _pkg_version("superlocalmemory")
+    except Exception:
+        _ver = "unknown"
+
+    parser = argparse.ArgumentParser(
+        prog="slm",
+        description=f"SuperLocalMemory V3 ({_ver}) — AI agent memory with mathematical foundations",
+        epilog=_HELP_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"superlocalmemory {_ver}",
+    )
+    sub = parser.add_subparsers(dest="command", title="commands")
 
-    # Setup
-    sub.add_parser("setup", help="Run setup wizard")
+    # -- Setup & Config ------------------------------------------------
+    sub.add_parser("setup", help="Interactive first-time setup wizard")
 
-    # Mode
-    mode_p = sub.add_parser("mode", help="Get or set operating mode")
+    mode_p = sub.add_parser("mode", help="Get or set operating mode (a/b/c)")
     mode_p.add_argument(
         "value", nargs="?", choices=["a", "b", "c"], help="Mode to set",
     )
 
-    # Provider
-    provider_p = sub.add_parser("provider", help="Get or set LLM provider")
+    provider_p = sub.add_parser("provider", help="Get or set LLM provider for Mode B/C")
     provider_p.add_argument(
         "action", nargs="?", choices=["set"], help="Action",
     )
 
-    # Connect
-    connect_p = sub.add_parser("connect", help="Configure IDE integrations")
+    connect_p = sub.add_parser("connect", help="Auto-configure IDE integrations (17+ IDEs)")
     connect_p.add_argument("ide", nargs="?", help="Specific IDE to configure")
     connect_p.add_argument(
         "--list", action="store_true", help="List all supported IDEs",
     )
 
-    # Migrate
-    migrate_p = sub.add_parser("migrate", help="Migrate from V2")
+    migrate_p = sub.add_parser("migrate", help="Migrate data from V2 to V3 schema")
     migrate_p.add_argument(
         "--rollback", action="store_true", help="Rollback migration",
     )
 
-    # Memory ops
-    remember_p = sub.add_parser("remember", help="Store a memory")
+    # -- Memory Operations ---------------------------------------------
+    remember_p = sub.add_parser("remember", help="Store a memory (extracts facts, builds graph)")
     remember_p.add_argument("content", help="Content to remember")
     remember_p.add_argument("--tags", default="", help="Comma-separated tags")
 
-    recall_p = sub.add_parser("recall", help="Search memories")
+    recall_p = sub.add_parser("recall", help="Semantic search with 4-channel retrieval")
     recall_p.add_argument("query", help="Search query")
-    recall_p.add_argument("--limit", type=int, default=10, help="Max results")
+    recall_p.add_argument("--limit", type=int, default=10, help="Max results (default 10)")
 
-    forget_p = sub.add_parser("forget", help="Delete memories matching query")
-    forget_p.add_argument("query", help="Query to match")
+    forget_p = sub.add_parser("forget", help="Delete memories matching a query")
+    forget_p.add_argument("query", help="Query to match for deletion")
 
-    # Status & diagnostics
-    sub.add_parser("status", help="System status")
-    sub.add_parser("health", help="Math layer health")
+    list_p = sub.add_parser("list", help="List recent memories chronologically")
+    list_p.add_argument(
+        "--limit", "-n", type=int, default=20, help="Number of entries (default 20)",
+    )
+
+    # -- Diagnostics ---------------------------------------------------
+    sub.add_parser("status", help="System status (mode, profile, DB size)")
+    sub.add_parser("health", help="Math layer health (Fisher-Rao, Sheaf, Langevin)")
 
-    trace_p = sub.add_parser("trace", help="Recall with channel breakdown")
+    trace_p = sub.add_parser("trace", help="Recall with per-channel score breakdown")
     trace_p.add_argument("query", help="Search query")
 
-    # MCP server (for IDE integration)
+    # -- Services ------------------------------------------------------
     sub.add_parser("mcp", help="Start MCP server (stdio transport for IDE integration)")
+    sub.add_parser("warmup", help="Pre-download embedding model (~500MB, one-time)")
 
-    # Warmup (pre-download model)
-    sub.add_parser("warmup", help="Pre-download embedding model (~500MB)")
-
-    # Dashboard
-    dashboard_p = sub.add_parser("dashboard", help="Open web dashboard")
+    dashboard_p = sub.add_parser("dashboard", help="Open 17-tab web dashboard")
     dashboard_p.add_argument(
         "--port", type=int, default=8765, help="Port (default 8765)",
     )
 
-    # Profiles
-    profile_p = sub.add_parser("profile", help="Profile management")
+    # -- Profiles ------------------------------------------------------
+    profile_p = sub.add_parser("profile", help="Profile management (list/switch/create)")
     profile_p.add_argument(
         "action", choices=["list", "switch", "create"], help="Action",
     )

package/src/superlocalmemory/mcp/tools_v3.py

@@ -20,6 +20,27 @@ logger = logging.getLogger(__name__)
 def register_v3_tools(server, get_engine: Callable) -> None:
     """Register 5 V3-exclusive tools on *server*."""
 
+    # ------------------------------------------------------------------
+    # 0. get_version (so IDEs can check compatibility)
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def get_version() -> dict:
+        """Get SuperLocalMemory version, Python version, and platform info."""
+        try:
+            from importlib.metadata import version as _pkg_version
+            slm_ver = _pkg_version("superlocalmemory")
+        except Exception:
+            slm_ver = "unknown"
+        import platform
+        import sys as _sys
+        return {
+            "success": True,
+            "version": slm_ver,
+            "python": _sys.version.split()[0],
+            "platform": platform.system(),
+            "arch": platform.machine(),
+        }
+
     # ------------------------------------------------------------------
     # 1. set_mode
     # ------------------------------------------------------------------

package/src/superlocalmemory/server/routes/memories.py

@@ -46,19 +46,61 @@ def _fetch_graph_data(
 ) -> tuple[list, list, list]:
     """Fetch graph nodes, links, clusters from V3 or V2 schema."""
     if use_v3:
+        # Graph-first: fetch edges, then get connected nodes, then fill slots
         cursor.execute("""
-            SELECT f.fact_id as id, f.content, f.fact_type as category,
-                   f.confidence as importance, f.session_id as project_name,
-                   f.created_at
-            FROM atomic_facts f WHERE f.profile_id = ? AND f.confidence >= ?
-            ORDER BY f.confidence DESC, f.created_at DESC LIMIT ?
-        """, (profile, min_importance / 10.0, max_nodes))
-        nodes = cursor.fetchall()
+            SELECT source_id as source, target_id as target,
+                   weight, edge_type as relationship_type
+            FROM graph_edges WHERE profile_id = ?
+            ORDER BY weight DESC
+        """, (profile,))
+        all_links = cursor.fetchall()
+
+        connected_ids = set()
+        for lk in all_links:
+            connected_ids.add(lk['source'])
+            connected_ids.add(lk['target'])
+
+        # Fetch connected nodes first (these have edges to display)
+        connected_nodes: list = []
+        if connected_ids:
+            ph = ','.join('?' * len(connected_ids))
+            cursor.execute(f"""
+                SELECT fact_id as id, content, fact_type as category,
+                       confidence as importance, session_id as project_name,
+                       created_at
+                FROM atomic_facts
+                WHERE profile_id = ? AND fact_id IN ({ph})
+            """, [profile] + list(connected_ids))
+            connected_nodes = cursor.fetchall()
+
+        # Fill remaining slots with top-confidence unconnected nodes
+        remaining = max_nodes - len(connected_nodes)
+        if remaining > 0:
+            existing = {n['id'] for n in connected_nodes}
+            cursor.execute("""
+                SELECT fact_id as id, content, fact_type as category,
+                       confidence as importance, session_id as project_name,
+                       created_at
+                FROM atomic_facts
+                WHERE profile_id = ? AND confidence >= ?
+                ORDER BY confidence DESC, created_at DESC
+                LIMIT ?
+            """, (profile, min_importance / 10.0, remaining + len(existing)))
+            for n in cursor.fetchall():
+                if n['id'] not in existing:
+                    connected_nodes.append(n)
+                    if len(connected_nodes) >= max_nodes:
+                        break
+
+        nodes = connected_nodes[:max_nodes]
         for n in nodes:
             n['entities'] = []
             n['content_preview'] = _preview(n.get('content'))
-        ids = [n['id'] for n in nodes]
-        links = _fetch_edges_v3(cursor, profile, ids)
+
+        # Filter edges to only those between displayed nodes
+        node_ids = {n['id'] for n in nodes}
+        links = [lk for lk in all_links
+                 if lk['source'] in node_ids and lk['target'] in node_ids]
         return nodes, links, []
 
     # V2 fallback

package/src/superlocalmemory/server/routes/stats.py

@@ -72,6 +72,17 @@ async def get_stats():
                 total_clusters = cursor.fetchone()['total']
             except Exception:
                 pass
+            # Fallback: V2-migrated clusters stored as cluster_id on memories
+            if total_clusters == 0:
+                try:
+                    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']
+                except Exception:
+                    pass
 
             # Fact type breakdown (replaces category in V3)
             cursor.execute("""

package/src/superlocalmemory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superlocalmemory
-Version: 3.0.16
+Version: 3.0.17
 Summary: Information-geometric agent memory with mathematical guarantees
 Author-email: Varun Pratap Bhardwaj <admin@superlocalmemory.com>
 License: MIT

package/ui/index.html

@@ -740,7 +740,7 @@
             </li>
             <li class="nav-item">
                 <button class="nav-link" id="learning-tab" data-bs-toggle="tab" data-bs-target="#learning-pane">
-                    <i class="bi bi-mortarboard"></i> Learning <span class="badge bg-warning text-dark" style="font-size:0.6rem;vertical-align:top;">v2.7</span>
+                    <i class="bi bi-mortarboard"></i> Learning
                 </button>
             </li>
             <li class="nav-item">
@@ -760,17 +760,17 @@
             </li>
             <li class="nav-item" role="presentation">
                 <button class="nav-link" id="lifecycle-tab" data-bs-toggle="tab" data-bs-target="#lifecycle-pane" type="button" role="tab">
-                    <i class="bi bi-hourglass-split"></i> Lifecycle <span class="badge bg-success ms-1">v2.8</span>
+                    <i class="bi bi-hourglass-split"></i> Lifecycle
                 </button>
             </li>
             <li class="nav-item" role="presentation">
                 <button class="nav-link" id="behavioral-tab" data-bs-toggle="tab" data-bs-target="#behavioral-pane" type="button" role="tab">
-                    <i class="bi bi-lightbulb"></i> Behavioral <span class="badge bg-success ms-1">v2.8</span>
+                    <i class="bi bi-lightbulb"></i> Behavioral
                 </button>
             </li>
             <li class="nav-item" role="presentation">
                 <button class="nav-link" id="compliance-tab" data-bs-toggle="tab" data-bs-target="#compliance-pane" type="button" role="tab">
-                    <i class="bi bi-shield-lock"></i> Compliance <span class="badge bg-success ms-1">v2.8</span>
+                    <i class="bi bi-shield-lock"></i> Compliance
                 </button>
             </li>
             <li class="nav-item">
@@ -1023,8 +1023,13 @@
                 <p class="text-muted">See how each retrieval channel contributes to results.</p>
                 <div class="input-group mb-3">
                     <input type="text" id="recall-lab-query" class="form-control form-control-lg" placeholder="Enter your query...">
+                    <select id="recall-lab-per-page" class="form-select" style="max-width:100px;">
+                        <option value="10" selected>10</option>
+                        <option value="25">25</option>
+                        <option value="50">50</option>
+                    </select>
                     <button class="btn btn-primary btn-lg" id="recall-lab-search">
-                        <i class="bi bi-search"></i> Search with Trace
+                        <i class="bi bi-search"></i> Search
                     </button>
                 </div>
                 <div id="recall-lab-meta" class="mb-3 text-muted small"></div>
@@ -1070,8 +1075,19 @@
                 </div>
             </div>
 
-            <!-- Learning System (v2.7) -->
+            <!-- Learning System -->
             <div class="tab-pane fade" id="learning-pane">
+                <!-- Getting Started Guide -->
+                <div class="alert alert-light border mb-3" id="learning-getting-started">
+                    <h6 class="mb-2"><i class="bi bi-info-circle text-primary"></i> How Learning Works</h6>
+                    <p class="mb-1 small">SuperLocalMemory learns from your usage patterns to improve retrieval ranking over time. This happens automatically as you use <code>slm recall</code> or search via MCP.</p>
+                    <ul class="small mb-0">
+                        <li><strong>0-20 signals:</strong> Baseline phase (collecting data)</li>
+                        <li><strong>20+ signals:</strong> Rule-based ranking adjustments</li>
+                        <li><strong>200+ signals:</strong> ML model trained on your patterns</li>
+                    </ul>
+                    <p class="mb-0 mt-1 small text-muted">Each recall query generates a signal. Keep using SLM and this tab will populate automatically.</p>
+                </div>
                 <!-- Ranking Phase & Engagement -->
                 <div class="row g-3 mb-3">
                     <div class="col-md-4">
@@ -1424,12 +1440,18 @@
                 </div>
             </div>
 
-            <!-- Behavioral Learning (v2.8) -->
+            <!-- Behavioral Learning -->
             <div class="tab-pane fade" id="behavioral-pane" role="tabpanel">
                 <div class="d-flex justify-content-between align-items-center mb-3">
                     <h5 class="mb-0"><i class="bi bi-lightbulb text-info"></i> Behavioral Learning</h5>
                     <span class="badge bg-secondary" id="behavioral-profile-badge">default</span>
                 </div>
+                <!-- Getting Started Guide -->
+                <div class="alert alert-light border mb-3">
+                    <h6 class="mb-2"><i class="bi bi-info-circle text-primary"></i> How Behavioral Learning Works</h6>
+                    <p class="mb-1 small">This tab tracks how memories are used in practice — which recalls led to successful outcomes (code written, decisions made, bugs fixed) and which didn't.</p>
+                    <p class="mb-0 small text-muted">Report outcomes using the form below, or via MCP: <code>report_outcome</code>. Patterns emerge after 10+ outcomes.</p>
+                </div>
                 <!-- Stats Row -->
                 <div class="row g-3 mb-4">
                     <div class="col-md-3"><div class="card p-3 text-center"><div class="fw-bold fs-3 text-success" id="bh-success-count">-</div><small class="text-muted">Successes</small></div></div>
@@ -1465,12 +1487,18 @@
                 </div>
             </div>
 
-            <!-- Compliance & Audit (v2.8) -->
+            <!-- Compliance & Audit -->
             <div class="tab-pane fade" id="compliance-pane" role="tabpanel">
                 <div class="d-flex justify-content-between align-items-center mb-3">
                     <h5 class="mb-0"><i class="bi bi-shield-lock text-success"></i> Compliance &amp; Audit</h5>
                     <span class="badge bg-secondary" id="compliance-profile-badge">default</span>
                 </div>
+                <!-- Getting Started Guide -->
+                <div class="alert alert-light border mb-3">
+                    <h6 class="mb-2"><i class="bi bi-info-circle text-primary"></i> Compliance Overview</h6>
+                    <p class="mb-1 small">Set retention policies and access controls for your memories. In Mode A, all data stays on your device — EU AI Act compliant by default.</p>
+                    <p class="mb-0 small text-muted">Create a retention policy below to start managing memory lifecycle automatically.</p>
+                </div>
                 <!-- Stats Row -->
                 <div class="row g-3 mb-4">
                     <div class="col-md-4"><div class="card p-3 text-center"><div class="fw-bold fs-3" id="cp-audit-count">-</div><small class="text-muted">Audit Events</small></div></div>

package/ui/js/clusters.js

@@ -1,7 +1,5 @@
-// SuperLocalMemory V2 - Clusters View
-// Depends on: core.js
-//
-// Security: All dynamic values escaped via escapeHtml(). Data from local DB only.
+// SuperLocalMemory V3 - Clusters View
+// Part of Qualixar | https://superlocalmemory.com
 
 async function loadClusters() {
     showLoading('clusters-list', 'Loading clusters...');
@@ -18,152 +16,180 @@ async function loadClusters() {
 function renderClusters(clusters) {
     var container = document.getElementById('clusters-list');
     if (!clusters || clusters.length === 0) {
-        showEmpty('clusters-list', 'collection', 'No clusters found. Run "slm build-graph" to generate clusters.');
+        showEmpty('clusters-list', 'collection', 'No clusters found yet. Clusters form automatically as you store related memories.');
         return;
     }
 
-    var colors = ['#667eea', '#f093fb', '#4facfe', '#43e97b', '#fa709a'];
+    var colors = ['#667eea', '#f093fb', '#4facfe', '#43e97b', '#fa709a', '#30cfd0', '#764ba2', '#f5576c'];
     container.textContent = '';
 
     clusters.forEach(function(cluster, idx) {
         var color = colors[idx % colors.length];
 
         var card = document.createElement('div');
-        card.className = 'card cluster-card';
-        card.style.cssText = 'border-color:' + color + '; cursor:pointer;';
-        card.setAttribute('data-cluster-id', cluster.cluster_id);
-        card.title = 'Click to filter graph to this cluster';
+        card.className = 'card mb-2';
+        card.style.borderLeft = '4px solid ' + color;
 
         var body = document.createElement('div');
-        body.className = 'card-body';
+        body.className = 'card-body py-2 px-3';
+        body.style.cursor = 'pointer';
+
+        // Header row
+        var headerRow = document.createElement('div');
+        headerRow.className = 'd-flex justify-content-between align-items-center';
 
         var title = document.createElement('h6');
-        title.className = 'card-title';
-        title.textContent = 'Cluster ' + cluster.cluster_id + ' ';
+        title.className = 'mb-0';
+        title.textContent = 'Cluster ' + cluster.cluster_id;
+
+        var badges = document.createElement('div');
         var countBadge = document.createElement('span');
-        countBadge.className = 'badge bg-secondary float-end';
+        countBadge.className = 'badge bg-secondary me-1';
         countBadge.textContent = cluster.member_count + ' memories';
-        title.appendChild(countBadge);
-        body.appendChild(title);
-
-        var imp = document.createElement('p');
-        imp.className = 'mb-2';
-        imp.textContent = 'Avg Importance: ' + parseFloat(cluster.avg_importance).toFixed(1);
-        body.appendChild(imp);
-
-        var cats = document.createElement('p');
-        cats.className = 'mb-2';
-        cats.textContent = 'Categories: ' + (cluster.categories || 'None');
-        body.appendChild(cats);
-
-        var entLabel = document.createElement('strong');
-        entLabel.textContent = 'Top Entities:';
-        body.appendChild(entLabel);
-        body.appendChild(document.createElement('br'));
-
-        if (cluster.top_entities && cluster.top_entities.length > 0) {
-            cluster.top_entities.forEach(function(e) {
-                var badge = document.createElement('span');
-                badge.className = 'badge bg-info entity-badge';
-                badge.textContent = e.entity + ' (' + e.count + ')';
-                body.appendChild(badge);
-                body.appendChild(document.createTextNode(' '));
-            });
-        } else {
-            var none = document.createElement('span');
-            none.className = 'text-muted';
-            none.textContent = 'No entities';
-            body.appendChild(none);
+        badges.appendChild(countBadge);
+
+        if (cluster.avg_importance) {
+            var impBadge = document.createElement('span');
+            impBadge.className = 'badge bg-outline-primary';
+            impBadge.style.cssText = 'border:1px solid #667eea; color:#667eea;';
+            impBadge.textContent = 'imp: ' + parseFloat(cluster.avg_importance).toFixed(1);
+            badges.appendChild(impBadge);
+        }
+
+        var expandIcon = document.createElement('i');
+        expandIcon.className = 'bi bi-chevron-down ms-2';
+        expandIcon.style.transition = 'transform 0.2s';
+        badges.appendChild(expandIcon);
+
+        headerRow.appendChild(title);
+        headerRow.appendChild(badges);
+        body.appendChild(headerRow);
+
+        // Summary line (categories if available)
+        if (cluster.categories) {
+            var catLine = document.createElement('small');
+            catLine.className = 'text-muted';
+            catLine.textContent = cluster.categories;
+            body.appendChild(catLine);
         }
 
+        // Expandable member area (hidden by default)
+        var memberArea = document.createElement('div');
+        memberArea.className = 'mt-2';
+        memberArea.style.display = 'none';
+        memberArea.id = 'cluster-members-' + cluster.cluster_id;
+
+        var loadingText = document.createElement('div');
+        loadingText.className = 'text-center text-muted small py-2';
+        loadingText.textContent = 'Loading members...';
+        memberArea.appendChild(loadingText);
+
+        body.appendChild(memberArea);
         card.appendChild(body);
         container.appendChild(card);
 
-        // v2.6.5: Click card → filter graph to this cluster
-        card.addEventListener('click', function(e) {
-            // Don't trigger if clicking on badge or entity
-            if (e.target.classList.contains('entity-badge') || e.target.classList.contains('badge')) {
-                return;
-            }
+        // Click to expand/collapse
+        var expanded = false;
+        body.addEventListener('click', function(e) {
+            expanded = !expanded;
+            memberArea.style.display = expanded ? 'block' : 'none';
+            expandIcon.style.transform = expanded ? 'rotate(180deg)' : 'rotate(0)';
 
-            const clusterId = parseInt(card.getAttribute('data-cluster-id'));
-            filterGraphToCluster(clusterId);
+            if (expanded && memberArea.children.length === 1 && memberArea.children[0] === loadingText) {
+                loadClusterMembers(cluster.cluster_id, memberArea);
+            }
         });
+    });
+}
 
-        // v2.6.5: Click entity badge → filter graph by entity
-        if (cluster.top_entities && cluster.top_entities.length > 0) {
-            const entityBadges = body.querySelectorAll('.entity-badge');
-            entityBadges.forEach(function(badge) {
-                badge.style.cursor = 'pointer';
-                badge.title = 'Click to show memories with this entity';
-                badge.addEventListener('click', function(e) {
-                    e.stopPropagation(); // Don't trigger card click
-                    const entityText = badge.textContent.split(' (')[0]; // Extract entity name
-                    filterGraphByEntity(entityText);
-                });
-            });
+async function loadClusterMembers(clusterId, container) {
+    try {
+        var response = await fetch('/api/clusters/' + clusterId + '?limit=10');
+        var data = await response.json();
+        container.textContent = '';
+
+        if (!data.members || data.members.length === 0) {
+            var empty = document.createElement('div');
+            empty.className = 'text-muted small';
+            empty.textContent = 'No members found.';
+            container.appendChild(empty);
+            return;
         }
 
-        // v2.6.5: Click "X memories" badge → show list in sidebar (future feature)
-        countBadge.style.cursor = 'pointer';
-        countBadge.title = 'Click to view memories in this cluster';
-        countBadge.addEventListener('click', function(e) {
-            e.stopPropagation(); // Don't trigger card click
-            showClusterMemories(cluster.cluster_id);
+        data.members.forEach(function(m, i) {
+            var row = document.createElement('div');
+            row.className = 'border-bottom py-1';
+            if (i === data.members.length - 1) row.className = 'py-1';
+
+            var content = document.createElement('div');
+            content.className = 'small';
+            var text = m.content || m.summary || '';
+            content.textContent = (i + 1) + '. ' + (text.length > 150 ? text.substring(0, 150) + '...' : text);
+            row.appendChild(content);
+
+            var meta = document.createElement('div');
+            meta.className = 'text-muted';
+            meta.style.fontSize = '0.7rem';
+            var parts = [];
+            if (m.category) parts.push(m.category);
+            if (m.importance) parts.push('imp: ' + m.importance);
+            if (m.created_at) parts.push(m.created_at.substring(0, 10));
+            meta.textContent = parts.join(' | ');
+            row.appendChild(meta);
+
+            container.appendChild(row);
         });
-    });
+
+        // View in graph button
+        var graphBtn = document.createElement('button');
+        graphBtn.className = 'btn btn-sm btn-outline-primary mt-2';
+        graphBtn.textContent = 'View in Knowledge Graph';
+        graphBtn.addEventListener('click', function(e) {
+            e.stopPropagation();
+            filterGraphToCluster(clusterId);
+        });
+        container.appendChild(graphBtn);
+
+    } catch (error) {
+        container.textContent = '';
+        var errDiv = document.createElement('div');
+        errDiv.className = 'text-danger small';
+        errDiv.textContent = 'Failed to load: ' + error.message;
+        container.appendChild(errDiv);
+    }
 }
 
-// v2.6.5: Filter graph to a specific cluster
 function filterGraphToCluster(clusterId) {
-    // Switch to Graph tab
-    const graphTab = document.querySelector('a[href="#graph"]');
-    if (graphTab) {
-        graphTab.click();
-    }
+    var graphTab = document.querySelector('a[href="#graph"]');
+    if (graphTab) graphTab.click();
 
-    // Apply filter after a delay (for tab to load)
     setTimeout(function() {
         if (typeof filterState !== 'undefined' && typeof filterByCluster === 'function' && typeof renderGraph === 'function') {
             filterState.cluster_id = clusterId;
-            const filtered = filterByCluster(originalGraphData, clusterId);
+            var filtered = filterByCluster(originalGraphData, clusterId);
             renderGraph(filtered);
-
-            // Update URL
-            const url = new URL(window.location);
+            var url = new URL(window.location);
             url.searchParams.set('cluster_id', clusterId);
             window.history.replaceState({}, '', url);
         }
     }, 300);
 }
 
-// v2.6.5: Filter graph by entity
 function filterGraphByEntity(entity) {
-    // Switch to Graph tab
-    const graphTab = document.querySelector('a[href="#graph"]');
-    if (graphTab) {
-        graphTab.click();
-    }
+    var graphTab = document.querySelector('a[href="#graph"]');
+    if (graphTab) graphTab.click();
 
-    // Apply filter after a delay
     setTimeout(function() {
         if (typeof filterState !== 'undefined' && typeof filterByEntity === 'function' && typeof renderGraph === 'function') {
             filterState.entity = entity;
-            const filtered = filterByEntity(originalGraphData, entity);
+            var filtered = filterByEntity(originalGraphData, entity);
             renderGraph(filtered);
         }
     }, 300);
 }
 
-// v2.6.5: Show memories in a cluster (future: sidebar list)
 function showClusterMemories(clusterId) {
-    // For now, just filter Memories tab
-    const memoriesTab = document.querySelector('a[href="#memories"]');
-    if (memoriesTab) {
-        memoriesTab.click();
-    }
-
-    // TODO: Implement sidebar memory list view
-    console.log('Show memories for cluster', clusterId);
-    showToast('Filtering memories for cluster ' + clusterId);
+    var memoriesTab = document.querySelector('a[href="#memories"]');
+    if (memoriesTab) memoriesTab.click();
+    if (typeof showToast === 'function') showToast('Filtering memories for cluster ' + clusterId);
 }

package/ui/js/graph-core.js

@@ -98,8 +98,10 @@ function transformDataForCytoscape(data) {
 
     // Add nodes
     data.nodes.forEach(node => {
-        const label = node.category || node.project_name || `Memory #${node.id}`;
         const contentPreview = node.content_preview || node.summary || node.content || '';
+        // Label: first 4 words of content (readable on node), fallback to category
+        const contentWords = contentPreview.split(/\s+/).slice(0, 4).join(' ');
+        const label = contentWords || node.category || `Memory #${node.id}`;
         const preview = contentPreview.substring(0, 50) + (contentPreview.length > 50 ? '...' : '');
 
         elements.push({

package/ui/js/recall-lab.js

@@ -1,10 +1,23 @@
-// SuperLocalMemory V3 — Recall Lab
+// SuperLocalMemory V3 — Recall Lab with Pagination
 // Part of Qualixar | https://superlocalmemory.com
 
+var recallLabState = {
+    allResults: [],
+    page: 0,
+    perPage: 10,
+    query: '',
+};
+
 document.getElementById('recall-lab-search')?.addEventListener('click', function() {
     var query = document.getElementById('recall-lab-query').value.trim();
     if (!query) return;
 
+    recallLabState.query = query;
+    recallLabState.page = 0;
+    var perPageEl = document.getElementById('recall-lab-per-page');
+    recallLabState.perPage = perPageEl ? parseInt(perPageEl.value) : 10;
+    var fetchLimit = Math.max(recallLabState.perPage * 5, 50); // Fetch up to 5 pages
+
     var resultsDiv = document.getElementById('recall-lab-results');
     var metaDiv = document.getElementById('recall-lab-meta');
     resultsDiv.textContent = '';
@@ -18,7 +31,7 @@ document.getElementById('recall-lab-search')?.addEventListener('click', function
     fetch('/api/v3/recall/trace', {
         method: 'POST',
         headers: {'Content-Type': 'application/json'},
-        body: JSON.stringify({query: query, limit: 10})
+        body: JSON.stringify({query: query, limit: fetchLimit})
     }).then(function(r) { return r.json(); }).then(function(data) {
         if (data.error) {
             resultsDiv.textContent = '';
@@ -32,11 +45,13 @@ document.getElementById('recall-lab-search')?.addEventListener('click', function
         metaDiv.textContent = '';
         appendMetaField(metaDiv, 'Query type: ', data.query_type || 'unknown');
         metaDiv.appendChild(document.createTextNode(' | '));
-        appendMetaField(metaDiv, 'Results: ', String(data.result_count));
+        appendMetaField(metaDiv, 'Results: ', String((data.results || []).length));
         metaDiv.appendChild(document.createTextNode(' | '));
         appendMetaField(metaDiv, 'Time: ', (data.retrieval_time_ms || 0).toFixed(0) + 'ms');
 
-        if (!data.results || data.results.length === 0) {
+        recallLabState.allResults = data.results || [];
+
+        if (recallLabState.allResults.length === 0) {
             resultsDiv.textContent = '';
             var infoDiv = document.createElement('div');
             infoDiv.className = 'alert alert-info';
@@ -45,57 +60,7 @@ document.getElementById('recall-lab-search')?.addEventListener('click', function
             return;
         }
 
-        resultsDiv.textContent = '';
-        var listGroup = document.createElement('div');
-        listGroup.className = 'list-group';
-
-        data.results.forEach(function(r, i) {
-            var channels = r.channel_scores || {};
-            var maxChannel = Math.max(channels.semantic || 0, channels.bm25 || 0, channels.entity_graph || 0, channels.temporal || 0) || 1;
-
-            var item = document.createElement('div');
-            item.className = 'list-group-item list-group-item-action';
-            item.style.cursor = 'pointer';
-            item.title = 'Click to view full memory';
-            (function(result) {
-                item.addEventListener('click', function() {
-                    if (typeof openMemoryDetail === 'function') {
-                        openMemoryDetail({
-                            id: result.fact_id,
-                            content: result.content,
-                            score: result.score,
-                            importance: Math.round((result.confidence || 0.5) * 10),
-                            category: 'recall',
-                            tags: Object.keys(result.channel_scores || {}).join(', '),
-                            created_at: null,
-                            trust_score: result.trust_score,
-                            channel_scores: result.channel_scores
-                        });
-                    }
-                });
-            })(r);
-
-            var header = document.createElement('h6');
-            header.className = 'mb-1';
-            header.textContent = (i + 1) + '. ' + (r.content || '').substring(0, 200);
-            item.appendChild(header);
-
-            var meta = document.createElement('small');
-            meta.className = 'text-muted';
-            meta.textContent = 'Score: ' + r.score + ' | Trust: ' + r.trust_score + ' | Confidence: ' + r.confidence;
-            item.appendChild(meta);
-
-            var barsDiv = document.createElement('div');
-            barsDiv.className = 'mt-2';
-            barsDiv.appendChild(buildChannelBar('Semantic', channels.semantic || 0, maxChannel, 'primary'));
-            barsDiv.appendChild(buildChannelBar('BM25', channels.bm25 || 0, maxChannel, 'success'));
-            barsDiv.appendChild(buildChannelBar('Entity', channels.entity_graph || 0, maxChannel, 'info'));
-            barsDiv.appendChild(buildChannelBar('Temporal', channels.temporal || 0, maxChannel, 'warning'));
-            item.appendChild(barsDiv);
-
-            listGroup.appendChild(item);
-        });
-        resultsDiv.appendChild(listGroup);
+        renderRecallPage();
     }).catch(function(e) {
         resultsDiv.textContent = '';
         var errDiv = document.createElement('div');
@@ -105,6 +70,140 @@ document.getElementById('recall-lab-search')?.addEventListener('click', function
     });
 });
 
+function renderRecallPage() {
+    var resultsDiv = document.getElementById('recall-lab-results');
+    resultsDiv.textContent = '';
+
+    var results = recallLabState.allResults;
+    var start = recallLabState.page * recallLabState.perPage;
+    var end = Math.min(start + recallLabState.perPage, results.length);
+    var pageResults = results.slice(start, end);
+    var totalPages = Math.ceil(results.length / recallLabState.perPage);
+
+    var listGroup = document.createElement('div');
+    listGroup.className = 'list-group';
+
+    pageResults.forEach(function(r, i) {
+        var globalIndex = start + i;
+        var channels = r.channel_scores || {};
+        var maxChannel = Math.max(channels.semantic || 0, channels.bm25 || 0, channels.entity_graph || 0, channels.temporal || 0) || 1;
+
+        var item = document.createElement('div');
+        item.className = 'list-group-item list-group-item-action';
+        item.style.cursor = 'pointer';
+        item.title = 'Click to view full memory';
+        (function(result) {
+            item.addEventListener('click', function() {
+                if (typeof openMemoryDetail === 'function') {
+                    openMemoryDetail({
+                        id: result.fact_id,
+                        content: result.content,
+                        score: result.score,
+                        importance: Math.round((result.confidence || 0.5) * 10),
+                        category: 'recall',
+                        tags: Object.keys(result.channel_scores || {}).join(', '),
+                        created_at: null,
+                        trust_score: result.trust_score,
+                        channel_scores: result.channel_scores
+                    });
+                }
+            });
+        })(r);
+
+        var header = document.createElement('h6');
+        header.className = 'mb-1';
+        header.textContent = (globalIndex + 1) + '. ' + (r.content || '').substring(0, 200);
+        item.appendChild(header);
+
+        var meta = document.createElement('small');
+        meta.className = 'text-muted';
+        meta.textContent = 'Score: ' + r.score + ' | Trust: ' + r.trust_score + ' | Confidence: ' + r.confidence;
+        item.appendChild(meta);
+
+        var barsDiv = document.createElement('div');
+        barsDiv.className = 'mt-2';
+        barsDiv.appendChild(buildChannelBar('Semantic', channels.semantic || 0, maxChannel, 'primary'));
+        barsDiv.appendChild(buildChannelBar('BM25', channels.bm25 || 0, maxChannel, 'success'));
+        barsDiv.appendChild(buildChannelBar('Entity', channels.entity_graph || 0, maxChannel, 'info'));
+        barsDiv.appendChild(buildChannelBar('Temporal', channels.temporal || 0, maxChannel, 'warning'));
+        item.appendChild(barsDiv);
+
+        listGroup.appendChild(item);
+    });
+    resultsDiv.appendChild(listGroup);
+
+    // Pagination controls
+    if (totalPages > 1) {
+        var nav = document.createElement('nav');
+        nav.className = 'mt-3';
+        nav.setAttribute('aria-label', 'Recall results pagination');
+        var ul = document.createElement('ul');
+        ul.className = 'pagination justify-content-center';
+
+        // Prev
+        var prevLi = document.createElement('li');
+        prevLi.className = 'page-item' + (recallLabState.page === 0 ? ' disabled' : '');
+        var prevA = document.createElement('a');
+        prevA.className = 'page-link';
+        prevA.href = '#';
+        prevA.textContent = 'Previous';
+        prevA.addEventListener('click', function(e) {
+            e.preventDefault();
+            if (recallLabState.page > 0) {
+                recallLabState.page--;
+                renderRecallPage();
+            }
+        });
+        prevLi.appendChild(prevA);
+        ul.appendChild(prevLi);
+
+        // Page numbers
+        for (var p = 0; p < totalPages; p++) {
+            var li = document.createElement('li');
+            li.className = 'page-item' + (p === recallLabState.page ? ' active' : '');
+            var a = document.createElement('a');
+            a.className = 'page-link';
+            a.href = '#';
+            a.textContent = String(p + 1);
+            (function(pageNum) {
+                a.addEventListener('click', function(e) {
+                    e.preventDefault();
+                    recallLabState.page = pageNum;
+                    renderRecallPage();
+                });
+            })(p);
+            li.appendChild(a);
+            ul.appendChild(li);
+        }
+
+        // Next
+        var nextLi = document.createElement('li');
+        nextLi.className = 'page-item' + (recallLabState.page >= totalPages - 1 ? ' disabled' : '');
+        var nextA = document.createElement('a');
+        nextA.className = 'page-link';
+        nextA.href = '#';
+        nextA.textContent = 'Next';
+        nextA.addEventListener('click', function(e) {
+            e.preventDefault();
+            if (recallLabState.page < totalPages - 1) {
+                recallLabState.page++;
+                renderRecallPage();
+            }
+        });
+        nextLi.appendChild(nextA);
+        ul.appendChild(nextLi);
+
+        nav.appendChild(ul);
+        resultsDiv.appendChild(nav);
+
+        // Page info
+        var info = document.createElement('div');
+        info.className = 'text-center text-muted small';
+        info.textContent = 'Showing ' + (start + 1) + '-' + end + ' of ' + results.length + ' results';
+        resultsDiv.appendChild(info);
+    }
+}
+
 function appendMetaField(parent, label, value) {
     var text = document.createTextNode(label);
     parent.appendChild(text);
@@ -115,27 +214,22 @@ function appendMetaField(parent, label, value) {
 
 function buildChannelBar(name, score, max, color) {
     var pct = max > 0 ? Math.round((score / max) * 100) : 0;
-
     var row = document.createElement('div');
     row.className = 'd-flex align-items-center mb-1';
-
     var label = document.createElement('span');
     label.className = 'me-2';
     label.style.width = '70px';
     label.style.fontSize = '0.75rem';
     label.textContent = name;
     row.appendChild(label);
-
     var progressWrap = document.createElement('div');
     progressWrap.className = 'progress flex-grow-1';
     progressWrap.style.height = '14px';
-
     var bar = document.createElement('div');
     bar.className = 'progress-bar bg-' + color;
     bar.style.width = pct + '%';
     bar.textContent = score.toFixed(3);
     progressWrap.appendChild(bar);
-
     row.appendChild(progressWrap);
     return row;
 }