superlocalmemory 3.4.7 → 3.4.8

package/package.json

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

package/src/superlocalmemory/cli/commands.py

@@ -60,6 +60,8 @@ def dispatch(args: Namespace) -> None:
         "serve": cmd_serve,
         # V3.4.3 ingestion adapters
         "adapters": cmd_adapters,
+        # V3.4.8 external observation ingestion
+        "ingest": cmd_ingest,
     }
     handler = handlers.get(args.command)
     if handler:
@@ -144,6 +146,12 @@ def cmd_serve(args: Namespace) -> None:
 # -- Ingestion Adapters (V3.4.3) ------------------------------------------
 
 
+def cmd_ingest(args: Namespace) -> None:
+    """Import external observations into SLM learning pipeline."""
+    from superlocalmemory.cli.ingest_cmd import cmd_ingest as _ingest
+    _ingest(args)
+
+
 def cmd_adapters(args: Namespace) -> None:
     """Manage ingestion adapters (Gmail, Calendar, Transcript).
 

package/src/superlocalmemory/cli/daemon.py

@@ -16,7 +16,7 @@ This module contains CLIENT functions used by CLI commands:
 The actual daemon server code is in server/unified_daemon.py.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/cli/ingest_cmd.py

@@ -0,0 +1,261 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""CLI handler for `slm ingest` — import external observations into SLM.
+
+Supported sources:
+  --source ecc    Import ECC (Everything Claude Code) session summaries
+  --source jsonl  Import generic JSONL observations
+
+Each imported record becomes a tool_event in the behavioral learning pipeline,
+so the AssertionMiner can learn from them.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import sys
+from argparse import Namespace
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+MEMORY_DIR = Path.home() / ".superlocalmemory"
+MEMORY_DB = MEMORY_DIR / "memory.db"
+
+
+def cmd_ingest(args: Namespace) -> None:
+    """Ingest external observations into SLM tool_events table."""
+    source = getattr(args, "source", "ecc")
+    file_path = getattr(args, "file", "")
+    use_json = getattr(args, "json", False)
+    dry_run = getattr(args, "dry_run", False)
+
+    if source == "ecc":
+        result = _ingest_ecc(file_path, dry_run=dry_run)
+    elif source == "jsonl":
+        if not file_path:
+            _error("--file required for jsonl source", use_json)
+            return
+        result = _ingest_jsonl(file_path, dry_run=dry_run)
+    else:
+        _error(f"Unknown source: {source}", use_json)
+        return
+
+    if use_json:
+        from superlocalmemory.cli.json_output import json_print
+        json_print("ingest", data=result, next_actions=[
+            {"command": "slm consolidate --cognitive", "description": "Run consolidation to mine assertions"},
+        ])
+        return
+
+    if result.get("error"):
+        print(f"Error: {result['error']}")
+        sys.exit(1)
+
+    print(f"Ingested: {result['ingested']} events from {source}")
+    if result.get("skipped"):
+        print(f"Skipped:  {result['skipped']} (duplicates/invalid)")
+    if dry_run:
+        print("(dry run — no data written)")
+
+
+def _error(msg: str, use_json: bool) -> None:
+    if use_json:
+        from superlocalmemory.cli.json_output import json_print
+        json_print("ingest", error={"code": "INGEST_ERROR", "message": msg})
+    else:
+        print(f"Error: {msg}")
+    sys.exit(1)
+
+
+def _ingest_ecc(file_path: str, *, dry_run: bool = False) -> dict:
+    """Ingest ECC session summaries from transcript JSONL files.
+
+    Scans the Claude projects directory for session JSONL files and
+    extracts tool usage patterns from them.
+    """
+    result = {"source": "ecc", "ingested": 0, "skipped": 0, "dry_run": dry_run}
+
+    # Find ECC session files
+    if file_path:
+        files = [Path(file_path)]
+    else:
+        # Auto-discover: scan Claude project session files
+        claude_dir = Path.home() / ".claude" / "projects"
+        if not claude_dir.exists():
+            result["error"] = f"Claude projects dir not found: {claude_dir}"
+            return result
+        files = sorted(claude_dir.rglob("*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True)
+        # Limit to recent files (last 20)
+        files = files[:20]
+
+    if not files:
+        result["error"] = "No session files found"
+        return result
+
+    result["files_scanned"] = len(files)
+    events = []
+
+    for fpath in files:
+        try:
+            with open(fpath) as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        record = json.loads(line)
+                    except json.JSONDecodeError:
+                        result["skipped"] += 1
+                        continue
+
+                    # Extract tool usage from ECC session records
+                    extracted = _extract_tool_events_from_record(record)
+                    events.extend(extracted)
+        except (OSError, PermissionError):
+            result["skipped"] += 1
+            continue
+
+    if dry_run:
+        result["ingested"] = len(events)
+        result["sample"] = events[:5]
+        return result
+
+    # Write to tool_events table
+    if events:
+        ingested = _write_tool_events(events)
+        result["ingested"] = ingested
+    else:
+        result["ingested"] = 0
+
+    return result
+
+
+def _extract_tool_events_from_record(record: dict) -> list[dict]:
+    """Extract tool events from a single ECC/Claude session JSONL record."""
+    events = []
+
+    # Handle ECC summary format
+    if "type" in record:
+        rtype = record.get("type", "")
+
+        # Tool use records
+        if rtype == "assistant" and "content" in record:
+            content = record.get("content", [])
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "tool_use":
+                        tool_name = block.get("name", "unknown")
+                        events.append({
+                            "tool_name": tool_name,
+                            "event_type": "complete",
+                            "session_id": record.get("session_id", "ecc_import"),
+                            "created_at": record.get("timestamp", datetime.now(timezone.utc).isoformat()),
+                        })
+
+            # Also extract from tool_use type directly
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "tool_result":
+                        tool_name = block.get("tool_use_id", "unknown")
+                        is_error = block.get("is_error", False)
+                        events.append({
+                            "tool_name": tool_name,
+                            "event_type": "error" if is_error else "complete",
+                            "session_id": record.get("session_id", "ecc_import"),
+                            "created_at": record.get("timestamp", datetime.now(timezone.utc).isoformat()),
+                        })
+
+    # Handle direct tool event format (from hook output)
+    if "tool_name" in record and "event_type" in record:
+        events.append({
+            "tool_name": record["tool_name"],
+            "event_type": record.get("event_type", "complete"),
+            "session_id": record.get("session_id", "ecc_import"),
+            "created_at": record.get("created_at", datetime.now(timezone.utc).isoformat()),
+        })
+
+    return events
+
+
+def _ingest_jsonl(file_path: str, *, dry_run: bool = False) -> dict:
+    """Ingest generic JSONL file with tool event records."""
+    result = {"source": "jsonl", "ingested": 0, "skipped": 0, "dry_run": dry_run}
+
+    fpath = Path(file_path)
+    if not fpath.exists():
+        result["error"] = f"File not found: {file_path}"
+        return result
+
+    events = []
+    with open(fpath) as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                result["skipped"] += 1
+                continue
+
+            if "tool_name" not in record:
+                result["skipped"] += 1
+                continue
+
+            events.append({
+                "tool_name": record["tool_name"],
+                "event_type": record.get("event_type", "complete"),
+                "session_id": record.get("session_id", "jsonl_import"),
+                "created_at": record.get("created_at", datetime.now(timezone.utc).isoformat()),
+            })
+
+    if dry_run:
+        result["ingested"] = len(events)
+        return result
+
+    if events:
+        result["ingested"] = _write_tool_events(events)
+
+    return result
+
+
+def _write_tool_events(events: list[dict]) -> int:
+    """Write tool events to SLM's memory.db tool_events table."""
+    db_path = MEMORY_DB
+    if not db_path.exists():
+        return 0
+
+    conn = sqlite3.connect(str(db_path), timeout=10)
+    count = 0
+
+    try:
+        for ev in events:
+            try:
+                conn.execute(
+                    "INSERT INTO tool_events "
+                    "(session_id, profile_id, project_path, tool_name, event_type, "
+                    " input_summary, output_summary, duration_ms, metadata, created_at) "
+                    "VALUES (?, 'default', '', ?, ?, '', '', 0, '{}', ?)",
+                    (
+                        ev.get("session_id", "import"),
+                        ev["tool_name"],
+                        ev.get("event_type", "complete"),
+                        ev.get("created_at", datetime.now(timezone.utc).isoformat()),
+                    ),
+                )
+                count += 1
+            except sqlite3.Error:
+                continue
+        conn.commit()
+    finally:
+        conn.close()
+
+    return count

package/src/superlocalmemory/cli/main.py

@@ -282,6 +282,26 @@ def main() -> None:
         help="Subcommand: list, enable, disable, start, stop, status [name]",
     )
 
+    # V3.4.8: External observation ingestion
+    ingest_p = sub.add_parser(
+        "ingest",
+        help="Import external observations (ECC, JSONL) into SLM learning",
+    )
+    ingest_p.add_argument(
+        "--source", default="ecc",
+        choices=["ecc", "jsonl"],
+        help="Source type: ecc (Claude Code sessions), jsonl (generic)",
+    )
+    ingest_p.add_argument(
+        "--file", default="",
+        help="Specific file to ingest (auto-discovers if not set)",
+    )
+    ingest_p.add_argument(
+        "--dry-run", action="store_true", default=False,
+        help="Preview without writing",
+    )
+    ingest_p.add_argument("--json", action="store_true", help="Output structured JSON")
+
     args = parser.parse_args()
 
     if not args.command:

package/src/superlocalmemory/core/consolidation_engine.py

@@ -151,7 +151,7 @@ class ConsolidationEngine:
                     except ImportError:
                         class CrossProjectAggregator:
                             def __init__(self, db): pass
-                            def aggregate(self, *a, **kw): return []
+                            def get_preferences(self, *a, **kw): return {}
                     try:
                         from superlocalmemory.parameterization.workflow_miner import WorkflowMiner
                     except ImportError:
@@ -169,7 +169,7 @@ class ConsolidationEngine:
                     wf_miner = WorkflowMiner(self._db)
                     extractor = PatternExtractor(self._db, beh_store, cross_proj, wf_miner, p_config)
                     generator = SoftPromptGenerator(p_config)
-                    injector = PromptInjector(self._db)
+                    injector = PromptInjector(self._db, generator, p_config)
                     lifecycle = PromptLifecycleManager(self._db, p_config)
                     hook = AutoParameterizeHook(extractor, generator, injector, lifecycle, p_config)
                     sp_result = hook.on_consolidation_complete(profile_id)

package/src/superlocalmemory/encoding/entity_resolver.py

@@ -15,7 +15,7 @@ entity resolution ran but results were silently discarded.
   d) LLM disambiguation (Mode B/C only)
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations
@@ -112,20 +112,59 @@ def jaro_winkler(s1: str, s2: str, prefix_weight: float = 0.1) -> float:
     return jaro + prefix * prefix_weight * (1.0 - jaro)
 
 
+_COMMON_WORDS = frozenset({
+    "april", "may", "june", "march", "august", "phase", "test", "gap",
+    "dashboard", "remaining", "session", "results", "tools", "projects",
+    "prompts", "integration", "cli", "engagement", "mode", "error",
+    "step", "fix", "build", "check", "run", "start", "stop", "config",
+    "status", "version", "query", "data", "file", "path", "node", "edge",
+    "table", "index", "schema", "model", "type", "class", "function",
+    "module", "package", "import", "export", "default", "pattern",
+    "memory", "profile", "context", "pipeline", "worker", "daemon",
+    "server", "client", "route", "endpoint", "handler", "hook",
+})
+
+
 def _guess_entity_type(name: str) -> str:
-    """Heuristic entity type classification from name string."""
+    """Heuristic entity type classification from name string.
+
+    v3.4.8: Fixed false-positive "person" classification. Single capitalized
+    common words (April, Phase, Dashboard) are concepts, not people.
+    Only classify as "person" when it looks like a real human name.
+    """
     if any(m in name for m in _ORG_MARKERS):
         return "organization"
     if any(m in name for m in _PLACE_MARKERS):
         return "place"
     if any(m in name for m in _EVENT_MARKERS):
         return "event"
-    # Two capitalized words = likely a person name
+
+    # Filter out common words that aren't people
+    if name.lower() in _COMMON_WORDS:
+        return "concept"
+
+    # Two capitalized words = likely a person name (e.g. "Varun Bhardwaj")
     if re.match(r"^[A-Z][a-z]+ [A-Z][a-z]+$", name):
-        return "person"
-    # Single capitalized word = likely a person first name
+        # But not if either word is a common term
+        parts = name.lower().split()
+        if not any(p in _COMMON_WORDS for p in parts):
+            return "person"
+
+    # Single short capitalized word with no digits or dots = concept, not person
+    # "person" should only be assigned for real names, not generic terms
     if re.match(r"^[A-Z][a-z]+$", name):
+        if name.lower() in _COMMON_WORDS:
+            return "concept"
+        # Only classify as person if it's a plausible first name
+        # (short word not in common terms — still a heuristic)
+        if len(name) <= 3:
+            return "concept"
         return "person"
+
+    # Contains dots/slashes/hyphens = likely a technical term
+    if re.search(r"[./\-_]", name):
+        return "concept"
+
     return "concept"
 
 

package/src/superlocalmemory/learning/assertion_miner.py

@@ -28,6 +28,8 @@ logger = logging.getLogger(__name__)
 MIN_EVIDENCE = 3  # Minimum events to create an assertion
 MAX_ASSERTIONS_PER_RUN = 20  # Cap assertions per mining cycle
 REINFORCEMENT_NUDGE = 0.15  # Bayesian confidence increase
+PROMOTION_MIN_PROJECTS = 2  # Minimum projects for cross-project promotion
+PROMOTION_MIN_CONFIDENCE = 0.8  # Minimum avg confidence for promotion
 
 
 class AssertionMiner:
@@ -74,6 +76,11 @@ class AssertionMiner:
             results["created"] += s4.get("created", 0)
             results["reinforced"] += s4.get("reinforced", 0)
 
+            # Strategy 5: Cross-project assertion promotion
+            s5 = self._promote_cross_project(conn, profile_id)
+            results["strategies"]["cross_project"] = s5
+            results["created"] += s5.get("promoted", 0)
+
             conn.commit()
         except Exception as exc:
             logger.warning("Assertion mining failed: %s", exc)
@@ -263,6 +270,92 @@ class AssertionMiner:
 
         return result
 
+    # ------------------------------------------------------------------
+    # Strategy 5: Cross-project assertion promotion
+    # ------------------------------------------------------------------
+
+    def _promote_cross_project(
+        self, conn: sqlite3.Connection, profile_id: str,
+    ) -> dict:
+        """Promote assertions that appear in 2+ projects to global scope.
+
+        When the same trigger+action pattern is observed across multiple
+        project_paths with avg confidence >= 0.8, create a global assertion
+        (project_path='') so it applies everywhere.
+        """
+        result = {"promoted": 0, "candidates": 0}
+
+        # Find assertions grouped by trigger+action across projects
+        rows = conn.execute(
+            "SELECT trigger_condition, action, category, "
+            "COUNT(DISTINCT project_path) AS project_count, "
+            "AVG(confidence) AS avg_confidence, "
+            "SUM(evidence_count) AS total_evidence "
+            "FROM behavioral_assertions "
+            "WHERE profile_id = ? AND project_path != '' "
+            "GROUP BY trigger_condition, action "
+            "HAVING COUNT(DISTINCT project_path) >= ?",
+            (profile_id, PROMOTION_MIN_PROJECTS),
+        ).fetchall()
+
+        result["candidates"] = len(rows)
+
+        for row in rows:
+            avg_conf = row["avg_confidence"]
+            if avg_conf < PROMOTION_MIN_CONFIDENCE:
+                continue
+
+            trigger = row["trigger_condition"]
+            action = row["action"]
+            category = row["category"]
+            total_ev = row["total_evidence"]
+            project_count = row["project_count"]
+
+            # Check if global assertion already exists
+            global_id = hashlib.sha256(
+                f"{profile_id}:{trigger}:{action}".encode()
+            ).hexdigest()[:16]
+
+            existing = conn.execute(
+                "SELECT id FROM behavioral_assertions "
+                "WHERE id = ? AND project_path = ''",
+                (global_id,),
+            ).fetchone()
+
+            if existing:
+                # Reinforce existing global assertion
+                now = datetime.now(timezone.utc).isoformat()
+                conn.execute(
+                    "UPDATE behavioral_assertions SET "
+                    "confidence = MIN(0.95, confidence + ?), "
+                    "evidence_count = ?, "
+                    "reinforcement_count = reinforcement_count + 1, "
+                    "last_reinforced_at = ?, updated_at = ? "
+                    "WHERE id = ?",
+                    (REINFORCEMENT_NUDGE, total_ev, now, now, global_id),
+                )
+            else:
+                # Create new global assertion from cross-project evidence
+                now = datetime.now(timezone.utc).isoformat()
+                promoted_conf = min(0.9, avg_conf)
+                conn.execute(
+                    "INSERT INTO behavioral_assertions "
+                    "(id, profile_id, project_path, trigger_condition, action, "
+                    " category, confidence, evidence_count, source, "
+                    " created_at, updated_at) "
+                    "VALUES (?, ?, '', ?, ?, ?, ?, ?, 'cross_project', ?, ?)",
+                    (global_id, profile_id, trigger, action,
+                     category, round(promoted_conf, 4), total_ev, now, now),
+                )
+                result["promoted"] += 1
+                logger.info(
+                    "Promoted assertion to global: '%s' → '%s' "
+                    "(from %d projects, avg_conf=%.2f)",
+                    trigger, action, project_count, avg_conf,
+                )
+
+        return result
+
     # ------------------------------------------------------------------
     # Upsert logic
     # ------------------------------------------------------------------

package/src/superlocalmemory/learning/engagement.py

@@ -1,7 +1,6 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: Elastic-2.0
 # Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Part of Qualixar | Author: Varun Pratap Bhardwaj (qualixar.com | varunpratap.com)
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
 """
 EngagementTracker -- Local-only engagement metrics for V3 learning.
 

package/src/superlocalmemory/parameterization/prompt_injector.py

@@ -186,7 +186,8 @@ class PromptInjector:
             )
             max_version = 0
             if version_rows:
-                max_version = version_rows[0].get("max_version", 0) or 0
+                row = version_rows[0]
+                max_version = (dict(row) if hasattr(row, "keys") else {"max_version": row[0]}).get("max_version", 0) or 0
             new_version = max_version + 1
 
             # Insert new prompt

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

@@ -226,11 +226,15 @@ async def get_soft_prompts():
         conn = _sqlite3.connect(str(MEMORY_DIR / "memory.db"))
         conn.row_factory = _sqlite3.Row
         rows = conn.execute(
-            "SELECT * FROM soft_prompt_templates WHERE active = 1 "
-            "ORDER BY category"
+            "SELECT prompt_id, category, content, confidence, effectiveness, "
+            "token_count, active, version, created_at "
+            "FROM soft_prompt_templates WHERE active = 1 ORDER BY category"
         ).fetchall()
         conn.close()
-        return {"prompts": [dict(r) for r in rows], "count": len(rows)}
+        return {"prompts": [dict(zip(
+            ["prompt_id", "category", "content", "confidence", "effectiveness",
+             "token_count", "active", "version", "created_at"], r
+        )) for r in rows], "count": len(rows)}
     except Exception as e:
         logger.debug("get_soft_prompts error: %s", e)
         return {"prompts": [], "count": 0, "error": str(e)}

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

@@ -143,12 +143,29 @@ async def learning_status():
             "signals": signal_count,
         }
 
-        # Engagement
+        # Engagement — v3.4.8: Fixed method name (was get_engagement_stats, actual is get_stats)
         engagement = _get_engagement()
         if engagement:
             try:
-                result["engagement"] = engagement.get_engagement_stats()
-            except Exception:
+                stats = engagement.get_stats(active_profile)
+                health = engagement.get_health(active_profile)
+                active_days = stats.get("active_days", 0)
+                total_events = stats.get("total_events", 0)
+                memories_per_day = (
+                    round(total_events / active_days, 1) if active_days > 0 else 0
+                )
+                result["engagement"] = {
+                    "health_status": health.upper(),
+                    "days_active": active_days,
+                    "memories_per_day": memories_per_day,
+                    "total_events": total_events,
+                    "recall_count": stats.get("recall_count", 0),
+                    "store_count": stats.get("store_count", 0),
+                    "session_count": stats.get("session_count", 0),
+                    "engagement_score": stats.get("engagement_score", 0),
+                }
+            except Exception as exc:
+                logger.debug("engagement stats: %s", exc)
                 result["engagement"] = None
         else:
             result["engagement"] = None