> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/resources/changelog.md).

# Changelog

Release history for the public Telys SDK — every shipped version, what changed, and the compatibility facts that go with it.

Released versions of the public `telys` package, newest first. Telys is generally available (GA since `0.1.0`); the on-disk format is versioned separately as `FORMAT_VERSION` so storage can evolve without breaking data. Pin a specific version:

```bash
pipx install 'telys==0.1.0'   # or: pip install 'telys==0.1.0'
```

## Releases

| Version   | Channel              | On-disk format       | Highlights                                                                                                                                |
| --------- | -------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `0.1.1`   | Stable               | `FORMAT_VERSION = 1` | MCP hardening + auditability — `ids:null` tolerance, actionable faiss errors, `telys mcp --monitor`, `telys mcp install` learns Qwen Code |
| `0.1.0`   | General availability | `FORMAT_VERSION = 1` | **GA.** TypeScript SDK (`npm install telys-ai`), zero-touch release chain, strict `update_texts`, A–Z audit repairs                       |
| `0.1.0b4` | Public beta          | `FORMAT_VERSION = 1` | **Fixes `telys login`**, which failed for every user on `0.1.0b3`; full MCP tool surface + automatic repo indexing                        |
| `0.1.0b3` | Public beta          | `FORMAT_VERSION = 1` | Self-host server hardening — `build_ivf`, `snapshot`, `drop_collection` over the wire (RemoteTelys)                                       |
| `0.1.0b2` | Public beta          | `FORMAT_VERSION = 1` | MCP registry ownership marker carried onto PyPI; `server.json` fixes                                                                      |
| `0.1.0b1` | Public beta          | `FORMAT_VERSION = 1` | Initial public beta — SDK, CLI, MCP server, signed runtime                                                                                |

Exact release dates are omitted where not recorded; the beta series shipped during the 2026 public beta.

## 0.1.1

**MCP hardening + auditability.** A patch for the MCP surface under real client traffic: the CRUD tools stop crashing on the JSON sloppy clients actually send, IVF tuning fails with instructions instead of a stack trace, and two new operator capabilities ship — a built-in usage audit (`--monitor`) and Qwen Code as a first-class `telys mcp install` target.

* **CRUD tools tolerate real client JSON.** An explicit `ids: null` on `telys_upsert` now behaves like omitting ids (generated ids — same as `telys_add`) instead of crashing on `len(None)`. `telys_update` rejects it with the strict-contract message, and no longer surfaces a raw engine `KeyError` when `metadata` is omitted (the collection's partition key is now defaulted, matching `telys_add`/`telys_upsert`).
* **Actionable faiss error.** `telys_build_ivf` on an install without the optional faiss dependency (the pipx default) now says exactly how to install it (`pipx inject telys faiss-cpu` / `pip install faiss-cpu`) instead of a bare `ModuleNotFoundError`.
* **Usage auditing — `telys mcp --monitor`.** Appends every JSON-RPC request/response to `<memory dir>/mcp-monitor.jsonl` (`--monitor-log PATH` overrides the location), so you can see exactly which tools your assistant host calls. Best-effort writes — auditing never breaks the server.
* **`telys mcp install` learns Qwen Code.** `--client qwen` registers the canonical zero-env entry in `~/.qwen/settings.json` (or `.qwen/settings.json` at project scope); detection, `status`, and `uninstall` cover it too. Qwen's settings file may carry JSONC comments, so the installer fails closed rather than risk clobbering non-MCP state.
* **No breaking changes** to the Python SDK surface or the on-disk format (`FORMAT_VERSION = 1`).

Upgrade:

```bash
pipx upgrade telys
telys version        # telys 0.1.1 (format v1)
```

## 0.1.0

**General availability.** Telys graduates from beta: the distribution model is proven end-to-end on real users (b1–b4), and from this release on, a version tag drives the entire chain with **no manual steps** — guards → PyPI (trusted-publisher OIDC) → signed runtime bundles → GitHub Release → MCP registry → npm.

* **TypeScript SDK — `npm install telys-ai`.** The Mojo kernel is fully encapsulated: the signed native runtime loads **in-process** over the frozen C-ABI (no sidecar, no setup). Reuses a `telys runtime install` shared with the Python SDK, or fetches + offline-verifies the signed bundle itself (RS256 manifest + SHA-256 artifacts + strict ver:2 license policy, ported to `node:crypto`). Collections persist in the same on-disk format as Python — a store is portable across both SDKs in either direction. Surface: `Telys.open`, create/open collection, add/upsert/strict update, filtered search (`Eq`), ids/fetch/delete, compact/snapshot/stats/save. Node >= 22; macOS arm64 + Linux x86\_64 runtime targets.
* **Strict `update_texts`.** Honors the documented contract at last: unknown or deleted ids now RAISE instead of silently inserting a stray row (the implementation upserted). Use `upsert_texts` for mixed new+existing batches. Vector-level `update` in the TS SDK follows the same strict semantics.
* **`Telys.scope_key(...)` handle method.** The composite partition-key helper is now available on the engine handle, as the docs always presented it (module-level `telys.scope_key` unchanged).
* **Reinstall/upgrade after `telys login` works.** A bare `telys runtime install` now reuses the cached login license; previously it fell through to the OEM-only license route and 404'd for every self-service user.
* **`telys mem add` works repeatedly.** Auto-generated ids no longer restart at `m0` on every call (second add failed with "ids already exist"); they are now unique (`m-<uuid12>`).
* **Native `compact()` parity.** Returns the RuntimeHandle contract `{rows_before, rows_after, reclaimed, lsn}` on both runtimes (the native runtime returned a stats dict).
* **Dev-environment repairs.** `uv sync` resolves again (the `httpx` pin conflicted with `algenta-sdk`), and a verified `telys runtime install` no longer shadows an ambient dev engine (ambient-engine-wins activation) — the nine suites that broke on any machine with an installed runtime are green.
* **Docs rebuilt to match the product.** The full GitBook surface was re-verified against the code: 19-tool MCP surface, remote-API subset (`build_ivf`/`snapshot`/`drop_collection` are served remotely), offline-install examples carry the required `--license`, env-var pages complete.
* **No breaking changes** to the Python SDK surface or the on-disk format (`FORMAT_VERSION = 1`); code written against `0.1.0b4` runs unmodified (the one behavioral fix — strict `update_texts` — corrects a contract violation, see above).

Install:

```bash
pipx install telys
telys version        # telys 0.1.0 (format v1)
```

## 0.1.0b4

**If you are on `0.1.0b3`, upgrade — `telys login` cannot succeed on that version.**

* **`telys login` works again.** On `0.1.0b3` every login attempt failed: the CLI sent Python's default `Python-urllib/X.Y` User-Agent, which the `api.telys.ai` edge rejects with Cloudflare Error 1010 (`browser_signature_banned`) before the request reaches the control plane. The failure was total — not intermittent, not environment-specific — so onboarding was impossible for anyone installing from PyPI. The CLI now sends a real, identifiable `telys-cli/<version>` User-Agent.
* **Two smaller login fixes that came with it.** Stale credentials are cleared *before* a new API key is requested, so a mid-flow failure can no longer leave the CLI pointing at a revoked key (which then surfaced as an unrelated-looking `401` from `packages.telys.ai`). And device-registration failures now surface the control plane's own error code — `local_runtime_not_included`, `device_platform_required`, `device_fingerprint_required`, `device_key_mismatch` — instead of a bare HTTP status.
* **Full MCP tool surface.** The MCP server grows from 5 tools to 19, covering the SDK surface rather than a subset: exact-id lookup, counts, collection listing, upsert/search/delete, and workspace info.
* **Automatic repo indexing.** The MCP server now indexes the workspace on startup and keeps it fresh as files change, so an assistant can search a repo without being told to index it first. Incremental refresh re-embeds only what changed; `.gitignore` is respected, so ignored files (`.env`, keys, secrets directories) are never read.
* **Runtime activation is version-guarded.** If a newer `telys-runtime-native` is present in the environment than the one inside the installed signed bundle, the bundle's copy no longer shadows it — which previously produced a confusing `NativeRuntime.build() ... 'texts'` failure.
* **No SDK API changes.** Public exports, existing CLI commands, and the on-disk format are unchanged from `0.1.0b3`; code written against `0.1.0b3` runs unmodified.

Install:

```bash
pipx install telys
telys version        # telys 0.1.0b4 (format v1)
```

## 0.1.0b3

Self-host server hardening on top of `0.1.0b2`; no breaking changes to the SDK surface.

> ⚠️ **Do not use `0.1.0b3` for a fresh install.** `telys login` fails on this version (see `0.1.0b4`).

* **More collection ops over the wire.** `RemoteTelys` now exposes `build_ivf`, `snapshot`, and `drop_collection`, so a served collection can be indexed, snapshotted, and dropped remotely — the surface the VectorDBBench Telys connector builds on.
* **Version alignment.** `telys-sdk`, the signed native runtime, and the MCP `server.json` are bumped together to `0.1.0b3`.
* **No SDK API changes.** Public exports, CLI commands, and the five MCP tools are unchanged from `0.1.0b2`; code written against `0.1.0b2` runs unmodified.

Install:

```bash
pipx install telys
telys version        # telys 0.1.0b3 (format v1)
```

## 0.1.0b2

A packaging and Model Context Protocol update on top of `0.1.0b1`; no breaking changes to the SDK surface.

* **MCP registry ownership marker.** The published package carries the registry ownership marker (`server.json`) through to PyPI, so the Telys MCP server is claimable and verifiable in the MCP registry.
* **`server.json` schema fixes.** The server description is trimmed to the registry's limit (100 characters) so the manifest validates.
* **No API changes.** Public exports, CLI commands, and the five MCP tools are unchanged from `0.1.0b1`; code written against `0.1.0b1` runs unmodified.

Install:

```bash
pipx install telys
telys version        # telys 0.1.0b2 (format v1)
```

## 0.1.0b1

The initial public beta — the first release of Telys as an installable package.

* **Public SDK.** The `telys` facade with `create_collection` / `open_collection`, the `Collection` ingest/query/tune/persist API, `Eq` filtering, and `scope_key` for composing partition keys.
* **Embedders** in `telys.embedding`: the deterministic lexical family (`AlgentaBigramEmbedder`, `AlgentaMultigramEmbedder`) and `CallableEmbedder` for bring-your-own vectors, with `EmbeddingProfile` space identity.
* **CLI** (`telys`): `login`, `version`, `runtime` (status / install / verify), `serve`, `mcp` (install / uninstall / status), and `mem`.
* **MCP server**: the stdio server exposing five tools — `telys_search`, `telys_add`, `telys_create_collection`, `telys_list_collections`, `telys_stats`.
* **Signed runtime**: the closed native runtime, downloaded per platform and verified offline before it is trusted, plus the `telys.verify` API and embedded release/license public keys.
* **Serving**: `telys serve` with `RemoteTelys` / `connect` over a Unix socket or TCP (TCP requires an access token).

## Compatibility notes

* **Python**: `requires-python >= 3.10`; classifiers list 3.10 through 3.13. The wheel is pure-Python (`py3-none-any`) and the runtime loads via `ctypes`, so it also runs on 3.14. See [Python version support](https://docs.telys.ai/operations/python-version-support.md).
* **Platforms**: the hosted runtime installer supports `macos-arm64`, `linux-x86_64`, and `linux-arm64` (experimental). Windows is supported via WSL2; Intel macOS is not yet supported. See [Supported platforms](https://docs.telys.ai/operations/supported-platforms.md).
* **Dependencies**: `numpy >= 1.24` and `cryptography >= 42`. The closed runtime is an optional extra (`telys[runtime]`), not a hard dependency.
* **`telys runtime update`** is a stub in this line: it prints "not implemented yet" and exits `2`. Update by reinstalling — see [Upgrade Telys](https://docs.telys.ai/operations/upgrading.md).

## See also

* [SDK API index](https://docs.telys.ai/reference/sdk-api-index.md) — the full current surface.
* [Upgrade Telys](https://docs.telys.ai/operations/upgrading.md) — how to move between versions.
