forget-connect 0.1.0 → 0.3.0

package/README.md

@@ -1,14 +1,16 @@
 # forget-connect
 
-Connect Claude Code, Codex, and Claude Desktop to [Forget](https://multi-turn.ai)
-without overwriting the MCP servers or global instructions you already have.
+Connect Claude Code, Codex, and Claude Desktop to a local
+[Forget](https://github.com/junghunkim/forget) memory server without
+overwriting the MCP servers or global instructions you already have.
 
 ```bash
-npx forget-connect --user-id <memory-user> --app-id <project>
+npx forget-connect
 ```
 
-The guided flow detects installed clients, asks for a hosted Forget API key
-with hidden input, and then:
+By default this targets the local server at `http://localhost:8000/mcp` —
+your memories stay on your machine. The guided flow detects installed
+clients and then:
 
 - merges a `forget` entry into each selected MCP config;
 - installs a marked memory rule in Claude Code's `CLAUDE.md` and Codex's
@@ -20,36 +22,33 @@ with hidden input, and then:
 Other MCP servers and text outside the marked rule block are preserved. Invalid
 JSON or a damaged marker block aborts before any selected client is changed.
 
-The two scope values are part of the connection, not search-time hints. They
-produce `/mcp/<app-id>/http/<user-id>` so a new client resumes the intended
-project instead of the legacy default scope. For hosted continuity, always set
-both. A bare hosted connection remains available for compatibility but prints a
-warning, and `doctor` will not call it continuity-ready.
-
 ## Non-interactive use
 
-Pass the key through the environment, not a command-line flag (command-line
-arguments can be visible to other local processes):
-
 ```bash
-FORGET_API_KEY=... npx forget-connect \
-  --user-id my-user \
-  --app-id my-project \
-  --client claude-code,codex
+npx forget-connect --client claude-code,codex --yes
 ```
 
-`FORGET_USER_ID` and `FORGET_APP_ID` are equivalent to the two scope flags.
+Use `FORGET_MCP_URL` or `--url` for a server on another port or host. A Bearer
+token (`FORGET_API_KEY`) is only sent over HTTPS; over loopback HTTP the CLI
+connects without a token and says so.
 
-For a local, unauthenticated Forget server:
+## Hosted service (legacy)
+
+The managed service remains available behind an explicit flag while it is
+phased out in favor of local-first:
 
 ```bash
-npx forget-connect \
-  --url http://localhost:8000/mcp \
-  --no-auth \
-  --client all
+FORGET_API_KEY=... npx forget-connect --hosted \
+  --user-id <memory-user> --app-id <project>
 ```
 
-Use `FORGET_MCP_URL` instead of `--url` if preferred.
+Pass the key through the environment, not a command-line flag (command-line
+arguments can be visible to other local processes). `FORGET_USER_ID` and
+`FORGET_APP_ID` are equivalent to the two scope flags. The scope values are
+part of the connection, not search-time hints: they produce
+`/mcp/<app-id>/http/<user-id>` so a new client resumes the intended project.
+A bare hosted connection prints a warning, and `doctor` will not call it
+continuity-ready.
 
 ## Inspect or remove
 
@@ -62,11 +61,10 @@ npx forget-connect disconnect
 `doctor` is non-mutating. It checks that each selected client has the generated
 transport shape, expected URL and authorization, plus the current full
 instruction block (not only its markers). Only after those local checks pass
-does it verify the scoped endpoint identity and perform MCP initialize and
-tools/list against that URL. It fails when hosted scope is absent or mismatched,
-or when the continuity tools for search, write, context, outcome, and task state
-are missing. Add `--json` for automation or `--timeout 30` on a slow network.
-No authorization value or memory content is printed.
+does it perform MCP initialize and tools/list against that URL. For hosted
+connections it also verifies the scoped endpoint identity. Add `--json` for
+automation or `--timeout 30` on a slow network. No authorization value or
+memory content is printed.
 
 `disconnect` removes only the `forget` MCP entry and the marked Forget rules
 block. It does not restore backups or remove unrelated config.
@@ -75,7 +73,8 @@ block. It does not restore backups or remove unrelated config.
 
 ```text
 --client <ids>       claude-code,codex,claude-desktop,all
---url <url>          MCP URL (default: https://api.multi-turn.ai/mcp)
+--url <url>          MCP URL (default: http://localhost:8000/mcp)
+--hosted             Use the managed Forget service (legacy)
 --user-id <id>       Memory user scope; pair with --app-id
 --app-id <id>        Project/app scope; pair with --user-id
 --no-auth            Do not install a Bearer token
@@ -87,9 +86,9 @@ block. It does not restore backups or remove unrelated config.
 -y, --yes            Use detected clients, or all if none are detected
 ```
 
-By default, a legacy `enacta` entry is removed only when it points to the same
-MCP URL being installed. Its marked instruction block is upgraded to the
-Forget block. Use `--no-migrate-enacta` to keep both.
+By default, a legacy `enacta` entry is removed when it points to the URL being
+installed or to the hosted service. Its marked instruction block is upgraded
+to the Forget block. Use `--no-migrate-enacta` to keep both.
 
 ## Files managed
 
@@ -108,3 +107,19 @@ npm test
 npm run lint
 npm pack --dry-run
 ```
+
+## Hooks (Claude Code)
+
+`forget-connect` installs four harness hooks so memory arrives without being asked:
+
+- **SessionStart** — injects a context capsule (open tasks, next actions, constraints)
+- **UserPromptSubmit** — pushes memories relevant to the current turn, with trust lights
+  (green = act on it, yellow = confirm first, red = superseded), and raises a
+  conflict-zone alert when the conversation enters territory with a correction history
+- **PreCompact / SessionEnd** — captures the session into the ledger and records
+  whether offered memories were actually used (the outcome flywheel)
+
+Hooks are judgment-free and fail-open: if the Forget server is down they exit
+silently and never block your session. They need `python3` on PATH.
+Skip them with `--no-hooks`; `disconnect` always removes them. Foreign hooks
+registered by other tools are preserved byte-for-byte.

package/assets/hooks/forget_capture.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""Session capture + mechanical outcome labeling (PreCompact and SessionEnd).
+
+Two judgment-free jobs, each fail-open on its own:
+1. capture — register the session in forget: pointer + mechanical digest,
+   source_role="tool" (green). The transcript on disk is the lossless ledger;
+   this makes it findable.
+2. outcome — if a SessionStart capsule was offered this session (state file
+   exists), measure mechanically whether the session echoed it and record a
+   context outcome against the capsule's trace. This is the crudest possible
+   label (all-or-none echo, substring match); its job is to start the data
+   flywheel, not to be right — retire it when a learned labeler exists
+   (observer W2) or when per-memory matching lands.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import urllib.request
+
+FORGET_URL = os.environ.get("FORGET_MCP_URL", "http://127.0.0.1:8000/mcp")
+STATE_DIR = os.path.expanduser("~/.forget/hooks/state")
+TAIL_BYTES = 400_000
+SNIPPET_LIMIT = 200
+USER_SNIPPETS = 3
+ASSISTANT_BLOB_LIMIT = 300_000
+PROBE_MIN_LEN = 12  # sessionstart의 장부 프로브 최소 길이와 일치해야 함
+PROBE_MAX_LEN = 80
+
+
+def _rpc(name: str, arguments: dict, timeout: int = 5) -> None:
+    payload = {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": name, "arguments": arguments}}
+    request = urllib.request.Request(
+        FORGET_URL,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+    )
+    urllib.request.urlopen(request, timeout=timeout).read()
+
+
+def _text_of(content) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = [block.get("text", "") for block in content if isinstance(block, dict) and block.get("type") == "text"]
+        return " ".join(part for part in parts if part)
+    return ""
+
+
+def _normalize(text: str) -> str:
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def _digest(transcript_path: str) -> dict:
+    with open(transcript_path, "rb") as fh:
+        fh.seek(0, os.SEEK_END)
+        size = fh.tell()
+        fh.seek(max(0, size - TAIL_BYTES))
+        tail = fh.read().decode("utf-8", errors="replace")
+    lines = [line for line in tail.splitlines() if line.strip()]
+    if size > TAIL_BYTES and lines:
+        lines = lines[1:]  # first line of a mid-file seek is usually truncated
+    user_snippets: list[str] = []
+    assistant_parts: list[str] = []
+    assistant_len = 0
+    counts = {"user": 0, "assistant": 0}
+    first_ts = last_ts = ""
+    for line in lines:
+        try:
+            entry = json.loads(line)
+        except ValueError:
+            continue
+        kind = entry.get("type")
+        if kind not in counts:
+            continue
+        counts[kind] += 1
+        ts = str(entry.get("timestamp") or "")
+        if ts:
+            first_ts = first_ts or ts
+            last_ts = ts
+        text = _text_of((entry.get("message") or {}).get("content")).strip()
+        if kind == "user":
+            # skill expansions and system payloads arrive as user-role messages;
+            # real typed utterances are short — length is the cheapest tell
+            if text and len(text) <= 600 and not text.startswith(("<local-command", "<command-name", "[SYSTEM", "#")):
+                user_snippets.append(text[:SNIPPET_LIMIT])
+        elif text and assistant_len < ASSISTANT_BLOB_LIMIT:
+            assistant_parts.append(text)
+            assistant_len += len(text)
+    return {
+        "counts": counts,
+        "first_ts": first_ts,
+        "last_ts": last_ts,
+        "user_snippets": user_snippets[-USER_SNIPPETS:],
+        "assistant_blob": _normalize(" ".join(assistant_parts)),
+        "tail_only": size > TAIL_BYTES,
+    }
+
+
+def _capture(hook_input: dict, digest: dict, transcript_path: str, session_id: str) -> None:
+    event = str(hook_input.get("hook_event_name") or "PreCompact")
+    label = str(hook_input.get("trigger") or hook_input.get("reason") or "auto")
+    snippets = " / ".join(digest["user_snippets"]) or "(없음)"
+    text = (
+        f"세션 캡처 ({event}/{label}): 세션 {session_id} — "
+        f"user {digest['counts']['user']}·assistant {digest['counts']['assistant']} 메시지"
+        f"{' (꼬리 표본)' if digest['tail_only'] else ''}, {digest['first_ts']}~{digest['last_ts']}. "
+        f"최근 사용자 발화: {snippets}. 전문: {transcript_path}"
+    )
+    _rpc(
+        "add_memory",
+        {
+            "text": text,
+            "infer": False,
+            "source_role": "tool",
+            "metadata": {
+                "hook": event,
+                "session_id": session_id,
+                "transcript_path": transcript_path,
+                "trigger": label,
+            },
+        },
+    )
+
+
+def _outcome(digest: dict, session_id: str) -> None:
+    state_path = os.path.join(STATE_DIR, f"{session_id}.json")
+    if not os.path.exists(state_path):
+        return
+    with open(state_path, encoding="utf-8") as fh:
+        state = json.load(fh)
+    trace_id = str(state.get("trace_id") or "")
+    if not trace_id:
+        os.replace(state_path, state_path + ".done")
+        return
+    blob = digest["assistant_blob"]
+    echoed = []
+    for line in state.get("capsule_lines") or []:
+        probe = _normalize(str(line))[:PROBE_MAX_LEN]
+        if len(probe) >= PROBE_MIN_LEN and probe in blob:
+            echoed.append(probe[:40])
+    memory_ids = state.get("memory_ids") or []
+    _rpc(
+        "record_context_outcome",
+        {
+            "trace_id": trace_id,
+            "used_memory_ids": memory_ids if echoed else [],
+            "missing_memory_ids": [],
+            "harmful_memory_ids": [],
+            "first_action_productive": bool(echoed),
+            "user_correction_required": False,
+            "metadata": {
+                "labeler": "mechanical-echo-v1",
+                "session_id": session_id,
+                "echo_count": len(echoed),
+                "echoed_probes": echoed[:5],
+                "granularity": "all-or-none",
+            },
+        },
+        timeout=6,
+    )
+    os.replace(state_path, state_path + ".done")
+
+
+def main() -> None:
+    hook_input = json.load(sys.stdin)
+    transcript_path = str(hook_input.get("transcript_path") or "")
+    session_id = str(hook_input.get("session_id") or "unknown")
+    if not transcript_path or not os.path.exists(transcript_path):
+        return
+    digest = _digest(transcript_path)
+    try:
+        _capture(hook_input, digest, transcript_path, session_id)
+    except Exception:
+        pass
+    # Outcome is a session-final label: a mid-session compact must not consume
+    # the offer ledger, or usage after the compact goes unmeasured.
+    if str(hook_input.get("hook_event_name") or "") == "SessionEnd":
+        try:
+            _outcome(digest, session_id)
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)

package/assets/hooks/forget_sessionstart.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""SessionStart hook: inject a small assembled context capsule from forget.
+
+Design contract (research/ideas/observer-consolidation.md §4.5):
+- the capsule is an OFFER, not a command — the main-thread agent judges
+  whether to use it; low confidence → silence
+- strict token budget: the main context window is the scarcest resource
+- fail-open: any error prints nothing and exits 0
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.request
+
+FORGET_URL = os.environ.get("FORGET_MCP_URL", "http://127.0.0.1:8000/mcp")
+STATE_DIR = os.path.expanduser("~/.forget/hooks/state")
+CAPSULE_CHAR_BUDGET = 1_600  # ~400 tokens
+
+
+def main() -> None:
+    hook_input = json.load(sys.stdin)
+    cwd = str(hook_input.get("cwd") or os.getcwd())
+    source = str(hook_input.get("source") or "startup")
+    payload = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {
+            "name": "prepare_context_autopilot",
+            "arguments": {
+                "query": f"session {source} in {cwd} — active tasks, open loops, recent decisions",
+                "include_debug": False,
+            },
+        },
+    }
+    request = urllib.request.Request(
+        FORGET_URL,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+    )
+    body = json.loads(urllib.request.urlopen(request, timeout=8).read())
+    result = json.loads(body["result"]["content"][0]["text"])
+    capsule = str(result.get("capsule_text") or "").strip()
+    if not capsule:
+        use_now = result.get("use_now") or {}
+        items = use_now.get("items") if isinstance(use_now, dict) else None
+        if isinstance(items, list) and items:
+            capsule = "\n".join(f"- {item}" for item in items[:6] if isinstance(item, str))
+    if not capsule:
+        return  # low confidence → silence
+    shown = capsule[:CAPSULE_CHAR_BUDGET]
+    print(
+        "[forget 캡슐 — 제안이며 명령이 아님. 채택/기각은 네 판단. "
+        "라벨 없는 항목은 노랑(행동 전 확인) 취급]\n" + shown
+    )
+    # Offer ledger: record what was offered so the capture hook can measure,
+    # at session end, whether the offer was actually used (outcome flywheel).
+    session_id = str(hook_input.get("session_id") or "").strip()
+    trace_id = str(result.get("context_trace_id") or "").strip()
+    if session_id and trace_id:
+        os.makedirs(STATE_DIR, exist_ok=True)
+        state = {
+            "trace_id": trace_id,
+            "memory_ids": (result.get("evidence") or {}).get("memory_ids", []),
+            "capsule_lines": [line.strip() for line in shown.splitlines() if len(line.strip()) >= 12][:12],
+        }
+        with open(os.path.join(STATE_DIR, f"{session_id}.json"), "w", encoding="utf-8") as fh:
+            json.dump(state, fh, ensure_ascii=False)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)

package/assets/hooks/forget_turnrecall.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook: push-recall memories relevant to THIS turn.
+
+The session-start capsule covers "where were we"; this covers "wait, we know
+something about that" mid-session — the pull-only problem's other half. The
+main context window is the scarcest resource, so the gate is strict:
+
+- silence unless the top hit clears a relevance threshold
+- a memory is offered at most once per session (repeat-suppression ledger)
+- memories already offered in the session-start capsule are not re-offered
+- the injection is an OFFER with trust lights; adoption stays the
+  main-thread agent's judgment
+- fail-open, hard 5s timeout: forget being down must never slow a turn
+
+Known gap (deliberate): these injections are not yet linked to the outcome
+flywheel (search_memories creates no context trace). Wire when per-turn
+traces land server-side.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.request
+
+FORGET_URL = os.environ.get("FORGET_MCP_URL", "http://127.0.0.1:8000/mcp")
+STATE_DIR = os.path.expanduser("~/.forget/hooks/state")
+SCORE_THRESHOLD = float(os.environ.get("FORGET_TURNRECALL_THRESHOLD", "0.45"))
+# Conflict-zone members get a looser gate: missing a plain recall costs
+# silence, but missing a corrected-zone alert is how incident #1 happened —
+# and being part of a supersede pair is itself strong prior evidence the
+# zone matters. Recalibrate both when the embedder switches to e5.
+CONFLICT_THRESHOLD = float(os.environ.get("FORGET_CONFLICT_THRESHOLD", "0.32"))
+MAX_RECALLS = 3
+MEMORY_CHAR_LIMIT = 160
+MIN_PROMPT_LEN = 8
+
+
+def _rpc(name: str, arguments: dict, timeout: int = 5) -> dict:
+    payload = {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": name, "arguments": arguments}}
+    request = urllib.request.Request(
+        FORGET_URL,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+    )
+    body = json.loads(urllib.request.urlopen(request, timeout=timeout).read())
+    return json.loads(body["result"]["content"][0]["text"])
+
+
+def _conflict_pair(item: dict) -> tuple[str, str] | None:
+    """(old_id, new_id) if this memory sits in a supersede pair, else None.
+
+    Retro-scoring incident #1 (2026-07-23) showed direction is not measurable
+    in embedding space — old and corrected versions sit nearly parallel
+    (negation-blindness). But *territory* separates perfectly (100% vs 3%
+    false positives). So geometry only detects entry into a corrected zone;
+    judging which version to act on is delegated to the reading LLM, which
+    handles negation natively.
+    """
+    metadata = item.get("metadata") or {}
+    memory_id = str(item.get("id") or "")
+    successor = str(metadata.get("superseded_by") or "")
+    if successor:
+        return (memory_id, successor)
+    supersedes = metadata.get("supersedes")
+    if isinstance(supersedes, list) and supersedes:
+        return (str(supersedes[0]), memory_id)
+    return None
+
+
+def _seen_ids(session_id: str) -> tuple[set[str], str]:
+    seen: set[str] = set()
+    offer_path = os.path.join(STATE_DIR, f"{session_id}.json")
+    for candidate in (offer_path, offer_path + ".done"):
+        if os.path.exists(candidate):
+            try:
+                with open(candidate, encoding="utf-8") as fh:
+                    seen.update(json.load(fh).get("memory_ids") or [])
+            except Exception:
+                pass
+    turns_path = os.path.join(STATE_DIR, f"{session_id}.turns.json")
+    if os.path.exists(turns_path):
+        try:
+            with open(turns_path, encoding="utf-8") as fh:
+                seen.update(json.load(fh).get("injected") or [])
+        except Exception:
+            pass
+    return seen, turns_path
+
+
+def _remember_injected(turns_path: str, injected: list[str]) -> None:
+    existing: list[str] = []
+    if os.path.exists(turns_path):
+        try:
+            with open(turns_path, encoding="utf-8") as fh:
+                existing = json.load(fh).get("injected") or []
+        except Exception:
+            pass
+    os.makedirs(STATE_DIR, exist_ok=True)
+    with open(turns_path, "w", encoding="utf-8") as fh:
+        json.dump({"injected": existing + injected}, fh, ensure_ascii=False)
+
+
+def main() -> None:
+    hook_input = json.load(sys.stdin)
+    prompt = str(hook_input.get("prompt") or "").strip()
+    session_id = str(hook_input.get("session_id") or "").strip()
+    if len(prompt) < MIN_PROMPT_LEN or prompt.startswith(("/", "!", "<", "#")):
+        return
+    seen, turns_path = _seen_ids(session_id) if session_id else (set(), "")
+    result = _rpc("search_memories", {"query": prompt[:300], "top_k": MAX_RECALLS + 2})
+    picks = []
+    conflict_pairs: dict[tuple[str, str], None] = {}
+    for item in result.get("results") or []:
+        score = float(item.get("score") or 0.0)
+        memory_id = str(item.get("id") or "")
+        if not memory_id or memory_id in seen:
+            continue
+        if (item.get("metadata") or {}).get("hook"):
+            continue  # session-capture pointers are for rehydration, not recall
+        pair = _conflict_pair(item)
+        if pair:
+            if score >= CONFLICT_THRESHOLD:
+                conflict_pairs.setdefault(pair)
+            continue  # presented as a pair below, not as a plain recall
+        if score < SCORE_THRESHOLD:
+            continue
+        trust = item.get("trust") or {}
+        light = str(trust.get("light") or "yellow")
+        picks.append((memory_id, light, str(item.get("memory") or "")[:MEMORY_CHAR_LIMIT]))
+        if len(picks) >= MAX_RECALLS:
+            break
+
+    conflicts = []
+    for old_id, new_id in list(conflict_pairs)[:2]:
+        if old_id in seen and new_id in seen:
+            continue
+        try:
+            old = _rpc("get_memory", {"memory_id": old_id})
+            new = _rpc("get_memory", {"memory_id": new_id})
+        except Exception:
+            continue
+        conflicts.append((old_id, new_id, str(old.get("memory") or "")[:MEMORY_CHAR_LIMIT], str(new.get("memory") or "")[:MEMORY_CHAR_LIMIT]))
+
+    if not picks and not conflicts:
+        return  # below threshold or nothing new → silence
+    lines = []
+    if conflicts:
+        lines.append("[forget 충돌지대 — 이 주제엔 정정 이력이 있음. 현재본 기준으로 행동하고, 구본 위에서 행동하지 말 것]")
+        for _, _, old_text, new_text in conflicts:
+            lines.append(f"- (현재) {new_text}")
+            lines.append(f"- (red/구본) {old_text}")
+    if picks:
+        lines.append("[forget 회상 — 이 턴과 관련된 기억 제안. green=행동 근거 OK, yellow=행동 전 확인, red=참고만]")
+        lines += [f"- ({light}) {memory}" for _, light, memory in picks]
+    print("\n".join(lines))
+    if session_id and turns_path:
+        injected = [memory_id for memory_id, _, _ in picks]
+        ledger_picks = list(picks)
+        for old_id, new_id, old_text, new_text in conflicts:
+            injected += [old_id, new_id]
+            ledger_picks.append((new_id, "green", new_text))  # 메아리 측정은 현재본 기준
+        _remember_injected(turns_path, injected)
+        _extend_offer_ledger(session_id, ledger_picks)
+
+
+def _extend_offer_ledger(session_id: str, picks: list) -> None:
+    """Feed turn recalls into the outcome flywheel: append their probes and
+    ids to the session's offer ledger so the capture hook measures them too.
+    (Discovered gap 07-22: a session answered purely from a turn recall and
+    the capsule-only labeler scored it "not used".)"""
+    ledger_path = os.path.join(STATE_DIR, f"{session_id}.json")
+    if not os.path.exists(ledger_path):
+        return  # no capsule trace this session — nothing to record against
+    try:
+        with open(ledger_path, encoding="utf-8") as fh:
+            state = json.load(fh)
+        state["memory_ids"] = list({*(state.get("memory_ids") or []), *(memory_id for memory_id, _, _ in picks)})
+        state["capsule_lines"] = (state.get("capsule_lines") or []) + [memory[:80] for _, _, memory in picks]
+        with open(ledger_path, "w", encoding="utf-8") as fh:
+            json.dump(state, fh, ensure_ascii=False)
+    except Exception:
+        pass
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forget-connect",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Safely connect Claude Code, Codex, and Claude Desktop to Forget memory.",
   "type": "module",
   "bin": {
@@ -10,11 +10,12 @@
     "bin",
     "src",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "assets"
   ],
   "scripts": {
     "test": "node --test",
-    "lint": "node --check bin/forget-connect.js && node --check src/cli.js && node --check src/core.js && node --check src/doctor.js"
+    "lint": "node --check bin/forget-connect.js && node --check src/cli.js && node --check src/core.js && node --check src/doctor.js && node --check src/hooks.js"
   },
   "engines": {
     "node": ">=18"

package/src/cli.js

@@ -1,12 +1,14 @@
 import { readFile } from "node:fs/promises";
 import readline from "node:readline/promises";
-import { stdin, stdout } from "node:process";
+import { stdin, stdout, stderr } from "node:process";
 import {
   DEFAULT_MCP_URL,
+  HOSTED_MCP_URL,
   ConfigError,
   applyPlan,
   buildPlan,
   detectClients,
+  detectInstalledScope,
   getClients,
   inspectClients,
   normalizeUrl,
@@ -16,6 +18,15 @@ import {
   validateApiKey,
 } from "./core.js";
 import { doctorRemote } from "./doctor.js";
+import {
+  connectHooksSettings,
+  disconnectHooksSettings,
+  hooksDirFor,
+  inspectHooks,
+  installHookScripts,
+  removeHookScripts,
+  settingsPathFor,
+} from "./hooks.js";
 
 const CLIENT_IDS = new Set(["claude-code", "codex", "claude-desktop"]);
 
@@ -31,10 +42,13 @@ Usage:
 Options:
   --client <ids>       Comma-separated: claude-code,codex,claude-desktop,all
   --url <url>          MCP URL (default: ${DEFAULT_MCP_URL})
+  --hosted             Use the managed Forget service (legacy) instead of a local server
   --user-id <id>       Memory user scope (pair with --app-id)
   --app-id <id>        Project/app scope (pair with --user-id)
-  --no-auth            Connect without a Bearer token (for a local server)
+  --no-auth            Connect without a Bearer token
   --no-rules           Do not manage CLAUDE.md or AGENTS.md instruction blocks
+  --no-hooks           Do not install Claude Code memory hooks (session capsule,
+                       per-turn recall, conflict alerts, session capture)
   --no-migrate-enacta  Keep matching legacy config and rules blocks
   --dry-run            Show the files that would change without writing them
   --timeout <seconds>  Doctor network timeout (default: 10)
@@ -44,14 +58,14 @@ Options:
   -v, --version        Show version
 
 Authentication:
-  Set FORGET_API_KEY, or run interactively and paste the key when prompted.
+  The default local server needs no token. For --hosted (legacy) set
+  FORGET_API_KEY, or run interactively and paste the key when prompted.
   Keys are intentionally not accepted as command-line arguments.
 
 Examples:
-  npx forget-connect
-  FORGET_API_KEY=... npx forget-connect --client claude-code,codex
-  FORGET_API_KEY=... npx forget-connect --user-id junghunkim --app-id Mem1
-  npx forget-connect --url http://localhost:8000/mcp --no-auth --client all
+  npx forget-connect                    # local server at ${DEFAULT_MCP_URL}
+  npx forget-connect --client claude-code,codex
+  FORGET_API_KEY=... npx forget-connect --hosted --user-id junghunkim --app-id Mem1
   npx forget-connect status
   npx forget-connect doctor --client codex
   npx forget-connect disconnect --client codex
@@ -68,7 +82,7 @@ function requireValue(argv, index, flag) {
 
 function isHostedBaseUrl(value) {
   const candidate = new URL(value);
-  const hosted = new URL(DEFAULT_MCP_URL);
+  const hosted = new URL(HOSTED_MCP_URL);
   const candidateHost = candidate.hostname.toLowerCase().replace(/\.+$/, "");
   const hostedHost = hosted.hostname.toLowerCase().replace(/\.+$/, "");
   if (candidateHost !== hostedHost) return false;
@@ -88,10 +102,13 @@ export function parseArgs(argv, env = process.env) {
     action: "connect",
     clientValues: [],
     url: env.FORGET_MCP_URL || DEFAULT_MCP_URL,
+    urlExplicit: false,
+    hostedFlag: false,
     userId: env.FORGET_USER_ID?.trim() || "",
     appId: env.FORGET_APP_ID?.trim() || "",
     auth: true,
     rules: true,
+    hooks: true,
     migrateLegacy: true,
     dryRun: false,
     yes: false,
@@ -114,9 +131,13 @@ export function parseArgs(argv, env = process.env) {
       options.clientValues.push(arg.slice("--client=".length));
     } else if (arg === "--url") {
       options.url = requireValue(argv, index, arg);
+      options.urlExplicit = true;
       index += 1;
     } else if (arg.startsWith("--url=")) {
       options.url = arg.slice("--url=".length);
+      options.urlExplicit = true;
+    } else if (arg === "--hosted") {
+      options.hostedFlag = true;
     } else if (arg === "--user-id") {
       options.userId = requireValue(argv, index, arg);
       index += 1;
@@ -131,6 +152,8 @@ export function parseArgs(argv, env = process.env) {
       options.auth = false;
     } else if (arg === "--no-rules") {
       options.rules = false;
+    } else if (arg === "--no-hooks") {
+      options.hooks = false;
     } else if (arg === "--no-migrate-enacta") {
       options.migrateLegacy = false;
     } else if (arg === "--dry-run") {
@@ -160,6 +183,12 @@ export function parseArgs(argv, env = process.env) {
       throw new ConfigError(`Unknown argument: ${arg}`);
     }
   }
+  if (options.hostedFlag) {
+    if (options.urlExplicit) {
+      throw new ConfigError("--hosted and --url are mutually exclusive.");
+    }
+    options.url = HOSTED_MCP_URL;
+  }
   options.baseUrl = normalizeUrl(options.url);
   options.hosted = isHostedBaseUrl(options.baseUrl);
   if (Boolean(options.userId) !== Boolean(options.appId)) {
@@ -278,16 +307,27 @@ async function promptHidden(question) {
   }
 }
 
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+function isLoopbackUrl(value) {
+  return LOOPBACK_HOSTS.has(new URL(value).hostname.toLowerCase());
+}
+
 async function apiKeyFor(options, env) {
   if (!["connect", "doctor"].includes(options.action) || !options.auth || options.dryRun) return "";
   const fromEnv = env.FORGET_API_KEY?.trim();
   if (fromEnv) {
-    if (new URL(options.url).protocol !== "https:") {
+    if (new URL(options.url).protocol === "https:") return validateApiKey(fromEnv);
+    if (!isLoopbackUrl(options.url)) {
       throw new ConfigError(
         "Bearer authentication requires HTTPS. Use --no-auth for a local HTTP server.",
       );
     }
-    return validateApiKey(fromEnv);
+    // A leftover hosted key must not block the local-first default flow, and
+    // a loopback target never puts the secret on the wire anyway.
+    stderr.write(
+      "Note: FORGET_API_KEY is set but the target is a loopback HTTP server; connecting without a token.\n",
+    );
   }
   if (!options.hosted) return "";
   const prompted = (await promptHidden("Paste your Forget API key: ")).trim();
@@ -335,6 +375,12 @@ function localDoctorResults(statuses, { requireRules = true } = {}) {
 
 function printDoctor(result) {
   stdout.write("Forget connection doctor\n");
+  if (result.hooks) {
+    const hooksDetail = result.hooks.registered
+      ? `registered, scripts ${result.hooks.scripts_present ? "present" : "missing"}, python3 ${result.hooks.python3 ? "ok" : "missing"}`
+      : "not installed (use connect without --no-hooks)";
+    stdout.write(`${result.hooks.ok ? "✓" : "✗"} Hooks: ${hooksDetail}\n`);
+  }
   for (const client of result.clients) {
     const details = [
       client.config ? "config found" : "config missing",
@@ -394,6 +440,23 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
     return;
   }
 
+  if (options.action === "doctor" && !options.scope && !options.urlExplicit && !options.hostedFlag) {
+    // A user who connected with --user-id/--app-id will run a bare
+    // `forget-connect doctor` next; comparing their scoped install against the
+    // unscoped default URL would report false failures. Adopt the scope the
+    // installed config already carries.
+    const installed = await detectInstalledScope(clients);
+    if (installed) {
+      options.scope = { userId: installed.userId, appId: installed.appId };
+      options.baseUrl = installed.baseUrl;
+      options.hosted = isHostedBaseUrl(options.baseUrl);
+      options.url = scopedMcpUrl(options.baseUrl, options.scope);
+      stdout.write(
+        `Scope detected from installed config: user ${installed.userId} · app ${installed.appId}\n`,
+      );
+    }
+  }
+
   const apiKey = await apiKeyFor(options, env);
   if (options.action === "doctor") {
     const local = localDoctorResults(
@@ -427,11 +490,15 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
           skipped: true,
         },
       };
+    const hooksStatus = clients.some((client) => client.id === "claude-code")
+      ? await inspectHooks({ env })
+      : null;
     const result = {
-      ok: local.every((client) => client.ok) && remote.ok,
+      ok: local.every((client) => client.ok) && remote.ok && (hooksStatus?.ok ?? true),
       url: redactUrlForDisplay(options.url),
       scope: { configured: Boolean(options.scope) },
       clients: local,
+      hooks: hooksStatus,
       remote,
     };
     if (options.json) stdout.write(`${JSON.stringify(result)}\n`);
@@ -444,30 +511,84 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
     apiKey,
     installInstructionRules: options.rules,
     migrateLegacy: options.migrateLegacy,
-    legacyUrls: [...new Set([options.url, options.baseUrl])],
+    legacyUrls: [...new Set([options.url, options.baseUrl, HOSTED_MCP_URL])],
   });
 
+  // Claude Code is the only client with a hook system today; the hooks are
+  // what make memory arrive without being asked. Disconnect always cleans
+  // them up, even when the install used --no-hooks.
+  const claudeCode = clients.find((client) => client.id === "claude-code");
+  let manageHooks = Boolean(claudeCode)
+    && (options.action === "disconnect" || options.hooks);
+  if (manageHooks && process.platform === "win32" && options.action === "connect") {
+    // The hook commands are POSIX shell strings and the scripts need
+    // python3 — installing them on Windows would register broken hooks.
+    stderr.write("Note: memory hooks are not yet supported on Windows; skipping hook install.\n");
+    manageHooks = false;
+  }
+  const hooksDir = manageHooks ? hooksDirFor({ env }) : "";
+  if (manageHooks) {
+    const settingsPath = settingsPathFor({ env });
+    let settingsRaw = "";
+    try {
+      settingsRaw = await readFile(settingsPath, "utf8");
+    } catch (error) {
+      if (!error || error.code !== "ENOENT") throw error;
+    }
+    const settingsNext = options.action === "connect"
+      ? connectHooksSettings(settingsRaw, { hooksDir, url: options.url })
+      : disconnectHooksSettings(settingsRaw);
+    if (settingsRaw !== settingsNext) {
+      changes.push({
+        client: claudeCode,
+        filePath: settingsPath,
+        before: settingsRaw,
+        after: settingsNext,
+        kind: "hooks",
+        sensitive: false,
+        backup: options.action === "connect",
+      });
+    }
+  }
+
   if (options.dryRun) {
-    if (!changes.length) {
+    if (!changes.length && !manageHooks) {
       stdout.write("No changes needed.\n");
       return;
     }
     for (const change of changes) {
       stdout.write(`Would update ${change.filePath} (${change.client.name} ${change.kind})\n`);
     }
+    if (manageHooks && options.action === "connect") {
+      stdout.write(`Would install hook scripts into ${hooksDir}\n`);
+    }
+    if (manageHooks && options.action === "disconnect") {
+      stdout.write(`Would remove hook scripts from ${hooksDir}\n`);
+    }
     return;
   }
 
   const result = await applyPlan(changes);
+  let hookScriptPaths = [];
+  if (manageHooks) {
+    hookScriptPaths = options.action === "connect"
+      ? await installHookScripts(hooksDir)
+      : await removeHookScripts(hooksDir);
+  }
   const verb = options.action === "connect" ? "Connected" : "Disconnected";
-  if (!result.changed.length) {
+  if (!result.changed.length && !hookScriptPaths.length) {
     stdout.write("No changes needed.\n");
   } else {
     stdout.write(`${verb} ${clients.map((client) => client.name).join(", ")}.\n`);
     for (const filePath of result.changed) stdout.write(`  updated ${filePath}\n`);
     for (const filePath of result.backups) stdout.write(`  backup  ${filePath}\n`);
+    const hookVerb = options.action === "connect" ? "installed" : "removed";
+    for (const filePath of hookScriptPaths) stdout.write(`  ${hookVerb} ${filePath}\n`);
   }
   if (options.action === "connect") {
+    if (manageHooks) {
+      stdout.write("  hooks: session capsule, per-turn recall, conflict alerts, session capture (needs python3 on PATH)\n");
+    }
     if (options.hosted && !options.scope) {
       stdout.write(
         "\nWarning: hosted continuity scope is not configured. Reconnect with --user-id and --app-id before relying on cross-client recall.\n",

package/src/core.js

@@ -14,7 +14,8 @@ import {
 import os from "node:os";
 import path from "node:path";
 
-export const DEFAULT_MCP_URL = "https://api.multi-turn.ai/mcp";
+export const DEFAULT_MCP_URL = "http://localhost:8000/mcp";
+export const HOSTED_MCP_URL = "https://api.multi-turn.ai/mcp";
 export const SERVER_KEY = "forget";
 export const BACKUP_SUFFIX = ".forget-backup";
 
@@ -29,8 +30,10 @@ export const MEMORY_RULES = [
   "# Memory (Forget)",
   "You have the user's long-term memory via the `forget` MCP server.",
   "ALWAYS call `search_memories` on `forget` FIRST — before any shell command or file search — whenever the user refers to their own past decisions, preferences, plans, or anything previously discussed. Trust recent memories over old ones.",
-  "For resume or continue requests, then call `get_task_state` and `prepare_context_autopilot` with the current working directory before searching files.",
-  "When the user states a durable decision, preference, or lasting fact, save it with `add_memory`.",
+  "At session start and on resume/continue requests, call `prepare_context_autopilot` once and treat its capsule as a suggestion (open tasks, next actions, constraints); call `get_task_state` for active work.",
+  "Results may carry a `trust` label — treat it as a permission, not a decoration: green (user-stated or tool-observed) = safe to act on; yellow (agent-inferred or self-summarized) = confirm with the user before real-world action; red (superseded) = reference only; unlabeled = treat as yellow.",
+  "When the user states a durable decision, preference, or lasting fact, save it with `add_memory`. Never record a planned action as completed — completion claims without evidence stay unverified.",
+  "To retire a fact that turned out wrong, use `supersede_memory` and always pass `superseded_by` to link the replacement. When a true-but-unverified claim gets its receipt, use `confirm_memory` with evidence instead.",
   RULES_END,
 ].join("\n");
 
@@ -391,6 +394,64 @@ async function readOptional(filePath) {
   }
 }
 
+export function configuredServerUrl(client, raw) {
+  if (!raw) return "";
+  if (client.kind === "toml") {
+    const bounds = sectionBounds(raw, SERVER_KEY);
+    if (bounds.start === -1 || bounds.count !== 1) return "";
+    const section = bounds.lines.slice(bounds.start, bounds.end).join("\n");
+    const match = section.match(/^\s*url\s*=\s*("(?:[^"\\]|\\.)*")\s*$/m);
+    if (!match) return "";
+    try {
+      return JSON.parse(match[1]);
+    } catch {
+      return "";
+    }
+  }
+  try {
+    const config = parseJsonStrict(raw, client.configPath);
+    const server = isObject(config.mcpServers) ? config.mcpServers[SERVER_KEY] : null;
+    if (!isObject(server)) return "";
+    if (client.id === "claude-desktop") {
+      return Array.isArray(server.args) && typeof server.args[2] === "string"
+        ? server.args[2]
+        : "";
+    }
+    return typeof server.url === "string" ? server.url : "";
+  } catch {
+    return "";
+  }
+}
+
+export function scopeFromUrl(value) {
+  if (!value) return null;
+  let parsed;
+  try {
+    parsed = new URL(normalizeUrl(value));
+  } catch {
+    return null;
+  }
+  const match = parsed.pathname.match(/^(.*\/mcp)\/([^/]+)\/http\/([^/]+)\/?$/);
+  if (!match) return null;
+  try {
+    const appId = validateScopeId(decodeURIComponent(match[2]), "app_id");
+    const userId = validateScopeId(decodeURIComponent(match[3]), "user_id");
+    parsed.pathname = match[1];
+    return { userId, appId, baseUrl: parsed.toString().replace(/\/$/, "") };
+  } catch {
+    return null;
+  }
+}
+
+export async function detectInstalledScope(clients) {
+  for (const client of clients) {
+    const raw = await readOptional(client.configPath);
+    const scope = scopeFromUrl(configuredServerUrl(client, raw));
+    if (scope) return scope;
+  }
+  return null;
+}
+
 export async function detectClients(clients) {
   const detected = [];
   for (const client of clients) {
@@ -629,7 +690,7 @@ async function sourceMode(filePath, fallback) {
   }
 }
 
-async function atomicWrite(filePath, content, mode) {
+export async function atomicWrite(filePath, content, mode) {
   const target = await resolvedWritePath(filePath);
   await mkdir(path.dirname(target), { recursive: true });
   const temp = `${target}.forget-connect-${process.pid}-${randomBytes(5).toString("hex")}`;

package/src/hooks.js

@@ -0,0 +1,250 @@
+// The hooks layer is the product thesis made real: memory that arrives
+// without being asked. Claude Code gets four harness hooks — a session-start
+// context capsule, per-turn push recall with conflict-zone alerts, and
+// session capture feeding the outcome flywheel. Other clients (Codex,
+// Desktop) rely on instruction rules until they grow hook systems.
+//
+// First rule of touching ~/.claude/settings.json: it is the user's file.
+// Foreign hooks (other tools register there too) must survive connect,
+// reconnect, and disconnect byte-for-byte. Ownership is recognized by the
+// command path marker, never by position.
+
+import { execFile } from "node:child_process";
+import { readFile, unlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ConfigError, atomicWrite, parseJsonStrict } from "./core.js";
+
+export const HOOK_SCRIPTS = [
+  "forget_sessionstart.py",
+  "forget_turnrecall.py",
+  "forget_capture.py",
+];
+
+// Ownership marker: every command we install invokes a script whose path
+// contains this fragment. Recognizes hand-installed variants too.
+export const HOOK_MARKER = `${path.join(".forget", "hooks", "forget_")}`;
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function shellQuote(value) {
+  // POSIX single-quote escaping: closes the quote, emits an escaped quote,
+  // reopens. Safe for every byte except NUL.
+  return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}
+
+export function hooksDirFor(options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.home ?? env.HOME ?? env.USERPROFILE ?? os.homedir();
+  return path.join(home, ".forget", "hooks");
+}
+
+export function settingsPathFor(options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.home ?? env.HOME ?? env.USERPROFILE ?? os.homedir();
+  return path.join(home, ".claude", "settings.json");
+}
+
+export function hookCommand(script, { hooksDir, url }) {
+  const scriptPath = path.join(hooksDir, script);
+  return `FORGET_MCP_URL=${shellQuote(url)} python3 ${shellQuote(scriptPath)}`;
+}
+
+export function hookEntries({ hooksDir, url }) {
+  return {
+    SessionStart: {
+      command: hookCommand("forget_sessionstart.py", { hooksDir, url }),
+      timeout: 12,
+      statusMessage: "forget: assembling context capsule",
+    },
+    UserPromptSubmit: {
+      command: hookCommand("forget_turnrecall.py", { hooksDir, url }),
+      timeout: 6,
+      statusMessage: "forget: checking relevant memories",
+    },
+    PreCompact: {
+      command: hookCommand("forget_capture.py", { hooksDir, url }),
+      timeout: 10,
+      statusMessage: "forget: capturing session",
+    },
+    SessionEnd: {
+      command: hookCommand("forget_capture.py", { hooksDir, url }),
+      timeout: 10,
+      statusMessage: "forget: capturing session + outcome",
+    },
+  };
+}
+
+function ownsHook(hook) {
+  return isObject(hook)
+    && typeof hook.command === "string"
+    && hook.command.includes(HOOK_MARKER);
+}
+
+function withoutOurHooks(groups) {
+  const cleaned = [];
+  for (const group of groups) {
+    if (!isObject(group) || !Array.isArray(group.hooks)) {
+      cleaned.push(group);
+      continue;
+    }
+    const foreign = group.hooks.filter((hook) => !ownsHook(hook));
+    if (foreign.length === group.hooks.length) {
+      cleaned.push(group);
+    } else if (foreign.length) {
+      cleaned.push({ ...group, hooks: foreign });
+    }
+    // groups that held only our hooks are dropped entirely
+  }
+  return cleaned;
+}
+
+function validatedHooks(config, label) {
+  if (config.hooks !== undefined && !isObject(config.hooks)) {
+    throw new ConfigError(
+      `The existing hooks value in ${label} is not a JSON object. Nothing was changed.`,
+    );
+  }
+  const hooks = config.hooks ?? {};
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) {
+      throw new ConfigError(
+        `hooks.${event} in ${label} is not an array. Nothing was changed.`,
+      );
+    }
+  }
+  return hooks;
+}
+
+export function connectHooksSettings(raw, { hooksDir, url }) {
+  const config = parseJsonStrict(raw, "settings.json");
+  const hooks = validatedHooks(config, "settings.json");
+  for (const [event, entry] of Object.entries(hookEntries({ hooksDir, url }))) {
+    const groups = withoutOurHooks(hooks[event] ?? []);
+    groups.push({
+      hooks: [{
+        type: "command",
+        command: entry.command,
+        timeout: entry.timeout,
+        statusMessage: entry.statusMessage,
+      }],
+    });
+    hooks[event] = groups;
+  }
+  config.hooks = hooks;
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+export function disconnectHooksSettings(raw) {
+  const config = parseJsonStrict(raw, "settings.json");
+  if (config.hooks === undefined) return raw;
+  const hooks = validatedHooks(config, "settings.json");
+  let touched = false;
+  for (const [event, groups] of Object.entries(hooks)) {
+    const cleaned = withoutOurHooks(groups);
+    if (cleaned.length !== groups.length
+      || JSON.stringify(cleaned) !== JSON.stringify(groups)) {
+      touched = true;
+    }
+    if (cleaned.length) hooks[event] = cleaned;
+    else delete hooks[event];
+  }
+  if (!touched) return raw;
+  if (Object.keys(hooks).length) config.hooks = hooks;
+  else delete config.hooks;
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+export function hooksInstalled(raw, { hooksDir } = {}) {
+  let config;
+  try {
+    config = parseJsonStrict(raw, "settings.json");
+  } catch {
+    return false;
+  }
+  if (!isObject(config.hooks)) return false;
+  const events = Object.keys(hookEntries({ hooksDir: hooksDir ?? "", url: "http://x" }));
+  return events.every((event) => {
+    const groups = config.hooks[event];
+    return Array.isArray(groups) && groups.some(
+      (group) => isObject(group)
+        && Array.isArray(group.hooks)
+        && group.hooks.some((hook) => ownsHook(hook)),
+    );
+  });
+}
+
+function assetsDir() {
+  return fileURLToPath(new URL("../assets/hooks/", import.meta.url));
+}
+
+export async function readHookAssets() {
+  const dir = assetsDir();
+  const assets = [];
+  for (const script of HOOK_SCRIPTS) {
+    assets.push({
+      name: script,
+      content: await readFile(path.join(dir, script), "utf8"),
+    });
+  }
+  return assets;
+}
+
+export async function installHookScripts(hooksDir) {
+  const assets = await readHookAssets();
+  const written = [];
+  for (const asset of assets) {
+    const target = path.join(hooksDir, asset.name);
+    await atomicWrite(target, asset.content, 0o755);
+    written.push(target);
+  }
+  return written;
+}
+
+export async function inspectHooks({ env } = {}) {
+  const hooksDir = hooksDirFor({ env });
+  const settingsPath = settingsPathFor({ env });
+  let settingsRaw = "";
+  try {
+    settingsRaw = await readFile(settingsPath, "utf8");
+  } catch {
+    settingsRaw = "";
+  }
+  const registered = hooksInstalled(settingsRaw, { hooksDir });
+  let scriptsPresent = true;
+  for (const script of HOOK_SCRIPTS) {
+    try {
+      await readFile(path.join(hooksDir, script), "utf8");
+    } catch {
+      scriptsPresent = false;
+    }
+  }
+  const python3 = await new Promise((resolve) => {
+    execFile("python3", ["--version"], (error) => resolve(!error));
+  });
+  return {
+    registered,
+    scripts_present: scriptsPresent,
+    python3,
+    // registered-but-broken is a failure; absent hooks are a legitimate
+    // choice (--no-hooks), so they don't fail the check
+    ok: !registered || (scriptsPresent && python3),
+  };
+}
+
+export async function removeHookScripts(hooksDir) {
+  const removed = [];
+  for (const script of HOOK_SCRIPTS) {
+    const target = path.join(hooksDir, script);
+    try {
+      await unlink(target);
+      removed.push(target);
+    } catch (error) {
+      if (!error || error.code !== "ENOENT") throw error;
+    }
+  }
+  return removed;
+}