surreal-memory 2.7.2__tar.gz → 2.7.3__tar.gz

{surreal_memory-2.7.2 → surreal_memory-2.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-memory
-Version: 2.7.2
+Version: 2.7.3
 Summary: Reflex-based memory system for AI agents with SurrealDB backend — retrieval through activation, not search
 Project-URL: Homepage, https://github.com/acidkill/surreal-memory
 Project-URL: Documentation, https://github.com/acidkill/surreal-memory/blob/main/docs/getting-started/quickstart.md

{surreal_memory-2.7.2 → surreal_memory-2.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "surreal-memory"
-version = "2.7.2"
+version = "2.7.3"
 description = "Reflex-based memory system for AI agents with SurrealDB backend — retrieval through activation, not search"
 readme = "README.md"
 license = "MIT"

{surreal_memory-2.7.2 → surreal_memory-2.7.3}/src/surreal_memory/__init__.py

@@ -16,7 +16,7 @@ from surreal_memory.engine.encoder import EncodingResult, MemoryEncoder
 from surreal_memory.engine.reflex_activation import CoActivation, ReflexActivation
 from surreal_memory.engine.retrieval import DepthLevel, ReflexPipeline, RetrievalResult
 
-__version__ = "2.7.2"
+__version__ = "2.7.3"
 
 __all__ = [
     "__version__",

{surreal_memory-2.7.2 → surreal_memory-2.7.3}/src/surreal_memory/engine/diagnostics.py

@@ -7,6 +7,7 @@ Supports both MCP and CLI exposure.
 
 from __future__ import annotations
 
+import asyncio
 import math
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
@@ -322,8 +323,14 @@ class DiagnosticsEngine:
         if hasattr(self._storage, "set_brain"):
             self._storage.set_brain(brain_id)
 
-        # Gather base data
-        enhanced = await self._storage.get_enhanced_stats(brain_id)
+        # Gather base data. Skip the neuron-type breakdown — it is the priciest
+        # query on a large brain (~2.6 s / 64k neurons) and none of the health
+        # metrics below read it. Backends whose get_enhanced_stats predates the
+        # flag fall back to the full call.
+        try:
+            enhanced = await self._storage.get_enhanced_stats(brain_id, include_neuron_types=False)
+        except TypeError:
+            enhanced = await self._storage.get_enhanced_stats(brain_id)
         neuron_count: int = enhanced.get("neuron_count", 0)
         synapse_count: int = enhanced.get("synapse_count", 0)
         fiber_count: int = enhanced.get("fiber_count", 0)
@@ -335,15 +342,26 @@ class DiagnosticsEngine:
         # Compute individual metrics
         synapse_stats = enhanced.get("synapse_stats", {})
 
-        # Fetch fibers once for freshness + diagnostics
-        fibers = await self._storage.get_fibers(limit=10000)
+        # The remaining DB-bound reads are independent, so run them concurrently
+        # rather than serially (measured ~1.6x on the shared HTTP connection).
+        # orphan-rate needs both fibers and the connected-neuron set, so fetch
+        # the set here and hand it in (avoids a second scan inside the compute).
+        get_connected = getattr(self._storage, "get_connected_neuron_ids", None)
+
+        async def _connected_or_none() -> set[str] | None:
+            return await get_connected() if get_connected is not None else None
+
+        fibers, consolidation_ratio, activation_efficiency, connected = await asyncio.gather(
+            self._storage.get_fibers(limit=10000),
+            self._compute_consolidation_ratio(fiber_count),
+            self._compute_activation_efficiency(neuron_count),
+            _connected_or_none(),
+        )
 
         connectivity = self._compute_connectivity(synapse_count, neuron_count)
         diversity = self._compute_diversity(synapse_stats)
         freshness = self._compute_freshness(fibers)
-        consolidation_ratio = await self._compute_consolidation_ratio(fiber_count)
-        orphan_rate = await self._compute_orphan_rate(neuron_count, fibers)
-        activation_efficiency = await self._compute_activation_efficiency(neuron_count)
+        orphan_rate = await self._compute_orphan_rate(neuron_count, fibers, connected=connected)
         recall_confidence = self._compute_recall_confidence(synapse_stats)
 
         # Compute purity score
@@ -500,7 +518,10 @@ class DiagnosticsEngine:
         return len(semantic_records) / fiber_count
 
     async def _compute_orphan_rate(
-        self, neuron_count: int, fibers: list[Any] | None = None
+        self,
+        neuron_count: int,
+        fibers: list[Any] | None = None,
+        connected: set[str] | None = None,
     ) -> float:
         """Compute fraction of neurons with no synapses AND no fiber membership.
 
@@ -513,16 +534,21 @@ class DiagnosticsEngine:
         if neuron_count == 0:
             return 0.0
 
-        # Prefer the DB-side distinct-endpoints aggregate over loading ~185k
-        # Synapse objects (that scan was seconds of the dashboard's slowness).
-        get_connected = getattr(self._storage, "get_connected_neuron_ids", None)
-        if get_connected is not None:
-            connected: set[str] = set(await get_connected())
+        # The caller may hand in the connected-neuron set (computed concurrently
+        # with the other reads). Otherwise fetch it: prefer the DB-side
+        # distinct-endpoints aggregate over loading ~185k Synapse objects (that
+        # scan was seconds of the dashboard's slowness).
+        if connected is None:
+            get_connected = getattr(self._storage, "get_connected_neuron_ids", None)
+            if get_connected is not None:
+                connected = set(await get_connected())
+            else:
+                connected = set()
+                for s in await self._storage.get_all_synapses():
+                    connected.add(s.source_id)
+                    connected.add(s.target_id)
         else:
-            connected = set()
-            for s in await self._storage.get_all_synapses():
-                connected.add(s.source_id)
-                connected.add(s.target_id)
+            connected = set(connected)
 
         # Also count neurons that belong to fibers as connected
         if fibers:

{surreal_memory-2.7.2 → surreal_memory-2.7.3}/src/surreal_memory/server/routes/dashboard_api.py

@@ -91,42 +91,51 @@ async def get_stats() -> DashboardStats:
     active_name = cfg.current_brain
 
     async def _analyze_brain(name: str) -> BrainSummary:
-        """Analyze a single brain using its own per-brain storage."""
+        """Summarize a single brain.
+
+        Only the ACTIVE brain gets the full DiagnosticsEngine.analyze (grade +
+        purity); every other brain returns just its counts. The overview shows
+        the active brain's grade at the top (health_grade) and the per-brain
+        grade has its own home (the /brains endpoint + the Health page), so
+        running the multi-second analyze for every brain was pure waste — a
+        station carrying integration-test residue brains paid a full diagnostic
+        pass for each of them on every overview load.
+        """
+        is_active = name == active_name
         try:
             brain_storage = await get_shared_storage(brain_name=name)
 
-            grade = "F"
-            purity = 0.0
-            nc = sc = fc = 0
-            try:
-                from surreal_memory.engine.diagnostics import DiagnosticsEngine
-
-                diag = DiagnosticsEngine(brain_storage)
-                report = await diag.analyze(name)
-                grade = report.grade
-                purity = report.purity_score
-                # The report already carries the counts (via get_enhanced_stats),
-                # so a separate get_stats here would just repeat the same three
-                # count queries per brain.
-                nc = report.neuron_count
-                sc = report.synapse_count
-                fc = report.fiber_count
-            except Exception:
-                logger.debug("Diagnostics failed for brain %s", name, exc_info=True)
-                stats = await brain_storage.get_stats(name)
-                nc = stats.get("neuron_count", 0)
-                sc = stats.get("synapse_count", 0)
-                fc = stats.get("fiber_count", 0)
+            if is_active:
+                try:
+                    from surreal_memory.engine.diagnostics import DiagnosticsEngine
+
+                    diag = DiagnosticsEngine(brain_storage)
+                    report = await diag.analyze(name)
+                    return BrainSummary(
+                        id=name,
+                        name=name,
+                        neuron_count=report.neuron_count,
+                        synapse_count=report.synapse_count,
+                        fiber_count=report.fiber_count,
+                        grade=report.grade,
+                        purity_score=report.purity_score,
+                        is_active=True,
+                    )
+                except Exception:
+                    logger.debug("Diagnostics failed for active brain %s", name, exc_info=True)
 
+            # Inactive brain (or active-brain diagnostics failure): counts only.
+            # "—" flags grade as "not computed here" rather than a real F.
+            stats = await brain_storage.get_stats(name)
             return BrainSummary(
                 id=name,
                 name=name,
-                neuron_count=nc,
-                synapse_count=sc,
-                fiber_count=fc,
-                grade=grade,
-                purity_score=purity,
-                is_active=name == active_name,
+                neuron_count=stats.get("neuron_count", 0),
+                synapse_count=stats.get("synapse_count", 0),
+                fiber_count=stats.get("fiber_count", 0),
+                grade="F" if is_active else "—",
+                purity_score=0.0,
+                is_active=is_active,
             )
         except Exception:
             # Surface at WARNING (not debug): swallowing this silently made the
@@ -134,7 +143,7 @@ async def get_stats() -> DashboardStats:
             # storage/config misconfiguration. Keep returning a placeholder so
             # one bad brain does not break the whole dashboard.
             logger.warning("Brain analysis failed for %s", name, exc_info=True)
-            return BrainSummary(id=name, name=name, is_active=name == active_name)
+            return BrainSummary(id=name, name=name, is_active=is_active)
 
     # Analyze brains sequentially, NOT via asyncio.gather: the SurrealDB backend
     # shares one storage singleton with a mutable current-brain pointer, so

{surreal_memory-2.7.2 → surreal_memory-2.7.3}/src/surreal_memory/storage/base.py

@@ -712,7 +712,9 @@ class NeuralStorage(ABC):
         ...
 
     @abstractmethod
-    async def get_enhanced_stats(self, brain_id: str) -> dict[str, Any]:
+    async def get_enhanced_stats(
+        self, brain_id: str, include_neuron_types: bool = True
+    ) -> dict[str, Any]:
         """
         Get enhanced statistics for a brain.
 

{surreal_memory-2.7.2 → surreal_memory-2.7.3}/src/surreal_memory/storage/factory.py

@@ -308,8 +308,12 @@ class HybridStorage:
     async def get_stats(self, brain_id: str) -> dict[str, int]:
         return await self._local.get_stats(brain_id)
 
-    async def get_enhanced_stats(self, brain_id: str) -> dict[str, Any]:
-        return await self._local.get_enhanced_stats(brain_id)
+    async def get_enhanced_stats(
+        self, brain_id: str, include_neuron_types: bool = True
+    ) -> dict[str, Any]:
+        return await self._local.get_enhanced_stats(
+            brain_id, include_neuron_types=include_neuron_types
+        )
 
     async def clear(self, brain_id: str) -> None:
         await self._local.clear(brain_id)

{surreal_memory-2.7.2 → surreal_memory-2.7.3}/src/surreal_memory/storage/memory_store.py

@@ -421,7 +421,9 @@ class InMemoryStorage(
             "project_count": len(self._projects[brain_id]),
         }
 
-    async def get_enhanced_stats(self, brain_id: str) -> dict[str, Any]:
+    async def get_enhanced_stats(
+        self, brain_id: str, include_neuron_types: bool = True
+    ) -> dict[str, Any]:
         basic_stats = await self.get_stats(brain_id)
 
         # Hot neurons by access frequency

{surreal_memory-2.7.2 → surreal_memory-2.7.3}/src/surreal_memory/storage/shared_store.py

@@ -425,7 +425,9 @@ class SharedStorage(SharedFiberBrainMixin, NeuralStorage):
             "fiber_count": result.get("fiber_count", 0),
         }
 
-    async def get_enhanced_stats(self, brain_id: str) -> dict[str, Any]:
+    async def get_enhanced_stats(
+        self, brain_id: str, include_neuron_types: bool = True
+    ) -> dict[str, Any]:
         """Get enhanced brain statistics via API."""
         result = await self._request("GET", f"/brain/{brain_id}/stats")
         return result

{surreal_memory-2.7.2 → surreal_memory-2.7.3}/src/surreal_memory/storage/sqlite_store.py

@@ -224,7 +224,9 @@ class SQLiteStorage(
                 "project_count": row["project_count"] if row else 0,
             }
 
-    async def get_enhanced_stats(self, brain_id: str) -> dict[str, Any]:
+    async def get_enhanced_stats(
+        self, brain_id: str, include_neuron_types: bool = True
+    ) -> dict[str, Any]:
         conn = self._ensure_read_conn()
         basic_stats = await self.get_stats(brain_id)
 

{surreal_memory-2.7.2 → surreal_memory-2.7.3}/src/surreal_memory/storage/surrealdb/store.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import asyncio
 import dataclasses
 import logging
+import re
 from datetime import datetime
 from hashlib import sha256
 from typing import Any, Literal
@@ -96,6 +97,24 @@ def _to_surreal_id(record_id: str) -> str:
     return record_id.replace("-", "_")
 
 
+_BRAIN_ID_SAFE = re.compile(r"^[a-zA-Z0-9_.\-]+$")
+
+
+def _brain_literal(brain_id: str) -> str:
+    """Return ``brain_id`` as a safe inline SurrealQL string literal.
+
+    SurrealDB 3.2.0's planner only uses the ``brain_id`` index when the value is
+    an inline literal — a parameterized ``WHERE brain_id = $bid`` falls back to a
+    full table scan. On the 64k-neuron table (each row carrying a 1024-float
+    vector) that turned ``count() … GROUP ALL`` from 0.01 s into ~2.5 s, and it
+    was the single biggest cost behind the dashboard's stats endpoint. brain_id
+    is validated to a strict charset, so inlining it is injection-safe.
+    """
+    if not _BRAIN_ID_SAFE.match(brain_id):
+        raise ValueError(f"unsafe brain_id for inline query: {brain_id!r}")
+    return f'"{brain_id}"'
+
+
 def _from_surreal_id(surreal_id: str) -> str:
     """Extract the original ID from a SurrealDB record ID like 'neuron:abc_def'."""
     if ":" in surreal_id:
@@ -1430,17 +1449,14 @@ class SurrealDBStorage(
     # ================================================================
 
     async def get_stats(self, brain_id: str) -> dict[str, int]:
-        neuron_rows = await self._query(
-            "SELECT count() AS c FROM neuron WHERE brain_id = $bid GROUP ALL",
-            bid=brain_id,
-        )
-        synapse_rows = await self._query(
-            "SELECT count() AS c FROM synapse WHERE brain_id = $bid GROUP ALL",
-            bid=brain_id,
-        )
-        fiber_rows = await self._query(
-            "SELECT count() AS c FROM fiber WHERE brain_id = $bid GROUP ALL",
-            bid=brain_id,
+        # Inline the (validated) brain_id so the count() aggregates use the
+        # brain_id index instead of a full scan — see _brain_literal. The three
+        # scans are independent, so run them concurrently.
+        lit = _brain_literal(brain_id)
+        neuron_rows, synapse_rows, fiber_rows = await asyncio.gather(
+            self._query(f"SELECT count() AS c FROM neuron WHERE brain_id = {lit} GROUP ALL"),
+            self._query(f"SELECT count() AS c FROM synapse WHERE brain_id = {lit} GROUP ALL"),
+            self._query(f"SELECT count() AS c FROM fiber WHERE brain_id = {lit} GROUP ALL"),
         )
 
         def _count(rows: list[Any]) -> int:
@@ -1454,15 +1470,22 @@ class SurrealDBStorage(
             "fiber_count": _count(fiber_rows),
         }
 
-    async def get_enhanced_stats(self, brain_id: str) -> dict[str, Any]:
+    async def get_enhanced_stats(
+        self, brain_id: str, include_neuron_types: bool = True
+    ) -> dict[str, Any]:
         stats = await self.get_stats(brain_id)
 
-        # Neuron type breakdown
-        type_rows = await self._query(
-            "SELECT type, count() AS c FROM neuron WHERE brain_id = $bid GROUP BY type",
-            bid=brain_id,
-        )
-        type_counts = {str(r.get("type", "unknown")): int(r.get("c", 0)) for r in type_rows}
+        # Neuron type breakdown. This GROUP BY over the whole neuron table is the
+        # single most expensive query on a large brain (~2.6 s for 64k neurons)
+        # and DiagnosticsEngine never reads it — so callers that only need the
+        # health metrics pass include_neuron_types=False to skip it entirely.
+        type_counts: dict[str, int] = {}
+        if include_neuron_types:
+            type_rows = await self._query(
+                "SELECT type, count() AS c FROM neuron WHERE brain_id = $bid GROUP BY type",
+                bid=brain_id,
+            )
+            type_counts = {str(r.get("type", "unknown")): int(r.get("c", 0)) for r in type_rows}
 
         # Synapse stats by type — required by DiagnosticsEngine for diversity
         # (Shannon entropy over by_type counts) and recall_confidence (avg_weight).
@@ -2084,14 +2107,20 @@ class SurrealDBStorage(
         replaces loading ~185k Synapse objects (~10 s) for the orphan-rate metric
         with two distinct-key scans (~2 s total)."""
         bid = brain_id or self._get_brain_id()
-        connected: set[str] = set()
-        for field in ("in", "out"):
-            rows = await self._query(
+
+        async def _endpoints(field: str) -> list[Any]:
+            return await self._query(
                 f"SELECT VALUE {field} FROM synapse WHERE brain_id = $bid GROUP BY {field}",
                 bid=bid,
             )
-            for rid in rows:
-                connected.add(_from_surreal_id(str(rid)))
+
+        # The two distinct-endpoint scans are independent, so run them
+        # concurrently — on a large brain this ~halves the wall time (measured
+        # 2.5 s -> ~1.3 s) versus scanning in then out.
+        in_rows, out_rows = await asyncio.gather(_endpoints("in"), _endpoints("out"))
+        connected: set[str] = set()
+        for rid in (*in_rows, *out_rows):
+            connected.add(_from_surreal_id(str(rid)))
         return connected
 
     async def get_synapse_degrees(self, brain_id: str | None = None) -> dict[str, int]:
@@ -2102,17 +2131,21 @@ class SurrealDBStorage(
         real ``in``/``out`` record links — the ``source_id``/``target_id``
         fields are computed and do not aggregate."""
         bid = brain_id or self._get_brain_id()
-        degree: dict[str, int] = {}
-        for field in ("in", "out"):
-            rows = await self._query(
+
+        async def _degree(field: str) -> list[Any]:
+            return await self._query(
                 f"SELECT {field} AS nid, count() AS deg FROM synapse"
                 f" WHERE brain_id = $bid GROUP BY {field}",
                 bid=bid,
             )
-            for r in rows:
-                nid = _endpoint_to_id(r.get("nid"))
-                if nid:
-                    degree[nid] = degree.get(nid, 0) + int(r.get("deg", 0) or 0)
+
+        # The in/out degree scans are independent — run them concurrently.
+        in_rows, out_rows = await asyncio.gather(_degree("in"), _degree("out"))
+        degree: dict[str, int] = {}
+        for r in (*in_rows, *out_rows):
+            nid = _endpoint_to_id(r.get("nid"))
+            if nid:
+                degree[nid] = degree.get(nid, 0) + int(r.get("deg", 0) or 0)
         return degree
 
     async def get_edges_for_neurons(self, neuron_ids: list[str]) -> list[Synapse]: