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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-memory
-Version: 2.7.2
+Version: 2.7.4
 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.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "surreal-memory"
-version = "2.7.2"
+version = "2.7.4"
 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.4}/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.4"
 
 __all__ = [
     "__version__",

{surreal_memory-2.7.2 → surreal_memory-2.7.4}/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.4}/src/surreal_memory/server/app.py

@@ -14,6 +14,7 @@ from fastapi.responses import FileResponse, RedirectResponse, Response
 from fastapi.staticfiles import StaticFiles
 
 from surreal_memory import __version__
+from surreal_memory.server.dashboard_cache import TTLCache
 from surreal_memory.server.models import HealthResponse, ReadyResponse
 from surreal_memory.server.routes import (
     brain_router,
@@ -32,6 +33,12 @@ from surreal_memory.storage.sqlite_schema import SCHEMA_VERSION
 # Static files directory
 STATIC_DIR = Path(__file__).parent / "static"
 
+# The graph view aggregates degree over the whole synapse graph + fetches the
+# dense core's nodes/edges — a few seconds on a large brain. The graph structure
+# is slow-moving, so cache the built payload per (brain, limit, offset) for a
+# short window (see dashboard_cache).
+_GRAPH_CACHE = TTLCache()
+
 
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
@@ -586,6 +593,19 @@ def create_app(
         capped_limit = min(limit, 2000)
         edge_cap = 4000
 
+        # Serve a recently-built graph for this (brain, limit, offset) from cache.
+        _brain_id = "default"
+        _get_bid = getattr(storage, "_get_brain_id", None)
+        if _get_bid is not None:
+            try:
+                _brain_id = _get_bid()
+            except Exception:
+                pass
+        _cache_key = f"graph:{_brain_id}:{limit}:{offset}"
+        _cached_graph = _GRAPH_CACHE.get(_cache_key)
+        if _cached_graph is not None:
+            return dict(_cached_graph)
+
         # Degree ranking + edge fetch via DB aggregates/graph traversal when the
         # backend supports it (SurrealDB). Loading all ~185k synapses into Python
         # just to rank/filter them was ~10 s of the graph view's 30 s+ hang.
@@ -636,7 +656,7 @@ def create_app(
 
         fibers = await storage.get_fibers(limit=1000)
 
-        return {
+        payload = {
             "neurons": [
                 {
                     "id": n.id,
@@ -673,6 +693,8 @@ def create_app(
                 "fiber_count": len(fibers),
             },
         }
+        _GRAPH_CACHE.set(_cache_key, payload)
+        return payload
 
     # React SPA dist directory
     spa_dist = STATIC_DIR / "dist"

surreal_memory-2.7.4/src/surreal_memory/server/dashboard_cache.py

@@ -0,0 +1,82 @@
+"""Tiny TTL cache for the expensive dashboard reads.
+
+The overview grade/purity (a full ``DiagnosticsEngine.analyze``) and the graph
+view are inherently a few seconds each on a large brain — they aggregate over
+hundreds of thousands of synapses (``GROUP BY`` scans that no index removes).
+But these are *slow-moving quality/structure* views: the health grade barely
+shifts between two page loads seconds apart, and neither does a 64k-node graph.
+
+So instead of recomputing on every request, cache the result per brain for a
+short window. Repeat loads (the common case — the dashboard auto-refreshes and
+users navigate back and forth) are served instantly; the value is recomputed at
+most once per TTL. Counts (neuron/synapse/fiber) are cheap and are NOT cached
+here — the overview keeps them live.
+
+TTL is read from ``SURREAL_MEMORY_DASHBOARD_CACHE_TTL`` (seconds); set it to 0 to
+disable caching entirely (every request recomputes).
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable
+from typing import Any
+
+_DEFAULT_TTL_SECONDS = 60.0
+
+
+def _configured_ttl() -> float:
+    raw = os.environ.get("SURREAL_MEMORY_DASHBOARD_CACHE_TTL")
+    if raw is None or raw == "":
+        return _DEFAULT_TTL_SECONDS
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return _DEFAULT_TTL_SECONDS
+
+
+class TTLCache:
+    """A minimal, single-process TTL cache.
+
+    Entries expire ``ttl`` seconds after they are written. A ttl of 0 disables
+    the cache (``get`` always misses, ``set`` is a no-op) so it can be turned off
+    without touching call sites. The clock is injectable for deterministic tests.
+    """
+
+    def __init__(
+        self,
+        ttl: float | None = None,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._ttl = _configured_ttl() if ttl is None else max(0.0, ttl)
+        self._clock = clock
+        self._store: dict[str, tuple[float, Any]] = {}
+
+    @property
+    def enabled(self) -> bool:
+        return self._ttl > 0
+
+    def get(self, key: str) -> Any | None:
+        if not self.enabled:
+            return None
+        entry = self._store.get(key)
+        if entry is None:
+            return None
+        written_at, value = entry
+        if self._clock() - written_at > self._ttl:
+            self._store.pop(key, None)
+            return None
+        return value
+
+    def set(self, key: str, value: Any) -> None:
+        if not self.enabled:
+            return
+        self._store[key] = (self._clock(), value)
+
+    def invalidate(self, key: str) -> None:
+        self._store.pop(key, None)
+
+    def clear(self) -> None:
+        self._store.clear()

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

@@ -9,11 +9,33 @@ from typing import Annotated, Any
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from pydantic import BaseModel, Field
 
+from surreal_memory.server.dashboard_cache import TTLCache
 from surreal_memory.server.dependencies import get_storage, require_local_request
 from surreal_memory.storage.base import NeuralStorage
 
 logger = logging.getLogger(__name__)
 
+# Full diagnostics (grade/purity) aggregates over the whole synapse graph — a few
+# seconds on a large brain. The grade is slow-moving, so cache it per brain for a
+# short window; the overview's counts are computed live (cheap) around it.
+_GRADE_CACHE = TTLCache()
+
+
+async def _cached_grade_purity(storage: NeuralStorage, brain_name: str) -> tuple[str, float]:
+    """Return (grade, purity) for a brain, cached per brain for the TTL window."""
+    key = f"grade:{brain_name}"
+    cached = _GRADE_CACHE.get(key)
+    if cached is not None:
+        grade, purity = cached
+        return str(grade), float(purity)
+    from surreal_memory.engine.diagnostics import DiagnosticsEngine
+
+    report = await DiagnosticsEngine(storage).analyze(brain_name)
+    result = (report.grade, report.purity_score)
+    _GRADE_CACHE.set(key, result)
+    return result
+
+
 router = APIRouter(
     prefix="/api/dashboard",
     tags=["dashboard"],
@@ -91,42 +113,42 @@ 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"
+            # Counts are cheap (indexed count()) — always compute them live so the
+            # neuron/synapse/fiber numbers are never stale.
+            stats = await brain_storage.get_stats(name)
+            grade = "—"
             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:
+                # Grade/purity is the multi-second part — served from the per-brain
+                # TTL cache (recomputed at most once per window).
+                try:
+                    grade, purity = await _cached_grade_purity(brain_storage, name)
+                except Exception:
+                    logger.debug("Diagnostics failed for active brain %s", name, exc_info=True)
+                    grade = "F"
             return BrainSummary(
                 id=name,
                 name=name,
-                neuron_count=nc,
-                synapse_count=sc,
-                fiber_count=fc,
+                neuron_count=stats.get("neuron_count", 0),
+                synapse_count=stats.get("synapse_count", 0),
+                fiber_count=stats.get("fiber_count", 0),
                 grade=grade,
                 purity_score=purity,
-                is_active=name == active_name,
+                is_active=is_active,
             )
         except Exception:
             # Surface at WARNING (not debug): swallowing this silently made the
@@ -134,7 +156,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.4}/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.4}/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.4}/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.4}/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.4}/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.4}/src/surreal_memory/storage/surrealdb/schema.py

@@ -14,6 +14,12 @@ SCHEMA_SQL = """
 -- Surreal-Memory SurrealDB Schema
 -- ============================================================
 
+-- Full-text analyzer for neuron.content search (the @@ operator). Defined
+-- before the index that uses it. Tokenizes on whitespace/class and lowercases,
+-- so keyword/entity lookups become case-insensitive and index-backed instead of
+-- full-scanning with CONTAINS.
+DEFINE ANALYZER IF NOT EXISTS smem_content TOKENIZERS blank, class FILTERS lowercase, ascii;
+
 -- Neurons (primary memory units)
 DEFINE TABLE neuron SCHEMAFULL;
 DEFINE FIELD id              ON neuron TYPE string;
@@ -36,6 +42,7 @@ DEFINE INDEX idx_neuron_brain    ON neuron FIELDS brain_id;
 DEFINE INDEX idx_neuron_type     ON neuron FIELDS brain_id, type;
 DEFINE INDEX idx_neuron_hash     ON neuron FIELDS brain_id, content_hash;
 DEFINE INDEX idx_neuron_content  ON neuron FIELDS brain_id, content;
+DEFINE INDEX IF NOT EXISTS idx_neuron_content_fts ON neuron FIELDS content FULLTEXT ANALYZER smem_content BM25;
 -- idx_neuron_embedding (HNSW) is defined dynamically in ensure_schema() with the
 -- configured embedding dimension, so the vector index always matches the model.