> 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/start-here/what-is-telys.md).

# What is Telys

How Telys gives apps and agents durable, private semantic memory on-device — a thin public SDK over a closed, signed native runtime, with nothing leaving the machine.

Telys is an on-device, offline-first vector-memory engine. An app or AI agent stores text and vectors, then retrieves them by semantic and lexical similarity — entirely on the local machine. You program against the open `telys` Python SDK; the work happens in a closed, signed native runtime the SDK loads locally.

Telys gives you durable semantic memory that behaves like a local library, not a remote service: no per-query round-trips, no vectors uploaded to a third party, and no dependency on connectivity once the runtime is installed.

## The problem

Apps need memory that understands meaning, not just keywords: an assistant that recalls last week's conversation, a coding agent that remembers a repository, a RAG pipeline that ranks passages by relevance. The usual answer is a hosted vector database, but that puts your documents and embeddings on someone else's servers, makes every query a network call, and stops working offline.

For desktop tools, editor extensions, on-device agents, and regulated or air-gapped deployments, that tradeoff is unacceptable. The memory belongs on the user's hardware, under their control, and must keep working with no network.

## How Telys solves it

Telys splits into two parts with a clear trust boundary:

* **A thin, open SDK (`telys`).** You `pip install` and import it. It defines the public API — the `Telys` facade, collections, embedders, filters, and tuning — and handles signature and license verification. Pure Python, with only `numpy` and `cryptography` as dependencies.
* **A closed, signed native runtime.** The vector store, IVF index, and embedding kernels ship as a separate signed bundle, downloaded once from `packages.telys.ai` and verified offline against public keys embedded in the wheel. The SDK loads it lazily through `ctypes`; a verified install runs native-only and fail-closed.

Importing `telys` activates a verified installed runtime by prepending its packaged Python site to `sys.path`. The runtime then executes every collection operation on local files, and the embedding kernels turn text into vectors in-process. Verifying against embedded keys and a signed release manifest lets the engine prove its integrity without contacting a server — see [**How Telys works**](https://docs.telys.ai/understand-telys/how-telys-works.md).

## What ships today

Version `0.1.15` covers the full local memory lifecycle:

| Capability        | What you get                                                                                                                |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Collections       | Create, open, save, and list collections of vectors with metadata.                                                          |
| Ingestion         | `add` / `upsert` raw vectors, or `add_texts` / `upsert_texts` / `update_texts` to embed on the fly.                         |
| Search            | `search` (by vector) and `search_text` (embed then search), with equality filters and optional metadata.                    |
| Embedders         | Lexical `AlgentaBigramEmbedder` and `AlgentaMultigramEmbedder`, plus `CallableEmbedder` to bring your own (OpenAI, BGE, …). |
| Indexing & tuning | Build a per-partition IVF index and tune recall vs. latency.                                                                |
| Serving           | Run `telys serve` and connect from another process with `RemoteTelys`.                                                      |
| MCP               | A stdio MCP server exposing 19 tools — the full SDK text surface — to Claude, Cursor, and other clients.                    |

## What is not in the beta

* **No temporal or time-travel queries.** No `as_of()` or validity-window API; retrieval is `search`, `search_text`, and `ids` only.
* **Equality filters only.** `Eq(column, value)` (or a single-key dict) is the only filter — there are no AND/OR/NOT, comparison, or range operators.
* **Some pieces need the runtime or kernel.** `HeuristicTuner` and `AlgentaPooledEmbedder` resolve from the runtime and are unavailable in a runtime-free install; the lexical embedders need the native kernel.
* **Remote is a subset.** `RemoteCollection` omits `update_texts`, `tune`, and `apply_tuning`, and its `search` has no `target_recall`.

## Telys vs. cloud vector databases

|                  | Telys                                | Hosted vector DB                      |
| ---------------- | ------------------------------------ | ------------------------------------- |
| Where data lives | On the local machine                 | On the provider's servers             |
| Query path       | In-process native call               | Network round-trip                    |
| Works offline    | Yes, after first install             | No                                    |
| Embeddings       | On-device kernels or your own model  | Usually uploaded or provider-computed |
| Trust model      | Signed runtime, offline verification | Provider's infrastructure and policy  |

Telys is not a distributed database. It is local semantic memory — private by construction, fast because there is no network, and verifiable because the runtime is signed.

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>How Telys works</strong></td><td>The SDK, the signed runtime, and the trust boundary.</td><td><a href="https://docs.telys.ai/understand-telys/how-telys-works.md">How it works</a></td></tr><tr><td><strong>Quickstart: your first collection</strong></td><td>Install, create a collection, and search on-device.</td><td><a href="https://docs.telys.ai/quickstarts/quickstart-first-collection.md">First collection</a></td></tr><tr><td><strong>On-device &#x26; offline-first</strong></td><td>What runs locally and what never leaves the machine.</td><td><a href="https://docs.telys.ai/understand-telys/on-device-offline.md">On-device &amp; offline</a></td></tr></tbody></table>

Next: read [**How Telys works**](https://docs.telys.ai/understand-telys/how-telys-works.md), then build in the [**Quickstart**](https://docs.telys.ai/quickstarts/quickstart-first-collection.md).
