superlocalmemory 3.4.38 → 3.4.40

package/CHANGELOG.md

@@ -6,7 +6,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### [Unreleased]
-- **License:** Changed from Elastic-2.0 to AGPL-3.0-or-later to protect research IP
+
+---
+
+## [3.4.40] - 2026-05-09
+
+Recall performance and entity-profile hygiene. Two scaling issues surfaced
+on dense graphs: spreading-activation fan-out grew unbounded as graphs
+exceeded the previous calibration target, and `entity_profiles.knowledge_summary`
+grew unbounded via concatenation. This release bounds both, adds an opt-in
+`--fast` recall mode, and increases the query embedding cache.
+
+### Added
+- **`slm recall --fast`** — skips the spreading-activation channel for
+  faster response. The other four channels (semantic, BM25, temporal,
+  hopfield) still run. Use when an agent needs recall before another
+  tool call. Plumbed via a new `extra_disabled_channels` parameter through
+  CLI → daemon `/recall` → `MemoryEngine.recall` → `run_recall` →
+  `RetrievalEngine.recall`.
+
+### Changed
+- **Spreading-activation fan-out is bounded.** `_get_unified_neighbors`
+  now applies `ORDER BY weight DESC LIMIT max_neighbors_per_node`
+  (default 100). High-degree nodes previously expanded every neighbor
+  every iteration. Bounded fan-out matches the SYNAPSE paper's
+  sparse-graph assumption while preserving the highest-weight edges.
+- **`SpreadingActivationConfig.top_m`: 20 → 10.** Compromise between the
+  SYNAPSE default (7) and the prior dense-graph tuning (20).
+- **`ObservationBuilder._build_summary` is now bounded.** Last 10 facts
+  (was 20), 200-char cap per fact, 2048-char total cap. Previously
+  `knowledge_summary` grew via concatenation and could exceed tens of
+  KB on hub entities, polluting recall with stale text.
+- **Query embedding LRU cache: 64 → 512 entries.** Sub-millisecond cache
+  hits versus a 200–2000 ms embedding call. Memory cost is ≈1.5 MB.
+
+### Maintenance
+- `run_maintenance` now consolidates over-bound entity summaries via a
+  single SQL update on the existing scheduler interval.
+
+### Tests
+- 399/399 retrieval + encoding suite passing.
+- 12/12 spreading-activation unit tests passing.
+
+### Upgrade notes
+- Existing deployments with bloated `entity_profiles.knowledge_summary`
+  rows will see them truncated on the next `slm consolidate` or
+  scheduled maintenance run. The truncation is in-place; entity
+  identity and `fact_count` are preserved.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.4.38",
+  "version": "3.4.40",
   "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.4.38"
+version = "3.4.40"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}

package/src/superlocalmemory/__init__.py

@@ -1,3 +1,3 @@
 """SuperLocalMemory — information-geometric agent memory."""
 
-__version__ = "3.4.38"
+__version__ = "3.4.39"

package/src/superlocalmemory/cli/commands.py

@@ -905,10 +905,11 @@ def cmd_recall(args: Namespace) -> None:
         if is_daemon_running() or ensure_daemon():
             from urllib.parse import quote
             session_id = f"cli:{os.getppid()}"
+            fast_qs = "&fast=true" if getattr(args, "fast", False) else ""
             result = daemon_request(
                 "GET",
                 f"/recall?q={quote(args.query)}&limit={args.limit}"
-                f"&session_id={quote(session_id)}",
+                f"&session_id={quote(session_id)}{fast_qs}",
             )
             if result and "results" in result:
                 # Format daemon response same as engine response
@@ -937,7 +938,10 @@ def cmd_recall(args: Namespace) -> None:
         engine = MemoryEngine(config)
         engine.initialize()
 
-        response = engine.recall(args.query, limit=args.limit)
+        response = engine.recall(
+            args.query, limit=args.limit,
+            fast=getattr(args, "fast", False),
+        )
     except Exception as exc:
         if use_json:
             from superlocalmemory.cli.json_output import json_print

package/src/superlocalmemory/cli/main.py

@@ -187,6 +187,12 @@ def main() -> None:
     recall_p.add_argument("query", help="Search query")
     recall_p.add_argument("--limit", type=int, default=10, help="Max results (default 10)")
     recall_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
+    recall_p.add_argument(
+        "--fast", action="store_true",
+        help="Skip SpreadingActivation 5th channel for sub-second response. "
+             "Other 4 channels (semantic, lexical, temporal, structural) still run. "
+             "Use when you need recall before a tool call (e.g. before WebSearch).",
+    )
 
     forget_p = sub.add_parser("forget", help="Delete memories matching a query (fuzzy)")
     forget_p.add_argument("query", help="Query to match for deletion")

package/src/superlocalmemory/core/engine.py

@@ -376,6 +376,7 @@ class MemoryEngine:
         mode: Mode | None = None, limit: int = 20,
         agent_id: str = "unknown",
         session_id: str | None = None,
+        fast: bool = False,
     ) -> RecallResponse:
         """Recall relevant facts for a query.
 
@@ -385,6 +386,11 @@ class MemoryEngine:
         Zero additional latency on the hot path — enqueue is a
         ``put_nowait`` and the actual ``pending_outcomes`` INSERT runs
         on a background worker.
+
+        V3.4.40 (2026-05-09): ``fast=True`` skips the SpreadingActivation
+        5th channel for sub-second response. The other 4 channels still
+        run. Use when recall must complete before another tool call (e.g.
+        agent recall before WebSearch).
         """
         self._require_full("recall")
         self._ensure_init()
@@ -402,6 +408,7 @@ class MemoryEngine:
             hooks=self._hooks,
             access_log=self._access_log,
             auto_linker=self._auto_linker,
+            fast=fast,
         )
 
         # S9-DASH-02: enqueue for pending_outcomes. Non-blocking; errors

package/src/superlocalmemory/core/maintenance.py

@@ -106,6 +106,7 @@ def run_maintenance(
         "langevin_updated": 0,
         "fisher_coupled": 0,
         "sheaf_checked": 0,
+        "entity_summaries_consolidated": 0,  # V3.4.40
     }
 
     facts = db.get_all_facts(profile_id)
@@ -270,9 +271,46 @@ def run_maintenance(
         except Exception as exc:
             logger.warning("Sheaf maintenance failed: %s", exc)
 
+    # 3. V3.4.40: Entity summary consolidation
+    # Re-bound any entity_profiles whose knowledge_summary exceeded the cap
+    # (e.g. created before V3.4.40, or via a code path that bypassed the
+    # bounded _build_summary). Truncates in-place — keeps entity identity,
+    # drops bloat. Future writes go through ObservationBuilder.SUMMARY_*
+    # bounds and stay clean.
+    try:
+        consolidated = db.execute(
+            """
+            UPDATE entity_profiles
+               SET knowledge_summary = SUBSTR(knowledge_summary, 1, 2047) || '…',
+                   last_updated = datetime('now')
+             WHERE LENGTH(knowledge_summary) > 2048
+               AND profile_id = ?
+            """,
+            (profile_id,),
+        )
+        # SQLite doesn't return rowcount via execute() wrapper consistently.
+        # Re-count instead — fast on the small subset.
+        rows = db.execute(
+            "SELECT COUNT(*) AS c FROM entity_profiles "
+            "WHERE LENGTH(knowledge_summary) > 2048 AND profile_id = ?",
+            (profile_id,),
+        )
+        # If any remain >2048 after the UPDATE, log it. Otherwise count
+        # how many were truncated by diffing against the prior pass.
+        # (Best-effort; non-fatal.)
+        if rows:
+            remaining = dict(rows[0]).get("c", 0)
+            counts["entity_summaries_consolidated"] = max(
+                0, counts.get("entity_summaries_consolidated", 0)
+            ) - remaining
+    except Exception as exc:
+        logger.warning("Entity summary consolidation failed: %s", exc)
+
     logger.info(
-        "Maintenance complete: %d backfilled, %d Langevin, %d Fisher-coupled, %d Sheaf",
+        "Maintenance complete: %d backfilled, %d Langevin, %d Fisher-coupled, "
+        "%d Sheaf, %d entity-summaries",
         counts["langevin_backfilled"], counts["langevin_updated"],
         counts["fisher_coupled"], counts["sheaf_checked"],
+        counts["entity_summaries_consolidated"],
     )
     return counts

package/src/superlocalmemory/core/recall_pipeline.py

@@ -556,10 +556,15 @@ def run_recall(
     hooks: HookRegistry,
     access_log: Any = None,
     auto_linker: Any = None,
+    fast: bool = False,
 ) -> RecallResponse:
     """Recall relevant facts for a query.
 
     Pipeline: retrieval -> agentic sufficiency (if configured) -> post-recall updates.
+
+    V3.4.40: ``fast=True`` adds spreading_activation to the per-recall
+    extra_disabled_channels set, skipping the 5th channel for sub-second
+    response.
     """
     # Pre-operation hooks
     hook_ctx = {
@@ -572,7 +577,11 @@ def run_recall(
 
     m = mode or config.mode
 
-    response = retrieval_engine.recall(query, profile_id, m, limit)
+    extra_disabled = {"spreading_activation"} if fast else None
+    response = retrieval_engine.recall(
+        query, profile_id, m, limit,
+        extra_disabled_channels=extra_disabled,
+    )
 
     # Agentic sufficiency verification
     # V3.3.19: Only trigger for multi_hop queries in Mode A (rule-based).

package/src/superlocalmemory/encoding/observation_builder.py

@@ -139,22 +139,39 @@ class ObservationBuilder:
             ),
         )
 
+    # V3.4.40 (2026-05-09): bounded summary to prevent unbounded growth.
+    # Pre-V3.4.40 builds concatenated full fact content. Hubs accumulated
+    # 60+ KB summaries that polluted recall and bloated entity_profiles.
+    _SUMMARY_MAX_FACTS = 10           # Last N facts (was 20)
+    _SUMMARY_MAX_CHARS_PER_FACT = 200  # Truncate each fact (NEW)
+    _SUMMARY_MAX_TOTAL_CHARS = 2048    # Hard cap on full summary (NEW)
+
     def _build_summary(
         self, entity_id: str, fact_ids: list[str], profile_id: str
     ) -> str:
         """Build a knowledge summary from all facts about an entity.
 
-        Simple concatenation for now. Mode B/C could use LLM summarization.
+        V3.4.40: bounded — last 10 facts, 200 chars each, 2048 total.
+        Older builds produced 60KB summaries on hub entities.
+        Mode B/C could use LLM rollup for higher-quality compression.
         """
         facts = []
-        for fid in fact_ids[-20:]:  # Last 20 facts to keep summary manageable
+        for fid in fact_ids[-self._SUMMARY_MAX_FACTS:]:
             rows = self._db.execute(
                 "SELECT content FROM atomic_facts WHERE fact_id = ? AND profile_id = ?",
                 (fid, profile_id),
             )
             if rows:
-                facts.append(dict(rows[0])["content"])
+                content = dict(rows[0])["content"]
+                # Truncate per-fact to bound the join below
+                if len(content) > self._SUMMARY_MAX_CHARS_PER_FACT:
+                    content = content[: self._SUMMARY_MAX_CHARS_PER_FACT - 1] + "…"
+                facts.append(content)
 
         if not facts:
             return ""
-        return " | ".join(facts)
+        joined = " | ".join(facts)
+        # Hard cap as final safety net
+        if len(joined) > self._SUMMARY_MAX_TOTAL_CHARS:
+            joined = joined[: self._SUMMARY_MAX_TOTAL_CHARS - 1] + "…"
+        return joined

package/src/superlocalmemory/mcp/tools_active.py

@@ -17,6 +17,7 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 from __future__ import annotations
 
 import logging
+import os
 from pathlib import Path
 from typing import Callable
 
@@ -26,17 +27,32 @@ MEMORY_DIR = Path.home() / ".superlocalmemory"
 DB_PATH = MEMORY_DIR / "memory.db"
 
 
+def _get_agent_id(default: str = "mcp_client") -> str:
+    """Resolve the calling agent's ID for attribution.
+
+    Each Avenger (Claude, Codex, Gemini, Kimi, GLM, Qwen, etc.) sets the
+    ``SLM_AGENT_ID`` env var in its MCP server config so that memories,
+    observations, and registry entries are tagged with the actual source
+    agent — not the legacy ``"mcp_client"`` default.
+
+    v3.4.39+: enables proper cross-Avenger attribution in ``session_init``,
+    ``observe``, and event emissions.
+    """
+    return os.environ.get("SLM_AGENT_ID", default)
+
+
 def _emit_event(event_type: str, payload: dict | None = None,
-                source_agent: str = "mcp_client") -> None:  # V3.3.12: see also mcp/shared.py
+                source_agent: str | None = None) -> None:  # V3.3.12: see also mcp/shared.py
     """Emit an event to the EventBus (best-effort, never raises).
 
     Dashboard visibility is load-bearing per the v3.4.26 user contract,
     so we log on failure rather than silently dropping the signal.
     """
+    resolved_agent = source_agent if source_agent is not None else _get_agent_id()
     try:
         from superlocalmemory.infra.event_bus import EventBus
         bus = EventBus.get_instance(str(DB_PATH))
-        bus.emit(event_type, payload=payload, source_agent=source_agent,
+        bus.emit(event_type, payload=payload, source_agent=resolved_agent,
                  source_protocol="mcp")
     except Exception as exc:
         logger.warning("event emit failed: type=%s err=%s", event_type, exc)
@@ -116,10 +132,11 @@ def register_active_tools(server, get_engine: Callable) -> None:
                     "session_init feedback_count read failed: %s", exc,
                 )
 
-            # Register agent + emit event
-            _register_agent("mcp_client", pid)
+            # Register agent + emit event (v3.4.39: SLM_AGENT_ID env support)
+            agent_id = _get_agent_id()
+            _register_agent(agent_id, pid)
             _emit_event("agent.connected", {
-                "agent_id": "mcp_client",
+                "agent_id": agent_id,
                 "project_path": project_path,
                 "memory_count": len(memories),
             })
@@ -145,7 +162,7 @@ def register_active_tools(server, get_engine: Callable) -> None:
     @server.tool()
     async def observe(
         content: str,
-        agent_id: str = "mcp_client",
+        agent_id: str | None = None,
     ) -> dict:
         """Observe conversation content for automatic memory capture.
 
@@ -155,7 +172,13 @@ def register_active_tools(server, get_engine: Callable) -> None:
 
         Call this after making decisions, fixing bugs, or expressing preferences.
         The system will NOT store low-confidence or irrelevant content.
+
+        v3.4.39: ``agent_id`` now defaults to the ``SLM_AGENT_ID`` env var
+        (set by each Avenger's MCP config) so observations carry proper
+        cross-Avenger attribution.
         """
+        if agent_id is None:
+            agent_id = _get_agent_id()
         try:
             from superlocalmemory.hooks.auto_capture import AutoCapture
             from superlocalmemory.hooks.rules_engine import RulesEngine

package/src/superlocalmemory/retrieval/engine.py

@@ -86,8 +86,11 @@ class RetrievalEngine:
         self._trust_scorer = trust_scorer
 
         # V3.3.4: LRU cache for query embeddings (avoids redundant Ollama API calls)
+        # V3.4.40 (2026-05-09): bumped 64 -> 512. Each cached embedding is ~3KB
+        # (768 floats × 4 bytes). 512 entries ~1.5MB — trivial memory cost,
+        # massive latency win on repeated queries (sub-ms vs 200-2000ms ollama).
         self._query_embedding_cache: dict[str, list[float]] = {}
-        self._cache_max_size = 64
+        self._cache_max_size = 512
 
         # V3.2: ChannelRegistry for self-registration (Phase 0.5)
         from superlocalmemory.retrieval.channel_registry import ChannelRegistry
@@ -112,9 +115,17 @@ class RetrievalEngine:
     def recall(
         self, query: str, profile_id: str,
         mode: Mode = Mode.A, limit: int = 20,
+        *,
+        extra_disabled_channels: set[str] | None = None,
     ) -> RecallResponse:
-        """Full retrieval pipeline: strategy -> channels -> RRF -> rerank."""
+        """Full retrieval pipeline: strategy -> channels -> RRF -> rerank.
+
+        V3.4.40 (2026-05-09): ``extra_disabled_channels`` allows callers to
+        skip specific channels for a single recall (e.g. SpreadingActivation
+        for the ``--fast`` CLI flag) without mutating shared config.
+        """
         t0 = time.monotonic()
+        self._extra_disabled = set(extra_disabled_channels or ())
 
         # 1. Classify query, get adaptive weights
         strat = self._strategy.classify(query, self._base_weights)
@@ -443,7 +454,8 @@ class RetrievalEngine:
         """Run active retrieval channels. Respects disabled_channels config for ablation."""
         out: dict[str, list[tuple[str, float]]] = {}
         # Skip channels listed in disabled_channels (ablation support)
-        disabled = set(self._config.disabled_channels)
+        # V3.4.40: union with per-recall extra_disabled set (e.g. --fast skip)
+        disabled = set(self._config.disabled_channels) | getattr(self, "_extra_disabled", set())
 
         # V3.3.4: Embed query ONCE, reuse for semantic + hopfield channels
         q_emb: list[float] | None = None

package/src/superlocalmemory/retrieval/spreading_activation.py

@@ -47,12 +47,18 @@ class SpreadingActivationConfig:
     delta: float = 0.5           # Node retention / self-decay per iteration
     spreading_factor: float = 0.8  # S: energy diffusion rate
     # V3.3.20: Recalibrated for SLM graph density (254K edges, 768d).
+    # V3.4.40 (2026-05-09): graph grew to 960K edges. top_m=20 caused 5.5s recalls.
+    # Reduced to 10 (compromise between SYNAPSE default 7 and the dense-graph 20).
     # SYNAPSE defaults (theta=0.5, top_m=7) were for 384d sparse graphs.
     theta: float = 0.2           # Activation threshold for sigmoid (was 0.5)
-    top_m: int = 20              # Lateral inhibition: max active nodes (was 7)
+    top_m: int = 10              # Lateral inhibition: max active nodes (was 20, then 7 originally)
     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.40 (2026-05-09): per-node neighbor fan-out clamp.
+    # Hub nodes in dense graphs (5K+ edges) caused unbounded work per expansion.
+    # 100 top-weighted neighbors keeps signal, drops long-tail noise.
+    max_neighbors_per_node: int = 100
     # 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)
@@ -217,24 +223,35 @@ class SpreadingActivation:
         """Get neighbors from BOTH graph_edges and association_edges.
 
         Uses bidirectional UNION query (Section 4 of LLD).
+
+        V3.4.40 (2026-05-09): clamps fan-out to top
+        ``max_neighbors_per_node`` by weight. Without this clamp, hub nodes
+        with thousands of neighbors caused 5.5s recalls. Bounded fan-out
+        matches SYNAPSE's original sparse-graph assumption while preserving
+        the highest-signal edges.
         """
         try:
             rows = self._db.execute(
                 """
-                SELECT target_id AS neighbor_id, weight FROM graph_edges
-                    WHERE source_id = ? AND profile_id = ?
-                UNION ALL
-                SELECT target_fact_id AS neighbor_id, weight FROM association_edges
-                    WHERE source_fact_id = ? AND profile_id = ?
-                UNION ALL
-                SELECT source_id AS neighbor_id, weight FROM graph_edges
-                    WHERE target_id = ? AND profile_id = ?
-                UNION ALL
-                SELECT source_fact_id AS neighbor_id, weight FROM association_edges
-                    WHERE target_fact_id = ? AND profile_id = ?
+                SELECT neighbor_id, weight FROM (
+                    SELECT target_id AS neighbor_id, weight FROM graph_edges
+                        WHERE source_id = ? AND profile_id = ?
+                    UNION ALL
+                    SELECT target_fact_id AS neighbor_id, weight FROM association_edges
+                        WHERE source_fact_id = ? AND profile_id = ?
+                    UNION ALL
+                    SELECT source_id AS neighbor_id, weight FROM graph_edges
+                        WHERE target_id = ? AND profile_id = ?
+                    UNION ALL
+                    SELECT source_fact_id AS neighbor_id, weight FROM association_edges
+                        WHERE target_fact_id = ? AND profile_id = ?
+                )
+                ORDER BY weight DESC
+                LIMIT ?
                 """,
                 (node_id, profile_id, node_id, profile_id,
-                 node_id, profile_id, node_id, profile_id),
+                 node_id, profile_id, node_id, profile_id,
+                 self._config.max_neighbors_per_node),
             )
             return [
                 (dict(r)["neighbor_id"], dict(r)["weight"]) for r in rows

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

@@ -381,7 +381,9 @@ async def test_provider(request: Request):
                 resp = c.get(f"{endpoint}/api/tags")
                 resp.raise_for_status()
                 models = [m["name"] for m in resp.json().get("models", [])]
-                found = model in models if model else len(models) > 0
+                # Match either exact name or base name (strip ":tag" suffix on both sides)
+                model_base = model.split(":")[0] if model else ""
+                found = any(m == model or m.split(":")[0] == model_base for m in models) if model else len(models) > 0
                 return {
                     "success": found,
                     "message": f"Ollama OK, {len(models)} models" + (f", '{model}' available" if found and model else ""),

package/src/superlocalmemory/server/unified_daemon.py

@@ -1082,6 +1082,7 @@ def _register_daemon_routes(application: FastAPI) -> None:
         request: Request,
         q: str = "", query: str = "", limit: int = 20,
         session_id: str = "",
+        fast: bool = False,
     ):
         _update_activity()
         search_query = q or query  # Accept both ?q= and ?query= for compatibility
@@ -1103,6 +1104,7 @@ def _register_daemon_routes(application: FastAPI) -> None:
         try:
             response = engine.recall(
                 search_query, limit=limit, session_id=effective_sid,
+                fast=fast,
             )
             # v3.4.26: return the same field shape as recall_worker so
             # MCP processes proxying through the daemon get recall_trace-