superlocalmemory 4.0.5 → 4.0.7

package/src/superlocalmemory/cli/gdpr_io.py

@@ -0,0 +1,109 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V4 | https://qualixar.com | https://varunpratap.com
+
+"""Shared I/O helpers and compliance constants for ``slm gdpr`` subcommands.
+
+Separated from gdpr_cmd.py to honour the 800-line file cap (coding-style.md).
+All symbols here are internal (prefixed ``_``) or ALL_CAPS constants.
+"""
+
+from __future__ import annotations
+
+import json as _json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Output helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _die(message: str, code: int = 1) -> None:
+    """Print an actionable error to stderr and exit non-zero."""
+    print(f"error: {message}", file=sys.stderr)
+    sys.exit(code)
+
+
+def _print_json(data: Any) -> None:
+    """Emit pretty-printed JSON to stdout (evidence-pipeline format)."""
+    print(_json.dumps(data, indent=2, default=str))
+
+
+def _json_envelope(
+    command: str, *, data: dict | None = None, error: dict | None = None
+) -> dict:
+    """Build the standard agent-native JSON envelope used across all SLM CLIs."""
+    from superlocalmemory.cli.json_output import _get_version
+
+    env: dict = {
+        "success": error is None,
+        "command": command,
+        "version": _get_version(),
+    }
+    if error is not None:
+        env["error"] = error
+    else:
+        env["data"] = data if data is not None else {}
+    return env
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Path helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _data_root() -> Path:
+    """Resolve the canonical SLM data root (honours SLM_DATA_DIR env var)."""
+    from superlocalmemory.infra.data_root import canonical_data_root
+
+    return canonical_data_root()
+
+
+def _db_path() -> Path:
+    return _data_root() / "memory.db"
+
+
+def _audit_chain_path() -> Path:
+    return _data_root() / "audit_chain.db"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# GDPR compliance constants (DPO-facing, surfaced in ``status`` output)
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Known gaps in this release — reported honestly so a DPO can plan remediation.
+# Gaps C1 and C2 are tracked as open items in the Wave 3 backlog.
+KNOWN_GAPS = [
+    {
+        "ref": "C1",
+        "summary": "backups/ directory is outside erasure scope",
+        "detail": (
+            "Up to 10 rotating snapshots of memory.db, learning.db and "
+            "related DB files survive an Art.17 erasure.  The erasure receipt "
+            "records a 'backup_obligation' so the obligation is tracked, but "
+            "the snapshots are not automatically purged.  Snapshots are "
+            "re-erased on restore."
+        ),
+    },
+    {
+        "ref": "C2",
+        "summary": "code_graph.db is not in erasure scope",
+        "detail": (
+            "Repository paths, file names and symbol names (identifying data "
+            "in a work context) are stored in code_graph.db.  This file is "
+            "covered by compliance/gdpr.py but the per-table discovery "
+            "operates on the main memory.db only."
+        ),
+    },
+]
+
+# Art. coverage flags that compliance/gdpr.py actively implements.
+ART_COVERAGE = {
+    "art15_right_to_access": True,
+    "art17_right_to_erasure": True,
+    "art20_right_to_portability": True,
+    "backup_scope": "outstanding_obligation_recorded_on_receipt",
+    "audit_chain": "HMAC-chained tamper-evident",
+    "erasure_fails_closed": True,
+}

package/src/superlocalmemory/cli/main.py

@@ -88,6 +88,11 @@ _NO_DAEMON_COMMANDS = {
     "help",
     # Lifecycle orchestration must run before any global auto-start hook.
     "serve", "restart",
+    # V4.0.6: GDPR CLI accesses the DB directly; no daemon required.
+    "gdpr",
+    # V4.0.7: summaries read memory.db directly and are extractive by default,
+    # so they need neither the daemon nor a language model.
+    "summary",
 }
 
 
@@ -966,6 +971,86 @@ def main() -> None:
         _sp.add_argument("--json", action="store_true",
                          help="Output structured JSON (agent-native)")
 
+    # V4.0.7: the readable summary layer from issue #113. The generators shipped
+    # in 4.0.6 with no caller; this is the surface that makes them reachable.
+    from superlocalmemory.cli.summary_cmd import register_summary_parser
+
+    register_summary_parser(sub)
+
+    # Wave-3 / V4.0.6: GDPR subject-rights CLI (Art.15/17/20)
+    gdpr_p = sub.add_parser(
+        "gdpr",
+        help="GDPR subject rights: status, export (Art.15/20), erase (Art.17), verify",
+    )
+    gdpr_sub = gdpr_p.add_subparsers(dest="gdpr_command", title="gdpr subcommands")
+
+    gdpr_status_p = gdpr_sub.add_parser(
+        "status",
+        help="Compliance posture: receipts, audit events, known gaps (read-only)",
+    )
+    gdpr_status_p.add_argument(
+        "--profile", default=None, metavar="PROFILE",
+        help="Scope to a specific profile (default: report all)",
+    )
+    gdpr_status_p.add_argument(
+        "--json", action="store_true", help="Output structured JSON (agent-native)",
+    )
+
+    gdpr_export_p = gdpr_sub.add_parser(
+        "export",
+        help="Art.15/20 subject access / data portability export",
+    )
+    gdpr_export_p.add_argument(
+        "--profile", required=True, metavar="PROFILE",
+        help="Profile to export (required)",
+    )
+    gdpr_export_p.add_argument(
+        "--output", default=None, metavar="FILE",
+        help="Write export JSON to FILE (default: stdout)",
+    )
+    gdpr_export_p.add_argument(
+        "--json", action="store_true", help="Output structured JSON envelope",
+    )
+
+    gdpr_erase_p = gdpr_sub.add_parser(
+        "erase",
+        help=(
+            "Art.17 right to erasure — IRREVERSIBLE. "
+            "Requires --profile PROFILE AND --yes."
+        ),
+    )
+    gdpr_erase_p.add_argument(
+        "--profile", default=None, metavar="PROFILE",
+        help="Profile to erase (required for live erasure)",
+    )
+    gdpr_erase_p.add_argument(
+        "--yes", action="store_true",
+        help="Confirm irreversible erasure (required together with --profile)",
+    )
+    gdpr_erase_p.add_argument(
+        "--dry-run", action="store_true", dest="dry_run",
+        help="Preview what would be erased without deleting anything",
+    )
+    gdpr_erase_p.add_argument(
+        "--json", action="store_true", help="Output structured JSON",
+    )
+
+    gdpr_verify_p = gdpr_sub.add_parser(
+        "verify",
+        help="Verify HMAC integrity of an erasure receipt (exit 0=ok, 1=tampered, 2=not-found)",
+    )
+    gdpr_verify_p.add_argument(
+        "--receipt-id", dest="receipt_id", default=None, metavar="ID",
+        help="Erasure receipt ID to verify",
+    )
+    gdpr_verify_p.add_argument(
+        "--profile", default=None, metavar="PROFILE",
+        help="Scope receipt lookup to a specific profile",
+    )
+    gdpr_verify_p.add_argument(
+        "--json", action="store_true", help="Output structured JSON",
+    )
+
     # Wave-3: operational recovery & admin remediation
     ops_p = sub.add_parser(
         "ops",

package/src/superlocalmemory/cli/summary_cmd.py

@@ -0,0 +1,195 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory | https://qualixar.com
+
+"""``slm summary`` — the readable layer over your memories (issue #113).
+
+WHY THIS FILE EXISTS
+--------------------
+4.0.6 shipped the three generators in ``superlocalmemory/summaries/`` with no way
+to call them: no command, no MCP tool, no route. The changelog listed the feature
+as added, the issue reply said it had landed, and a user could do nothing with it.
+This is that missing surface.
+
+Three summaries, each bounded and traceable:
+
+  ``slm summary session <id>``   what one session covered
+  ``slm summary day [DATE]``     what a day's main topics were
+  ``slm summary project <path>`` what was worked on in a project
+
+Every result states its coverage. Session data in particular is sparse — roughly
+4% of facts carry a session id on a real store — so a session summary reports what
+fraction it could actually see rather than presenting a slice as the whole.
+
+No language model is required: the generators are extractive by default, so this
+works in Local Guardian mode with nothing installed.
+"""
+
+from __future__ import annotations
+
+import json
+from argparse import Namespace
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Any
+
+from superlocalmemory.infra.data_root import state_path
+
+def _coverage_is_complete(coverage: str) -> bool:
+    """Whether *coverage* means "this really is the whole picture".
+
+    Deliberately inverted. My first version listed the values that needed a
+    caveat — ``("partial", "sparse", "none", "empty")`` — and three of those four
+    are not values this system emits. The real vocabulary is COVERAGE_FULL /
+    PARTIAL / INSUFFICIENT / NO_SESSION / UNAVAILABLE, so a session summary
+    reporting "no_session" printed no caveat at all: the one honesty feature
+    issue #113 asked for, silently inactive.
+
+    Testing for completeness instead means any value that is not FULL — including
+    one added later — gets the caveat. The failure mode becomes an unnecessary
+    warning rather than a missing one.
+    """
+    try:
+        from superlocalmemory.summaries.base import COVERAGE_FULL
+
+        return coverage == COVERAGE_FULL
+    except Exception:
+        return coverage == "full"
+
+
+def _db_path() -> Path:
+    return state_path("memory.db")
+
+
+def _active_profile() -> str:
+    """Resolve the active profile without a daemon and without side effects.
+
+    Reads the ``active`` pointer out of ``profiles.json`` directly.
+    ``ProfileManager`` would give the same answer, but its constructor calls
+    ``mkdir(parents=True)`` — creating directories is not something a read-only
+    summary command should do. ``core.profiles`` also has no module-level
+    accessor; ``get_active_profile`` there is a method on the manager, and the
+    module-level one lives in ``server/routes/helpers.py``, which the CLI must
+    not import.
+    """
+    try:
+        from superlocalmemory.core.profiles import DEFAULT_PROFILES_FILE
+
+        path = state_path(DEFAULT_PROFILES_FILE)
+        if path.exists():
+            raw = json.loads(path.read_text(encoding="utf-8"))
+            active = raw.get("active")
+            if isinstance(active, str) and active:
+                return active
+    except Exception:
+        pass
+    return "default"
+
+
+def _emit(result: Any, as_json: bool) -> None:
+    """Print a SummaryResult as JSON or as prose."""
+    if as_json:
+        print(json.dumps({
+            "kind": result.kind,
+            "profile_id": result.profile_id,
+            "content": result.content,
+            "source_fact_ids": result.source_fact_ids,
+            "coverage": result.coverage,
+            "generated_by": result.generated_by,
+            "metadata": result.metadata,
+        }, indent=2, default=str))
+        return
+
+    print()
+    print(result.content.rstrip() or "(nothing recorded)")
+    print()
+
+    # Coverage is not decoration. A summary built from a fraction of the data
+    # that presents itself as the whole is the failure mode issue #113 called
+    # out by name, so it is stated on every single result, not only bad ones.
+    n = len(result.source_fact_ids)
+    line = f"Built from {n} memor{'y' if n == 1 else 'ies'} · coverage: {result.coverage}"
+    if not _coverage_is_complete(result.coverage):
+        line += " — treat as a partial view, not a complete record"
+    print(line)
+    if result.generated_by:
+        print(f"Method: {result.generated_by}")
+    print("Use --json to see the exact memories this came from.")
+
+
+def cmd_summary(args: Namespace) -> None:
+    """Dispatch ``slm summary <subcommand>``."""
+    sub = getattr(args, "summary_command", None)
+    as_json = bool(getattr(args, "json", False))
+    profile = getattr(args, "profile", None) or _active_profile()
+    db = _db_path()
+
+    if not db.exists():
+        print(f"No memory database at {db}. Run `slm status` first.")
+        return
+
+    if sub == "session":
+        from superlocalmemory.summaries import generate_session_summary
+
+        _emit(generate_session_summary(db, args.session_id, profile), as_json)
+        return
+
+    if sub == "day":
+        from superlocalmemory.summaries import generate_daily_reflection
+
+        target = getattr(args, "date", None) or date.today().isoformat()
+        if target == "yesterday":
+            target = (date.today() - timedelta(days=1)).isoformat()
+        elif target == "today":
+            target = date.today().isoformat()
+        _emit(generate_daily_reflection(db, target, profile), as_json)
+        return
+
+    if sub == "project":
+        from superlocalmemory.summaries import generate_project_work_log
+
+        path = getattr(args, "path", None) or str(Path.cwd())
+        _emit(generate_project_work_log(db, path, profile), as_json)
+        return
+
+    print("Usage: slm summary {session <id> | day [DATE] | project [PATH]}")
+    print()
+    print("  slm summary day                 what you recorded today")
+    print("  slm summary day yesterday       ...or yesterday")
+    print("  slm summary day 2026-08-17      ...or a specific date")
+    print("  slm summary project             work log for the current directory")
+    print("  slm summary session <id>        what one session covered")
+    print()
+    print("Add --json to include the ids of the memories a summary came from.")
+
+
+def register_summary_parser(sub: Any) -> None:
+    """Attach the ``summary`` parser. Called from cli/main.py."""
+    p = sub.add_parser(
+        "summary",
+        help="Readable summaries of your memories (session, day, project)",
+    )
+    p.add_argument("--json", action="store_true", help="machine-readable output")
+    p.add_argument("--profile", help="profile to summarise (default: active)")
+    ssub = p.add_subparsers(dest="summary_command", title="summary subcommands")
+
+    s = ssub.add_parser("session", help="what one session covered")
+    s.add_argument("session_id", help="session id (see `slm status`)")
+    s.add_argument("--json", action="store_true")
+    s.add_argument("--profile")
+
+    d = ssub.add_parser("day", help="what a day's main topics were")
+    d.add_argument(
+        "date", nargs="?",
+        help="YYYY-MM-DD, 'today' or 'yesterday' (default: today)",
+    )
+    d.add_argument("--json", action="store_true")
+    d.add_argument("--profile")
+
+    pr = ssub.add_parser("project", help="what was worked on in a project")
+    pr.add_argument(
+        "path", nargs="?",
+        help="project directory (default: current directory)",
+    )
+    pr.add_argument("--json", action="store_true")
+    pr.add_argument("--profile")

package/src/superlocalmemory/code_graph/bridge/entity_resolver.py

@@ -152,9 +152,25 @@ class EntityResolver:
         self,
         fact_text: str,
         fact_id: str,
+        max_links: int | None = None,
     ) -> list[CodeMemoryLink]:
         """Resolve code entity mentions in fact text and create links.
 
+        Args:
+            fact_text: Text to scan for code mentions.
+            fact_id:   The fact these links belong to.
+            max_links: Keep at most this many links, highest confidence first.
+                ``None`` (the default) is unbounded, preserving the behaviour the
+                manual ``link_memory_to_code`` path relies on.
+
+                A bound matters for automatic resolution. One file-path mention
+                matches EVERY node in that file: the fact "the parser in
+                code_graph/parser.py was dropping edges" produced 17 links at
+                confidence 0.6-0.8, while a backticked function name produces one
+                at 0.95. Unbounded, a fact naming a few files buries its own
+                high-signal links and hands a large node set to HebbianLinker,
+                whose neighbourhood expansion then grows accordingly.
+
         Returns list of CodeMemoryLink objects created.
         """
         if not fact_text or not fact_id:
@@ -177,6 +193,16 @@ class EntityResolver:
         if not matches:
             return []
 
+        selected = list(matches.values())
+        if max_links is not None and len(selected) > max_links:
+            # Confidence ranks the match kinds correctly already — backticked and
+            # call-syntax mentions score 0.95, a bare identifier 0.9, file-path
+            # fan-out 0.6-0.8 — so ordering by it keeps the precise mentions and
+            # drops the broad ones.
+            selected.sort(key=lambda m: m.confidence, reverse=True)
+            selected = selected[:max_links]
+            matches = {m.node_id: m for m in selected}
+
         # Classify link type
         link_type = self._classify_link_type(fact_text)
         now_str = datetime.now(timezone.utc).isoformat()

package/src/superlocalmemory/code_graph/bridge/event_listeners.py

@@ -57,12 +57,23 @@ class BridgeEventListeners:
         return self._started
 
     def start(self, event_bus: Any) -> None:
-        """Register all listeners on the event bus.
+        """Register code-graph listeners on the event bus.
 
         Registers:
-        - on_memory_stored: listens to "memory.stored"
         - on_code_node_deleted: listens to "code_graph.node_deleted"
         - on_code_node_changed: listens to "code_graph.node_changed"
+
+        DELIBERATELY NOT REGISTERED: ``on_memory_stored``.
+        ``EventBus._notify_listeners`` invokes every listener synchronously on
+        the emitting thread, so subscribing to ``memory.stored`` would run entity
+        resolution, enrichment and Hebbian linking inside each ``remember`` —
+        putting all three on the write path. That work now runs in background
+        maintenance instead; see ``code_graph.bridge.maintenance``.
+
+        ``on_memory_stored`` is kept as a callable so a caller that genuinely
+        wants synchronous linking for one fact can invoke it directly, but
+        nothing subscribes it to the bus. ``tests/test_code_graph/
+        test_bridge_off_write_path.py`` fails if that changes.
         """
         if self._started:
             logger.warning("BridgeEventListeners already started")
@@ -70,8 +81,8 @@ class BridgeEventListeners:
 
         self._event_bus = event_bus
 
+        # Both events are emitted by code-graph builds, never by memory writes.
         listeners: list[tuple[str, Callable[..., Any]]] = [
-            ("memory.stored", self.on_memory_stored),
             ("code_graph.node_deleted", self.on_code_node_deleted),
             ("code_graph.node_changed", self.on_code_node_changed),
         ]