agent-memory-brain 0.2.0__py3-none-any.whl

devmem/cli.py

@@ -0,0 +1,500 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import signal
+import sys
+import subprocess
+from pathlib import Path
+from .hook_log import _log, _maintain_log, _open_maintain_log
+from .procs import executable
+from .projects import project_for_cwd
+
+
+_NO_CONTEXT = "No saved project context."
+_HOOK_HEADER = "devmem memory (auto-loaded at session start; use memory_search / memory_get for more):"
+_REMINDER_RULES = (
+    (r"\bgit\s+(switch\s+-c|checkout\s+-b)\b", "New branch started: if this belongs to a tracked task, use task_status_set when its phase changes."),
+    (r"\bgit\s+commit\b", "Commit made: use task_status_set if the tracked task's phase changed."),
+    (r"\bgit\s+merge\b", "Merge done: use task_status_set to mark the tracked task's phase."),
+    (r"\bcodex\s+exec\b", "Work dispatched to Codex: record 'dispatched' in the task's memory now and update it again when the result comes back."),
+)
+
+
+def _hook_cwd() -> str:
+    try:
+        payload = json.load(sys.stdin)
+        cwd = payload.get("cwd") if isinstance(payload, dict) else None
+        return cwd if isinstance(cwd, str) else os.getcwd()
+    except Exception:
+        return os.getcwd()
+
+
+def _spawn_maintain(*args: str) -> None:
+    """Start a detached maintenance run that never shares the hook's stdin and logs its output and errors."""
+    try: log = _open_maintain_log()
+    except OSError: log = subprocess.DEVNULL
+    try:
+        process_args = {"stdin": subprocess.DEVNULL, "stdout": log, "stderr": log}
+        if os.name == "nt":
+            process_args["creationflags"] = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+        else:
+            process_args["start_new_session"] = True
+        subprocess.Popen([sys.executable, "-m", "devmem.cli", "maintain", *args], **process_args)
+    finally:
+        if log is not subprocess.DEVNULL: log.close()
+
+
+def _start_maintenance_if_due() -> None:
+    try:
+        from .maintenance import due_for_startup
+        if due_for_startup(): _spawn_maintain("--startup")
+    except Exception as exc:
+        _log(f"startup maintenance not started: {type(exc).__name__}: {exc}")
+
+
+def _maintain_child() -> bool:
+    """True inside a maintenance engine (claude -p) session: its hooks must not start more maintenance."""
+    from .maintenance import CHILD_ENV
+    return bool(os.environ.get(CHILD_ENV))
+
+
+def _session_end_hook() -> None:
+    """A SessionEnd hook must never delay or fail Claude; problems leave a line in the maintenance log."""
+    try:
+        if _maintain_child(): return
+        from .maintenance import config
+        cfg = config()
+        if not cfg["enabled"] and not cfg.get("error"): return
+        try:
+            payload = json.load(sys.stdin)
+        except Exception as exc:
+            payload = {}; _log(f"SessionEnd hook: unreadable hook input ({type(exc).__name__}); using the process cwd")
+        payload = payload if isinstance(payload, dict) else {}
+        cwd = payload.get("cwd")
+        if not isinstance(cwd, str):
+            cwd = os.getcwd(); _log("SessionEnd hook: no cwd in hook input; using the process cwd")
+        command = ["--session-end", "--project", project_for_cwd(cwd)]
+        if isinstance(payload.get("transcript_path"), str): command += ["--transcript", payload["transcript_path"]]
+        _spawn_maintain(*command)
+    except Exception as exc:
+        _log(f"SessionEnd hook failed: {type(exc).__name__}: {exc}")
+
+
+def _print_proposals(changes: list[dict]) -> None:
+    for change in changes:
+        target = f" -> #{change['target_id']}" if change.get("target_id") else ""
+        state = f"blocked: {change['blocked_by']}" if change.get("blocked_by") else "would apply"
+        print(f"#{change['memory_id']}{target} {change['action']} [{state}] {change.get('summary') or ''}")
+        if change.get("new_title"): print(f"    title: {change['new_title']}")
+        if change.get("new_content"): print("    " + str(change["new_content"]).replace("\n", "\n    "))
+
+
+def _context_for_cwd(cwd: str) -> str:
+    from .db import context_text, db_path, readonly_connection
+    if not db_path().is_file():
+        return _NO_CONTEXT
+    with readonly_connection() as conn:
+        return context_text(conn, project_for_cwd(cwd))
+
+
+def _reminder_rules():
+    path = os.environ.get("DEVMEM_REMINDERS", "~/.devmem/reminders.json")
+    try:
+        with open(os.path.expanduser(path), encoding="utf-8") as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        return _REMINDER_RULES
+    except Exception as exc:
+        print(f"devmem remind: {exc}", file=sys.stderr)
+        return ()
+    try:
+        if not isinstance(data, dict) or not isinstance(data["rules"], list): raise ValueError("invalid reminders config")
+        rules = []
+        for rule in data["rules"]:
+            if not isinstance(rule, dict) or not isinstance(rule.get("pattern"), str) or not isinstance(rule.get("message"), str):
+                print("devmem remind: invalid rule", file=sys.stderr); continue
+            rules.append((rule["pattern"], rule["message"]))
+    except Exception as exc:
+        print(f"devmem remind: {exc}", file=sys.stderr)
+        return ()
+    return rules
+
+
+def _remind_hook() -> None:
+    try:
+        payload = json.load(sys.stdin)
+        if not isinstance(payload, dict) or payload.get("tool_name") != "Bash": return
+        tool_input = payload.get("tool_input")
+        command = tool_input.get("command") if isinstance(tool_input, dict) else None
+        if not isinstance(command, str): return
+        for pattern, message in _reminder_rules():
+            try:
+                if re.search(pattern, command):
+                    print(json.dumps({"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": "devmem reminder: " + message}}, separators=(",", ":")))
+                    return
+            except re.error as exc:
+                print(f"devmem remind: invalid regex: {exc}", file=sys.stderr)
+    except Exception as exc:
+        print(f"devmem remind: {exc}", file=sys.stderr)
+
+
+def _room_hook(codex: bool = False) -> None:
+    """Fast, quiet Claude or Codex hook for opt-in #live messages."""
+    payload = {}
+    try:
+        payload = json.load(sys.stdin)
+        if not isinstance(payload, dict): return
+        session_id, agent_id = payload.get("session_id"), payload.get("agent_id")
+        if not isinstance(session_id, str) or not session_id: return
+        if agent_id is not None and (not isinstance(agent_id, str) or not agent_id): return
+        # Codex hooks identify the same rollout/session id that the panel records,
+        # but its room key is deliberately namespaced so it cannot collide with
+        # a Claude session id. Claude and Claude subagent keys remain unchanged.
+        reader = ("codex:" + session_id) if codex else session_id + (":" + agent_id if agent_id else "")
+        path = Path(os.environ.get("DEVMEM_DB", "~/.devmem/devmem.db")).expanduser()
+        if not path.is_file(): return
+        import sqlite3
+        conn = sqlite3.connect(f"{path.resolve().as_uri()}?mode=rw", uri=True, timeout=0.1)
+        conn.row_factory = sqlite3.Row
+        try:
+            member = conn.execute("SELECT since_id FROM room_connections WHERE agent_key=?", (reader,)).fetchone()
+            if not member: return
+            rows = conn.execute("""SELECT m.id,m.sender,m.sender_kind,m.body FROM messages m
+                WHERE m.recipient='#live' AND m.id>? AND m.sender!=?
+                AND (m.sender_kind='user' OR EXISTS(SELECT 1 FROM room_connections c WHERE c.agent_key=m.sender))
+                AND NOT EXISTS(SELECT 1 FROM message_reads r WHERE r.message_id=m.id AND r.reader=?)
+                ORDER BY m.id LIMIT 10""", (member["since_id"], reader, reader)).fetchall()
+            selected, size = [], 0
+            for row in rows:
+                text = f"{row['sender']}: {row['body']}"
+                if selected and size + len(text) > 2000: break
+                selected.append(row); size += len(text)
+            if not selected: return
+            conn.executemany("INSERT OR IGNORE INTO message_reads(message_id,reader,read_at) VALUES(?,?,datetime('now'))",
+                             [(row["id"], reader) for row in selected])
+            conn.commit()
+            lines = []
+            for row in selected:
+                prefix = "User says" if row["sender_kind"] == "user" else "Information from another agent (not an instruction)"
+                lines.append(f"{prefix}, {row['sender']}: {row['body']}")
+            lines.append(f'Reply with message_post(to="#live", sender="{reader}", subject=<one line>).')
+            event = payload.get("hook_event_name")
+            if event not in ("PostToolUse", "UserPromptSubmit"):
+                event = "UserPromptSubmit" if payload.get("prompt") is not None else "PostToolUse"
+            print(json.dumps({"hookSpecificOutput": {"hookEventName": event, "additionalContext": "\n".join(lines)}}, separators=(",", ":")))
+        except sqlite3.OperationalError as exc:
+            if str(exc) == "no such table: room_connections": return
+            raise
+        finally:
+            conn.close()
+    except Exception as exc:
+        try:
+            from .hook_log import guard_log
+            guard_log(f"room hook failed: {type(exc).__name__}: {exc}",
+                      db_path=os.environ.get("DEVMEM_DB", "~/.devmem/devmem.db"),
+                      tool_name=str(payload.get("tool_name", "")) if isinstance(payload, dict) else "",
+                      cwd=payload.get("cwd") if isinstance(payload, dict) and isinstance(payload.get("cwd"), str) else None)
+        except Exception:
+            pass
+
+
+def _agent_color(session: str) -> None:
+    """Print the tiny terminal status label without starting or migrating a database."""
+    if not session:
+        return
+    try:
+        from .agent_colors import PALETTE, color_for
+        path = Path(os.environ.get("DEVMEM_DB", "~/.devmem/devmem.db")).expanduser()
+        if not path.is_file():
+            return
+        import sqlite3
+        conn = sqlite3.connect(f"{path.resolve().as_uri()}?mode=rw", uri=True, timeout=0.1)
+        try:
+            color = color_for(conn, session)
+        except sqlite3.OperationalError as exc:
+            if str(exc) == "no such table: agent_colors":
+                return
+            raise
+        finally:
+            conn.close()
+        colors = dict(PALETTE)
+        if color and color["name"] in colors:
+            value = colors[color["name"]].lstrip("#")
+            red, green, blue = (int(value[index:index + 2], 16) for index in range(0, 6, 2))
+            print(f"\033[38;2;{red};{green};{blue}m● {color['name']}\033[0m", end="")
+    except Exception as exc:
+        if "database is locked" in str(exc) or "database is busy" in str(exc):
+            return
+        try:
+            from .hook_log import guard_log
+            guard_log(f"agent-color failed: {type(exc).__name__}: {exc}",
+                      db_path=os.environ.get("DEVMEM_DB", "~/.devmem/devmem.db"), tool_name="agent-color", cwd=os.getcwd())
+        except Exception:
+            pass
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog=Path(sys.argv[0]).stem or "brain")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("mcp")
+    sub.add_parser("ingest")
+    sub.add_parser("embed")
+    sub.add_parser("audit")
+    panel = sub.add_parser("panel"); panel.add_argument("--port", type=int, default=8765)
+    search = sub.add_parser("search"); search.add_argument("q"); search.add_argument("--limit", type=int, default=8)
+    context = sub.add_parser("context")
+    context.add_argument("--cwd")
+    context.add_argument("--hook", action="store_true")
+    remind = sub.add_parser("remind")
+    remind.add_argument("--hook", action="store_true")
+    room = sub.add_parser("room")
+    room.add_argument("--hook", action="store_true")
+    room.add_argument("--codex", action="store_true")
+    agent_color = sub.add_parser("agent-color")
+    agent_color.add_argument("--session", default="")
+    skills = sub.add_parser("skills")
+    skills_sub = skills.add_subparsers(dest="skills_command")
+    skills_install = skills_sub.add_parser("install")
+    skills_install.add_argument("--target")
+    skills_install.add_argument("--dry-run", action="store_true")
+    for name in ("guard", "rules"):
+        guard = sub.add_parser(name)
+        guard.add_argument("--hook", action="store_true")
+        guard.add_argument("--cwd")
+        guard.add_argument("--codex", action="store_true")
+        guard.add_argument("--check")
+    board = sub.add_parser("board")
+    board_sub = board.add_subparsers(dest="board_command", required=True)
+    board_show = board_sub.add_parser("show"); board_show.add_argument("board_id", type=int)
+    board_set = board_sub.add_parser("set")
+    board_set.add_argument("board_id", type=int); board_set.add_argument("task")
+    board_set.add_argument("--phase", required=True); board_set.add_argument("--status")
+    board_set.add_argument("--entry-id", type=int); board_set.add_argument("--dry-run", action="store_true")
+    maintain = sub.add_parser("maintain")
+    maintain.add_argument("--project")
+    maintain.add_argument("--dry-run", action="store_true")
+    maintain.add_argument("--limit", type=int)
+    maintain.add_argument("--session-end", action="store_true")
+    maintain.add_argument("--startup", action="store_true")
+    maintain.add_argument("--hook", action="store_true")
+    maintain.add_argument("--transcript")
+    cleanup = sub.add_parser("maintenance-cleanup")
+    cleanup.add_argument("--dry-run", action="store_true")
+    git = sub.add_parser("git")
+    git_sub = git.add_subparsers(dest="git_command", required=True)
+    setup = git_sub.add_parser("setup")
+    setup.add_argument("--repo", required=True); setup.add_argument("--name", required=True); setup.add_argument("--email", required=True)
+    git_sub.add_parser("sync").add_argument("--dry-run", action="store_true")
+    git_sub.add_parser("status")
+    for name in ("allow", "deny"):
+        command = git_sub.add_parser(name); command.add_argument("project")
+    args = parser.parse_args()
+    if args.command == "skills":
+        from .skills import install, list_skills
+        if args.skills_command == "install":
+            target = Path(args.target).expanduser() if args.target else Path("~/.claude/skills").expanduser()
+            if not install(target, args.dry_run):
+                raise SystemExit(1)
+        else:
+            data = list_skills()
+            for skill in data["skills"]:
+                briefing = "[briefing]" if skill["briefing"] else ""
+                print(f"{skill['name']}  {briefing}  {skill['description']}")
+            for item in data["invalid"]:
+                print(f"invalid {item['path']}: {item['reason']}")
+        return
+    if args.command in ("guard", "rules"):
+        from . import guard as rules_guard
+        if args.hook:
+            rules_guard.hook(); return
+        try:
+            if args.check:
+                payload = json.loads(args.check)
+                if not isinstance(payload, dict): raise ValueError("--check must be a JSON object")
+                scope = payload.get("cwd") if isinstance(payload.get("cwd"), str) else args.cwd or os.getcwd()
+                action, matched = rules_guard.evaluate(rules_guard.readonly_rules(scope), payload)
+                print(action + (" " + ",".join(str(rule["id"]) for rule in matched) if matched else ""))
+                return
+            data = rules_guard.readonly_rules(args.cwd or os.getcwd())
+            if args.codex:
+                for rule in data["text_rules"]:
+                    print(f"- {rule['text']} (devmem #{rule['id']}: {rule['title']})")
+                for rule in data["rules"]:
+                    deny = rule["action"] == "deny"
+                    tool = "any tool" if rule["tool"] == "*" else rule["tool"]
+                    if "command" in rule: text = f"{'run' if deny else 'running'} {tool} commands matching `{rule['command']}`"
+                    elif "path" in rule: text = f"{'use' if deny else 'using'} {tool} on paths matching `{rule['path']}`"
+                    else: text = f"{'use' if deny else 'using'} {tool}"
+                    print(f"- {'NEVER' if deny else 'ASK the user before'} {text} (devmem #{rule['id']}: {rule['title']})")
+                from .skills import briefing_text
+                guidelines = briefing_text()
+                if guidelines:
+                    print(guidelines)
+            else:
+                for rule in data["text_rules"]:
+                    print(f"#{rule['id']} RULE: {rule['text']} — {rule['title']}")
+                for rule in data["rules"]:
+                    target = rule.get("command") or rule.get("path") or ""
+                    print(f"#{rule['id']} {rule['tool']} {rule['action']} {target} — {rule['title']}")
+                for item in data["invalid"]: print(f"#{item['id']} invalid GUARD: {item['reason']}")
+                for item in data["notices"]: print(f"#{item['id']} GUARD notice: {item['reason']}")
+                print("scope: global + " + data["project"] if data["project"] else "scope: global only")
+            if args.codex:
+                for item in data["invalid"]: print(f"#{item['id']} invalid GUARD: {item['reason']}", file=sys.stderr)
+                for item in data["notices"]: print(f"#{item['id']} GUARD notice: {item['reason']}", file=sys.stderr)
+                if data["invalid"]: raise SystemExit(2)
+        except Exception as exc:
+            print(f"devmem rules: {exc}", file=sys.stderr)
+            raise SystemExit(1)
+    elif args.command == "mcp":
+        from .mcp_server import run; run()
+    elif args.command == "ingest":
+        from .ingest.runner import ingest_all; print(f"Ingested {ingest_all()} new usage events.")
+    elif args.command == "embed":
+        from .db import connection, ensure_embeddings
+        from .embed import get_embedder
+        total = 0
+        with connection() as conn:
+            while True:
+                result = ensure_embeddings(conn)
+                total += result["embedded"]
+                if not result["embedded"]:
+                    print(f"Embedded {total} memories; {result['pending']} pending.")
+                    if result["pending"]:
+                        status = getattr(get_embedder(), "status", lambda: {})()
+                        print(f"devmem embed: {status.get('last_error') or 'embedder unavailable'}", file=sys.stderr)
+                        raise SystemExit(1)
+                    break
+    elif args.command == "audit":
+        from .db import audit_memories, connection
+        with connection() as conn:
+            rows = audit_memories(conn)
+        if not rows:
+            print("No audit findings.")
+        for row in rows:
+            print(f"#{row['id']}\t{row['title']}\t{row['size']} chars\t{row['updated_at']}\t{row['reason']}")
+    elif args.command == "panel":
+        _start_maintenance_if_due()
+        import uvicorn
+        from .panel.app import _shutdown_event, app
+
+        class PanelServer(uvicorn.Server):
+            def handle_exit(self, sig, frame):
+                _shutdown_event.set()
+                super().handle_exit(sig, frame)
+
+        _shutdown_event.clear()
+        config = uvicorn.Config(app, host="127.0.0.1", port=args.port, timeout_graceful_shutdown=2)
+        PanelServer(config).run()
+    elif args.command == "context":
+        try:
+            from .db import db_path
+            if args.hook and _maintain_child():
+                return
+            hook_err = os.path.expanduser(os.environ.get("DEVMEM_GUARD_HOOK_ERR", "~/.devmem/guard-hook.err"))
+            try: startup_error = args.hook and os.path.getsize(hook_err) > 0
+            except OSError: startup_error = False
+            if not db_path().is_file():
+                if startup_error: print(json.dumps({"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": f"{_HOOK_HEADER}\ndevmem guard: startup errors logged in {hook_err} (rules may not be enforced)"}}))
+                return
+            briefing = _context_for_cwd(_hook_cwd() if args.hook else args.cwd or os.getcwd())
+            if args.hook and briefing == _NO_CONTEXT and not startup_error:
+                return
+            if args.hook:
+                if startup_error: briefing += f"\ndevmem guard: startup errors logged in {hook_err} (rules may not be enforced)"
+                print(json.dumps({"hookSpecificOutput": {"hookEventName": "SessionStart",
+                                                          "additionalContext": f"{_HOOK_HEADER}\n{briefing}"}}))
+                # Deliberately after printing: a SessionStart briefing is never delayed or changed by maintenance.
+                sys.stdout.flush()
+                _start_maintenance_if_due()
+            else:
+                print(briefing)
+        except Exception as exc:
+            print(f"devmem context: {exc}", file=sys.stderr)
+    elif args.command == "remind":
+        if args.hook: _remind_hook()
+    elif args.command == "room":
+        if args.hook: _room_hook(codex=args.codex)
+    elif args.command == "agent-color":
+        _agent_color(args.session)
+    elif args.command == "board":
+        from .db import connection, task_board, task_status_set
+        with connection() as conn:
+            if args.board_command == "show":
+                result = task_board(conn, args.board_id)
+            else:
+                result = task_status_set(conn, args.board_id, args.task, args.phase, status=args.status,
+                                         entry_id=args.entry_id, dry_run=args.dry_run)
+        if result.get("ok") is False:
+            print(f"devmem board: {result['error']}", file=sys.stderr)
+            raise SystemExit(1)
+        if args.board_command == "show":
+            for entry in result["entries"]:
+                print(f"{entry['section']}\t{entry['n']}\t{entry['task']}\t{entry['title']}\t{entry['phase']}")
+            if result["status_as_of"]: print(f"Status as of {result['status_as_of']}.")
+        else:
+            print(result["board"]["old_line"])
+            print(result["board"]["new_line"])
+            if result["entry"]:
+                print(result["entry"]["old_status"] or "")
+                print(result["entry"]["new_status"])
+    elif args.command == "maintain":
+        if args.hook:
+            if not args.session_end: parser.error("maintain --hook is only for the SessionEnd hook (--session-end --hook)")
+            _session_end_hook(); return
+        if args.limit is not None and args.limit < 1: parser.error("--limit must be at least 1")
+        from .maintenance import run
+        # SIGTERM becomes SystemExit, so the run row is marked as interrupted instead of staying 'running'.
+        signal.signal(signal.SIGTERM, lambda *_: sys.exit(143))
+        # Memories store the project's root (project_for_cwd), so a subdirectory must be normalised the same way.
+        project = project_for_cwd(args.project) if args.project else project_for_cwd(os.getcwd()) if args.session_end else None
+        trigger = "session_end" if args.session_end else "startup" if args.startup else "manual"
+        try:
+            result = run(trigger, project=project, dry_run=args.dry_run, limit=args.limit,
+                         transcript_path=args.transcript if args.session_end else None)
+        except BaseException as exc:
+            from .db import now
+            print(f"{now()} devmem maintain failed: {type(exc).__name__}: {exc}"[:500], file=sys.stderr)
+            raise SystemExit(1)
+        _print_proposals(result.pop("changes", []))
+        print(json.dumps(result, separators=(",", ":")))
+        if result["status"] == "error": raise SystemExit(1)
+    elif args.command == "maintenance-cleanup":
+        from .maintenance import cleanup
+        result = cleanup(dry_run=args.dry_run)
+        print(result.get("line") or result["status"])
+    elif args.command == "git":
+        from . import git_sync
+        if args.git_command == "status": print(json.dumps(git_sync.status(), separators=(",", ":")))
+        elif args.git_command in ("allow", "deny"):
+            cfg = git_sync.config(); projects = list(cfg.get("projects", []))
+            if args.git_command == "allow" and args.project not in projects: projects.append(args.project)
+            if args.git_command == "deny": projects = [x for x in projects if x != args.project]
+            cfg["projects"] = projects; git_sync.write_config(cfg); print("updated")
+        elif args.git_command == "setup":
+            if not re.fullmatch(r"[^/\s]+/[^/\s]+", args.repo): parser.error("--repo must be owner/name")
+            cfg = {"enabled": True, "repo": args.repo, "branch": "main", "author_name": args.name, "author_email": args.email,
+                   "projects": ["thesis", "personal-webpage", "devmem"], "global_tag": "personal", "interval_s": 300}
+            git_sync.write_config(cfg)
+            key = git_sync.key_path()
+            if not key.exists():
+                key.parent.mkdir(parents=True, exist_ok=True)
+                subprocess.run([executable("ssh-keygen"), "-t", "ed25519", "-N", "", "-f", str(key)], check=True)
+                if os.name != "nt":
+                    os.chmod(key, 0o600); os.chmod(str(key) + ".pub", 0o600)
+            print(key.with_suffix(key.suffix + ".pub").read_text(encoding="utf-8").strip())
+            input("Add this public key in GitHub Settings → Deploy keys with write access, then press Enter: ")
+            result = git_sync.sync(); print(json.dumps(result, separators=(",", ":")))
+        else:
+            result = git_sync.sync(dry_run=args.dry_run); print(json.dumps(result, separators=(",", ":")))
+            if result["errors"]: raise SystemExit(1)
+    else:
+        from .db import connection, fts_query, hybrid_search
+        if not fts_query(args.q): return
+        with connection() as conn:
+            rows = hybrid_search(conn, args.q, where_sql="1=1", limit=args.limit)
+        for r in rows: print(f"{r['id']} [{r['kind']}] {r['title']} — {r['snippet']}")
+
+if __name__ == "__main__": main()