threadkeeper 0.4.0__py3-none-any.whl

threadkeeper/config.py

@@ -0,0 +1,216 @@
+"""Paths, env-driven defaults, semantic-search availability flag.
+Imported wherever a constant or config is needed; cheap to import."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+DB_PATH: Path = Path(
+    os.environ.get("THREADKEEPER_DB", "~/.threadkeeper/db.sqlite")
+).expanduser()
+
+EMBED_MODEL_NAME: str = os.environ.get(
+    "THREADKEEPER_EMBED_MODEL",
+    "paraphrase-multilingual-MiniLM-L12-v2",  # 118 MB, RU+EN cross-lingual
+)
+
+DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+# One-shot migration from the historical name `memory_partner`. If the new
+# DB doesn't exist yet but the legacy one does, copy it (including the WAL
+# sidecars) so users can rename mid-life without losing memory. After this
+# import the legacy directory is left in place — caller can `rm -rf` once
+# they've verified the new path is working.
+#
+# Gate: only run when DB_PATH is the default `~/.threadkeeper/db.sqlite`.
+# Tests + custom paths must NOT trigger the migration — otherwise every
+# test would copy the user's ~683MB DB into its tmp dir and exhaust disk.
+_DEFAULT_DB = Path("~/.threadkeeper/db.sqlite").expanduser()
+_LEGACY_DIR = Path("~/.memory_partner").expanduser()
+_LEGACY_DB = _LEGACY_DIR / "db.sqlite"
+if (
+    DB_PATH == _DEFAULT_DB
+    and not DB_PATH.exists()
+    and _LEGACY_DB.exists()
+):
+    import shutil
+    for fname in ("db.sqlite", "db.sqlite-wal", "db.sqlite-shm"):
+        src = _LEGACY_DIR / fname
+        if src.exists():
+            shutil.copy2(src, DB_PATH.parent / fname)
+
+# Semantic search opt-out. When this process is light (spawned slim child that
+# should never load PyTorch/transformers), set THREADKEEPER_NO_EMBEDDINGS=1.
+# This process will then delegate semantic queries to a peer via the signals
+# channel (search_via_parent). Notes still get inserted with embedding=NULL;
+# a parent process with embeddings backfills them asynchronously.
+NO_EMBEDDINGS: bool = os.environ.get(
+    "THREADKEEPER_NO_EMBEDDINGS", ""
+).lower() in {"1", "true", "yes", "on"}
+
+# Optional semantic search. If sentence-transformers is not installed OR the
+# no-embeddings opt-out is set, fall back to FTS5 keyword matching + delegate.
+# Brief still works either way.
+if NO_EMBEDDINGS:
+    SEMANTIC_AVAILABLE: bool = False
+else:
+    try:
+        from sentence_transformers import SentenceTransformer  # type: ignore  # noqa: F401
+        import numpy as np  # type: ignore  # noqa: F401
+        SEMANTIC_AVAILABLE = True
+    except Exception:
+        SEMANTIC_AVAILABLE = False
+
+# Client label used for `presence`/`sessions` rows.
+CLIENT_LABEL: str = os.environ.get("THREADKEEPER_CLIENT", "claude")
+
+# Write-origin for this server process. 'foreground' = a regular user-facing
+# conversation; 'background_review' = a headless review fork spawned to
+# auto-curate memory/skills after a complex task. Curator only ever touches
+# skills created under 'background_review' so user-authored skills are safe.
+WRITE_ORIGIN: str = os.environ.get(
+    "THREADKEEPER_WRITE_ORIGIN", "foreground"
+)
+
+# Where Claude's user-local skills live. Used by skill_manage / curator.
+CLAUDE_SKILLS_DIR: Path = Path(
+    os.environ.get("CLAUDE_SKILLS_DIR", "~/.claude/skills")
+).expanduser()
+
+# Where the live ingester reads claude code transcripts from.
+CLAUDE_PROJECTS_DIR: Path = Path(
+    os.environ.get("CLAUDE_PROJECTS_DIR", "~/.claude/projects")
+).expanduser()
+
+# Per-session ingest cap so brief() at session start doesn't block.
+INGEST_CAP_PER_CALL: int = int(os.environ.get("THREADKEEPER_INGEST_CAP", "50"))
+
+# Background live-ingester tick (seconds). 0 disables.
+INGEST_INTERVAL_S: float = float(
+    os.environ.get("THREADKEEPER_INGEST_INTERVAL_S", "3")
+)
+INGEST_RECENT_WINDOW_S: int = int(
+    os.environ.get("THREADKEEPER_INGEST_WINDOW_S", "600")
+)
+
+# Self-cid heuristic cache TTL (only matters when ppid walk fails).
+SELF_CID_TTL_S: float = float(
+    os.environ.get("THREADKEEPER_SELF_CID_TTL_S", "5")
+)
+
+# Per-task log directory for spawned children.
+TASK_LOG_DIR: Path = Path(
+    os.environ.get("THREADKEEPER_TASK_LOG_DIR", "/tmp/thread-keeper-tasks")
+).expanduser()
+DIALOG_LOG: Path = TASK_LOG_DIR / "dialog.log"
+
+# Counter-driven nudge thresholds. Memory nudge fires when N mutating events
+# have passed since the last memory_save event in this session; skill nudge
+# fires after N events since the last skill_materialized event. 0 disables.
+MEMORY_NUDGE_INTERVAL: int = int(
+    os.environ.get("THREADKEEPER_MEMORY_NUDGE_INTERVAL", "10")
+)
+SKILL_NUDGE_INTERVAL: int = int(
+    os.environ.get("THREADKEEPER_SKILL_NUDGE_INTERVAL", "10")
+)
+# When true, review_thread(thread_id) automatically spawns a background fork
+# for rich closed threads at the moment of close_thread(). Default off so
+# behavior is predictable; users opt in via env.
+AUTO_REVIEW_ENABLED: bool = os.environ.get(
+    "THREADKEEPER_AUTO_REVIEW", ""
+).lower() in {"1", "true", "yes", "on"}
+
+# Budget cap on combined RSS of all running spawned children (not the
+# parent itself). spawn() refuses a new child whose estimated RSS would
+# push total over this. Default 3 GB. Set 0 to disable budget enforcement.
+SPAWN_BUDGET_MB: int = int(
+    os.environ.get("THREADKEEPER_SPAWN_BUDGET_MB", "3072")
+)
+# Initial RSS estimate for a freshly-spawned child before its real RSS is
+# measured by the budget daemon. Updated to actual value within ~10s.
+SPAWN_ESTIMATE_SLIM_MB: int = int(
+    os.environ.get("THREADKEEPER_SPAWN_ESTIMATE_SLIM_MB", "500")
+)
+SPAWN_ESTIMATE_FULL_MB: int = int(
+    os.environ.get("THREADKEEPER_SPAWN_ESTIMATE_FULL_MB", "1500")
+)
+# Budget daemon poll interval (seconds). 0 disables the daemon (estimates
+# stay frozen; not recommended outside tests).
+SPAWN_BUDGET_POLL_S: float = float(
+    os.environ.get("THREADKEEPER_SPAWN_BUDGET_POLL_S", "10")
+)
+
+# Shadow-review daemon. Periodically scans recently-ingested
+# dialog_messages from ALL active sessions, looks for class-level
+# learning signals, and spawns an LLM evaluator child to decide whether
+# to materialize a skill. 0 disables (default — opt in via env).
+SHADOW_REVIEW_INTERVAL_S: float = float(
+    os.environ.get("THREADKEEPER_SHADOW_REVIEW_INTERVAL_S", "0")
+)
+# Sliding window of dialog history each shadow pass considers, in
+# seconds. Combined with the dedup cursor: actual scan range is
+# max(cursor_ts, now-window_s) → now.
+SHADOW_REVIEW_WINDOW_S: int = int(
+    os.environ.get("THREADKEEPER_SHADOW_REVIEW_WINDOW_S", "900")
+)
+# Minimum significant chars (user+assistant dialog combined) before a
+# pass is worth spawning the evaluator. Cheap floor against periodic
+# misfires on idle windows.
+SHADOW_REVIEW_MIN_CHARS: int = int(
+    os.environ.get("THREADKEEPER_SHADOW_REVIEW_MIN_CHARS", "500")
+)
+
+# Curator daemon. Periodic LLM-driven audit of the existing
+# lessons.md + ~/.claude/skills/ library — grades, suggests
+# consolidation/patches/prunes, writes a per-run REPORT.md. Where
+# shadow_review LOOKS FOR NEW class-level learning every few minutes,
+# the Curator REVIEWS THE STORE every few days. Inspired by Hermes
+# Agent v0.12's `hermes curator` cron agent. 0 disables (default —
+# opt in via env). Recommended: 604800 (7 days).
+CURATOR_INTERVAL_S: float = float(
+    os.environ.get("THREADKEEPER_CURATOR_INTERVAL_S", "0")
+)
+# Don't bother curating a tiny library; below this lessons-count there's
+# nothing meaningful to consolidate.
+CURATOR_MIN_LESSONS: int = int(
+    os.environ.get("THREADKEEPER_CURATOR_MIN_LESSONS", "3")
+)
+# Where the Curator writes its REPORT-<isodate>.md per run. One file
+# per pass; latest is the canonical one to read. Anchored to DB_PATH's
+# parent so a custom THREADKEEPER_DB co-locates its curator reports.
+CURATOR_REPORTS_DIR: Path = Path(
+    os.environ.get(
+        "THREADKEEPER_CURATOR_REPORTS_DIR",
+        str(DB_PATH.parent / "curator"),
+    )
+).expanduser()
+# When TRUE, curator-child gets write-mode tools (skill_manage delete/
+# patch + lesson_append) and is instructed to apply its own PRUNE /
+# PATCH / CONSOLIDATE recommendations directly, not just report them.
+# Default OFF — Phase 1 is advisory-only, user reviews REPORT.md and
+# applies manually. Flip to "1" once you trust the curator's verdicts.
+CURATOR_DESTRUCTIVE: bool = bool(
+    os.environ.get("THREADKEEPER_CURATOR_DESTRUCTIVE", "")
+)
+
+# Extract daemon. Periodically scans dialog_messages for heuristic
+# candidates (note / concept / distill / verbatim) via extract_recent()
+# and enqueues them under extract_candidates.status='pending'. Where
+# shadow_review extracts CLASS-LEVEL durable rules, extract harvests
+# PER-INCIDENT decision-shaped utterances ("let's use X", "next time
+# we should Y", insight markers, bullet-listed regularities). Agent's
+# subsequent review_candidates() / accept_candidate() materializes the
+# survivors into notes/concepts/distills.
+# 0 disables (default — opt in via env). Recommended: 600 (every 10
+# min) — extract is cheap, just regex + cosine clustering on the
+# already-ingested dialog window.
+EXTRACT_INTERVAL_S: float = float(
+    os.environ.get("THREADKEEPER_EXTRACT_INTERVAL_S", "0")
+)
+# Sliding window of dialog history each extract pass considers, in
+# minutes. Defaults align with the typical agent-task duration so a
+# whole task's worth of decisions gets harvested at once.
+EXTRACT_WINDOW_MIN: int = int(
+    os.environ.get("THREADKEEPER_EXTRACT_WINDOW_MIN", "30")
+)

threadkeeper/curator.py

@@ -0,0 +1,390 @@
+"""Autonomous Curator — periodic library audit & consolidation.
+
+Inspired by Hermes Agent v0.12's `hermes curator` cron agent. Where
+shadow_review LOOKS FOR NEW class-level learning every few minutes,
+the Curator REVIEWS THE STORE every few days:
+
+  1. Daemon thread wakes every CURATOR_INTERVAL_S seconds (0 = off).
+  2. Collects inventory: every lesson slug + every recently-touched
+     skill + usage telemetry.
+  3. Spawns slim child with CURATOR_PROMPT + inventory dump.
+  4. Child grades each entry, suggests KEEP / PATCH / CONSOLIDATE /
+     PRUNE, and writes REPORT-<isodate>.md under CURATOR_REPORTS_DIR.
+  5. Parent records `curator_pass` event with high-water timestamp.
+
+Design choices borrowed from Hermes:
+
+  • **Class-first / rubric-based output** — child uses an explicit
+    decision matrix (see CURATOR_PROMPT) rather than free-form grading.
+  • **Defense-in-depth** — pinned lessons/skills and foreground-origin
+    entries are listed in the inventory as PROTECTED so the child knows
+    not to touch them.
+  • **Scoped toolset** — child gets only lesson_*/skill_*/Read/Write.
+    No shell, no web, no spawn. Curator can't sprawl into anything else.
+  • **Per-run REPORT.md** — every pass leaves an auditable trail.
+  • **Read-only-by-default destructive ops** — Phase 1: child writes a
+    REPORT.md with recommendations only. User reviews it and decides
+    whether to apply patches/consolidations manually. Future versions
+    can flip an env knob to let the curator merge/delete in place.
+
+Why this exists: shadow_review accumulates lessons over weeks. Without
+periodic curation, the library grows unbounded with overlapping,
+duplicate, or stale content — the same failure mode that pushed
+Hermes to add their Curator in v0.12.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import threading
+import time
+
+from .config import (
+    CURATOR_INTERVAL_S,
+    CURATOR_MIN_LESSONS,
+    CURATOR_REPORTS_DIR,
+    CURATOR_DESTRUCTIVE,
+)
+from .db import get_db
+from . import identity, lessons
+
+logger = logging.getLogger(__name__)
+
+_started = False
+
+
+CURATOR_PROMPT = """\
+You are an autonomous CURATOR for thread-keeper's lessons + skills
+library. You read the inventory below — every lesson slug, every
+recently-touched skill, usage telemetry — and decide what to keep,
+patch, consolidate, or prune.
+
+Where the shadow_review observer LOOKS FOR new class-level learning,
+your role is the inverse: review the EXISTING store for quality, dedup,
+and freshness.
+
+OUTPUT: write a REPORT.md to ~/.threadkeeper/curator/REPORT-<isodate>.md
+via Write tool. The REPORT.md is your sole user-visible output; the
+human reads it later and decides which recommendations to apply.
+
+RUBRIC (per-entry decision matrix — answer for every lesson and every
+recently-active skill):
+
+  KEEP — entry is class-level, in use, accurate. Note "KEEP: <slug>".
+
+  PATCH — entry is mostly right but missing a step, has outdated
+  example, or contradicts something more recent. Quote the exact
+  string to change and the replacement. Format:
+    PATCH: <slug>
+      old: "<exact substring>"
+      new: "<replacement>"
+      reason: <one line>
+
+  CONSOLIDATE — two or more entries cover overlapping territory and
+  would be stronger as one umbrella. Format:
+    CONSOLIDATE: <merged-slug>
+      merges: <slug-a>, <slug-b>, ...
+      keep_in_umbrella: <bullet list of what carries over>
+      reason: <one line on why they overlap>
+
+  PRUNE — entry is one-off incident narrative, env-specific transient,
+  superseded by a newer entry, or a **FALSE POSITIVE** (auto-created
+  by the background-review loop but never validated by actual use).
+  Specifically flag as PRUNE:
+    • origin=background_review AND use_count=0 AND patches=0 AND
+      created >14 days ago → strong false-positive signal: nobody ever
+      consulted it, and the agent that created it never came back to
+      refine it.
+    • SKILL_OUTCOME signals (in the events table) marking the skill
+      as 'wrong' more often than 'helped' → user-judgment override.
+  Format:
+    PRUNE: <slug>
+      reason: <one line; note "false_positive" if from the criteria above>
+
+INVENTORY ORDERING — entries marked [PROTECTED] are pinned or
+foreground-authored. NEVER suggest PATCH/CONSOLIDATE/PRUNE on those —
+only KEEP. Always-OK to RECOMMEND that the user manually review them,
+but the curator must not propose destructive changes.
+
+PRIORITY ORDER inside the REPORT.md:
+  1. CONSOLIDATE recommendations first (highest leverage — merging two
+     overlapping entries clarifies the whole library).
+  2. PATCH recommendations next (low-risk, in-place improvements).
+  3. PRUNE recommendations last (highest-risk; require explicit human
+     confirmation).
+  4. KEEP entries summarised at the end as a short list of slugs.
+
+OPEN with a one-paragraph LIBRARY HEALTH summary: total entries,
+average use_count, most/least-used skill, oldest untouched entry.
+
+CLOSE with the literal line `CURATOR_PASS_COMPLETE` so the parent
+process knows the run finished cleanly.
+
+CONSTRAINTS:
+- Do NOT cite internal IDs (T-codes, cids, task IDs) in the REPORT.md.
+  Plain prose for the human reader.
+- If the inventory is genuinely fine (no patches/consolidations/prunes
+  warranted), still write a REPORT.md that says so — the trail matters
+  even when nothing changes.
+- {DESTRUCTIVE_CLAUSE}
+
+INVENTORY
+=========
+"""
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Pure functions: cursor, inventory collection
+# ──────────────────────────────────────────────────────────────────────
+
+def _last_curator_ts(conn: sqlite3.Connection) -> int:
+    """High-water timestamp of the most recent curator pass. Stored in
+    `target` of the latest `events.kind='curator_pass'` row so `summary`
+    is free for human-readable outcome. Returns 0 when no prior pass."""
+    try:
+        row = conn.execute(
+            "SELECT target FROM events WHERE kind='curator_pass' "
+            "ORDER BY id DESC LIMIT 1"
+        ).fetchone()
+    except sqlite3.OperationalError:
+        return 0
+    if not row or not row["target"]:
+        return 0
+    try:
+        return int(row["target"])
+    except (ValueError, TypeError):
+        return 0
+
+
+def _record_curator_pass(conn: sqlite3.Connection,
+                         ts: int,
+                         outcome: str) -> None:
+    try:
+        conn.execute(
+            "INSERT INTO events (session_id, kind, target, summary, "
+            "created_at) VALUES (?, 'curator_pass', ?, ?, ?)",
+            (identity._session_id or "", str(ts), outcome[:300],
+             int(time.time())),
+        )
+        conn.commit()
+    except sqlite3.OperationalError:
+        logger.debug("curator: failed to record pass", exc_info=True)
+
+
+def _format_lesson(item: dict) -> str:
+    """One inventory line per lesson.
+
+    Lessons aren't pinned in the same way skills are — but lessons
+    flagged with `source=foreground` (i.e. user-typed via lesson_append
+    in a live session, not auto-spawned) get the PROTECTED marker so
+    the curator never proposes destructive changes against them."""
+    src = (item.get("source") or "").strip()
+    protected = " [PROTECTED]" if src in ("foreground", "user") else ""
+    ts = item.get("ts") or 0
+    age_d = (int(time.time()) - ts) // 86400 if ts else "?"
+    body_preview = (item.get("body") or "")[:200].replace("\n", " ")
+    if len(item.get("body") or "") > 200:
+        body_preview += "…"
+    return (
+        f"- LESSON {item['slug']}{protected} "
+        f"(source={src or '?'}, age={age_d}d)\n"
+        f"    body: {body_preview}"
+    )
+
+
+def _format_skill(row: dict) -> str:
+    """One inventory line per recently-touched skill row from
+    skill_usage. Foreground-origin and pinned skills are PROTECTED."""
+    origin = row.get("created_by_origin") or "?"
+    protected = ""
+    if row.get("pinned") or origin == "foreground":
+        protected = " [PROTECTED]"
+    now = int(time.time())
+    last_active = max(
+        row.get("last_used_at") or 0,
+        row.get("last_viewed_at") or 0,
+        row.get("last_patched_at") or 0,
+        row.get("created_at") or 0,
+    )
+    age_d = (now - last_active) // 86400 if last_active else "?"
+    return (
+        f"- SKILL {row['name']}{protected} "
+        f"(origin={origin}, uses={row.get('use_count', 0)}, "
+        f"views={row.get('view_count', 0)}, "
+        f"patches={row.get('patch_count', 0)}, "
+        f"last_active={age_d}d_ago, state={row.get('state', '?')})"
+    )
+
+
+def _collect_inventory(conn: sqlite3.Connection) -> tuple[str, int, int]:
+    """Build the inventory dump the curator child will read.
+
+    Returns (dump_text, lesson_count, skill_count). The dump format is
+    plain text — `_format_lesson` and `_format_skill` produce one line
+    per entry, grouped into LESSONS and SKILLS sections.
+    """
+    # ---- Lessons ----
+    lesson_lines: list[str] = []
+    n_lessons = 0
+    try:
+        for item in lessons.iter_lessons():
+            lesson_lines.append(_format_lesson(item))
+            n_lessons += 1
+    except Exception:
+        logger.debug("curator: iter_lessons failed", exc_info=True)
+
+    # ---- Skills ----
+    skill_lines: list[str] = []
+    n_skills = 0
+    try:
+        rows = conn.execute(
+            "SELECT name, created_at, created_by_origin, last_used_at, "
+            "last_viewed_at, last_patched_at, use_count, view_count, "
+            "patch_count, pinned, state "
+            "FROM skill_usage "
+            "WHERE state IN ('active', 'stale') "
+            "ORDER BY COALESCE(last_used_at, last_viewed_at, "
+            "                  last_patched_at, created_at) DESC"
+        ).fetchall()
+        for r in rows:
+            skill_lines.append(_format_skill(dict(r)))
+            n_skills += 1
+    except sqlite3.OperationalError:
+        logger.debug("curator: skill_usage scan failed", exc_info=True)
+
+    parts: list[str] = []
+    parts.append(f"## LESSONS (n={n_lessons})\n")
+    parts.extend(lesson_lines if lesson_lines else ["(none)"])
+    parts.append(f"\n## SKILLS (n={n_skills})\n")
+    parts.extend(skill_lines if skill_lines else ["(none)"])
+
+    return ("\n".join(parts), n_lessons, n_skills)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Synchronous pass + daemon loop
+# ──────────────────────────────────────────────────────────────────────
+
+def run_curator_pass(force: bool = False) -> str:
+    """Execute one curator pass synchronously. Used by the daemon AND
+    by the MCP tool for manual triggering / testing.
+
+    Returns a short status string for observability:
+      - 'disabled'        — env knob off and not forced
+      - 'below_threshold' — fewer than CURATOR_MIN_LESSONS lessons; skip
+      - 'spawned task_id=…' — curator child launched
+      - 'spawn_error: …'  — spawn() rejected
+    """
+    if CURATOR_INTERVAL_S <= 0 and not force:
+        return "disabled"
+    conn = get_db()
+    inventory, n_lessons, n_skills = _collect_inventory(conn)
+    now = int(time.time())
+    if n_lessons < CURATOR_MIN_LESSONS:
+        _record_curator_pass(
+            conn, now,
+            f"below_threshold lessons={n_lessons} skills={n_skills}",
+        )
+        return f"below_threshold lessons={n_lessons}"
+
+    # Ensure reports dir exists before the child tries to Write into it.
+    CURATOR_REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Phase-1 default: advisory-only. CURATOR_DESTRUCTIVE=1 promotes
+    # the child to "apply your own recommendations directly" mode and
+    # widens the allowed-tools list to include skill_manage + lesson_append.
+    if CURATOR_DESTRUCTIVE:
+        destructive_clause = (
+            "DESTRUCTIVE MODE ENABLED. After writing the REPORT.md you "
+            "MAY apply your own PATCH / PRUNE / CONSOLIDATE recommendations "
+            "directly via skill_manage(action='patch'|'delete'|'write_file') "
+            "and lesson_append(...). Always cross-check against the "
+            "[PROTECTED] marker — never touch protected entries even in "
+            "destructive mode. Apply changes ONLY after the REPORT.md is "
+            "written (audit trail first, mutation second)."
+        )
+        allowed_tools = (
+            "mcp__thread-keeper__lesson_list,"
+            "mcp__thread-keeper__lesson_get,"
+            "mcp__thread-keeper__lesson_append,"
+            "mcp__thread-keeper__skill_list,"
+            "mcp__thread-keeper__skill_manage,"
+            "Read,Write"
+        )
+    else:
+        destructive_clause = (
+            "ADVISORY MODE. Do NOT call lesson_append, skill_manage with "
+            "action in {create,patch,delete,write_file}, or any other "
+            "destructive tool. Your output is the REPORT.md ONLY — the "
+            "human reviews and applies changes manually. Flip "
+            "THREADKEEPER_CURATOR_DESTRUCTIVE=1 in env when ready to let "
+            "the curator apply its own recommendations."
+        )
+        allowed_tools = (
+            "mcp__thread-keeper__lesson_list,"
+            "mcp__thread-keeper__lesson_get,"
+            "mcp__thread-keeper__skill_list,"
+            "Read,Write"
+        )
+
+    full_prompt = (
+        CURATOR_PROMPT.replace("{DESTRUCTIVE_CLAUSE}", destructive_clause)
+        + inventory
+        + "\n\n"
+        + f"REPORT_PATH = {CURATOR_REPORTS_DIR}/REPORT-"
+        f"{time.strftime('%Y%m%dT%H%M%S')}.md\n"
+        + "Write the REPORT.md to that exact path."
+    )
+
+    from .tools.spawn import spawn  # type: ignore
+    try:
+        result = spawn(
+            prompt=full_prompt,
+            visible=False,
+            capture_output=True,
+            permission_mode="auto",
+            role="curator",
+            write_origin="curator",
+            slim=True,
+            extra_allowed_tools=allowed_tools,
+        )
+    except Exception as e:
+        _record_curator_pass(conn, now, f"spawn_error: {e}")
+        return f"spawn_error: {e}"
+
+    _record_curator_pass(
+        conn, now,
+        f"spawned lessons={n_lessons} skills={n_skills} :: {str(result)[:140]}",
+    )
+    return str(result)
+
+
+def _serve_loop() -> None:
+    """Daemon body. Sleep → tick → sleep, until process dies."""
+    while True:
+        try:
+            run_curator_pass()
+        except Exception:
+            logger.debug("curator tick failed", exc_info=True)
+        time.sleep(CURATOR_INTERVAL_S)
+
+
+def start_curator_daemon() -> None:
+    """Idempotent daemon starter. Honors env: no-op when
+    CURATOR_INTERVAL_S<=0. Identical cascade-prevention as
+    start_shadow_daemon: slim children (SEMANTIC_AVAILABLE=False)
+    refuse to start the daemon so spawn() doesn't recurse."""
+    global _started
+    if _started:
+        return
+    if CURATOR_INTERVAL_S <= 0:
+        return
+    from .config import SEMANTIC_AVAILABLE
+    if not SEMANTIC_AVAILABLE:
+        return  # slim child: don't fire curator from here
+    t = threading.Thread(
+        target=_serve_loop, name="curator", daemon=True,
+    )
+    t.start()
+    _started = True