superlocalmemory 3.7.8 → 3.8.0

package/src/superlocalmemory/loops/ledger.py

@@ -0,0 +1,243 @@
+"""Durable, queryable ledger for bounded-loop runs.
+
+Every lap produces one append-only :class:`LedgerEntry`. A ledger persists
+those entries so a run can be inspected, resumed, and audited after the fact.
+
+Two implementations ship:
+
+* :class:`InMemoryLedger` — a dict-backed store used by tests and as a safe
+  fallback when no SLM data root is available.
+* :class:`SLMMemoryLedger` — the real backend. It writes each lap through a
+  SuperLocalMemory engine so the ledger *is* memory: queryable via ``slm
+  recall``, visible in the dashboard, and resumable across sessions. This is
+  what makes SLM's take on bounded loops distinct — the loop's history lives
+  in the same durable store as everything else the agent remembers.
+
+The engine-backed store mirrors the exact profile-scoped SQL contract the
+shipped framework adapters already rely on, so it stays valid as the engine
+evolves.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+LEDGER_TAG = "slm-loop"
+_LEDGER_IMPORTANCE = 2  # below ordinary user memories so laps never crowd recall
+_SESSION_PREFIX = "loop:"
+
+
+@dataclass(frozen=True)
+class LedgerEntry:
+    """One immutable row recording what happened on a single lap."""
+
+    run_id: str
+    name: str
+    lap: int
+    ts: str
+    decision: str  # continue | done | halt | pause | killed | error
+    passed: bool
+    detail: str
+    # The runner's own claim (audit-only; never terminates the loop) + its log.
+    agent_claimed_done: bool = False
+    runner_log: str = ""
+    budget: dict[str, Any] = field(default_factory=dict)
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), ensure_ascii=False, separators=(",", ":"))
+
+    @classmethod
+    def from_json(cls, text: str) -> "LedgerEntry | None":
+        try:
+            data = json.loads(text)
+        except (TypeError, json.JSONDecodeError):
+            return None
+        if not isinstance(data, dict) or "run_id" not in data or "lap" not in data:
+            return None
+        return cls(
+            run_id=str(data.get("run_id", "")),
+            name=str(data.get("name", "")),
+            lap=int(data.get("lap", 0)),
+            ts=str(data.get("ts", "")),
+            decision=str(data.get("decision", "")),
+            passed=bool(data.get("passed", False)),
+            detail=str(data.get("detail", "")),
+            agent_claimed_done=bool(data.get("agent_claimed_done", False)),
+            runner_log=str(data.get("runner_log", "")),
+            budget=data.get("budget") if isinstance(data.get("budget"), dict) else {},
+        )
+
+
+@runtime_checkable
+class LedgerStore(Protocol):
+    """Append-only audit trail keyed by run."""
+
+    def record(self, entry: LedgerEntry) -> None: ...
+    def laps(self, run_id: str) -> list[LedgerEntry]: ...
+    def runs(self, name: str) -> list[str]: ...
+
+
+class InMemoryLedger:
+    """Process-local ledger. Never raises; ideal for tests and offline demos."""
+
+    def __init__(self) -> None:
+        self._by_run: dict[str, list[LedgerEntry]] = {}
+
+    def record(self, entry: LedgerEntry) -> None:
+        self._by_run.setdefault(entry.run_id, []).append(entry)
+
+    def laps(self, run_id: str) -> list[LedgerEntry]:
+        return list(self._by_run.get(run_id, ()))
+
+    def runs(self, name: str) -> list[str]:
+        seen: list[str] = []
+        for run_id, entries in self._by_run.items():
+            if entries and entries[0].name == name and run_id not in seen:
+                seen.append(run_id)
+        return seen
+
+
+class SLMMemoryLedger:
+    """Ledger backed by a SuperLocalMemory engine store.
+
+    ``store`` is any object exposing ``add(content, *, session_id, metadata)``,
+    ``list_session(session_id)`` and ``list_prefix(prefix)`` — the small
+    contract :func:`open_engine_store` provides. Injecting it keeps this class
+    free of engine-construction concerns and trivially testable with a fake.
+    """
+
+    def __init__(self, store: Any) -> None:
+        self._store = store
+
+    @staticmethod
+    def _session_id(run_id: str) -> str:
+        return f"{_SESSION_PREFIX}{run_id}"
+
+    def record(self, entry: LedgerEntry) -> None:
+        self._store.add(
+            entry.to_json(),
+            session_id=self._session_id(entry.run_id),
+            metadata={
+                "integration": "slm-loop",
+                "loop_name": entry.name,
+                "loop_run_id": entry.run_id,
+                "loop_lap": entry.lap,
+                "loop_decision": entry.decision,
+                "tags": [LEDGER_TAG, f"loop:{entry.name}"],
+                "importance": _LEDGER_IMPORTANCE,
+                "project_name": "slm-loop",
+            },
+        )
+
+    def laps(self, run_id: str) -> list[LedgerEntry]:
+        rows = self._store.list_session(self._session_id(run_id))
+        entries = [LedgerEntry.from_json(r.get("content", "")) for r in rows]
+        return [e for e in entries if e is not None]
+
+    def runs(self, name: str) -> list[str]:
+        """Run ids for ``name``, newest run first.
+
+        ``list_prefix`` returns rows created_at DESC, so the first time a run's
+        id is seen it is its most-recent lap; ``slm loop history`` therefore
+        lists the most recent runs first.
+        """
+        rows = self._store.list_prefix(_SESSION_PREFIX)
+        ordered: list[str] = []
+        for row in rows:
+            entry = LedgerEntry.from_json(row.get("content", ""))
+            if entry is not None and entry.name == name and entry.run_id not in ordered:
+                ordered.append(entry.run_id)
+        return ordered
+
+
+class _EngineLedgerStore:
+    """Minimal profile-scoped store over a SuperLocalMemory engine.
+
+    Uses ``MemoryEngine.store`` for writes and direct, escaped, profile-scoped
+    reads — the same contract the LangChain/LlamaIndex adapters depend on.
+    """
+
+    def __init__(self, engine: Any, *, owns_engine: bool = True) -> None:
+        self._engine = engine
+        # When False, this store does NOT own the engine's lifecycle (the
+        # caller — e.g. the MCP daemon — keeps it), so close() must not tear
+        # down a shared engine. open_engine_store() passes True (it built the
+        # engine); engine_backed_ledger() passes False (daemon-owned engine).
+        self._owns_engine = owns_engine
+
+    def add(self, content: str, *, session_id: str, metadata: dict) -> None:
+        # The parent memory row is what the ledger needs; fact extraction is a
+        # bonus, so (unlike chat history) an empty fact set is not an error.
+        self._engine.store(content, session_id=session_id, metadata=metadata)
+
+    def list_session(self, session_id: str) -> list[dict]:
+        # Cap the read: a bounded-loop run is capped at max_iterations laps, so
+        # a legitimate run is small; the LIMIT stops a pathologically long
+        # session_id from forcing an unbounded materialization on every
+        # `slm loop show` / history lookup.
+        rows = self._engine.db.execute(
+            "SELECT content, created_at FROM memories "
+            "WHERE profile_id=? AND session_id=? "
+            "ORDER BY created_at ASC, rowid ASC LIMIT 5000",
+            (self._engine.profile_id, session_id),
+        )
+        return [dict(row) for row in rows]
+
+    def list_prefix(self, prefix: str) -> list[dict]:
+        escaped = prefix.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        # Cap the scan so a long-lived, high-volume ledger can't force an
+        # unbounded read on `slm loop history`.
+        rows = self._engine.db.execute(
+            "SELECT content, created_at FROM memories "
+            "WHERE profile_id=? AND session_id LIKE ? ESCAPE '\\' "
+            "ORDER BY created_at DESC, rowid DESC LIMIT 5000",
+            (self._engine.profile_id, escaped + "%"),
+        )
+        return [dict(row) for row in rows]
+
+    def close(self) -> None:
+        if self._owns_engine:
+            self._engine.close()
+
+
+def engine_backed_ledger(engine: Any) -> SLMMemoryLedger:
+    """Build an SLM-backed ledger over an ALREADY-OPEN engine.
+
+    Unlike :func:`open_engine_store`, this neither creates nor owns the engine —
+    the caller (e.g. the MCP daemon, which keeps one long-lived engine per
+    profile) retains full ownership and lifecycle. The returned ledger never
+    closes the engine, so it is safe to build one per tool call. The engine's
+    per-call, WAL-mode connection model makes the ledger's reads/writes safe
+    from a worker thread.
+    """
+    return SLMMemoryLedger(_EngineLedgerStore(engine, owns_engine=False))
+
+
+def open_engine_store(db_path: str | Path) -> _EngineLedgerStore:
+    """Build an engine-backed ledger store rooted at ``db_path``.
+
+    Raises ``ImportError`` with an install hint if the SLM runtime is missing.
+    """
+    from dataclasses import replace
+
+    try:
+        from superlocalmemory.core.config import SLMConfig
+        from superlocalmemory.core.engine import MemoryEngine
+        from superlocalmemory.storage.models import Mode
+    except ImportError as exc:  # pragma: no cover - defensive
+        raise ImportError(
+            "SuperLocalMemory runtime is required for the SLM-backed loop "
+            "ledger. Install it with: python -m pip install superlocalmemory."
+        ) from exc
+
+    path = Path(db_path).expanduser().resolve()
+    config = SLMConfig.for_mode(Mode.A, base_dir=path.parent)
+    config.db_path = path
+    config.forgetting = replace(config.forgetting, enabled=False)
+    config.retrieval.use_cross_encoder = False
+    engine = MemoryEngine(config)
+    engine.initialize()
+    return _EngineLedgerStore(engine)

package/src/superlocalmemory/loops/models.py

@@ -0,0 +1,152 @@
+"""Immutable value types for SuperLocalMemory bounded loops.
+
+A *bounded loop* is an agent loop that terminates when an independent gate
+passes — never when the agent claims it is finished. This module holds the
+pure data types the loop engine reasons over.
+
+Design rules (kept deliberately strict):
+  * Standard-library imports only. No I/O, no framework, no side effects.
+  * Every dataclass is ``frozen=True`` — any attribute mutation raises
+    ``TypeError`` at runtime, so a lap result cannot be rewritten after the
+    gate has judged it.
+  * Timestamps are ISO-8601 strings supplied by the engine's clock, never
+    produced here with ``datetime.now()``.
+
+This is SuperLocalMemory's own realization of the bounded-loop concept; the
+loop-control discipline it encodes (gate-verified termination, enforced
+bounds, an advisory-only agent claim) is a general practice, reimplemented
+here against SLM's durable memory rather than a flat file.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class Rung(str, Enum):
+    """Autonomy rung governing how much a human stays in the loop.
+
+    ``L1`` report      — a human reads every verdict; the loop still exits on
+                         a passing gate but nothing is auto-approved.
+    ``L2`` assisted     — the agent acts but pauses for human approval before a
+                         passing gate is accepted as DONE.
+    ``L3`` unattended   — the agent acts autonomously; approval is derived from
+                         the bounds alone.
+
+    Subclassing ``(str, Enum)`` makes ``Rung.L2 == "L2"`` true and
+    ``Rung("L2")`` reconstruct the member, so a rung round-trips through JSON
+    or a CLI argument without a hand-written lookup table.
+    """
+
+    L1 = "L1"
+    L2 = "L2"
+    L3 = "L3"
+
+
+class Status(str, Enum):
+    """Terminal status of a bounded-loop run.
+
+    ``DONE``   — the gate passed and approval was granted or not required.
+    ``HALT``   — a safety bound tripped (iteration cap, no progress, budget).
+    ``PAUSE``  — the gate passed but required approval was not granted.
+    ``KILLED`` — an external kill switch tripped between laps.
+    ``ERROR``  — the runner or gate raised before a verdict was produced.
+    """
+
+    DONE = "DONE"
+    HALT = "HALT"
+    PAUSE = "PAUSE"
+    KILLED = "KILLED"
+    ERROR = "ERROR"
+
+
+@dataclass(frozen=True)
+class Bounds:
+    """The safety envelope a loop runs inside.
+
+    ``max_iterations``     hard cap on laps; required and must be >= 1.
+    ``no_progress_window`` consecutive no-change laps that trigger a HALT.
+    ``max_tokens``         cumulative token budget across laps, or ``None``.
+    ``max_wallclock_s``    wall-clock ceiling in seconds, or ``None``.
+    ``require_approval``    ``True``/``False`` forces the approval posture;
+                           ``None`` derives it from the rung (L1 -> no
+                           approval, L2/L3 -> approval required).
+    """
+
+    max_iterations: int
+    no_progress_window: int = 3
+    max_tokens: Optional[int] = None
+    max_wallclock_s: Optional[float] = None
+    require_approval: Optional[bool] = None
+
+    def __post_init__(self) -> None:
+        if self.max_iterations < 1:
+            raise ValueError("max_iterations must be >= 1")
+        if self.no_progress_window < 0:
+            raise ValueError("no_progress_window must be >= 0")
+        if self.max_tokens is not None and self.max_tokens < 0:
+            raise ValueError("max_tokens must be >= 0 when set")
+        if self.max_wallclock_s is not None and self.max_wallclock_s < 0:
+            raise ValueError("max_wallclock_s must be >= 0 when set")
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """The independent gate's judgement of a single lap.
+
+    ``passed``   True only when the gate mechanically confirmed the goal.
+    ``detail``   human-readable one-line summary (required, non-empty).
+    ``evidence`` structured gate output (counts, tails, diffs). Defaults to a
+                 fresh dict per instance via ``default_factory`` so verdicts do
+                 not share one mutable dict.
+
+    ``passed=True`` is necessary but not sufficient for the loop to exit; the
+    engine still consults the approval rung.
+    """
+
+    passed: bool
+    detail: str
+    evidence: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class LapResult:
+    """What the runner reports after proposing one lap of work.
+
+    ``changed``            True if the runner altered the workspace/state.
+    ``agent_claimed_done`` the agent's own "I am finished" signal. Recorded for
+                           audit and **never** used to terminate the loop — the
+                           gate is the sole authority.
+    ``tokens``             tokens spent this lap (0 when unknown).
+    ``log``                short runner log for the lap.
+    """
+
+    changed: bool
+    agent_claimed_done: bool = False
+    tokens: int = 0
+    log: str = ""
+
+
+@dataclass(frozen=True)
+class Outcome:
+    """The final result of a bounded-loop run.
+
+    ``status``   terminal status.
+    ``reason``   short machine-friendly explanation ("gate-passed",
+                 "no-progress", "max-iterations", "awaiting-approval",
+                 "killed", or a gate/runner error string).
+    ``laps``     number of laps executed at termination.
+    ``run_id``   identifier used to locate this run's ledger in SLM memory.
+    """
+
+    status: Status
+    reason: str
+    laps: int
+    run_id: str
+
+    @property
+    def ok(self) -> bool:
+        """True only for a DONE outcome — the single success state."""
+        return self.status is Status.DONE

package/src/superlocalmemory/loops/rules.py

@@ -0,0 +1,52 @@
+"""Pure decision predicates for the bounded-loop engine.
+
+Every function here is a pure function of its arguments: same inputs give the
+same output, and nothing is mutated. The engine calls these to decide whether
+to stop, halt, or keep going; adapters never call them directly.
+
+Imports are limited to the standard library and the loop models.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from superlocalmemory.loops.models import Bounds, Rung, Verdict
+
+
+def stop_condition_met(verdict: Verdict) -> bool:
+    """Return True when the gate verdict means the loop may exit.
+
+    The rule is deliberately conservative: a loop is eligible to finish only
+    when the independent gate reports ``passed``. The agent's own opinion is
+    never consulted here — it is not even an argument.
+    """
+    return verdict.passed
+
+
+def no_progress(lap_changes: Sequence[bool], window: int) -> bool:
+    """Return True when the last ``window`` laps all made no change.
+
+    ``lap_changes`` is the ordered history of each lap's ``changed`` flag,
+    most-recent last. A window of ``0`` disables the check (a spinning agent
+    is then bounded only by the iteration cap). Fewer laps than the window
+    means "not enough evidence yet" and returns False.
+    """
+    if window <= 0:
+        return False
+    tail = lap_changes[-window:]
+    if len(tail) < window:
+        return False
+    return all(changed is False for changed in tail)
+
+
+def rung_requires_approval(rung: Rung, bounds: Bounds) -> bool:
+    """Return True when a human must approve a passing gate before DONE.
+
+    An explicit ``bounds.require_approval`` wins outright. When it is ``None``
+    the posture is derived from the rung: L1 exits without approval, while
+    L2 and L3 require it.
+    """
+    if bounds.require_approval is not None:
+        return bounds.require_approval
+    return rung in (Rung.L2, Rung.L3)

package/src/superlocalmemory/mcp/_daemon_proxy.py

@@ -43,6 +43,7 @@ class DaemonPoolProxy:
         fast: bool = False,
         include_global: bool | None = None,
         include_shared: bool | None = None,
+        window: str | None = None,
     ) -> dict[str, Any]:
         _params: dict[str, Any] = {
             "q": query,
@@ -57,6 +58,8 @@ class DaemonPoolProxy:
             _params["include_global"] = "true" if include_global else "false"
         if include_shared is not None:
             _params["include_shared"] = "true" if include_shared else "false"
+        if window:
+            _params["window"] = window
         params = urllib.parse.urlencode(_params)
         try:
             from superlocalmemory.cli.daemon import daemon_request

package/src/superlocalmemory/mcp/_pool_adapter.py

@@ -104,6 +104,8 @@ def pool_recall(query: str, limit: int = 10, **kwargs: Any) -> PoolRecallRespons
         _recall_kwargs["include_global"] = kwargs["include_global"]
     if "include_shared" in kwargs:
         _recall_kwargs["include_shared"] = kwargs["include_shared"]
+    if kwargs.get("window"):
+        _recall_kwargs["window"] = kwargs["window"]
     raw = _pool().recall(**_recall_kwargs)
     _unwrap_error(raw, "recall")
     items = raw.get("results", []) if isinstance(raw, dict) else []

package/src/superlocalmemory/mcp/profiles.py

@@ -0,0 +1,103 @@
+# 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
+
+"""MCP profile definitions — pure data, no side effects.
+
+Extracted from mcp/server.py (v3.8.0) so the daemon can import profile
+metadata without triggering FastMCP tool registration or engine warmup.
+
+server.py re-exports all names from this module for backward compatibility.
+Do NOT import FastMCP, MemoryEngine, or any heavy dependency here.
+"""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# v3.6.14 WP-01: Named profile definitions
+# ---------------------------------------------------------------------------
+
+_PROFILE_CORE: frozenset[str] = frozenset({  # 14
+    "remember", "recall", "search", "fetch", "list_recent", "update_memory", "forget",
+    "session_init", "close_session",
+    "slm_compress", "slm_retrieve", "slm_cache_set", "slm_cache_get", "slm_optimize_stats",
+})
+
+_PROFILE_CODE: frozenset[str] = _PROFILE_CORE | frozenset({  # 24
+    "build_code_graph", "get_blast_radius", "query_graph",
+    "semantic_search_code", "get_review_context", "detect_changes",
+    # switch_profile lets a plugin/IDE session change the active workspace over
+    # MCP (the plugin ships SLM_MCP_PROFILE=code, so it must be here). The
+    # underlying route is RBAC member-gated, so company-mode isolation holds.
+    "switch_profile",
+    # v3.8.0: bounded loops on the MCP surface. Coding agents (the /slm-loop
+    # command's audience) run gated, bounded loops and inspect the ledger.
+    "slm_loop_run", "slm_loop_history", "slm_loop_show",
+})
+
+_PROFILE_FULL_MESH: frozenset[str] = frozenset({  # 8
+    "mesh_summary", "mesh_peers", "mesh_send", "mesh_inbox",
+    "mesh_state", "mesh_lock", "mesh_events", "mesh_status",
+})
+
+_PROFILE_FULL: frozenset[str] = frozenset({  # 34 base — EXPLICIT literal, NOT runtime _ESSENTIAL_TOOLS (OQ-2)
+    "remember", "recall", "search", "fetch", "list_recent", "delete_memory", "update_memory",
+    "get_status", "session_init", "observe", "close_session", "report_feedback", "forget",
+    "run_maintenance", "consolidate_cognitive", "get_soft_prompts", "set_mode", "report_outcome",
+    "log_tool_event", "get_assertions", "reinforce_assertion", "contradict_assertion",
+    "evolve_skill", "skill_health", "skill_lineage", "switch_profile",
+    "slm_compress", "slm_retrieve", "slm_cache_set", "slm_cache_get", "slm_optimize_stats",
+    # v3.8.0: bounded-loop tools (CLI + /slm-loop command + MCP).
+    "slm_loop_run", "slm_loop_history", "slm_loop_show",
+}) | _PROFILE_FULL_MESH  # 42
+
+_PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 54
+    "get_version", "get_mode", "health", "consistency_check", "recall_trace",
+    "get_lifecycle_status", "set_retention_policy", "compact_memories",
+    "get_behavioral_patterns", "audit_trail", "quantize", "get_retention_stats",
+})
+
+_PROFILE_MESH: frozenset[str] = _PROFILE_FULL_MESH  # 8
+
+# Canonical name → frozenset mapping.  "whole" is intentionally absent —
+# it maps to the raw server (all tools, D-2 LOCKED).
+_PROFILE_DEFINITIONS: dict[str, frozenset[str]] = {
+    "core": _PROFILE_CORE,
+    "code": _PROFILE_CODE,
+    "full": _PROFILE_FULL,
+    "power": _PROFILE_POWER,
+    "mesh": _PROFILE_MESH,
+}
+
+# Compatibility aliases published by the v3.6 README.  Stale client
+# configurations have one deterministic meaning; migration warnings fire
+# at server startup.  Any other value is a configuration error (fail closed).
+_PROFILE_ALIASES: dict[str, str] = {
+    "core14": "core",
+    # 3.8.0: switch_profile (+1) then bounded-loop tools (+3) grew code/full/
+    # power. Every historical count-suffixed name is kept so a v3.6/3.7/early-
+    # 3.8 config still resolves (back-compat); new 3.8.0 counts added alongside.
+    "code20": "code",
+    "code21": "code",
+    "code24": "code",
+    "full38": "full",
+    "full39": "full",
+    "full42": "full",
+    "power50": "power",
+    "power51": "power",
+    "power54": "power",
+    "mesh8": "mesh",
+    "whole81": "whole",
+    "whole84": "whole",
+}
+
+# Plain-English descriptions for UI display.
+# Rules: no internal jargon (no POMDP, Fisher-Rao, TurboQuant, etc.),
+# one sentence, user-facing language only.
+PROFILE_DESCRIPTIONS: dict[str, str] = {
+    "core": "Essential memory: store, recall, search, sessions",
+    "code": "Core + code-graph tools + profile switching (default for IDE coding agents)",
+    "full": "All everyday memory, optimization, and mesh tools",
+    "power": "Everything in full plus advanced governance/behavioral tools",
+    "mesh": "Cross-device mesh coordination only",
+}