superlocalmemory 3.3.29 → 3.4.1

package/src/superlocalmemory/learning/consolidation_worker.py

@@ -133,127 +133,315 @@ class ConsolidationWorker:
             return 0
 
     def _generate_patterns(self, profile_id: str, dry_run: bool) -> int:
-        """Mine behavioral patterns from existing memories.
+        """Mine behavioral patterns from ALL memory sources.
 
-        Scans all facts to detect:
-        - Tech preferences (language/framework mentions)
-        - Topic clusters (frequently discussed subjects)
-        - Temporal patterns (time-of-day activity)
+        v3.4.1: Expanded from 3 to 7 pattern types. No 500-fact cap.
+        Analyzes: facts, signals, co-retrieval edges, channel credits,
+        entities, sessions, graph communities.
         """
         try:
             from superlocalmemory.learning.behavioral import BehavioralPatternStore
             import re
-            from collections import Counter
+            from collections import Counter, defaultdict
 
             conn = sqlite3.connect(self._memory_db, timeout=10)
             conn.execute("PRAGMA busy_timeout=5000")
             conn.row_factory = sqlite3.Row
 
+            # v3.4.1: No cap — analyze ALL facts
             facts = conn.execute(
-                "SELECT content, created_at FROM atomic_facts "
-                "WHERE profile_id = ? ORDER BY created_at DESC LIMIT 500",
+                "SELECT fact_id, content, fact_type, created_at, session_id, "
+                "confidence, canonical_entities_json "
+                "FROM atomic_facts "
+                "WHERE profile_id = ? AND lifecycle = 'active' "
+                "ORDER BY created_at DESC",
                 (profile_id,),
             ).fetchall()
-            conn.close()
 
-            if len(facts) < 10:
+            if len(facts) < 5:
+                conn.close()
                 return 0
 
             store = BehavioralPatternStore(self._learning_db)
             generated = 0
 
-            # Tech preferences: detect technology mentions
+            # ── 1. Tech Preferences (expanded keyword list) ───────────
             tech_keywords = {
-                "python": "Python", "javascript": "JavaScript", "typescript": "TypeScript",
-                "react": "React", "vue": "Vue", "angular": "Angular",
-                "postgresql": "PostgreSQL", "mysql": "MySQL", "sqlite": "SQLite",
-                "docker": "Docker", "kubernetes": "Kubernetes", "aws": "AWS",
-                "azure": "Azure", "gcp": "GCP", "node": "Node.js",
-                "fastapi": "FastAPI", "django": "Django", "flask": "Flask",
+                "python": "Python", "javascript": "JavaScript",
+                "typescript": "TypeScript", "react": "React",
+                "vue": "Vue", "angular": "Angular",
+                "postgresql": "PostgreSQL", "mysql": "MySQL",
+                "sqlite": "SQLite", "docker": "Docker",
+                "kubernetes": "Kubernetes", "aws": "AWS",
+                "azure": "Azure", "gcp": "GCP",
+                "node": "Node.js", "fastapi": "FastAPI",
+                "django": "Django", "flask": "Flask",
                 "rust": "Rust", "go": "Go", "java": "Java",
                 "git": "Git", "npm": "npm", "pip": "pip",
-                "langchain": "LangChain", "ollama": "Ollama", "pytorch": "PyTorch",
-                "claude": "Claude", "openai": "OpenAI", "anthropic": "Anthropic",
+                "langchain": "LangChain", "ollama": "Ollama",
+                "pytorch": "PyTorch", "claude": "Claude",
+                "openai": "OpenAI", "anthropic": "Anthropic",
+                "redis": "Redis", "mongodb": "MongoDB",
+                "graphql": "GraphQL", "nextjs": "Next.js",
+                "terraform": "Terraform", "nginx": "Nginx",
+                "linux": "Linux", "macos": "macOS",
+                "vscode": "VS Code", "neovim": "Neovim",
             }
 
-            tech_counts = Counter()
+            tech_counts: Counter = Counter()
             for f in facts:
                 content = dict(f)["content"].lower()
                 for keyword, label in tech_keywords.items():
                     if keyword in content:
                         tech_counts[label] += 1
 
-            for tech, count in tech_counts.most_common(15):
-                if count >= 3 and not dry_run:
-                    confidence = min(1.0, count / 20)
+            for tech, count in tech_counts.most_common(20):
+                if count >= 2 and not dry_run:
+                    confidence = min(1.0, count / max(len(facts) * 0.1, 10))
                     store.record_pattern(
                         profile_id=profile_id,
                         pattern_type="tech_preference",
-                        data={"topic": tech, "pattern_key": tech, "value": tech,
-                               "key": "tech", "evidence": count},
+                        data={"topic": tech, "pattern_key": tech,
+                              "value": tech, "key": "tech",
+                              "evidence": count},
                         success_rate=confidence,
                         confidence=confidence,
                     )
                     generated += 1
 
-            # Topic clusters: most discussed subjects
-            word_counts = Counter()
+            # ── 2. Topic Interests (word frequency) ───────────────────
             stopwords = frozenset({
-                "the", "is", "a", "an", "in", "on", "at", "to", "for", "of",
-                "and", "or", "not", "with", "that", "this", "was", "are", "be",
-                "has", "had", "have", "from", "by", "it", "its", "as", "but",
+                "the", "is", "a", "an", "in", "on", "at", "to", "for",
+                "of", "and", "or", "not", "with", "that", "this", "was",
+                "are", "be", "has", "had", "have", "from", "by", "it",
+                "its", "as", "but", "were", "been", "being", "would",
+                "could", "should", "will", "may", "might", "can", "do",
+                "does", "did", "about", "into", "over", "after", "before",
+                "then", "than", "also", "just", "like", "more", "some",
+                "only", "other", "such", "each", "every", "both", "most",
             })
+            word_counts: Counter = Counter()
             for f in facts:
                 words = re.findall(r'\b[a-zA-Z]{4,}\b', dict(f)["content"].lower())
                 for w in words:
                     if w not in stopwords:
                         word_counts[w] += 1
 
-            for topic, count in word_counts.most_common(10):
-                if count >= 5 and not dry_run:
-                    confidence = min(1.0, count / 30)
+            for topic, count in word_counts.most_common(15):
+                if count >= 3 and not dry_run:
+                    confidence = min(1.0, count / max(len(facts) * 0.05, 15))
                     store.record_pattern(
                         profile_id=profile_id,
                         pattern_type="interest",
                         data={"topic": topic, "pattern_key": topic,
-                               "count": count, "evidence": count},
+                              "count": count, "evidence": count},
                         success_rate=confidence,
                         confidence=confidence,
                     )
                     generated += 1
 
-            # Temporal patterns: time-of-day activity
-            hour_counts = Counter()
+            # ── 3. Temporal Activity Patterns ─────────────────────────
+            hour_counts: Counter = Counter()
             for f in facts:
                 created = dict(f).get("created_at", "")
-                if "T" in created:
-                    try:
+                try:
+                    if "T" in created:
                         hour = int(created.split("T")[1][:2])
-                        period = "morning" if 6 <= hour < 12 else (
-                            "afternoon" if 12 <= hour < 18 else (
-                                "evening" if 18 <= hour < 22 else "night"))
-                        hour_counts[period] += 1
-                    except (ValueError, IndexError):
-                        pass
-
+                    elif " " in created:
+                        hour = int(created.split(" ")[1][:2])
+                    else:
+                        continue
+                    period = ("morning" if 6 <= hour < 12 else
+                              "afternoon" if 12 <= hour < 18 else
+                              "evening" if 18 <= hour < 22 else "night")
+                    hour_counts[period] += 1
+                except (ValueError, IndexError):
+                    pass
+
+            total_hours = sum(hour_counts.values())
             for period, count in hour_counts.most_common():
-                if count >= 3 and not dry_run:
-                    total = sum(hour_counts.values())
-                    pct = round(count / total * 100)
+                if count >= 2 and total_hours > 0 and not dry_run:
+                    pct = round(count / total_hours * 100)
                     store.record_pattern(
                         profile_id=profile_id,
                         pattern_type="temporal",
                         data={"topic": period, "pattern_key": period,
-                               "value": f"{period} ({pct}%)", "evidence": count,
-                               "key": period, "distribution": dict(hour_counts)},
+                              "value": f"{period} ({pct}%)",
+                              "evidence": count, "key": period,
+                              "distribution": dict(hour_counts)},
                         success_rate=pct / 100,
-                        confidence=min(1.0, count / 20),
+                        confidence=min(1.0, count / max(total_hours * 0.1, 5)),
                     )
                     generated += 1
 
+            # ── 4. Entity Preferences (v3.4.1 NEW) ───────────────────
+            import json as _json
+            entity_counts: Counter = Counter()
+            for f in facts:
+                raw = dict(f).get("canonical_entities_json", "")
+                if raw:
+                    try:
+                        for ent in _json.loads(raw):
+                            entity_counts[ent] += 1
+                    except (ValueError, TypeError):
+                        pass
+
+            for entity, count in entity_counts.most_common(15):
+                if count >= 3 and not dry_run:
+                    confidence = min(1.0, count / max(len(facts) * 0.05, 10))
+                    store.record_pattern(
+                        profile_id=profile_id,
+                        pattern_type="interest",
+                        data={"topic": entity, "pattern_key": f"entity:{entity}",
+                              "value": entity, "evidence": count,
+                              "source": "entity_frequency"},
+                        success_rate=confidence,
+                        confidence=confidence,
+                    )
+                    generated += 1
+
+            # ── 5. Session Activity Patterns (v3.4.1 NEW) ────────────
+            session_counts: Counter = Counter()
+            for f in facts:
+                sid = dict(f).get("session_id", "")
+                if sid:
+                    session_counts[sid] += 1
+
+            if session_counts:
+                avg_facts_per_session = sum(session_counts.values()) / len(session_counts)
+                heavy_sessions = [s for s, c in session_counts.items() if c > avg_facts_per_session * 2]
+                if heavy_sessions and not dry_run:
+                    store.record_pattern(
+                        profile_id=profile_id,
+                        pattern_type="workflow",
+                        data={"pattern_key": "heavy_session_usage",
+                              "value": f"{len(heavy_sessions)} intensive sessions",
+                              "evidence": len(heavy_sessions),
+                              "avg_facts": round(avg_facts_per_session, 1),
+                              "total_sessions": len(session_counts)},
+                        success_rate=0.8,
+                        confidence=min(1.0, len(heavy_sessions) / 5),
+                    )
+                    generated += 1
+
+            # ── 6. Fact Type Distribution (v3.4.1 NEW) ────────────────
+            type_counts: Counter = Counter()
+            for f in facts:
+                ft = dict(f).get("fact_type", "semantic")
+                type_counts[ft] += 1
+
+            total_ft = sum(type_counts.values())
+            if total_ft > 0 and not dry_run:
+                dominant_type = type_counts.most_common(1)[0]
+                pct = round(dominant_type[1] / total_ft * 100)
+                store.record_pattern(
+                    profile_id=profile_id,
+                    pattern_type="style",
+                    data={"pattern_key": "memory_style",
+                          "value": f"{dominant_type[0]} dominant ({pct}%)",
+                          "evidence": dominant_type[1],
+                          "distribution": dict(type_counts)},
+                    success_rate=pct / 100,
+                    confidence=min(1.0, dominant_type[1] / 20),
+                )
+                generated += 1
+
+            # ── 7. Channel Performance (v3.4.1 NEW — from signals) ────
+            try:
+                learn_conn = sqlite3.connect(self._learning_db, timeout=10)
+                learn_conn.row_factory = sqlite3.Row
+
+                # Retrieval usage patterns from learning_feedback
+                channel_rows = learn_conn.execute(
+                    "SELECT channel, COUNT(*) AS cnt, "
+                    "AVG(signal_value) AS avg_signal "
+                    "FROM learning_feedback "
+                    "WHERE profile_id = ? "
+                    "GROUP BY channel ORDER BY cnt DESC",
+                    (profile_id,),
+                ).fetchall()
+
+                for row in channel_rows:
+                    d = dict(row)
+                    ch = d.get("channel", "unknown")
+                    cnt = d.get("cnt", 0)
+                    avg_sig = round(float(d.get("avg_signal", 0) or 0), 3)
+                    if cnt >= 5 and not dry_run:
+                        store.record_pattern(
+                            profile_id=profile_id,
+                            pattern_type="style",
+                            data={"pattern_key": f"channel:{ch}",
+                                  "value": f"{ch} ({cnt} hits, {avg_sig} avg)",
+                                  "evidence": cnt,
+                                  "avg_signal": avg_sig},
+                            success_rate=avg_sig,
+                            confidence=min(1.0, cnt / 50),
+                        )
+                        generated += 1
+
+                # Co-retrieval cluster patterns
+                try:
+                    coret_rows = learn_conn.execute(
+                        "SELECT fact_a, fact_b, co_access_count "
+                        "FROM co_retrieval_edges "
+                        "WHERE profile_id = ? AND co_access_count >= 3 "
+                        "ORDER BY co_access_count DESC LIMIT 20",
+                        (profile_id,),
+                    ).fetchall()
+                    if coret_rows and not dry_run:
+                        store.record_pattern(
+                            profile_id=profile_id,
+                            pattern_type="workflow",
+                            data={"pattern_key": "co_retrieval_clusters",
+                                  "value": f"{len(coret_rows)} strong fact pairs",
+                                  "evidence": len(coret_rows),
+                                  "top_pair_count": dict(coret_rows[0]).get("co_access_count", 0) if coret_rows else 0},
+                            success_rate=0.7,
+                            confidence=min(1.0, len(coret_rows) / 10),
+                        )
+                        generated += 1
+                except Exception:
+                    pass
+
+                learn_conn.close()
+            except Exception as exc:
+                logger.debug("Signal pattern mining failed: %s", exc)
+
+            # ── 8. Community Membership (v3.4.1 NEW — from graph) ─────
+            try:
+                comm_rows = conn.execute(
+                    "SELECT community_id, COUNT(*) AS cnt "
+                    "FROM fact_importance "
+                    "WHERE profile_id = ? AND community_id IS NOT NULL "
+                    "GROUP BY community_id ORDER BY cnt DESC",
+                    (profile_id,),
+                ).fetchall()
+                if comm_rows and not dry_run:
+                    total_comm = sum(dict(r)["cnt"] for r in comm_rows)
+                    store.record_pattern(
+                        profile_id=profile_id,
+                        pattern_type="style",
+                        data={"pattern_key": "knowledge_structure",
+                              "value": f"{len(comm_rows)} topic communities, {total_comm} classified facts",
+                              "evidence": total_comm,
+                              "community_count": len(comm_rows)},
+                        success_rate=0.8,
+                        confidence=min(1.0, len(comm_rows) / 5),
+                    )
+                    generated += 1
+            except Exception:
+                pass
+
+            conn.close()
+
+            logger.info(
+                "Pattern mining: %d patterns generated for profile %s "
+                "from %d facts",
+                generated, profile_id, len(facts),
+            )
             return generated
         except Exception as exc:
-            logger.debug("Pattern generation error: %s", exc)
+            logger.warning("Pattern generation error: %s", exc)
             return 0
 
     def _retrain_ranker(self, profile_id: str, signal_count: int) -> bool:

package/src/superlocalmemory/retrieval/entity_channel.py

@@ -91,6 +91,7 @@ class EntityGraphChannel:
         entity_resolver: EntityResolver | None = None,
         decay: float = 0.7, activation_threshold: float = 0.05,
         max_hops: int = 4,
+        graph_metrics: dict[str, dict] | None = None,
     ) -> None:
         self._db = db
         self._resolver = entity_resolver
@@ -101,6 +102,9 @@ class EntityGraphChannel:
         self._adj: dict[str, list[tuple[str, float]]] = {}
         self._adj_profile: str = ""  # Track which profile is loaded
         self._adj_edge_count: int = 0  # Track edge count for staleness detection
+        # v3.4.1: Graph intelligence metrics (loaded from fact_importance)
+        self._graph_metrics: dict[str, dict] = graph_metrics or {}
+        self._graph_metrics_profile: str = ""
 
     def _ensure_adjacency(self, profile_id: str) -> None:
         """Load graph adjacency into memory for fast spreading activation.
@@ -133,6 +137,8 @@ class EntityGraphChannel:
         self._adj_edge_count = current_count
         # Also load entity maps (same staleness lifecycle)
         self._load_entity_maps(profile_id)
+        # v3.4.1: Load graph intelligence metrics (P0)
+        self._load_graph_metrics(profile_id)
 
         logger.info(
             "Loaded adjacency cache: %d nodes, %d edges, %d entity mappings for profile %s",
@@ -192,6 +198,37 @@ class EntityGraphChannel:
             len(self._entity_to_facts), len(self._fact_to_entities),
         )
 
+    def _load_graph_metrics(self, profile_id: str) -> None:
+        """Load PageRank, community_id, degree_centrality from fact_importance.
+
+        v3.4.1: Enables graph-enhanced retrieval (P0).
+        Called alongside adjacency loading. Same staleness lifecycle.
+        """
+        if self._graph_metrics_profile == profile_id and self._graph_metrics:
+            return
+        self._graph_metrics = {}
+        self._graph_metrics_profile = profile_id
+        try:
+            rows = self._db.execute(
+                "SELECT fact_id, pagerank_score, community_id, degree_centrality "
+                "FROM fact_importance WHERE profile_id = ?",
+                (profile_id,),
+            )
+            for r in rows:
+                d = dict(r)
+                self._graph_metrics[d["fact_id"]] = {
+                    "pagerank_score": float(d.get("pagerank_score", 0) or 0),
+                    "community_id": d.get("community_id"),
+                    "degree_centrality": float(d.get("degree_centrality", 0) or 0),
+                }
+            logger.info(
+                "Loaded graph metrics: %d facts for profile %s",
+                len(self._graph_metrics), profile_id,
+            )
+        except Exception as exc:
+            logger.debug("Graph metrics load failed (graceful degradation): %s", exc)
+            self._graph_metrics = {}
+
     def invalidate_cache(self) -> None:
         """Clear all caches. Call after adding/removing edges or facts."""
         self._adj.clear()
@@ -199,6 +236,8 @@ class EntityGraphChannel:
         self._adj_edge_count = 0
         self._entity_to_facts = defaultdict(list)
         self._fact_to_entities = defaultdict(list)
+        self._graph_metrics.clear()
+        self._graph_metrics_profile = ""
 
     def search(self, query: str, profile_id: str, top_k: int = 50) -> list[tuple[str, float]]:
         """Search via entity graph with spreading activation.
@@ -242,12 +281,20 @@ class EntityGraphChannel:
             for fid in frontier:
                 if use_cache:
                     neighbors = self._adj.get(fid, ())
-                    for neighbor, _weight in neighbors:
-                        propagated = activation[fid] * self._decay
-                        if propagated >= self._threshold and propagated > activation.get(neighbor, 0.0):
-                            activation[neighbor] = propagated
+                    for neighbor, edge_weight in neighbors:
+                        # v3.4.1 P1: Weighted propagation + PageRank bias
+                        weighted = activation[fid] * self._decay * edge_weight
+                        if self._graph_metrics and neighbor in self._graph_metrics:
+                            target_pr = self._graph_metrics[neighbor].get("pagerank_score", 0.0)
+                            pr_boost = min(1.0 + target_pr * 2.0, 2.0)
+                            weighted *= pr_boost
+                        if weighted >= self._threshold and weighted > activation.get(neighbor, 0.0):
+                            activation[neighbor] = weighted
                             next_frontier.add(neighbor)
                 else:
+                    # NOTE: SQL fallback path does NOT use graph intelligence (P1/P2/P3).
+                    # Graph intelligence is only available on the in-memory cache path.
+                    # This fallback exists for mock/test DBs. See Phase 7 LLD H-01.
                     for edge in self._db.get_edges_for_node(fid, profile_id):
                         neighbor = edge.target_id if edge.source_id == fid else edge.source_id
                         propagated = activation[fid] * self._decay
@@ -282,10 +329,94 @@ class EntityGraphChannel:
             if not frontier:
                 break
 
+        # v3.4.1 P2: Community-aware boosting
+        if self._graph_metrics and use_cache:
+            from collections import Counter as _Counter
+            seed_communities: _Counter = _Counter()
+            for eid in canonical_ids:
+                for fid in self._entity_to_facts.get(eid, ()):
+                    m = self._graph_metrics.get(fid, {})
+                    comm = m.get("community_id")
+                    if comm is not None:
+                        seed_communities[comm] += 1
+            if seed_communities:
+                total_seeds = sum(seed_communities.values())
+                for fid in list(activation.keys()):
+                    m = self._graph_metrics.get(fid, {})
+                    fact_comm = m.get("community_id")
+                    if fact_comm is not None and fact_comm in seed_communities:
+                        boost = min(1.0 + 0.15 * (seed_communities[fact_comm] / total_seeds), 1.3)
+                        activation[fid] *= boost
+                    elif fact_comm is not None and fact_comm not in seed_communities:
+                        activation[fid] *= 0.9  # Mild penalty for unrelated communities
+
+        # v3.4.1 P3: Contradiction suppression via graph_edges
+        if use_cache and activation:
+            self._suppress_contradictions(activation, profile_id)
+
+        # v3.4.1: Score normalization to [0, 1]
         results = [(fid, sc) for fid, sc in activation.items() if sc >= self._threshold]
+        if not results:
+            return []
+        max_score = max(sc for _, sc in results)
+        if max_score > 0:
+            results = [(fid, sc / max_score) for fid, sc in results]
         results.sort(key=lambda x: x[1], reverse=True)
         return results[:top_k]
 
+    def _suppress_contradictions(
+        self, activation: dict[str, float], profile_id: str,
+    ) -> None:
+        """P3: Penalize older fact in contradiction pairs, heavy-penalize superseded.
+
+        Uses graph_edges (edge_type CHECK includes 'contradiction', 'supersedes').
+        """
+        candidate_ids = list(activation.keys())
+        if not candidate_ids:
+            return
+        try:
+            placeholders = ",".join("?" * len(candidate_ids))
+            sql = (
+                "SELECT source_id, target_id, edge_type FROM graph_edges "
+                "WHERE profile_id = ? AND edge_type IN ('contradiction', 'supersedes') "
+                "AND (source_id IN (" + placeholders + ") "
+                "OR target_id IN (" + placeholders + "))"
+            )
+            rows = self._db.execute(sql, (profile_id, *candidate_ids, *candidate_ids))
+            edges = [dict(r) for r in rows]
+            if not edges:
+                return
+
+            # Batch load created_at for involved facts
+            involved = set()
+            for e in edges:
+                involved.add(e["source_id"])
+                involved.add(e["target_id"])
+            involved = involved & set(candidate_ids)
+            if not involved:
+                return
+            ph2 = ",".join("?" * len(involved))
+            ts_rows = self._db.execute(
+                "SELECT fact_id, created_at FROM atomic_facts "
+                "WHERE fact_id IN (" + ph2 + ") AND profile_id = ?",
+                (*involved, profile_id),
+            )
+            ts_map = {dict(r)["fact_id"]: dict(r).get("created_at", "") for r in ts_rows}
+
+            for e in edges:
+                src, tgt, etype = e["source_id"], e["target_id"], e["edge_type"]
+                if etype == "supersedes" and src in activation:
+                    activation[src] *= 0.3  # Heavy penalty: this fact was replaced
+                elif etype == "contradiction":
+                    src_ts = ts_map.get(src, "")
+                    tgt_ts = ts_map.get(tgt, "")
+                    if src_ts and tgt_ts:
+                        older = src if src_ts < tgt_ts else tgt
+                        if older in activation:
+                            activation[older] *= 0.5
+        except Exception as exc:
+            logger.debug("Contradiction suppression failed: %s", exc)
+
     def _resolve_entities(self, raw: list[str], profile_id: str) -> list[str]:
         """Resolve raw names to canonical entity IDs."""
         ids: list[str] = []

package/src/superlocalmemory/retrieval/spreading_activation.py

@@ -53,6 +53,9 @@ class SpreadingActivationConfig:
     max_iterations: int = 3      # T: propagation depth
     tau_gate: float = 0.05       # FOK confidence gate (was 0.12)
     enabled: bool = True         # Ships enabled by default
+    # v3.4.1: Graph intelligence integration
+    use_pagerank_bias: bool = False    # Multiply propagation by target PageRank
+    community_boost: float = 0.0       # Boost same-community nodes (0.0 = disabled)
 
 
 # ---------------------------------------------------------------------------
@@ -82,6 +85,11 @@ class SpreadingActivation:
         self._db = db
         self._vector_store = vector_store
         self._config = config or SpreadingActivationConfig()
+        # v3.4.1: Graph intelligence caches (loaded lazily per profile)
+        self._pr_cache: dict[str, float] = {}
+        self._pr_profile: str = ""
+        self._comm_cache: dict[str, int | None] = {}
+        self._comm_profile: str = ""
 
     def search(
         self,
@@ -311,3 +319,40 @@ class SpreadingActivation:
             return len(result) if result else 0
         except Exception:
             return 0
+
+    # ── v3.4.1: Graph Intelligence Helpers ────────────────────────
+
+    def _load_graph_metrics_cache(self, profile_id: str) -> None:
+        """Load PageRank + community data in a single SQL query.
+
+        Called lazily on first _get_pagerank() or _get_community() call.
+        Populates both _pr_cache and _comm_cache.
+        """
+        if self._pr_profile == profile_id and self._pr_cache:
+            return  # Already loaded for this profile
+        self._pr_cache = {}
+        self._pr_profile = profile_id
+        self._comm_cache = {}
+        self._comm_profile = profile_id
+        try:
+            rows = self._db.execute(
+                "SELECT fact_id, pagerank_score, community_id "
+                "FROM fact_importance WHERE profile_id = ?",
+                (profile_id,),
+            )
+            for r in rows:
+                d = dict(r)
+                self._pr_cache[d["fact_id"]] = float(d.get("pagerank_score", 0) or 0)
+                self._comm_cache[d["fact_id"]] = d.get("community_id")
+        except Exception:
+            pass
+
+    def _get_pagerank(self, fact_id: str, profile_id: str) -> float:
+        """Look up PageRank score from fact_importance. Cached per profile."""
+        self._load_graph_metrics_cache(profile_id)
+        return self._pr_cache.get(fact_id, 0.0)
+
+    def _get_community(self, fact_id: str, profile_id: str) -> int | None:
+        """Look up community_id from fact_importance. Shares unified cache."""
+        self._load_graph_metrics_cache(profile_id)
+        return self._comm_cache.get(fact_id)

package/src/superlocalmemory/server/api.py

@@ -176,8 +176,16 @@ def create_app() -> FastAPI:
     application.include_router(ws_router)
     application.include_router(v3_router)
 
+    # v3.4.1: Chat SSE endpoint
+    for _module_name_v341 in ("chat",):
+        try:
+            _mod_v341 = __import__(f"superlocalmemory.server.routes.{_module_name_v341}", fromlist=["router"])
+            application.include_router(_mod_v341.router)
+        except (ImportError, Exception):
+            pass
+
     # Graceful optional routers
-    for _module_name in ("learning", "lifecycle", "behavioral", "compliance"):
+    for _module_name in ("learning", "lifecycle", "behavioral", "compliance", "insights", "timeline"):
         try:
             _mod = __import__(f"superlocalmemory.server.routes.{_module_name}", fromlist=["router"])
             application.include_router(_mod.router)