> 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

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**](/understand-telys/how-telys-works.md).

## What ships today

Version `0.1.0b2` 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 five tools 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`, `build_ivf`, `snapshot`, `tune`, and `apply_tuning`, and its `search` has no `target_recall`.

Longer-term direction lives on the [**Roadmap**](/resources/roadmap.md).

## 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="/pages/4dMaM8DFGDPl772eoH6B">/pages/4dMaM8DFGDPl772eoH6B</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="/pages/3P7KO0CUnD1NfTy6KAyk">/pages/3P7KO0CUnD1NfTy6KAyk</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="/pages/8qFzJkRN9mhP0vZqJwZv">/pages/8qFzJkRN9mhP0vZqJwZv</a></td></tr></tbody></table>

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/start-here/what-is-telys.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.