superlocalmemory 4.1.6 → 4.1.7

package/src/superlocalmemory/hooks/codex_assets.py

@@ -2,6 +2,9 @@
 
 from __future__ import annotations
 
+import hashlib
+import json
+import re
 import shutil
 import sysconfig
 from pathlib import Path
@@ -24,11 +27,31 @@ SKILLS = (
 # Codex subagent files written to ~/.codex/agents (content built by _agent_files()).
 AGENTS = ("slm-memory-advisor.toml", "slm-optimize-advisor.toml")
 
-_MEMORY_ADVISOR_TOML = (
-    'name = "slm-memory-advisor"\n'
-    'description = "Use SuperLocalMemory safely: initialize once, recall before remember, and store only durable atomic facts."\n'
-    'instructions = "Use SLM for memory discipline only. Check results before claiming success; preserve private scope unless the user explicitly asks to share."\n'
-)
+#: Digests of the agent files this installer last wrote, kept beside them.  An
+#: agent file whose current content still matches its recorded digest is ours to
+#: refresh; anything else belongs to whoever changed it and is left alone.  A
+#: file with no recorded digest predates this manifest and is treated as theirs,
+#: which is the safe reading: this installer once replaced two hand-maintained
+#: 4.9 KB advisors with its own one-line stubs and there was nothing to restore
+#: from.
+MANIFEST_NAME = ".slm-managed.json"
+
+#: Used only when the advisor source document is unavailable — an installation
+#: that ships no agent sources still gets a usable, if terse, subagent.
+_FALLBACKS = {
+    "slm-memory-advisor.toml": (
+        "Use SuperLocalMemory safely: initialize once, recall before remember, "
+        "and store only durable atomic facts.",
+        "Use SLM for memory discipline only. Check results before claiming success; "
+        "preserve private scope unless the user explicitly asks to share.",
+    ),
+    "slm-optimize-advisor.toml": (
+        "Apply SuperLocalMemory's no-proxy context-optimization rules — reversible "
+        "compression of large tool output and KV-caching of repeated reads/searches.",
+        "Reduce context-window pressure with the Surface-B tools (reversible CCR "
+        "compression + a per-agent KV cache); fail-open — never block the task.",
+    ),
+}
 
 
 def _source_root() -> Path:
@@ -49,67 +72,164 @@ def _agents_source_root() -> Path | None:
     return installed if installed.exists() else None
 
 
-def _optimize_advisor_toml() -> str:
-    """Build the optimize-advisor TOML from the canonical advisor doc so Codex
-    ships the FULL decision rules (the 8-rule tree), not a one-line stub. Falls
-    back to a short instruction only if the source doc is unavailable.
+def _split_frontmatter(text: str) -> tuple[str, str]:
+    """Return (frontmatter, body); frontmatter is "" when the doc has none."""
+    if not text.startswith("---"):
+        return "", text.strip()
+    end = text.find("\n---", 3)
+    if end == -1:
+        return "", text.strip()
+    return text[3:end], text[end + 4:].strip()
+
+
+def _description(frontmatter: str, default: str) -> str:
+    """Read `description:`, joining YAML folded (`>`) blocks onto one line."""
+    folded = re.search(r"^description:\s*>[-+]?\s*\n((?:[ \t]+\S.*\n?)+)", frontmatter, re.M)
+    if folded:
+        return " ".join(line.strip() for line in folded.group(1).splitlines() if line.strip())
+    inline = re.search(r"^description:\s*(\S.*)$", frontmatter, re.M)
+    return inline.group(1).strip() if inline else default
+
+
+def _agent_toml(filename: str) -> str:
+    """Build one subagent's TOML, preferring the canonical advisor document so
+    Codex ships the advisor's full decision rules rather than a summary of them.
     """
-    description = (
-        "Apply SuperLocalMemory's no-proxy context-optimization rules — reversible "
-        "compression of large tool output and KV-caching of repeated reads/searches."
-    )
-    body = ""
+    name = filename.removesuffix(".toml")
+    default_description, default_body = _FALLBACKS[filename]
+    description, body = default_description, default_body
+
     root = _agents_source_root()
     if root is not None:
-        src = root / "slm-optimize-advisor.md"
-        if src.exists():
-            text = src.read_text(encoding="utf-8")
-            if text.startswith("---"):  # strip YAML frontmatter, keep the guidance body
-                end = text.find("\n---", 3)
-                if end != -1:
-                    text = text[end + 4:]
-            body = text.strip()
-    if not body:
-        body = (
-            "Reduce context-window pressure with the Surface-B tools (reversible CCR "
-            "compression + a per-agent KV cache); fail-open — never block the task."
-        )
-    # TOML literal multi-line string ('''...'''): no escape processing, and the
-    # advisor body contains no ''' sequence.
-    return (
-        'name = "slm-optimize-advisor"\n'
-        f'description = "{description}"\n'
-        f"instructions = '''\n{body}\n'''\n"
-    )
+        source = root / f"{name}.md"
+        if source.exists():
+            frontmatter, source_body = _split_frontmatter(source.read_text(encoding="utf-8"))
+            if source_body:
+                description = _description(frontmatter, default_description)
+                body = source_body
+
+    # description is a TOML basic string, so quotes and backslashes must be
+    # escaped — the advisor descriptions really do contain quoted questions.
+    escaped = description.replace("\\", "\\\\").replace('"', '\\"')
+    # A literal multi-line string ('''...''') performs no escape processing,
+    # which keeps the advisor markdown byte-exact.  It cannot contain the
+    # sequence that closes it, so fall back to an escaped basic string in that
+    # case rather than editing the advisor's own text.
+    if "'''" in body:
+        basic = body.replace("\\", "\\\\").replace('"', '\\"')
+        instructions = '"""\n' + basic + '\n"""'
+    else:
+        instructions = "'''\n" + body + "\n'''"
+    return f'name = "{name}"\ndescription = "{escaped}"\ninstructions = {instructions}\n'
 
 
 def _agent_files() -> dict:
     """Return {filename: TOML content} for the Codex subagents."""
-    return {
-        "slm-memory-advisor.toml": _MEMORY_ADVISOR_TOML,
-        "slm-optimize-advisor.toml": _optimize_advisor_toml(),
-    }
+    return {filename: _agent_toml(filename) for filename in AGENTS}
+
+
+def _digest(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
 
+def _read_manifest(agents_root: Path) -> dict:
+    try:
+        loaded = json.loads((agents_root / MANIFEST_NAME).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return loaded if isinstance(loaded, dict) else {}
 
-def install_assets(*, home: Path | None = None, dry_run: bool = False) -> dict:
-    """Copy only named SLM assets; never rewrite user-owned assets."""
+
+def _is_ours(target: Path, manifest: dict) -> bool:
+    """True when this installer may overwrite `target`.
+
+    Either it does not exist yet, or its content is byte-identical to what this
+    installer last recorded writing there.
+    """
+    if not target.exists():
+        return True
+    recorded = manifest.get(target.name)
+    if not recorded:
+        return False
+    try:
+        return _digest(target.read_text(encoding="utf-8")) == recorded
+    except OSError:
+        return False
+
+
+def _skills_read_elsewhere(home: Path, skills_root: Path) -> list[str]:
+    """Skill paths Codex may read that this installer does not write.
+
+    Some setups point ~/.codex/skills/<name> at a checkout instead of using the
+    copies under ~/.agents/skills, in which case writing the copies refreshes
+    nothing Codex will load.  Report those paths so the caller can say so rather
+    than claiming a refresh it did not perform.
+    """
+    elsewhere = []
+    for skill in SKILLS:
+        candidate = home / ".codex" / "skills" / skill
+        if not candidate.exists() and not candidate.is_symlink():
+            continue
+        resolved = candidate.resolve() if candidate.is_symlink() else candidate
+        if resolved != (skills_root / skill).resolve():
+            elsewhere.append(str(candidate))
+    return elsewhere
+
+
+def install_assets(*, home: Path | None = None, dry_run: bool = False, force: bool = False) -> dict:
+    """Copy only named SLM assets; never rewrite user-owned assets.
+
+    An agent file that this installer did not write, or that has been edited
+    since it did, is preserved and reported under ``agents_preserved`` rather
+    than overwritten.  Pass ``force=True`` to overwrite anyway, which first
+    copies the existing file aside with a ``.bak`` suffix.
+    """
     home = home or Path.home()
     source = _source_root()
     missing = [skill for skill in SKILLS if not (source / skill / "SKILL.md").exists()]
     if missing:
         return {"success": False, "errors": [f"missing bundled skills: {', '.join(missing)}"]}
-    if dry_run:
-        return {"success": True, "skills": list(SKILLS), "agents": list(AGENTS), "dry_run": True}
+
     skills_root, agents_root = home / ".agents" / "skills", home / ".codex" / "agents"
+    manifest = _read_manifest(agents_root)
+    planned = _agent_files()
+
+    writable, preserved = [], []
+    for filename, content in planned.items():
+        target = agents_root / filename
+        if force or _is_ours(target, manifest):
+            writable.append((filename, content, target))
+        else:
+            preserved.append(str(target))
+
+    skill_targets = [skills_root / skill / "SKILL.md" for skill in SKILLS]
+    result = {
+        "success": True,
+        "dry_run": dry_run,
+        "skills": list(SKILLS),
+        "agents": [filename for filename, _, _ in writable],
+        "skills_written": [str(path) for path in skill_targets],
+        "agents_written": [str(target) for _, _, target in writable],
+        "agents_preserved": preserved,
+        "skills_read_elsewhere": _skills_read_elsewhere(home, skills_root),
+    }
+    if dry_run:
+        return result
+
     skills_root.mkdir(parents=True, exist_ok=True)
     agents_root.mkdir(parents=True, exist_ok=True)
     for skill in SKILLS:
         target = skills_root / skill
         target.mkdir(parents=True, exist_ok=True)
         shutil.copy2(source / skill / "SKILL.md", target / "SKILL.md")
-    for filename, content in _agent_files().items():
-        (agents_root / filename).write_text(content, encoding="utf-8")
-    return {"success": True, "skills": list(SKILLS), "agents": list(AGENTS), "dry_run": False}
+    for filename, content, target in writable:
+        if force and target.exists():
+            shutil.copy2(target, target.with_suffix(target.suffix + ".bak"))
+        target.write_text(content, encoding="utf-8")
+        manifest[filename] = _digest(content)
+    if writable:
+        (agents_root / MANIFEST_NAME).write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+    return result
 
 
 def remove_assets(*, home: Path | None = None, dry_run: bool = False) -> dict:

package/src/superlocalmemory/learning/bandit.py

@@ -326,9 +326,20 @@ class ContextualBandit:
         play_id: int,
         reward: float,
         kind: str = "proxy_position",
+        weight: float = 1.0,
     ) -> bool:
         """Apply the reward to the (profile, stratum, arm) posterior.
 
+        ``weight`` scales how much this one observation counts, and exists for
+        inverse-propensity correction: the policy chose what was shown, so an
+        arm it almost always shows produces weak evidence whatever happens to
+        it, while one it rarely shows produces strong evidence. Weighting by
+        the inverse of that probability is what keeps the posterior from
+        recording popularity the policy manufactured. See ``propensity.py``.
+
+        A weight of 1.0 is the uncorrected update and the default, so a caller
+        with no competitor posteriors to estimate against changes nothing.
+
         Returns True on success. Never raises — DB failures logged at WARN.
         Cache invalidated on success (B5).
         """
@@ -343,6 +354,15 @@ class ContextualBandit:
         elif reward_f > 1.0:
             reward_f = 1.0
 
+        try:
+            weight_f = float(weight)
+        except (TypeError, ValueError):
+            weight_f = 1.0
+        # A non-positive weight would either freeze the arm or subtract
+        # evidence; neither is a meaningful observation.
+        if weight_f <= 0.0:
+            weight_f = 1.0
+
         try:
             conn = _conn_for(self._db_path)
         except sqlite3.Error as exc:  # pragma: no cover — defensive
@@ -389,8 +409,8 @@ class ContextualBandit:
                 "    plays = plays + 1, "
                 "    last_played_at = ? "
                 "WHERE profile_id = ? AND stratum = ? AND arm_id = ?",
-                (cap, reward_f, cap, 1.0 - reward_f, now,
-                 profile_id, stratum, arm_id),
+                (cap, weight_f * reward_f, cap, weight_f * (1.0 - reward_f),
+                 now, profile_id, stratum, arm_id),
             )
             conn.execute(
                 "UPDATE bandit_plays "

package/src/superlocalmemory/learning/engagement_features.py

@@ -0,0 +1,279 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Engagement observed from what an agent did, not from what it was asked to say.
+
+WHY THIS EXISTS
+---------------
+The reward ladder in ``reward_proxy`` asks one question — did a recalled
+``fact_id`` appear verbatim in a later tool event — and defaults to ``0.5`` when
+the answer is no. Both halves of that are broken.
+
+The question requires the caller to copy an opaque marker into its next tool
+call. Nothing makes it: no tool description asks for it and no rule requires
+it. A design that depends on a behaviour nothing produces has no signal, and
+in practice no signal was ever registered.
+
+The default is worse than no answer. ``alpha += 0.5`` and ``beta += 0.5`` move
+together, so a Beta posterior keeps its mean at exactly 0.5 while its variance
+*shrinks*. Every neutral settlement makes an arm more confident that it is
+average and harder for real evidence to move later. Neutral is not a safe
+default; it is a slow commitment to knowing nothing.
+
+WHAT REPLACES IT
+----------------
+Features computed from rows the system already writes. An agent that uses a
+recalled memory leaves traces whether or not it cooperates: it reads or edits
+the files the memory names, its next actions stay on the memory's subject, it
+writes a follow-up memory that overlaps. None of that requires it to quote an
+identifier.
+
+Every feature here is observable, and each is reported separately so a reward
+can say *why*. When nothing is observable the answer is ``None`` — abstain —
+never a number.
+
+NOT SELF-REFERENTIAL
+--------------------
+A signal derived from the mechanism it evaluates cannot detect that mechanism's
+failure. Ranking position is therefore not a feature: the bandit chose the
+ranking, so scoring it by what the bandit ranked first would confirm the bandit
+to itself. Position enters only in ``propensity.py``, as a correction applied
+*against* the observation, never as evidence for it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+
+__all__ = [
+    "EngagementFeatures",
+    "OBSERVATION_WINDOW_SEC",
+    "extract_features",
+    "tokenize",
+]
+
+#: How long after a recall an action may still be counted as caused by it.
+#: Wider than the old 30 s hit window: an agent reads a memory, then thinks,
+#: then acts, and 30 s discarded most of the acting.
+OBSERVATION_WINDOW_SEC = 300
+
+#: Tools whose payload naming a recalled memory's content is strong evidence
+#: the memory was actually used, not merely returned.
+_ARTIFACT_TOOLS = frozenset({"Write", "Edit", "NotebookEdit", "MultiEdit"})
+
+#: Words carrying no topical signal; overlap on these is noise, and without
+#: this filter every pair of payloads overlaps.
+_STOPWORDS = frozenset("""
+a an the and or but if then than that this these those is are was were be been
+being to of in on at by for with from as it its into over under about after
+before not no nor so such can will would should could may might must do does
+did done have has had i you he she we they them his her their our your my me
+""".split())
+
+_TOKEN_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_.\-/]{2,}")
+
+
+def tokenize(text: str) -> set[str]:
+    """Content-bearing lowercase tokens, stopwords and short words removed."""
+    if not text:
+        return set()
+    return {
+        tok for tok in (m.group(0).lower() for m in _TOKEN_RE.finditer(text))
+        if tok not in _STOPWORDS and len(tok) > 2
+    }
+
+
+@dataclass
+class EngagementFeatures:
+    """What was observed after one recall. Every field is measured, not inferred.
+
+    ``observed`` is the honest summary: False means nothing happened that this
+    module can see, which is a reason to abstain rather than a reason to
+    penalise. An agent may have used a memory perfectly and left no trace.
+    """
+
+    #: Best Jaccard-style overlap between any recalled fact and any following
+    #: tool payload, in [0, 1].
+    peak_overlap: float = 0.0
+    #: Overlap restricted to file-writing tools — the memory reached an artifact.
+    artifact_overlap: float = 0.0
+    #: A later remember/update_memory overlapping a recalled fact.
+    followup_write_overlap: float = 0.0
+    #: The same question asked again inside the requery window: the answer did
+    #: not satisfy. The one unambiguous negative available.
+    requeried: bool = False
+    #: Seconds from recall to the first following action, when there was one.
+    dwell_sec: float | None = None
+    #: Tool events seen in the window at all.
+    action_count: int = 0
+    #: Which fact ids the overlap landed on, so a reward can be explained.
+    matched_fact_ids: list[str] = field(default_factory=list)
+    #: A recalled fact's own id appeared verbatim in a later tool event. Rare,
+    #: because nothing makes an agent echo it — but unambiguous when it does
+    #: happen, so it is kept as the strongest single piece of evidence rather
+    #: than discarded along with the ladder that relied on it alone.
+    marker_hit: bool = False
+
+    @property
+    def observed(self) -> bool:
+        """Whether anything at all was seen. Drives abstention."""
+        return bool(
+            self.requeried
+            or self.marker_hit
+            or self.action_count > 0
+            and (
+                self.peak_overlap > 0.0
+                or self.artifact_overlap > 0.0
+                or self.followup_write_overlap > 0.0
+            )
+        )
+
+
+def _table_exists(conn: sqlite3.Connection, name: str) -> bool:
+    try:
+        return conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (name,),
+        ).fetchone() is not None
+    except sqlite3.Error:
+        return False
+
+
+def _fact_tokens(conn: sqlite3.Connection, fact_ids: list[str]) -> dict[str, set[str]]:
+    """Content tokens per fact. Entities are folded in when the column exists,
+    because a memory's entities are what a later action is most likely to name.
+    """
+    if not fact_ids or not _table_exists(conn, "atomic_facts"):
+        return {}
+    placeholders = ",".join("?" * len(fact_ids))
+    try:
+        rows = conn.execute(
+            f"SELECT fact_id, content, COALESCE(entities_json,'') "  # noqa: S608
+            f"FROM atomic_facts WHERE fact_id IN ({placeholders})",
+            tuple(fact_ids),
+        ).fetchall()
+    except sqlite3.Error:
+        return {}
+
+    out: dict[str, set[str]] = {}
+    for fact_id, content, entities_json in rows:
+        tokens = tokenize(content or "")
+        if entities_json:
+            try:
+                parsed = json.loads(entities_json)
+            except (ValueError, TypeError):
+                parsed = None
+            if isinstance(parsed, list):
+                for ent in parsed:
+                    tokens |= tokenize(ent if isinstance(ent, str) else str(ent))
+        if tokens:
+            out[str(fact_id)] = tokens
+    return out
+
+
+def _following_events(
+    conn: sqlite3.Connection,
+    session_id: str,
+    profile_id: str,
+    recalled_at: datetime,
+) -> list[tuple[str, str]]:
+    """(tool_name, payload) for actions in this conversation after the recall.
+
+    Scoped to the conversation. Without that predicate a busy machine's
+    unrelated activity in the same five minutes would read as engagement.
+    """
+    if not _table_exists(conn, "tool_events"):
+        return []
+    start = recalled_at.isoformat()
+    end = (recalled_at + timedelta(seconds=OBSERVATION_WINDOW_SEC)).isoformat()
+    try:
+        cols = {r[1] for r in conn.execute("PRAGMA table_info(tool_events)")}
+    except sqlite3.Error:
+        return []
+    if not {"session_id", "created_at", "tool_name"} <= cols:
+        return []
+
+    sql = (
+        "SELECT tool_name, COALESCE(input_summary,'') || ' ' || "
+        "COALESCE(output_summary,'') FROM tool_events "
+        "WHERE session_id = ? AND created_at > ? AND created_at <= ?"
+    )
+    params: tuple = (session_id, start, end)
+    if "profile_id" in cols:
+        sql += " AND (profile_id = ? OR profile_id IS NULL)"
+        params += (profile_id,)
+    sql += " ORDER BY created_at LIMIT 200"
+    try:
+        return [(str(r[0]), str(r[1])) for r in conn.execute(sql, params)]
+    except sqlite3.Error:
+        return []
+
+
+#: A single word in common is coincidence, not evidence. Any two texts about
+#: software share one token eventually, and containment makes that worse: a
+#: memory that reduces to one content word scores a perfect 1.0 against every
+#: payload containing it. Two independent tokens is the cheapest threshold that
+#: distinguishes a shared subject from a shared word.
+_MIN_OVERLAP_TOKENS = 2
+
+
+def _overlap(fact_tokens: set[str], payload_tokens: set[str]) -> float:
+    """Containment of the memory in the action, not symmetric Jaccard.
+
+    A tool payload is often far larger than a fact, and Jaccard would divide
+    that signal away precisely when the evidence is strongest.
+    """
+    if not fact_tokens or not payload_tokens:
+        return 0.0
+    shared = fact_tokens & payload_tokens
+    if len(shared) < _MIN_OVERLAP_TOKENS:
+        return 0.0
+    return len(shared) / len(fact_tokens)
+
+
+def extract_features(
+    memory_conn: sqlite3.Connection,
+    *,
+    session_id: str,
+    profile_id: str,
+    fact_ids: list[str],
+    recalled_at: datetime,
+    requeried: bool = False,
+    marker_hit: bool = False,
+) -> EngagementFeatures:
+    """Observe what followed one recall. Never raises; returns empty on error."""
+    features = EngagementFeatures(
+        requeried=bool(requeried), marker_hit=bool(marker_hit),
+    )
+    try:
+        by_fact = _fact_tokens(memory_conn, [str(f) for f in fact_ids])
+        events = _following_events(memory_conn, session_id, profile_id, recalled_at)
+    except sqlite3.Error:
+        return features
+
+    features.action_count = len(events)
+    if not by_fact or not events:
+        return features
+
+    matched: set[str] = set()
+    for tool_name, payload in events:
+        payload_tokens = tokenize(payload)
+        if not payload_tokens:
+            continue
+        for fact_id, tokens in by_fact.items():
+            score = _overlap(tokens, payload_tokens)
+            if score <= 0.0:
+                continue
+            matched.add(fact_id)
+            features.peak_overlap = max(features.peak_overlap, score)
+            if tool_name in _ARTIFACT_TOOLS:
+                features.artifact_overlap = max(features.artifact_overlap, score)
+            if tool_name.endswith(("remember", "update_memory")):
+                features.followup_write_overlap = max(
+                    features.followup_write_overlap, score,
+                )
+    features.matched_fact_ids = sorted(matched)
+    return features

package/src/superlocalmemory/learning/outcome_queue.py

@@ -26,6 +26,8 @@ by ``unified_daemon.py``'s lifespan hook.
 
 from __future__ import annotations
 
+
+from superlocalmemory.core.session_identity import is_conversation
 import logging
 import queue
 import threading
@@ -112,6 +114,18 @@ def enqueue_recall(event: RecallEvent) -> None:
         # If the caller can't name a session, we silently drop: this
         # is a recall whose outcome cannot match to a signal anyway.
         return
+    if not is_conversation(event.session_id, event.profile_id):
+        # Same reason, one step further. A front that invents an id names
+        # itself, not a caller: ``engine:<pid>`` is the daemon every client
+        # shares, ``cli:<pid>`` a process that exits before any follow-on
+        # action, ``http:<ms>`` a single request. No tool event can ever
+        # carry one, so the outcome is unmatchable the moment it is written.
+        # Recording it anyway is not free: a play that is never settled from
+        # evidence is eventually settled from nothing, and a neutral update
+        # tightens a Beta posterior around its prior instead of leaving it
+        # movable.
+        _bump("recall_dropped_synthetic_session")
+        return
     try:
         _queue.put_nowait(event)
         _bump("recall_enqueued")