telys 0.1.0__py3-none-any.whl

telys/__init__.py

@@ -0,0 +1,79 @@
+"""Telys — embedded, on-device memory & retrieval SDK (public, thin).
+
+    from telys import Telys, Eq, scope_key
+    eng = Telys(path, embedding_providers={...})
+    eng.create_collection(name, dim, partition_by, embedder=, dtype=, filter_columns=)
+    eng.open_collection(name, embedder=) · eng.collections()
+    col.add_texts / add / upsert_texts / upsert
+    col.search_text / search (where=, top_k=, explain=, target_recall=, with_metadata=)
+    col.ids(where=)   # live external ids in a scope (or off-key column)
+    col.delete / update_texts / compact / build_ivf / save / stats / snapshot
+
+This is the public SDK: facades, types, and provider/tuner interfaces only — no engine implementation. The
+engine is a separate, closed, on-device runtime loaded on first use (`telys runtime install`; see D-30).
+`telys turns filtered vector search into a contiguous memory operation.`
+"""
+def _activate_installed_runtime() -> None:
+    """Zero-config runtime: after a VERIFIED `telys runtime install`, add the installed runtime's Python package
+    dir (pysite, from the signed bundle's slim telys-runtime-native wheel) to sys.path — so the native engine and
+    kernel-backed embedders import with NO env vars. Only ever prepends a telys-managed, verified path; a silent
+    no-op when nothing is installed.
+
+    Ambient-engine-wins rule: pysite is prepended ONLY when no engine package (`memengine`) is already
+    resolvable in this environment. An ambient `memengine` — an editable dev install of `telys-runtime`, a
+    pip-installed `telys-runtime-native` (any version), or a source tree a harness put on sys.path — is an
+    explicit environment choice and must never be shadowed by the bundle's slim shim: the shim is the
+    native-only outsider artifact and intentionally lacks the internal reference engine
+    (`memengine.runtime`, `memengine.tuning_heuristic`, ...), so shadowing breaks dev environments and tests
+    the moment ANY runtime is installed. (Supersedes the b4 version guard, which compared telys-runtime-native
+    versions only and could not see the fat editable `telys-runtime` at all — that guard's b3-over-b1 case is
+    the strict subset where an ambient wheel provides `memengine`.)"""
+    try:
+        import json
+        import os
+        import sys
+
+        import telys.paths as _paths
+
+        record = os.path.join(_paths.install_dir(), _paths.INSTALL_RECORD_NAME)
+        with open(record, encoding="utf-8") as fh:
+            if not json.load(fh).get("verified"):
+                return
+        site = _paths.installed_pysite()
+        if not site or site in sys.path:
+            return
+        if _ambient_engine_present():
+            return
+        sys.path.insert(0, site)
+    except Exception:  # noqa: BLE001 — never let runtime activation break `import telys`
+        return
+
+
+def _ambient_engine_present() -> bool:
+    """True iff the engine package (`memengine`) is ALREADY resolvable in this environment, WITHOUT importing
+    it (find_spec resolves without executing module code, so this has no engine side effects)."""
+    try:
+        import importlib.util
+
+        return importlib.util.find_spec("memengine") is not None
+    except Exception:  # noqa: BLE001 — resolution probe must never break `import telys`
+        return False
+
+
+_activate_installed_runtime()
+
+from telys.engine import AME, Telys, FORMAT_VERSION, __version__, scope_key  # noqa: F401,E402
+from telys.filters import Eq  # noqa: F401,E402
+from telys.tuning import Tuner, TuningPlan  # noqa: F401,E402  (HeuristicTuner is lazy — see __getattr__)
+
+__all__ = ["Telys", "AME", "Eq", "scope_key", "Tuner", "HeuristicTuner", "TuningPlan",
+           "__version__", "FORMAT_VERSION"]
+
+
+def __getattr__(name):
+    # HeuristicTuner is a closed-runtime implementation; expose it lazily so `import telys` never loads the
+    # engine, while `from telys import HeuristicTuner` keeps working when the runtime is installed.
+    if name == "HeuristicTuner":
+        from telys.tuning import HeuristicTuner
+        return HeuristicTuner
+    raise AttributeError(f"module 'telys' has no attribute {name!r}")

telys/_keys/README.md

@@ -0,0 +1,36 @@
+# Embedded Telys verification keys (PUBLIC only)
+
+These are the **public** halves of the Telys signing keys, embedded as the default offline trust anchors
+(D-31 #3/#5). `telys.verify` loads them when no `TELYS_RELEASE_PUBKEY[_FILE]` / `TELYS_LICENSE_PUBKEY[_FILE]`
+override is set, so `telys runtime install --file …` verifies with **zero configuration**.
+
+| File | Verifies | Signed by (private key, NOT in repo) |
+|---|---|---|
+| `telys_release_pub.pem` | the runtime **manifest** (artifact SHA-256s) | **Telys release key** (Telys-owned, local) |
+| `telys_license_pub.pem` | the offline **RS256 license** token (ver:2 entitlement) | the **SHARED platform license key** (decision-engine `license-signer` Worker — the SOLE license key for Telys/Algenta/Codna) |
+
+**Two different authorities (post platform-convergence):**
+- **RELEASE** key is Telys-owned and signs runtime manifests (`scripts/telys_issuer.py bundle`). Production-real here.
+- **LICENSE** key is NOT Telys-owned — Telys *rides the shared signer*. Real licenses are issued by the
+  decision-engine control plane (`api.codna.ai` → the Cloudflare `license-signer` Worker), which alone holds
+  the license private key across all products. `telys_license_pub.pem` must therefore be the **decision-engine
+  license public key** (export from its JWKS `GET /.well-known/jwks.json` or the operator). `telys.verify`
+  checks the engine's ver:2 token (iss `https://license.algenta.ai`, aud `telys-runtime`) against it, offline.
+
+**Override:** `TELYS_LICENSE_PUBKEY[_FILE]`, `TELYS_RELEASE_PUBKEY[_FILE]`, and `TELYS_LICENSE_ISSUER` /
+`TELYS_LICENSE_AUDIENCE` env vars override the embedded defaults (rotation / self-hosted / air-gapped).
+
+> ⚠️ **`telys_license_pub.pem` is a BOOTSTRAP platform keypair** (generated locally for dev/staging continuity
+> so the offline-license path is exercisable end-to-end before the control plane is live). Its **private half is
+> at `dist-keys/platform_license_priv.pem`** (gitignored, issuer custody — NEVER committed). To make real
+> licenses verify, do ONE of:
+> 1. **Adopt this bootstrap pair (dev/staging):** load `dist-keys/platform_license_priv.pem` into the
+>    decision-engine `license-signer` (its `license_signing_private_key` / Cloudflare Worker secret) so the
+>    signer mints with the private half of the key embedded here.
+> 2. **Production:** generate a **KMS-born** RS256 key in the control plane, then replace `telys_license_pub.pem`
+>    with that signer's public half (export from its JWKS `GET /.well-known/jwks.json`) and delete the bootstrap
+>    private from `dist-keys/`.
+>
+> Either way, **one signer authority** holds the license private key across Telys/Algenta/Codna — never mint
+> Telys licenses with a separate Telys-local key (the parallel-signer mistake the convergence removed). The
+> RELEASE key remains Telys-owned and production-real.

telys/_keys/telys_license_pub.pem

@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0J1XV/U6NyCYqdwUCES1
+TRXHH+ZimEwWPi7CeDXsOT1bNo57i+MAvM1ho2hUmIjVJsF8f8snEPHWycg29e72
+BYmxtHRgcT9ErswIqzuEv7g8MzL1e7WqJMtevxGAuD2GtzrncVh51XOhc9VbIlcA
+AifNamfk3uLcSm+HRDJxlRw+PCcDCQDEjyHC9/akbNDQSK82csR8DO+zleYMs5pB
+pLrJc++Lamqq0IknT6dHeF2/VwGmMkZ+lRQxSXMvWdTcLw4w9eopeRq8/Yj3mwqA
+BhG+bAlqjUzl6rq87WRszOiZjtDlYnMln8V4oDvJw/iy58VNlW6xvlj42lVXpay7
+tQIDAQAB
+-----END PUBLIC KEY-----

telys/_keys/telys_release_pub.pem

@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzqOtDOYcDh0F3ImMt0kS
+sgefxYH11ULzOyAM8M5jlGidlpSreh/449fhyECJa998Qm7ouwPJWn8iF5cYvChY
+P5/aqlay8C3r7Q1jNkOrL3qnIYVVsORpNDHrQZCMwSBONUD8mkf+Qc219Jk8qjIj
+nCbo8SWiiG/Wqj2nuCS6Hq6xGKTw4GpSQ19PXEDBhFFk9rMVbw5TrdhbaAZczG2w
+pfvVnDaBu0iIBB6w+uzEkJQ5BN4Q+6gJb7JcBASENi1aXoklXm4nJMSF9FdHyAK/
+GZad3y1wO7htt1fHf+kgbfXpFwj/65ViTJ5qehqR+eTMAoSOYPyL1dQja56wdiOY
+iwIDAQAB
+-----END PUBLIC KEY-----

telys/_supervisor.py

@@ -0,0 +1,61 @@
+"""Supervisor for the Telys self-host server — run it as a child process and relaunch on abnormal exit.
+
+The engine runs in-process, so an (already-rare, after the FFI guards in P0/P1) uncatchable native crash takes
+the daemon down. The supervisor restarts it from the last on-disk snapshot (collections persist and are lazily
+reopened), bounding downtime; periodic save (`telys serve --save-interval`) bounds the data-loss window. A
+clean exit (code 0, e.g. a SIGTERM-drained shutdown) is NOT restarted. A crash loop is capped so the
+supervisor gives up instead of spinning forever.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import signal
+import subprocess
+import sys
+import time
+
+_log = logging.getLogger("telys.supervisor")
+
+
+def supervise(child_argv: list[str], *, env: dict | None = None,
+              max_restarts: int = 20, window_s: float = 60.0, backoff_s: float = 1.0) -> int:
+    """Run `python -m telys.cli <child_argv>` as a child, relaunching on abnormal exit.
+
+    Returns the child's last exit code (0 on a clean drain). Restarts are capped at ``max_restarts`` within
+    ``window_s`` to avoid a tight crash loop. SIGTERM/SIGINT are forwarded to the child for a graceful drain.
+    """
+    cmd = [sys.executable, "-m", "telys.cli", *child_argv]
+    child_env = dict(os.environ if env is None else env)
+    proc: subprocess.Popen | None = None
+    restarts: list[float] = []
+
+    def _forward(signum, _frame):
+        if proc is not None and proc.poll() is None:
+            proc.send_signal(signum)
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        try:
+            signal.signal(sig, _forward)
+        except (ValueError, OSError):
+            pass
+
+    while True:
+        _log.info("supervisor: starting child: telys %s", " ".join(child_argv))
+        proc = subprocess.Popen(cmd, env=child_env)
+        try:
+            rc = proc.wait()
+        except KeyboardInterrupt:
+            proc.send_signal(signal.SIGINT)
+            return proc.wait()
+        if rc == 0:
+            _log.info("supervisor: child exited cleanly (0) — done")
+            return 0
+        now = time.monotonic()
+        restarts = [t for t in restarts if now - t < window_s]
+        restarts.append(now)
+        if len(restarts) > max_restarts:
+            _log.error("supervisor: child crash-looping (%d restarts in %.0fs) — giving up (rc=%d)",
+                       len(restarts), window_s, rc)
+            return rc
+        _log.warning("supervisor: child died (rc=%d) — restarting from last snapshot in %.1fs", rc, backoff_s)
+        time.sleep(backoff_s)

telys/_wire.py

@@ -0,0 +1,38 @@
+"""Tiny length-prefixed JSON wire protocol shared by the Telys self-host server + client.
+
+Frame = 4-byte big-endian unsigned length, then that many bytes of UTF-8 JSON. A request is
+``{"op": str, "collection": str|null, "args": {...}}``; a reply is ``{"ok": true, "result": ...}`` or
+``{"ok": false, "error": str}``. Vectors travel as plain JSON number lists (MVP; a binary frame is a later
+optimization). The 4-byte length is bounded to fail closed on a hostile/oversized frame (anti-OOM).
+"""
+from __future__ import annotations
+
+import json
+import socket
+import struct
+
+MAX_FRAME = 256 * 1024 * 1024  # 256 MiB hard ceiling per message (anti-OOM on a bad/hostile length prefix)
+
+
+def send_msg(sock: socket.socket, obj) -> None:
+    data = json.dumps(obj).encode("utf-8")
+    if len(data) > MAX_FRAME:
+        raise ValueError(f"frame too large: {len(data)} > {MAX_FRAME}")
+    sock.sendall(struct.pack(">I", len(data)) + data)
+
+
+def _recv_exact(sock: socket.socket, n: int) -> bytes:
+    buf = bytearray()
+    while len(buf) < n:
+        chunk = sock.recv(n - len(buf))
+        if not chunk:
+            raise ConnectionError("peer closed the connection mid-frame")
+        buf += chunk
+    return bytes(buf)
+
+
+def recv_msg(sock: socket.socket):
+    (n,) = struct.unpack(">I", _recv_exact(sock, 4))
+    if n > MAX_FRAME:
+        raise ValueError(f"declared frame too large: {n} > {MAX_FRAME}")
+    return json.loads(_recv_exact(sock, n).decode("utf-8"))

telys/cli.py

@@ -0,0 +1,293 @@
+"""Telys CLI — `telys ...` (scaffold).
+
+Commands:
+  telys login                 authenticate for gated runtime downloads (Phase 1: real auth)
+  telys runtime status        show whether the on-device runtime is installed + where it resolves from
+  telys runtime install --file <bundle> --license <license.jwt>
+                              verify a signed runtime bundle + offline RS256 license LOCALLY and install it
+                              (offline-file install; hosted packages.telys.ai download lands later — D-31 #4)
+  telys runtime verify        re-verify the installed runtime offline (manifest signature + artifact SHA-256 + license)
+  telys runtime update        update to the latest runtime on the configured channel (Phase 1)
+  telys version               print SDK version + format version
+
+The SDK is thin: `runtime install` is the ONLY step that may touch the network (and offline-file install does
+not even do that). Verification + query execution are always local/offline (D-30/D-31): the runtime + license
+verify themselves against Telys public keys with no network, no OS-native signing.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+
+def _runtime_status() -> int:
+    from telys.runtime import runtime_available, load_runtime
+    from telys import __version__, FORMAT_VERSION
+    if not runtime_available():
+        print("runtime: NOT INSTALLED")
+        print("  install it:  telys runtime install   (or, for local dev:  pip install telys-runtime)")
+        return 1
+    # Ask the runtime where its kernel resolves from — the SDK never imports engine internals (D-30).
+    info = load_runtime().kernel_info()
+    ok = bool(info.get("found"))
+    if ok:
+        print(f"runtime: READY  (telys {__version__}, format v{FORMAT_VERSION}, impl={info.get('runtime')})")
+        print(f"  kernel: FOUND  [{info.get('source')}]  {info.get('path')}")
+        return 0
+    print(f"runtime: PACKAGE PRESENT, KERNEL NOT INSTALLED  (telys {__version__}, impl={info.get('runtime')})")
+    print(f"  kernel: MISSING  [{info.get('source')}]  {info.get('path')}")
+    print("  install it:  telys runtime install --file <bundle> --license <license.jwt>")
+    return 1
+
+
+def _not_implemented(what: str) -> int:
+    print(f"`telys {what}` is not implemented yet (Phase 1: gated download + signature verification).")
+    print("For local development, install the runtime package directly:  pip install telys-runtime")
+    return 2
+
+
+def _runtime_install(args) -> int:
+    # D-31 #4: --file = offline-file install (no network). Otherwise download the signed bundle from the host
+    # (the ONLY networked step) and verify it LOCALLY — same RS256/SHA-256 gate either way.
+    from telys.installer import install_from_file, install_from_host, InstallError
+    from telys.verify import VerificationError
+    try:
+        if getattr(args, "file", None):
+            rec = install_from_file(args.file, args.license)
+        else:
+            from telys.paths import packages_url
+            print(f"downloading runtime '{args.version}' from {packages_url()} …")
+            rec = install_from_host(version=args.version, license_path=getattr(args, "license", None))
+    except (InstallError, VerificationError) as e:
+        print(f"install FAILED: {e}")
+        return 1
+    lic = rec.get("license", {})
+    print(f"runtime INSTALLED + VERIFIED  [{rec['platform']}]  ({len(rec['artifacts'])} artifacts)")
+    print(f"  license: tier={lic.get('tier')} features={lic.get('features')} exp={lic.get('exp')}")
+    if rec.get("source"):
+        print(f"  source: {rec['source']}")
+    print("  query execution is now fully local/offline — no network.")
+    return 0
+
+
+def _login(args) -> int:
+    # One command: OAuth device-code -> create API key -> register device -> platform-signed license ->
+    # install + verify the signed runtime -> cache. After this, Telys runs fully offline. --token skips the
+    # browser step (headless/CI); --no-install provisions without downloading the runtime.
+    from telys.login import login, LoginError
+    try:
+        info = login(
+            plan=getattr(args, "plan", "telys_developer"),
+            access_token=getattr(args, "token", None) or os.environ.get("TELYS_TOKEN"),
+            install=not getattr(args, "no_install", False),
+            open_browser=not getattr(args, "no_browser", False),
+        )
+    except LoginError as e:
+        print(f"login FAILED: {e}")
+        return 1
+    runtime = "installed" if info["installed"] else "not installed (run `telys runtime install`)"
+    print(f"  api key: {info['api_key_prefix']}   device: {info['device_id'][:12]}…   "
+          f"tier: {info['tier']}   runtime: {runtime}")
+    return 0
+
+
+def _mem(args) -> int:
+    import json as _json
+
+    from telys.mcp import TelysMemory
+
+    m = TelysMemory(getattr(args, "path", None))
+    try:
+        if args.memcmd == "list":
+            out = m.list_collections()
+        elif args.memcmd == "create":
+            out = m.create_collection(args.name, partition_by=args.partition_by)
+        elif args.memcmd == "add":
+            out = m.add(args.collection, texts=args.text, ids=args.id or None)
+        elif args.memcmd == "search":
+            out = m.search(args.collection, args.query, top_k=args.top_k)
+        elif args.memcmd == "stats":
+            out = m.stats(args.collection)
+        else:
+            print("usage: telys mem {add,search,create,list,stats} …")
+            return 2
+    except Exception as e:  # noqa: BLE001
+        print(f"error: {e}")
+        return 1
+    print(_json.dumps(out, indent=2))
+    return 0
+
+
+def _runtime_verify() -> int:
+    from telys.installer import verify_installed, InstallError
+    from telys.verify import VerificationError
+    try:
+        rep = verify_installed()
+    except (InstallError, VerificationError) as e:
+        print(f"runtime verify FAILED: {e}")
+        return 1
+    print(f"runtime VERIFIED  [{rep['platform']}]  {rep['dir']}")
+    print(f"  artifacts: {', '.join(rep['artifacts_verified'])}")
+    print(f"  license: tier={rep.get('tier')} exp={rep.get('exp')}")
+    return 0
+
+
+def _serve(args) -> int:
+    import os
+    license_token = args.license or os.environ.get("TELYS_LICENSE")
+    access_token = args.access_token or os.environ.get("TELYS_ACCESS_TOKEN")
+    if not args.socket and not (args.host and args.port):
+        print("error: pass --socket <path> (Unix) or --host <h> --port <p> (TCP)")
+        return 2
+
+    if args.supervise:
+        # Re-run ourselves as a supervised child WITHOUT --supervise. Secrets go via env (inherited by the
+        # child), never on the child's argv, so they don't leak into the process list.
+        from telys._supervisor import supervise
+        if license_token:
+            os.environ["TELYS_LICENSE"] = license_token
+        if access_token:
+            os.environ["TELYS_ACCESS_TOKEN"] = access_token
+        child = ["serve", "--path", args.path]
+        if args.socket:
+            child += ["--socket", args.socket]
+        if args.host:
+            child += ["--host", args.host]
+        if args.port:
+            child += ["--port", str(args.port)]
+        if args.require_license:
+            child += ["--require-license"]
+        if args.save_interval:
+            child += ["--save-interval", str(args.save_interval)]
+        print(f"telys serve (supervised): {args.path}")
+        return supervise(child)
+
+    from telys.server import serve
+    where = args.socket if args.socket else f"{args.host}:{args.port}"
+    print(f"telys serve: shared memory at {args.path} on {where}"
+          + ("  [license-gated]" if args.require_license else "")
+          + ("  [token-auth]" if access_token else "")
+          + (f"  [save every {args.save_interval}s]" if args.save_interval else ""))
+    try:
+        serve(args.path, args.socket, host=args.host, port=args.port,
+              license_token=license_token, require_license=args.require_license,
+              access_token=access_token, save_interval_s=args.save_interval)
+    except KeyboardInterrupt:
+        print("\nshutting down")
+    except OSError as e:
+        print(f"error: cannot bind {where} ({e}); is another telys server already running there?")
+        return 2
+    except ValueError as e:
+        print(f"error: {e}")
+        return 2
+    return 0
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    p = argparse.ArgumentParser(prog="telys", description="Telys — on-device memory & retrieval SDK")
+    sub = p.add_subparsers(dest="cmd")
+    login = sub.add_parser("login", help="one command: OAuth -> API key -> device -> license -> runtime install")
+    login.add_argument("--token", help="use an existing OAuth token (headless/CI); else browser device-code login")
+    login.add_argument("--plan", default="telys_developer", help="tier to request (default: telys_developer, free)")
+    login.add_argument("--no-install", action="store_true", help="provision only; skip downloading the runtime")
+    login.add_argument("--no-browser", action="store_true", help="don't auto-open the browser (print the code)")
+    sub.add_parser("version", help="print SDK + format version")
+    rt = sub.add_parser("runtime", help="manage the on-device runtime").add_subparsers(dest="rtcmd")
+    rt.add_parser("status", help="is the runtime installed?")
+    rt_install = rt.add_parser("install", help="install + verify the signed runtime (online host, or --file offline)")
+    rt_install.add_argument("--file", help="path to a signed runtime bundle (.bundle/.tar.gz) for offline install")
+    rt_install.add_argument("--license", help="path to the signed offline license (license.jwt)")
+    rt_install.add_argument("--version", default="latest", help="runtime version to fetch from the host (default: latest)")
+    rt.add_parser("verify", help="re-verify the installed runtime's signature/integrity + license (offline)")
+    rt.add_parser("update", help="update to the latest runtime on the channel")
+    srv = sub.add_parser("serve", help="self-host a shared Telys memory (Team tier) over a Unix socket or TCP")
+    srv.add_argument("--path", required=True, help="engine data directory (the shared memory store)")
+    srv.add_argument("--socket", help="Unix-domain socket to listen on (trusted host; no token needed)")
+    srv.add_argument("--host", help="TCP bind host (e.g. 0.0.0.0 for a container); requires --access-token")
+    srv.add_argument("--port", type=int, help="TCP bind port (with --host)")
+    srv.add_argument("--access-token", help="shared bearer token for TCP clients; or set TELYS_ACCESS_TOKEN")
+    srv.add_argument("--license", help="Telys license token (Team tier); or set TELYS_LICENSE")
+    srv.add_argument("--require-license", action="store_true",
+                     help="refuse to serve without a valid Telys (products.telys) license")
+    srv.add_argument("--save-interval", type=float, default=0.0, metavar="SECONDS",
+                     help="background periodic save every N seconds (bounds data loss on a crash; 0=off)")
+    srv.add_argument("--supervise", action="store_true",
+                     help="run under a supervisor that auto-restarts the server from the last snapshot on crash")
+
+    mcp = sub.add_parser("mcp", help="Telys MCP stdio server (plugin for Claude/Cursor/OpenAI) + one-command install")
+    mcp.add_argument("--path", help="memory directory (default: ~/.telys/memory or $TELYS_MEMORY_PATH)")
+    mcp.add_argument("--workspace",
+                     help=("repo root the auto-indexer maps for telys_repo_search "
+                           "(default: $TELYS_MCP_WORKSPACE; unset = pass `path` per call)"))
+    mcp.add_argument("--persistent-index", action="store_true",
+                     help=("persist the auto-index fingerprint cache under the memory dir so a restart "
+                           "skips re-embedding an unchanged repo"))
+    _mcpsub = mcp.add_subparsers(dest="mcpcmd")  # bare `telys mcp` still runs the server (no subcommand)
+    for _verb, _help in (("install", "register the Telys MCP server in an AI client (Claude/Cursor/Codex)"),
+                         ("uninstall", "deregister the Telys MCP server"),
+                         ("status", "show where the Telys MCP server is registered")):
+        _sp = _mcpsub.add_parser(_verb, help=_help)
+        _sp.add_argument("--name", default="telys", help="server name in the client config")
+        if _verb != "status":
+            _sp.add_argument("--client", default="all",
+                             choices=["claude", "cursor", "codex", "claude-desktop", "all"],
+                             help="target client (default: auto-detect installed)")
+            _sp.add_argument("--scope", default="user", choices=["user", "project"],
+                             help="user config (default) or a project-local config file")
+
+    mem = sub.add_parser("mem", help="use Telys memory from the terminal (advanced)").add_subparsers(dest="memcmd")
+    for _name in ("add", "search", "create", "list", "stats"):
+        mp = mem.add_parser(_name)
+        mp.add_argument("--path", help="memory directory (default: ~/.telys/memory)")
+        if _name in ("add", "search", "stats"):
+            mp.add_argument("-c", "--collection", required=True)
+        if _name == "create":
+            mp.add_argument("--name", required=True)
+            mp.add_argument("--partition-by", default="scope")
+        if _name == "add":
+            mp.add_argument("-t", "--text", action="append", required=True, help="document text (repeatable)")
+            mp.add_argument("--id", action="append", help="document id (repeatable; matches --text order)")
+        if _name == "search":
+            mp.add_argument("-q", "--query", required=True)
+            mp.add_argument("--top-k", type=int, default=5)
+
+    args = p.parse_args(argv)
+    if args.cmd == "serve":
+        return _serve(args)
+    if args.cmd == "version":
+        from telys import __version__, FORMAT_VERSION
+        print(f"telys {__version__} (format v{FORMAT_VERSION})")
+        return 0
+    if args.cmd == "login":
+        return _login(args)
+    if args.cmd == "mcp":
+        mcpcmd = getattr(args, "mcpcmd", None)
+        if mcpcmd in ("install", "uninstall", "status"):
+            from telys import mcp_install
+            if mcpcmd == "status":
+                return mcp_install.status(name=args.name)
+            fn = mcp_install.install if mcpcmd == "install" else mcp_install.uninstall
+            return fn(client=args.client, scope=args.scope, name=args.name)
+        from telys.mcp import MCPServer, TelysMemory
+        return MCPServer(TelysMemory(getattr(args, "path", None),
+                                     workspace=getattr(args, "workspace", None),
+                                     persistent_index=getattr(args, "persistent_index", False))).serve()
+    if args.cmd == "mem":
+        return _mem(args)
+    if args.cmd == "runtime":
+        if args.rtcmd == "status":
+            return _runtime_status()
+        if args.rtcmd == "install":
+            return _runtime_install(args)
+        if args.rtcmd == "verify":
+            return _runtime_verify()
+        if args.rtcmd == "update":
+            return _not_implemented("runtime update")
+    p.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())