verimem 0.3.0__py3-none-any.whl

engram/__init__.py

@@ -0,0 +1,44 @@
+"""Engram — persistent memory layer for LLM agents.
+
+Architecture: hippocampal-cortical inspired learning loop.
+- Wake: ReAct execution, episodic recording.
+- Sleep: replay, skill synthesis, fitness selection.
+- Skills are persistent artifacts (not weights), inspectable and versioned.
+
+Formerly named ``hippoagent``. The legacy ``hippoagent`` package is a
+backward-compat shim that re-exports this module (see top-level
+``hippoagent/__init__.py``); it will be removed ~2026-08-13.
+"""
+from __future__ import annotations
+
+# Keep in lockstep with pyproject [project].version and .claude-plugin/
+# plugin.json — enforced by tests/test_version_single_source.py (audit#2 C-4).
+__version__ = "0.3.0"
+
+# Initialize backward-compat env mirror (HIPPO_* ↔ ENGRAM_*) at import time
+# so the rest of the package — and anyone importing ``engram`` — sees a
+# consistent environment regardless of which prefix the user has set.
+from . import _compat as _compat
+
+_compat.init_env_aliases()
+
+# ENGRAM_MODE single-knob (subscription | byok | local): derive the lower-level
+# flags (HIPPO_HOSTED / HIPPO_LLM_PROVIDER / HF_HUB_OFFLINE / ...) BEFORE any
+# submodule (config, llm, settings) reads the env. Runs on ANY `import
+# engram[.x]`. setdefault-safe (never clobbers an explicit flag); no-op when
+# ENGRAM_MODE is unset.
+from .mode import apply_engram_mode as _apply_engram_mode  # noqa: E402
+
+_apply_engram_mode()
+
+# Public turnkey SDK — exposed lazily so ``import engram`` stays light (the
+# Memory client pulls in the embedding/semantic stack only when first used).
+__all__ = ["Memory", "Client"]
+
+
+def __getattr__(name: str):  # PEP 562 lazy attribute access
+    if name in ("Memory", "Client"):
+        from .client import Client, Memory
+
+        return {"Memory": Memory, "Client": Client}[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

engram/_call_telemetry.py

@@ -0,0 +1,27 @@
+"""Detect cross-LLM call-telemetry episodes.
+
+The bridge auto-saves every ask_agy / ask_gemini / ask_claude / … as an episode
+whose ``task_text`` opens with ``[<llm>-call …]``. These are machine telemetry,
+not user tasks: 2026-06-13 they were 123/554 (22%) of the live episode store,
+polluting recall and diluting the emerging/correction/risk quartet.
+
+Shared single source of truth for the WRITE-time episode gate (engram.memory
+routes them to a separate ``episode_telemetry`` table) and the READ-time briefing
+filter. Leaf module: imports nothing from ``engram`` → no import cycle.
+"""
+from __future__ import annotations
+
+import re
+
+_CALL_TELEMETRY_RE = re.compile(
+    r"^\s*\[(?:agy|gemini|claude|kimi|deepseek|grok|gpt|qwen|llama|mistral)-call\b",
+    re.IGNORECASE,
+)
+
+
+def is_call_telemetry(task_text: str | None) -> bool:
+    """True when the episode's ``task_text`` is a cross-LLM call record, not a task."""
+    return bool(_CALL_TELEMETRY_RE.match(task_text or ""))
+
+
+__all__ = ["is_call_telemetry"]

engram/_compat.py

@@ -0,0 +1,99 @@
+"""Backward-compat bridge for the cycle #41 rename (hippoagent → engram).
+
+Two surfaces are bridged here so existing user configurations keep working:
+
+1. **Environment variables**: every ``HIPPO_*`` env var visible at process
+   start is mirrored to ``ENGRAM_*`` (and vice versa) via
+   :func:`init_env_aliases`. Existing ``HIPPO_HOSTED=1``, ``HIPPO_DATA_DIR``,
+   ``HIPPO_AUTH_TOKEN``, etc. continue to work without code changes; new
+   ``ENGRAM_*`` names are picked up by older code paths through the same
+   mirror. The mirror uses :py:meth:`os.environ.setdefault` so an explicit
+   value on one side never overrides an explicit value on the other.
+
+2. **User data directory**: :func:`data_dir` returns ``~/.engram`` if it
+   exists, falls back to ``~/.hippoagent`` if only the old dir exists,
+   otherwise creates ``~/.engram``. This keeps existing installations
+   reading their data while new installations get the new path.
+
+The module is intentionally tiny and stdlib-only — it's imported by
+``engram/__init__.py`` and must not have any heavy dependencies.
+
+Scheduled removal: ~2026-08-13 (3 months from rename). After that, all
+code is expected to use ``ENGRAM_*`` env names and the ``~/.engram``
+path; this module can be deleted and ``HIPPO_*`` configs will start
+failing — by then any user still on the old names has had 3 months
+of clear deprecation warnings to migrate.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_PREFIX_OLD = "HIPPO_"
+_PREFIX_NEW = "ENGRAM_"
+
+# Old data dir (cycle #1 — #40).
+_OLD_DIR_NAME = ".hippoagent"
+# New data dir (cycle #41+).
+_NEW_DIR_NAME = ".engram"
+
+
+def init_env_aliases() -> int:
+    """Mirror HIPPO_* ↔ ENGRAM_* env vars (idempotent).
+
+    For each environment variable starting with ``HIPPO_``, set the
+    corresponding ``ENGRAM_`` variant if not already defined. Same in
+    reverse for ``ENGRAM_*`` → ``HIPPO_*``. Uses :py:meth:`os.environ.setdefault`
+    so explicit user values are never clobbered.
+
+    Returns the number of mirror entries added (for tests / introspection).
+    """
+    added = 0
+    # Snapshot keys to avoid mutation-during-iteration warnings.
+    snapshot = list(os.environ.items())
+    for k, v in snapshot:
+        if k.startswith(_PREFIX_OLD):
+            new_key = _PREFIX_NEW + k[len(_PREFIX_OLD):]
+            if new_key not in os.environ:
+                os.environ[new_key] = v
+                added += 1
+        elif k.startswith(_PREFIX_NEW):
+            old_key = _PREFIX_OLD + k[len(_PREFIX_NEW):]
+            if old_key not in os.environ:
+                os.environ[old_key] = v
+                added += 1
+    return added
+
+
+def data_dir() -> Path:
+    """Return the canonical Engram data directory.
+
+    Order of preference:
+
+    1. If ``~/.engram`` exists, use it.
+    2. Else if ``~/.hippoagent`` exists, use it (legacy install).
+    3. Else create ``~/.engram`` and use it.
+
+    Never throws — best-effort. Callers should still handle :py:class:`OSError`
+    on subsequent disk operations.
+
+    The env var ``HIPPO_DATA_DIR`` / ``ENGRAM_DATA_DIR`` (whichever is set;
+    if both, the new name wins) overrides this default entirely.
+    """
+    # Explicit override via env (HIPPO_DATA_DIR or ENGRAM_DATA_DIR).
+    override = os.environ.get("ENGRAM_DATA_DIR") or os.environ.get("HIPPO_DATA_DIR")
+    if override:
+        p = Path(override).expanduser()
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    home = Path.home()
+    new_dir = home / _NEW_DIR_NAME
+    old_dir = home / _OLD_DIR_NAME
+
+    if new_dir.exists():
+        return new_dir
+    if old_dir.exists():
+        return old_dir
+    new_dir.mkdir(parents=True, exist_ok=True)
+    return new_dir

engram/_hang_watchdog.py

@@ -0,0 +1,87 @@
+"""Hang watchdog — make intermittent multi-minute MCP hangs DIAGNOSABLE.
+
+When a tool call exceeds a wall-clock budget, dump ALL thread stacks to
+``~/.engram/hang-traces/`` so the exact blocking frame is captured in the act
+(``_MODEL_LOCK.acquire`` / socket ``recv`` / sqlite lock / a stale-code path).
+Without this, a hang that only reproduces in a user's specific session is a
+black box.
+
+CONTRACT — observability ONLY:
+  * never changes dispatch behaviour (the call runs exactly as before),
+  * never raises (a broken trace dir must not break the tool),
+  * never cancels/returns the call (it only LOGS; fixing is a separate concern),
+  * a fast call leaves NO file (the header-only file is cleaned up).
+
+faulthandler's timer is process-global, so only ONE call is watched at a time
+(a non-blocking lock); concurrent calls run unwatched rather than clobbering the
+timer. With the synchronous MCP dispatch (one tool body on the loop at a time)
+this watches effectively every call.
+"""
+from __future__ import annotations
+
+import faulthandler
+import os
+import threading
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+_TRACE_DIR = Path(
+    os.environ.get("HIPPO_HANG_TRACE_DIR")
+    or (Path.home() / ".engram" / "hang-traces")
+)
+# Below this many bytes the file is header-only (nothing was dumped) → delete.
+_HEADER_MAX_BYTES = 300
+_ARMED = threading.Lock()
+
+
+@contextmanager
+def hang_trace(label: str, budget_s: float):
+    """Wrap a tool call. If it runs longer than ``budget_s`` seconds, append a
+    full all-thread stack dump to a per-call file under ``_TRACE_DIR``."""
+    if not budget_s or budget_s <= 0:
+        yield
+        return
+    # Process-global faulthandler timer → only one watcher at a time.
+    if not _ARMED.acquire(blocking=False):
+        yield
+        return
+    f = None
+    path = None
+    armed = False
+    try:
+        _TRACE_DIR.mkdir(parents=True, exist_ok=True)
+        safe = "".join(c if c.isalnum() or c in "-_." else "_" for c in str(label))[:40]
+        path = _TRACE_DIR / f"hang-{int(time.time())}-{os.getpid()}-{safe}.txt"
+        f = open(path, "w", encoding="utf-8")
+        f.write(
+            f"HANG WATCHDOG  tool={label}  pid={os.getpid()}  budget={budget_s}s\n"
+            "the stacks below were dumped because the call exceeded the budget:\n"
+        )
+        f.flush()
+        faulthandler.dump_traceback_later(budget_s, repeat=True, file=f)
+        armed = True
+    except Exception:  # noqa: BLE001 — tracing is best-effort, never break the call
+        if f is not None:
+            try:
+                f.close()
+            except Exception:  # noqa: BLE001
+                pass
+            f = None
+    try:
+        yield
+    finally:
+        if armed:
+            try:
+                faulthandler.cancel_dump_traceback_later()
+            except Exception:  # noqa: BLE001
+                pass
+        if f is not None:
+            try:
+                size = f.tell()
+                f.close()
+                if size <= _HEADER_MAX_BYTES and path is not None:
+                    path.unlink(missing_ok=True)
+            except Exception:  # noqa: BLE001
+                pass
+        _ARMED.release()

engram/_proc_quiet.py

@@ -0,0 +1,37 @@
+"""Cycle #136 (2026-05-17) — Windows console pop-up suppression helper.
+
+Aurelio direttiva 2026-05-17: "shell che si aprono e chiudono da sole,
+sono fastidiosissime". Root cause: every ``subprocess.run / Popen`` call
+in ``engram/`` that doesn't pass ``creationflags=CREATE_NO_WINDOW``
+flashes a Windows CMD window on the user's screen. This module exposes
+one tiny helper, ``quiet_popen_kwargs()``, that returns the right
+kwargs for the current platform — empty dict on Linux/macOS so the
+helper is a no-op cross-platform.
+
+Usage::
+
+    from engram._proc_quiet import quiet_popen_kwargs
+    subprocess.run(["git", "rev-parse", sha], **quiet_popen_kwargs())
+
+The Windows ``CREATE_NO_WINDOW`` constant is only defined when running
+on Windows (it lives in ``subprocess`` only on win32 Python builds).
+We guard the attribute access defensively.
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+from typing import Any
+
+
+def quiet_popen_kwargs() -> dict[str, Any]:
+    """Return kwargs that suppress the Windows console pop-up.
+
+    On Windows this is ``{"creationflags": subprocess.CREATE_NO_WINDOW}``;
+    on every other platform it is the empty dict (no behaviour change).
+    """
+    if sys.platform == "win32":
+        flag = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+        if flag:
+            return {"creationflags": flag}
+    return {}

engram/_singleton_guard.py

@@ -0,0 +1,109 @@
+"""Single-instance guard — reap ORPHANED `engram mcp` server processes on startup.
+
+Root cause of the recurring multi-minute "Engram froze on a save" incident
+(2026-06-06, empirical via Win32_Process enumeration): Claude Code restarts spawn
+a fresh `engram mcp` server each time, but the OLD ones are never reaped. They
+pile up (6 observed simultaneously); each contends for CPU/disk and drives its own
+embedding work, starving the live server's encode until a save blocks for minutes.
+
+This module, called once at server startup, terminates sibling `engram mcp`
+servers that are ORPHANED — their spawning client (Claude Code) is gone.
+
+Multi-window SAFE: a sibling whose parent client is still alive is NEVER touched
+(``psutil.Process.parent()`` validates ppid AND create_time, so a recycled PID is
+not mistaken for a live parent). Detached embedding daemons are intentionally
+excluded from the matcher (they have no live parent by design — single-instancing
+them is the daemon's own job, via the encode_service reachability lock).
+
+Best-effort: every failure path is swallowed — the guard must NEVER break server
+startup, and psutil is optional.
+"""
+from __future__ import annotations
+
+import os
+import re
+
+# Matches the engram MCP server in ALL its launch forms:
+#   "<path>\engram.exe" mcp   |   hippo mcp   |   engram mcp
+# plus the explicit-module substring "engram.mcp_server" (handled separately).
+# Deliberately does NOT match the sibling processes that merely contain "mcp":
+#   engram_bridge_mcp.py / clp_mcp_server.py / duo_bridge_mcp.py /
+#   critic_orchestrator.mcp_server / engram.encode_service / engram_embedding_daemon.py
+#   (none has the `(engram|hippo)[.exe] <whitespace> mcp` token boundary).
+_MCP_CMDLINE_RE = re.compile(
+    r'(?:^|[\s"/\\])(?:engram|hippo)(?:\.exe)?["\']?\s+mcp(?:\s|$|["\'])',
+    re.IGNORECASE,
+)
+
+
+def _is_engram_mcp_cmdline(cmdline: str) -> bool:
+    """True iff ``cmdline`` is an engram/hippo MCP *server* invocation."""
+    if not cmdline:
+        return False
+    if "engram.mcp_server" in cmdline:
+        return True
+    return bool(_MCP_CMDLINE_RE.search(cmdline))
+
+
+def _select_orphan_pids(procs, *, self_pid: int) -> list[int]:
+    """Pure selection: given ``procs`` = iterable of
+    ``(pid: int, cmdline: str, parent_alive: bool)``, return the pids that are
+    engram-mcp servers, orphaned (parent NOT alive), and not ``self_pid``."""
+    out: list[int] = []
+    for pid, cmdline, parent_alive in procs:
+        if pid == self_pid:
+            continue
+        if not _is_engram_mcp_cmdline(cmdline):
+            continue
+        if not parent_alive:
+            out.append(pid)
+    return out
+
+
+def _import_psutil():
+    """Return the psutil module, or None if unavailable (indirection for tests)."""
+    try:
+        import psutil  # noqa: PLC0415
+        return psutil
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def reap_orphan_mcp_servers(*, dry_run: bool = False) -> list[int]:
+    """Terminate orphaned sibling `engram mcp` servers. Returns the reaped pids
+    (or, under ``dry_run``, the pids that WOULD be reaped). Never raises."""
+    psutil = _import_psutil()
+    if psutil is None:
+        return []
+    self_pid = os.getpid()
+    candidates = []  # (pid, cmdline, parent_alive, proc)
+    try:
+        for p in psutil.process_iter(["pid", "cmdline"]):
+            try:
+                pid = p.info["pid"]
+                cmdline = " ".join(p.info.get("cmdline") or [])
+                if not _is_engram_mcp_cmdline(cmdline):
+                    continue
+                parent_alive = p.parent() is not None
+                candidates.append((pid, cmdline, parent_alive, p))
+            except Exception:  # noqa: BLE001 — one bad proc never aborts the sweep
+                continue
+    except Exception:  # noqa: BLE001
+        return []
+    orphan_pids = set(_select_orphan_pids(
+        [(pid, cmd, alive) for pid, cmd, alive, _ in candidates],
+        self_pid=self_pid,
+    ))
+    reaped: list[int] = []
+    for pid, _cmd, _alive, proc in candidates:
+        if pid not in orphan_pids:
+            continue
+        if dry_run:
+            reaped.append(pid)
+            continue
+        try:
+            proc.terminate()
+            reaped.append(pid)
+        except Exception:  # noqa: BLE001
+            continue
+    return reaped

engram/_sqlite_pragma.py

@@ -0,0 +1,25 @@
+"""Single source of truth for the SQLite connection PRAGMA policy.
+
+The four DB modules (semantic, memory/episodic, entity_kg, skill) each open
+short-lived per-operation connections with the same PRAGMA set (WAL +
+busy_timeout=60000 + synchronous=NORMAL + foreign_keys). The ``synchronous`` level
+was hard-coded in 5 places; this centralizes the ONE knob a deployment may want to
+tune (production-scaling review 2026-06-20).
+
+``synchronous=NORMAL`` (default) is WAL-safe and fast but, between checkpoints, a
+committed-but-uncheckpointed write can be lost on an OS crash / power loss.
+``ENGRAM_SQLITE_SYNCHRONOUS=FULL`` trades write throughput for per-commit fsync
+durability — for deployments that need it. Default keeps current behaviour.
+"""
+from __future__ import annotations
+
+import os
+
+
+def synchronous_mode() -> str:
+    """Return the SQLite ``synchronous`` level: 'NORMAL' (default) or 'FULL'."""
+    v = os.environ.get("ENGRAM_SQLITE_SYNCHRONOUS", "NORMAL").strip().upper()
+    return "FULL" if v == "FULL" else "NORMAL"
+
+
+__all__ = ["synchronous_mode"]

engram/_telemetry_prefixes.py

@@ -0,0 +1,97 @@
+"""Single source of truth for machine-state / telemetry topic prefixes.
+
+A fact whose topic starts with one of these is serialized machine state (event
+bus traffic, metrics, locks, market/cache/citation simulation blobs, agent
+diary exhaust, …), NOT curated natural-language knowledge. Two layers consume
+this list and they must NEVER drift:
+
+  - WRITE time: ``engram.admission_gate`` routes such a write to the telemetry
+    store instead of the curated corpus (ROUTE_TELEMETRY) — it never deletes.
+  - READ time: ``engram.semantic`` hides them from a GENERIC (topic=None) recall
+    (the cache fast-path SQL, the legacy SQL path, and the cold keyword
+    fallback all derive their denylist from this tuple).
+
+Before 2026-06-13 these were two hand-maintained lists (a tuple in semantic +
+a regex in admission_gate) that had silently drifted: a live hippo_facts_recall
+surfaced cache/ market/ citations/ blobs that semantic's recall denylist had
+just been extended to hide but the admission gate still admitted. Centralising
+here makes that drift structurally impossible.
+
+This module is a LEAF: it imports nothing from ``engram`` so neither
+``semantic`` nor ``admission_gate`` can create an import cycle by reading it.
+
+NOT in this list (deliberately curated knowledge, must stay recallable):
+``test/`` (canary fixtures the suite relies on), ``handoff/`` (real operator
+mandates), ``bench/`` (benchmark findings), ``project/``, ``lessons/``,
+``archive/``, ``decisions/``, ``preferences/``, ``emerging_skill/``.
+"""
+from __future__ import annotations
+
+#: Topic prefixes treated as machine-state/telemetry. ``startswith`` semantics
+#: (each entry is matched as a literal prefix, not a regex).
+TELEMETRY_TOPIC_PREFIXES: tuple[str, ...] = (
+    # original set (SCAN-68, 2026-06-02)
+    "bus/", "metric/", "alloc/", "lock/", "tx/", "nego/", "replay/",
+    "dialog/voice",
+    # 2026-06-13: serialized JSON machine-state / simulation blobs that a LIVE
+    # hippo_facts_recall surfaced at score ~0.82, crowding out real knowledge.
+    # Per-namespace sampling (B2) confirmed all are JSON state, not NL knowledge.
+    "cache/", "market/", "citations/", "obs/", "signal/",
+    "dispatch/", "supervisor/", "namespace/", "diary/",
+    # 2026-07-02: the real-corpus NLI truth scan surfaced 26 live dream/<id>
+    # facts, all serialized scenario state ({"state": "active", ...}) that had
+    # slipped past both layers because the prefix was missing.
+    "dream/",
+    # 2026-07-03: the first KNOWLEDGE-only scan exposed machine state nested
+    # under knowledge namespaces (sampled before listing, B2): pin/<fact_id>
+    # JSON pin/unpin state; skill/catalog/* auto-generated registry entries
+    # ("Pre-installed Engram skill. Path: ...", 49 near-identical rows = 395
+    # of 810 scan conflicts); project/recursive-mas/* MAS-worker exhaust
+    # (planner/critic run output incl. raw ANSI escapes). Deliberate skills
+    # knowledge (emerging_skill/, other skill/ topics) stays recallable.
+    "pin/", "skill/catalog/", "project/recursive-mas/",
+)
+
+#: Fact tiers. `classify_tier` is the single source of truth consumed by the
+#: truth-reconcile guard, the corpus truth scan, and any bench that must not
+#: mix machine state with knowledge (the 2026-07-02 real-corpus scan showed the
+#: residual NLI conflicts were telemetry near-duplicates, not knowledge).
+TIER_TELEMETRY = "telemetry"
+TIER_TEST = "test"
+TIER_DIALOG = "dialog"
+TIER_KNOWLEDGE = "knowledge"
+
+#: Suite canaries and lab-experiment material: deliberately recallable (see the
+#: NOT-in-this-list note above) but never a reconcile/scan subject.
+TEST_TOPIC_PREFIXES: tuple[str, ...] = ("test/", "lab/", "project/lab/")
+
+#: Verbatim conversation transcripts (e.g. the founding dialog/doc1-* docs):
+#: curated, recallable knowledge of record — but chat turns are not factual
+#: assertions, so a reconcile judge must not supersede/contest them.
+DIALOG_TOPIC_PREFIX = "dialog/"
+
+
+def classify_tier(topic: str | None) -> str:
+    """Map a fact topic to its tier. Telemetry wins over dialog so that
+    ``dialog/voice`` (machine exhaust) stays telemetry while ``dialog/doc*``
+    transcripts classify as dialog."""
+    t = topic or ""
+    if any(t.startswith(p) for p in TELEMETRY_TOPIC_PREFIXES):
+        return TIER_TELEMETRY
+    if any(t.startswith(p) for p in TEST_TOPIC_PREFIXES):
+        return TIER_TEST
+    if t.startswith(DIALOG_TOPIC_PREFIX):
+        return TIER_DIALOG
+    return TIER_KNOWLEDGE
+
+
+__all__ = [
+    "TELEMETRY_TOPIC_PREFIXES",
+    "TEST_TOPIC_PREFIXES",
+    "DIALOG_TOPIC_PREFIX",
+    "TIER_TELEMETRY",
+    "TIER_TEST",
+    "TIER_DIALOG",
+    "TIER_KNOWLEDGE",
+    "classify_tier",
+]

engram/active_learning.py

@@ -0,0 +1,114 @@
+"""Cycle 175 (2026-05-22) — Active Learning Design B: stuck-list cron.
+
+Implements the empirically-motivated active-learning loop the
+``docs/cycle174_active_learning_design.md`` proposed and Aurelio
+greenlit on 2026-05-22.
+
+Empirical motivation (fact ``d778cce2faa8``, verified on the live
+``~/.engram/skills/skills_index.db``):
+  - 326 total skills, 71% (233) never trialed
+  - 3 candidates stuck at fitness 0.33-0.40
+  - candidate→promoted conversion rate: 7/163 = 4.3 %
+
+Design B (this module) is the *stuck-list cron*: a deterministic
+``SELECT`` returns the next ids to retry. No bandit, no randomness.
+Design A (warm-up bandit) and Design C (task-driven expansion) are
+deferred to future cycles per the design doc.
+
+Falsifiable hypothesis H1 (pre-registered in the design doc):
+  Targeted retry over candidates in ``trials ∈ [3, 10]`` and
+  ``fitness ∈ (0.3, 0.5)`` lifts the candidate→promoted conversion
+  from 4.3 % to > 10 % within 20 Auto-Dream cycles.
+
+This module is the *selection* primitive only. The decision to actually
+emit a dream task from the selected ids is the caller's job (a thin
+hook in ``engram.auto_dream_trigger.maybe_trigger_dream`` — added in a
+follow-up commit if H1 holds in pilot).
+
+Pure-function contract
+----------------------
+``select_stuck_candidates`` opens the skills_index.db read-only, runs
+one SQL query, returns ids ordered oldest-``updated_at`` first (cron
+fairness — every cycle the longest-untouched stuck skill gets a turn).
+No state, no side effects, never raises (missing DB → []).
+
+Why SQL not ORM
+---------------
+Bayesian smoothed fitness ``(s+1)/(t+2)`` is cheap in SQL via a
+CAST(...) AS REAL division. Doing the math in Python would require
+loading every candidate skill — wasteful on a corpus of hundreds.
+The SQL prior matches ``Skill.fitness_mean`` *only when* the
+``CONFIG.fitness_prior_alpha = CONFIG.fitness_prior_beta = 1`` (the
+default). If a user customised the prior, this function's filter
+will diverge slightly from ``Skill.fitness_mean``; see the
+``BETA_PRIOR_NOTE`` constant below.
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+#: Pinned to the default Beta(1, 1) (uniform) prior used by
+#: ``engram.skill.Skill.fitness_mean`` when ``CONFIG.fitness_prior_*``
+#: stays at the package defaults. The SQL filter uses this prior to
+#: keep the band semantics consistent with the dataclass property.
+#: A user who customised the prior should call ``Skill.fitness_mean``
+#: per-row instead of using this fast SQL path.
+BETA_PRIOR_NOTE = "Beta(1,1) — pinned to CONFIG default"
+
+
+def select_stuck_candidates(
+    skill_db: Path | str,
+    *,
+    min_trials: int = 3,
+    max_trials: int = 10,
+    fitness_band: tuple[float, float] = (0.3, 0.5),
+    max_n: int = 3,
+    status: str = "candidate",
+) -> list[str]:
+    """Return the ids of stuck-band candidates eligible for retry.
+
+    Filters (all conjunctive):
+      - ``skills.status = <status>`` (default ``'candidate'``)
+      - ``min_trials ≤ skills.trials ≤ max_trials``
+      - ``fitness_band[0] < (successes+1)/(trials+2) < fitness_band[1]``
+        (strict inequalities — boundary skills are treated as
+        outside the "stuck" zone)
+
+    Ordering: ``updated_at ASC`` (oldest first → cron fairness).
+
+    Returns up to ``max_n`` ids. Empty list on missing DB or
+    SQL error (defensive — this is called from the Auto-Dream
+    cooldown path and must never crash a hook).
+    """
+    p = Path(skill_db)
+    if not p.exists():
+        return []
+    lo, hi = float(fitness_band[0]), float(fitness_band[1])
+    try:
+        conn = sqlite3.connect(str(p))
+        try:
+            conn.row_factory = sqlite3.Row
+            rows = conn.execute(
+                """
+                SELECT id
+                FROM skills
+                WHERE status = ?
+                  AND trials >= ?
+                  AND trials <= ?
+                  AND (CAST(successes + 1 AS REAL) / (trials + 2)) > ?
+                  AND (CAST(successes + 1 AS REAL) / (trials + 2)) < ?
+                ORDER BY updated_at ASC
+                LIMIT ?
+                """,
+                (status, int(min_trials), int(max_trials),
+                 lo, hi, int(max_n)),
+            ).fetchall()
+        finally:
+            conn.close()
+    except sqlite3.Error:
+        return []
+    return [str(r["id"]) for r in rows]
+
+
+__all__ = ["BETA_PRIOR_NOTE", "select_stuck_candidates"]