threadkeeper 0.4.0__py3-none-any.whl

threadkeeper/spawn_budget.py

@@ -0,0 +1,246 @@
+"""RSS budget enforcement for spawned children.
+
+Cap on combined RSS of all running spawned children. The parent process
+itself is not counted (we don't constrain the user's main agent). Default
+budget is `SPAWN_BUDGET_MB` (3072 MB).
+
+Flow:
+  spawn() pre-flight:
+    estimate child RSS (slim → SPAWN_ESTIMATE_SLIM_MB, else FULL)
+    check_budget(conn, new_kb) returns ("ok"|"refused", message)
+    if refused → spawn() returns ERR + reason
+    else → INSERT tasks row with rss_kb = estimate, then proceed
+
+  background daemon (start_budget_daemon):
+    every SPAWN_BUDGET_POLL_S seconds, walk running tasks, compute real
+    RSS of each process tree via `ps`, write back into tasks.rss_kb.
+    Tasks that have ended → no update (their rss_kb stays as last seen
+    but they're filtered out by ended_at IS NOT NULL anyway).
+
+  spawn_budget_status() (MCP):
+    "budget=N MB used=N MB free=N MB | per_task..."
+
+Set SPAWN_BUDGET_MB=0 to disable enforcement entirely.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+import threading
+import time
+from typing import Optional, Tuple
+
+from .config import (
+    SPAWN_BUDGET_MB,
+    SPAWN_ESTIMATE_SLIM_MB,
+    SPAWN_ESTIMATE_FULL_MB,
+    SPAWN_BUDGET_POLL_S,
+)
+from .db import get_db
+from .helpers import alive
+
+logger = logging.getLogger(__name__)
+
+_started = False
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Estimates
+# ─────────────────────────────────────────────────────────────────────
+
+def estimate_child_rss_kb(slim: bool) -> int:
+    """Initial RSS guess for a not-yet-running child, used by admission
+    control. Real value replaces this within `SPAWN_BUDGET_POLL_S`."""
+    mb = SPAWN_ESTIMATE_SLIM_MB if slim else SPAWN_ESTIMATE_FULL_MB
+    return int(mb) * 1024
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Tree walker — sum RSS of pid and all its descendants via `ps`
+# ─────────────────────────────────────────────────────────────────────
+
+def _ps_pairs() -> list[tuple[int, int]]:
+    """Snapshot of (pid, ppid) for every process visible to `ps`."""
+    try:
+        r = subprocess.run(
+            ["ps", "-ax", "-o", "pid=,ppid="],
+            capture_output=True, text=True, timeout=3,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return []
+    out: list[tuple[int, int]] = []
+    for line in (r.stdout or "").splitlines():
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        try:
+            out.append((int(parts[0]), int(parts[1])))
+        except ValueError:
+            continue
+    return out
+
+
+def _rss_for_pids(pids: list[int]) -> int:
+    """Sum RSS (KB) for the given pids via `ps`. Missing pids contribute 0."""
+    if not pids:
+        return 0
+    try:
+        r = subprocess.run(
+            ["ps", "-o", "pid=,rss="] + ["-p"] + [str(p) for p in pids],
+            capture_output=True, text=True, timeout=3,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return 0
+    total = 0
+    for line in (r.stdout or "").splitlines():
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        try:
+            total += int(parts[1])
+        except ValueError:
+            continue
+    return total
+
+
+def measure_tree_rss_kb(root_pid: int) -> Optional[int]:
+    """Walk descendants of root_pid and return summed RSS in KB.
+    Returns None when the root is gone (so caller can leave the row alone)."""
+    if root_pid is None or root_pid <= 0:
+        return None
+    pairs = _ps_pairs()
+    if not pairs:
+        return None
+    # Bail when the root isn't visible — process ended.
+    root_alive = any(pid == root_pid for pid, _ in pairs)
+    if not root_alive:
+        return None
+    # BFS descendants
+    children_by_parent: dict[int, list[int]] = {}
+    for pid, ppid in pairs:
+        children_by_parent.setdefault(ppid, []).append(pid)
+    tree = [root_pid]
+    frontier = [root_pid]
+    while frontier:
+        nxt: list[int] = []
+        for p in frontier:
+            for kid in children_by_parent.get(p, ()):
+                tree.append(kid)
+                nxt.append(kid)
+        frontier = nxt
+    return _rss_for_pids(tree)
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Budget check
+# ─────────────────────────────────────────────────────────────────────
+
+def _running_tasks_rss(conn) -> int:
+    """Sum rss_kb across tasks that are not ended. NULL rss_kb means we
+    haven't measured yet — assume the FULL estimate as a conservative
+    placeholder, otherwise a spawn flood could squeeze past the cap before
+    the daemon catches up."""
+    rows = conn.execute(
+        "SELECT rss_kb FROM tasks WHERE ended_at IS NULL"
+    ).fetchall()
+    total = 0
+    fallback_kb = SPAWN_ESTIMATE_FULL_MB * 1024
+    for r in rows:
+        total += (r["rss_kb"] if r["rss_kb"] is not None else fallback_kb)
+    return total
+
+
+def check_budget(conn, new_child_kb: int) -> Tuple[bool, str]:
+    """Decide whether spawning a child of `new_child_kb` would breach the
+    budget. Returns (ok, message). When SPAWN_BUDGET_MB=0, always ok."""
+    if SPAWN_BUDGET_MB <= 0:
+        return True, "budget_disabled"
+    budget_kb = SPAWN_BUDGET_MB * 1024
+    current = _running_tasks_rss(conn)
+    projected = current + new_child_kb
+    if projected > budget_kb:
+        cur_mb = current // 1024
+        new_mb = new_child_kb // 1024
+        proj_mb = projected // 1024
+        return False, (
+            f"budget_exceeded: running_subagents={cur_mb}MB + "
+            f"new_child={new_mb}MB = {proj_mb}MB > "
+            f"limit={SPAWN_BUDGET_MB}MB. Wait for a child to finish, "
+            f"raise THREADKEEPER_SPAWN_BUDGET_MB, or use task_kill()."
+        )
+    return True, (
+        f"ok: current={current // 1024}MB + new={new_child_kb // 1024}MB "
+        f"≤ {SPAWN_BUDGET_MB}MB"
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Daemon — refresh real RSS values
+# ─────────────────────────────────────────────────────────────────────
+
+def _refresh_all_running(conn) -> int:
+    """Sweep running tasks, update rss_kb with real measurement. Tasks
+    whose pid is invalid (0 / visible spawn) are skipped — their RSS
+    can't be tracked from here. Returns number of rows updated."""
+    rows = conn.execute(
+        "SELECT id, pid, spawned_cid FROM tasks "
+        "WHERE ended_at IS NULL ORDER BY started_at DESC LIMIT 100"
+    ).fetchall()
+    now = int(time.time())
+    updated = 0
+    for r in rows:
+        pid = r["pid"]
+        if not pid or pid <= 0:
+            continue  # visible spawns — Terminal-launched, pid not tracked
+        if not alive(pid):
+            # Process gone — mark ended, leave rss_kb as last-known.
+            conn.execute(
+                "UPDATE tasks SET ended_at=? WHERE id=? AND ended_at IS NULL",
+                (now, r["id"]),
+            )
+            continue
+        rss = measure_tree_rss_kb(pid)
+        if rss is None:
+            continue
+        conn.execute(
+            "UPDATE tasks SET rss_kb=?, rss_updated_at=? WHERE id=?",
+            (rss, now, r["id"]),
+        )
+        updated += 1
+    if updated:
+        try:
+            conn.commit()
+        except Exception:
+            pass
+    return updated
+
+
+def _daemon_loop() -> None:
+    while True:
+        try:
+            conn = get_db()
+            try:
+                _refresh_all_running(conn)
+            finally:
+                conn.close()
+        except Exception:
+            logger.debug("spawn_budget daemon tick failed", exc_info=True)
+        time.sleep(SPAWN_BUDGET_POLL_S)
+
+
+def start_budget_daemon() -> None:
+    """Idempotent — call from _ensure_session lazily."""
+    global _started
+    if _started:
+        return
+    if SPAWN_BUDGET_POLL_S <= 0:
+        return
+    if SPAWN_BUDGET_MB <= 0:
+        return  # budget disabled, no need to track
+    t = threading.Thread(
+        target=_daemon_loop, name="spawn_budget", daemon=True,
+    )
+    t.start()
+    _started = True

threadkeeper/tools/__init__.py

@@ -0,0 +1,2 @@
+"""Tool modules. Importing each one registers its @mcp.tool() entries on
+the singleton in threadkeeper._mcp.mcp."""

threadkeeper/tools/concepts.py

@@ -0,0 +1,111 @@
+"""Concept-registration MCP tools.
+
+Extracted from server.py. Provides registration, listing, and
+expansion for nameless concepts triangulated across paraphrase runs.
+"""
+
+import sqlite3
+import time
+from typing import Optional
+
+from .._mcp import mcp
+from ..db import get_db
+from ..helpers import fmt_age, q, gen_concept_id
+from ..identity import _ensure_session, _detect_self_cid, _emit
+
+
+@mcp.tool()
+def register_concept(description: str,
+                     triangulation_notes: str = "",
+                     confidence: str = "medium",
+                     source_thread: str = "") -> str:
+    """Register a concept that lacks a precise human name.
+
+    `description` should describe the phenomenon through EXAMPLES, not with
+    a canonical label — naming it locks it back into a human discipline.
+    `triangulation_notes` (optional): the paraphrase runs that surfaced
+    the invariant. `confidence` ∈ {low, medium, high}."""
+    if confidence not in ("low", "medium", "high"):
+        return f"ERR bad_confidence={confidence}"
+    if not description.strip():
+        return "ERR empty_description"
+    conn = get_db()
+    _ensure_session(conn)
+    cid = _detect_self_cid()
+    src = source_thread.strip() or None
+    if src and not conn.execute(
+        "SELECT 1 FROM threads WHERE id=?", (src,)
+    ).fetchone():
+        return f"ERR source_thread_not_found={src}"
+    pid = gen_concept_id(conn)
+    now_t = int(time.time())
+    conn.execute(
+        "INSERT INTO concepts (id, description, triangulation_notes, "
+        "confidence, source_thread, registered_by_cid, registered_at, "
+        "last_evidence_at) VALUES (?,?,?,?,?,?,?,?)",
+        (pid, description, triangulation_notes or None, confidence,
+         src, cid, now_t, now_t),
+    )
+    _emit(conn, "register_concept", target=pid,
+          summary=description[:140])
+    conn.commit()
+    return f"ok id={pid} conf={confidence}"
+
+
+@mcp.tool()
+def list_concepts(min_confidence: str = "low", k: int = 10) -> str:
+    """List registered concepts, filtered by minimum confidence."""
+    rank = {"low": 0, "medium": 1, "high": 2}
+    if min_confidence not in rank:
+        return f"ERR bad_confidence={min_confidence}"
+    conn = get_db()
+    rows = conn.execute(
+        "SELECT id, description, confidence, source_thread, registered_at "
+        "FROM concepts ORDER BY registered_at DESC LIMIT ?",
+        (max(1, int(k)) * 3,),
+    ).fetchall()
+    out = []
+    for r in rows:
+        if rank[r["confidence"]] < rank[min_confidence]:
+            continue
+        out.append({
+            "id": r["id"],
+            "conf": r["confidence"],
+            "src": r["source_thread"] or "-",
+            "age": fmt_age(int(time.time()) - r["registered_at"]),
+            "desc": r["description"][:240].replace("\n", " "),
+        })
+        if len(out) >= k:
+            break
+    if not out:
+        return f"no_concepts (min_confidence={min_confidence})"
+    lines = [f"concepts n={len(out)}"]
+    for c in out:
+        lines.append(
+            f"  {c['id']} conf={c['conf']} src={c['src']} "
+            f"age={c['age']}_ago"
+        )
+        lines.append(f"    {c['desc']}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def expand_concept(concept_id: str) -> str:
+    """Full description + triangulation_notes for one concept."""
+    conn = get_db()
+    r = conn.execute(
+        "SELECT * FROM concepts WHERE id=?", (concept_id.strip(),)
+    ).fetchone()
+    if not r:
+        return f"ERR concept_not_found={concept_id}"
+    parts = [
+        f"id={r['id']} conf={r['confidence']} src={r['source_thread'] or '-'} "
+        f"by={(r['registered_by_cid'] or '?')[:8]} "
+        f"age={fmt_age(int(time.time()) - r['registered_at'])}_ago",
+        "",
+        "description:",
+        r["description"],
+    ]
+    if r["triangulation_notes"]:
+        parts += ["", "triangulation_notes:", r["triangulation_notes"]]
+    return "\n".join(parts)

threadkeeper/tools/consolidate.py

@@ -0,0 +1,222 @@
+"""Consolidate MCP tool: periodic memory hygiene.
+
+Extracted from server.py. Provides a dry-run-by-default sweep that
+reports (and optionally applies) four kinds of cleanup:
+
+  merge_dup_notes : intra-thread cosine ≥ note_cosine, keep oldest
+  idle_stale      : active threads not touched in stale_days
+  dedupe_verbatim : exact text + (if embeddings) cosine ≥ verbatim_cosine
+  release_orphan  : claim ≥ orphan_days old, no progress past claim mark
+"""
+
+import sqlite3
+import time
+
+from .._mcp import mcp
+from ..db import get_db
+from ..config import SEMANTIC_AVAILABLE
+from ..helpers import fmt_age, q, normalize_text
+from ..identity import _ensure_session, _emit
+from ..embeddings import _get_model
+
+
+CONSOLIDATE_NOTE_COSINE = 0.95
+CONSOLIDATE_VERBATIM_COSINE = 0.90
+CONSOLIDATE_STALE_THREAD_DAYS = 30
+CONSOLIDATE_ORPHAN_CLAIM_DAYS = 7
+
+
+@mcp.tool()
+def consolidate(dry_run: bool = True,
+                stale_days: int = CONSOLIDATE_STALE_THREAD_DAYS,
+                orphan_days: int = CONSOLIDATE_ORPHAN_CLAIM_DAYS,
+                note_cosine: float = CONSOLIDATE_NOTE_COSINE,
+                verbatim_cosine: float = CONSOLIDATE_VERBATIM_COSINE) -> str:
+    """Periodic memory hygiene. dry_run=True (default) reports only.
+
+      merge_dup_notes : intra-thread cosine ≥ note_cosine, keep oldest
+      idle_stale      : active threads not touched in stale_days
+      dedupe_verbatim : exact text + (if embeddings) cosine ≥ verbatim_cosine
+      release_orphan  : claim ≥ orphan_days old, no progress past claim mark"""
+    conn = get_db()
+    _ensure_session(conn)
+    now = int(time.time())
+    findings = {
+        "merge_dup_notes": [], "idle_stale": [],
+        "dedupe_verbatim": [], "release_orphan": [],
+    }
+    np = None
+    if SEMANTIC_AVAILABLE:
+        try:
+            import numpy as np  # type: ignore
+        except ImportError:
+            np = None
+
+    if np is not None:
+        thread_ids = [
+            r["thread_id"] for r in conn.execute(
+                "SELECT thread_id FROM notes WHERE thread_id IS NOT NULL "
+                "AND embedding IS NOT NULL "
+                "GROUP BY thread_id HAVING COUNT(*) >= 2"
+            ).fetchall()
+        ]
+        for tid in thread_ids:
+            ns = conn.execute(
+                "SELECT id, content, embedding, created_at FROM notes "
+                "WHERE thread_id=? AND embedding IS NOT NULL "
+                "ORDER BY created_at ASC", (tid,)
+            ).fetchall()
+            if len(ns) < 2:
+                continue
+            embs = np.stack([
+                np.frombuffer(n["embedding"], dtype="float32") for n in ns
+            ])
+            sim = embs @ embs.T
+            kept = [True] * len(ns)
+            for i in range(len(ns)):
+                if not kept[i]:
+                    continue
+                for j in range(i + 1, len(ns)):
+                    if kept[j] and sim[i, j] >= note_cosine:
+                        kept[j] = False
+                        findings["merge_dup_notes"].append({
+                            "thread": tid, "keep": ns[i]["id"],
+                            "drop": ns[j]["id"],
+                            "cos": float(sim[i, j]),
+                            "snip": ns[j]["content"][:120],
+                        })
+
+    cutoff_stale = now - max(1, int(stale_days)) * 86400
+    for t in conn.execute(
+        "SELECT id, question, last_touched_at FROM threads "
+        "WHERE state='active' AND last_touched_at < ?", (cutoff_stale,)
+    ).fetchall():
+        findings["idle_stale"].append({
+            "thread": t["id"], "question": t["question"][:120],
+            "stale_for": fmt_age(now - t["last_touched_at"]),
+        })
+
+    vb = conn.execute(
+        "SELECT id, speaker, content, created_at FROM verbatim "
+        "ORDER BY created_at DESC"
+    ).fetchall()
+    seen_text: dict = {}
+    semantic_pool: list = []
+    for v in vb:
+        key = (v["speaker"], normalize_text(v["content"]))
+        if key in seen_text:
+            findings["dedupe_verbatim"].append({
+                "keep": seen_text[key], "drop": v["id"],
+                "via": "text_exact", "snip": v["content"][:120],
+            })
+        else:
+            seen_text[key] = v["id"]
+            semantic_pool.append(v)
+    if np is not None and 1 < len(semantic_pool) <= 200:
+        m = _get_model()
+        if m is not None:
+            by_speaker: dict = {}
+            for v in semantic_pool:
+                by_speaker.setdefault(v["speaker"], []).append(v)
+            for sp, vs in by_speaker.items():
+                if len(vs) < 2:
+                    continue
+                vecs = m.encode(
+                    [v["content"] for v in vs], normalize_embeddings=True
+                ).astype("float32")
+                sim = vecs @ vecs.T
+                kept = [True] * len(vs)
+                for i in range(len(vs)):
+                    if not kept[i]:
+                        continue
+                    for j in range(i + 1, len(vs)):
+                        if kept[j] and sim[i, j] >= verbatim_cosine:
+                            kept[j] = False
+                            findings["dedupe_verbatim"].append({
+                                "keep": vs[i]["id"], "drop": vs[j]["id"],
+                                "via": f"cos={float(sim[i, j]):.2f}",
+                                "snip": vs[j]["content"][:120],
+                            })
+
+    cutoff_orphan = now - max(1, int(orphan_days)) * 86400
+    for t in conn.execute(
+        "SELECT id, question, claimed_at, claimed_by_cid, last_touched_at "
+        "FROM threads WHERE claimed_at IS NOT NULL AND claimed_at < ? "
+        "AND last_touched_at <= claimed_at + 60", (cutoff_orphan,)
+    ).fetchall():
+        findings["release_orphan"].append({
+            "thread": t["id"],
+            "claimed_by": (t["claimed_by_cid"] or "?")[:8],
+            "claimed_age": fmt_age(now - t["claimed_at"]),
+            "question": t["question"][:120],
+        })
+
+    applied = {
+        "merge_dup_notes": 0, "idle_stale": 0,
+        "dedupe_verbatim": 0, "release_orphan": 0,
+    }
+    if not dry_run:
+        for f in findings["merge_dup_notes"]:
+            conn.execute("DELETE FROM notes WHERE id=?", (f["drop"],))
+            applied["merge_dup_notes"] += 1
+        for f in findings["idle_stale"]:
+            conn.execute(
+                "UPDATE threads SET state='idle', last_touched_at=? WHERE id=?",
+                (now, f["thread"]),
+            )
+            applied["idle_stale"] += 1
+        for f in findings["dedupe_verbatim"]:
+            conn.execute("DELETE FROM verbatim WHERE id=?", (f["drop"],))
+            applied["dedupe_verbatim"] += 1
+        for f in findings["release_orphan"]:
+            conn.execute(
+                "UPDATE threads SET claimed_at=NULL, claimed_by_cid=NULL "
+                "WHERE id=?", (f["thread"],)
+            )
+            applied["release_orphan"] += 1
+        _emit(conn, "consolidate_apply",
+              summary=" ".join(f"{k}={v}" for k, v in applied.items()))
+        conn.commit()
+
+    out = [
+        f"consolidate dry_run={dry_run} "
+        f"merge={len(findings['merge_dup_notes'])} "
+        f"idle={len(findings['idle_stale'])} "
+        f"dedupe={len(findings['dedupe_verbatim'])} "
+        f"orphan={len(findings['release_orphan'])}"
+    ]
+    if not dry_run:
+        out.append("applied " + " ".join(f"{k}={v}" for k, v in applied.items()))
+    if findings["merge_dup_notes"]:
+        out.append("")
+        out.append("merge_dup_notes (keep oldest)")
+        for f in findings["merge_dup_notes"][:10]:
+            out.append(
+                f"  thread={f['thread']} keep=#{f['keep']} drop=#{f['drop']} "
+                f"cos={f['cos']:.3f} {q(f['snip'])}"
+            )
+    if findings["idle_stale"]:
+        out.append("")
+        out.append(f"idle_stale (>{stale_days}d untouched)")
+        for f in findings["idle_stale"][:10]:
+            out.append(
+                f"  {f['thread']} stale={f['stale_for']} "
+                f"q={q(f['question'])}"
+            )
+    if findings["dedupe_verbatim"]:
+        out.append("")
+        out.append("dedupe_verbatim (keep most-recent)")
+        for f in findings["dedupe_verbatim"][:10]:
+            out.append(
+                f"  keep=#{f['keep']} drop=#{f['drop']} "
+                f"via={f['via']} {q(f['snip'])}"
+            )
+    if findings["release_orphan"]:
+        out.append("")
+        out.append(f"release_orphan (claimed >{orphan_days}d, no progress)")
+        for f in findings["release_orphan"][:10]:
+            out.append(
+                f"  {f['thread']} by={f['claimed_by']} "
+                f"age={f['claimed_age']} q={q(f['question'])}"
+            )
+    return "\n".join(out)

threadkeeper/tools/core_memory.py

@@ -0,0 +1,109 @@
+"""Core-memory MCP tools.
+
+Small key/value store always surfaced in `brief()`, sorted by priority
+DESC. Designed as the 'what new-claude must know' surface — not a note
+store. Entries are capped at 1KB and a soft hint at 20 entries total.
+"""
+
+import sqlite3
+import time
+
+from .._mcp import mcp
+from ..db import get_db
+from ..helpers import fmt_age, q
+from ..identity import _ensure_session, _emit
+
+
+CORE_MAX_BYTES = 1024
+CORE_MAX_ENTRIES_HINT = 20
+CORE_PRIORITY_MIN = 0
+CORE_PRIORITY_MAX = 100
+
+
+@mcp.tool()
+def core_set(key: str, content: str, priority: int = 50) -> str:
+    """Upsert a core-memory entry. ALWAYS shown in brief, sorted by priority DESC.
+
+    Use sparingly — this is the 'what new-claude must know' surface, not a
+    note store. Good: 'project_root=/Users/.../ai-memory'. Bad: 'today we
+    tried X'. `priority` 0-100 (higher = shown first). `content` capped 1KB."""
+    conn = get_db()
+    _ensure_session(conn)
+    key = key.strip()
+    if not key:
+        return "ERR empty_key"
+    if len(key) > 64:
+        return "ERR key_too_long max=64"
+    if not content.strip():
+        return "ERR empty_content"
+    if len(content.encode("utf-8")) > CORE_MAX_BYTES:
+        return f"ERR content_too_large max={CORE_MAX_BYTES}B"
+    if not (CORE_PRIORITY_MIN <= priority <= CORE_PRIORITY_MAX):
+        return f"ERR priority_out_of_range min={CORE_PRIORITY_MIN} max={CORE_PRIORITY_MAX}"
+    now = int(time.time())
+    conn.execute(
+        "INSERT INTO core_memory (key, content, priority, updated_at) "
+        "VALUES (?,?,?,?) ON CONFLICT(key) DO UPDATE SET "
+        "content=excluded.content, priority=excluded.priority, "
+        "updated_at=excluded.updated_at",
+        (key, content, priority, now),
+    )
+    _emit(conn, "core_set", target=key, summary=f"P{priority} {content[:80]}")
+    conn.commit()
+    n = conn.execute("SELECT COUNT(*) c FROM core_memory").fetchone()["c"]
+    warn = f" warn=over_hint({n}/{CORE_MAX_ENTRIES_HINT})" if n > CORE_MAX_ENTRIES_HINT else ""
+    return f"ok n={n}{warn}"
+
+
+@mcp.tool()
+def core_remove(key: str) -> str:
+    """Delete a core-memory entry by key."""
+    conn = get_db()
+    _ensure_session(conn)
+    cur = conn.execute("DELETE FROM core_memory WHERE key=?", (key.strip(),))
+    if cur.rowcount == 0:
+        return f"ERR not_found={key}"
+    _emit(conn, "core_remove", target=key)
+    conn.commit()
+    return "ok"
+
+
+@mcp.tool()
+def core_list() -> str:
+    """List all core-memory entries, ordered by priority DESC then key."""
+    conn = get_db()
+    rows = conn.execute(
+        "SELECT key, content, priority, updated_at FROM core_memory "
+        "ORDER BY priority DESC, key ASC"
+    ).fetchall()
+    if not rows:
+        return "empty"
+    now = int(time.time())
+    lines = []
+    for r in rows:
+        snip = r["content"][:120].replace("\n", " ")
+        if len(r["content"]) > 120:
+            snip += "…"
+        lines.append(
+            f"[P{r['priority']}] {r['key']}: {q(snip)} "
+            f"upd={fmt_age(now - r['updated_at'])}_ago"
+        )
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def core_get(key: str) -> str:
+    """Return the full content of a single core-memory entry."""
+    conn = get_db()
+    row = conn.execute(
+        "SELECT key, content, priority, updated_at FROM core_memory WHERE key=?",
+        (key.strip(),),
+    ).fetchone()
+    if not row:
+        return f"ERR not_found={key}"
+    now = int(time.time())
+    return (
+        f"key={row['key']} P{row['priority']} "
+        f"upd={fmt_age(now - row['updated_at'])}_ago\n"
+        f"{row['content']}"
+    )