superlocalmemory 3.3.19 → 3.3.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.3.19",
+  "version": "3.3.20",
   "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.3.19"
+version = "3.3.20"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "MIT"}

package/src/superlocalmemory/cli/commands.py

@@ -252,10 +252,11 @@ def cmd_remember(args: Namespace) -> None:
     from superlocalmemory.core.config import SLMConfig
 
     use_json = getattr(args, 'json', False)
-    fire_and_forget = getattr(args, 'fire_and_forget', False)
+    sync_mode = getattr(args, 'sync_mode', False)
 
-    # V3.3.19: --async flag for hooks/scripts — spawn background process, return instantly
-    if fire_and_forget:
+    # V3.3.19: Async by default — return instantly, process in background.
+    # Use --sync to wait for completion (e.g., when you need fact_ids back).
+    if not sync_mode:
         import subprocess
         cmd = [sys.executable, "-m", "superlocalmemory.cli.main", "remember", args.content]
         if args.tags:

package/src/superlocalmemory/cli/main.py

@@ -135,8 +135,8 @@ def main() -> None:
     remember_p.add_argument("--tags", default="", help="Comma-separated tags")
     remember_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
     remember_p.add_argument(
-        "--async", dest="fire_and_forget", action="store_true",
-        help="Return immediately, process in background (for hooks/scripts)",
+        "--sync", dest="sync_mode", action="store_true",
+        help="Wait for completion (default: async background processing)",
     )
 
     recall_p = sub.add_parser("recall", help="Semantic search with 4-channel retrieval")

package/src/superlocalmemory/core/config.py

@@ -740,9 +740,10 @@ class SLMConfig:
                 retrieval=RetrievalConfig(
                     # V3.3.2: ONNX cross-encoder enabled for all modes (~200MB)
                     use_cross_encoder=True,
-                    # Mode A is zero-LLM: disable agentic retrieval (it replaces
-                    # precision-tuned fusion with crude heuristic expansions)
-                    agentic_max_rounds=0,
+                    # V3.3.19: Enable 1 round of rule-based query decomposition.
+                    # The enhanced _heuristic_expand generates entity+action
+                    # sub-queries that dramatically improve multi-hop retrieval.
+                    agentic_max_rounds=1,
                 ),
                 math=MathConfig(
                     sheaf_contradiction_threshold=0.45,  # 768d threshold

package/src/superlocalmemory/core/recall_pipeline.py

@@ -157,13 +157,17 @@ def run_recall(
     response = retrieval_engine.recall(query, profile_id, m, limit)
 
     # Agentic sufficiency verification
+    # V3.3.19: Only trigger for multi_hop queries in Mode A (rule-based).
+    # Single-hop/factual/temporal queries get WORSE with decomposition —
+    # sub-query noise dilutes precision. Mode C (LLM) can trigger broadly.
     agentic_rounds = config.retrieval.agentic_max_rounds
     if agentic_rounds > 0 and response.results:
         max_score = max((r.score for r in response.results), default=0.0)
+        has_llm = llm is not None and getattr(llm, "is_available", False)
         should_trigger = (
-            max_score < config.retrieval.agentic_confidence_threshold
-            or response.query_type == "multi_hop"
-            or len(response.results) < 3
+            response.query_type == "multi_hop"
+            or (has_llm and max_score < config.retrieval.agentic_confidence_threshold)
+            or (has_llm and len(response.results) < 3)
         )
         if should_trigger:
             try:

package/src/superlocalmemory/retrieval/agentic.py

@@ -31,7 +31,10 @@ logger = logging.getLogger(__name__)
 
 _MAX_ROUNDS = 2
 _SUFFICIENCY_SCORE_THRESHOLD = 0.6
-_SKIP_TYPES = frozenset({"temporal"})  # S15: agentic harms temporal queries
+# V3.3.19: Removed "temporal" from skip list. S15's lesson was with
+# weak alias expansion. The new rule-based decomposer (v3.3.19) helps
+# temporal queries by generating entity+action sub-queries.
+_SKIP_TYPES: frozenset[str] = frozenset()  # No types skipped
 
 _SUFFICIENCY_SYSTEM = (
     "You evaluate whether retrieved context is sufficient to answer a query. "
@@ -241,22 +244,91 @@ class AgenticRetriever:
     def _heuristic_expand(
         self, query: str, profile_id: str,
     ) -> list[str]:
-        """Mode A: expand query with entity aliases (no LLM)."""
-        if self._db is None:
-            return []
-
-        expanded_parts: list[str] = []
-        entities = re.findall(r"\b[A-Z][a-z]{2,}\b", query)
-        for name in entities:
-            entity = self._db.get_entity_by_name(name, profile_id)
-            if entity:
-                aliases = self._db.get_aliases_for_entity(entity.entity_id)
-                for a in aliases[:3]:
-                    expanded_parts.append(a.alias)
-
-        if expanded_parts:
-            return [query + " " + " ".join(expanded_parts)]
-        return []
+        """Mode A: rule-based query decomposition (no LLM).
+
+        V3.3.19: Full rewrite. Generates targeted sub-queries by:
+        1. Extracting person/place names (real proper nouns only)
+        2. Extracting action/event keywords (non-stopwords minus entities)
+        3. Combining entity + action for focused retrieval
+        4. Entity-only and action-only lookups for broader context
+
+        For LoCoMo "When did [Person] [Action]?" patterns, this generates:
+          "Caroline LGBTQ support group"  (entity + action)
+          "Caroline"                       (entity only)
+          "LGBTQ support group"            (action only)
+        """
+        sub_queries: list[str] = []
+
+        # Extract REAL proper nouns from original query (not title-cased)
+        # This avoids the extract_query_entities trap where "Support Group"
+        # from title-casing gets treated as entities.
+        _STARTERS = {
+            "What", "Where", "Who", "Which", "How", "When", "Does", "Did",
+            "Can", "Could", "Would", "Should", "Are", "Is", "Was", "Were",
+            "Has", "Have", "The", "Tell", "Do",
+        }
+        entities = [
+            m for m in re.findall(r"\b[A-Z][a-z]{2,}\b", query)
+            if m not in _STARTERS
+        ]
+        # Also grab all-caps abbreviations (LGBTQ, MIT, NYC)
+        abbrevs = re.findall(r"\b[A-Z]{2,}\b", query)
+        entities.extend(abbrevs)
+
+        # Extract action/event keywords (remove question words + entity names)
+        _STOP = {
+            "when", "did", "does", "do", "what", "where", "who", "which",
+            "how", "is", "was", "were", "are", "has", "have", "had",
+            "the", "a", "an", "to", "for", "of", "in", "on", "at",
+            "and", "or", "but", "with", "from", "about", "that", "this",
+            "it", "they", "she", "he", "her", "his", "their", "its",
+            "been", "being", "would", "could", "should", "will", "can",
+            "may", "might", "not", "no", "so", "if", "by", "up",
+            "go", "going", "went", "get", "got", "ago",
+            "many", "much", "some", "any", "ever",
+        }
+        entity_lower = {e.lower() for e in entities}
+        words = re.sub(r"[^\w\s]", "", query.lower()).split()
+        action_words = [
+            w for w in words
+            if w not in _STOP and w not in entity_lower and len(w) > 2
+        ]
+
+        # Strategy 1: Entity + action keywords (most targeted)
+        if entities and action_words:
+            action_phrase = " ".join(action_words)
+            for ent in entities[:2]:
+                sub_queries.append(f"{ent} {action_phrase}")
+
+        # Strategy 2: Action keywords only (finds the event regardless of entity)
+        if action_words:
+            sub_queries.append(" ".join(action_words))
+
+        # Strategy 3: Entity-only lookup (broad context)
+        for ent in entities[:2]:
+            sub_queries.append(ent)
+
+        # Strategy 4: Alias expansion (original approach, still useful)
+        if self._db is not None:
+            for name in entities[:2]:
+                entity = self._db.get_entity_by_name(name, profile_id)
+                if entity:
+                    try:
+                        aliases = self._db.get_aliases_for_entity(entity.entity_id)
+                        for a in aliases[:2]:
+                            sub_queries.append(f"{a.alias} {' '.join(action_words)}")
+                    except Exception:
+                        pass
+
+        # Deduplicate, limit to 3 sub-queries (keep round 2 fast)
+        seen: set[str] = set()
+        unique: list[str] = []
+        for sq in sub_queries:
+            sq_lower = sq.strip().lower()
+            if sq_lower and sq_lower not in seen and sq_lower != query.lower():
+                seen.add(sq_lower)
+                unique.append(sq.strip())
+        return unique[:3]
 
 
 # ---------------------------------------------------------------------------