> 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/roadmap.md).

# Roadmap

Where Telys is heading. **Everything below is planned and not shipped** in the current public beta (`0.1.0b2`) — a direction of travel, not a commitment to dates or APIs; names and shapes will change. For what ships today, read the [Changelog](/resources/changelog.md) and the [SDK API index](/reference/sdk-api-index.md).

{% hint style="warning" %}
Nothing on this page exists in the installed SDK yet. Code written against a feature described here will fail against `0.1.0b2`. Build on the shipped surface first; treat this page as intent.
{% endhint %}

## What ships today

The shipped surface these plans build on:

* **Collections** of vectors with string IDs and JSON metadata, persisted on disk (`collection.json` is the commit point).
* **Queries**: `search`, `search_text`, and `ids` — nearest-neighbour retrieval plus id enumeration. There is no temporal or time-travel query.
* **Filters**: `Eq` only — single-column equality, passed as `Eq("tenant_id", "acme")` or a single-key dict.
* **Embedders**: the deterministic lexical family and `CallableEmbedder` for bring-your-own vectors, from `telys.embedding`.
* **Runtime**: a signed, native runtime downloaded to your machine and verified offline.

See [How Telys works](/understand-telys/how-telys-works.md) for the full picture.

## At a glance

| Area         | Today (`0.1.0b2`)                                                        | Planned direction                                                                       |
| ------------ | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| Memory model | Vectors + IDs + metadata, retrieved by similarity                        | Validity windows, `as_of` reads, remember/recall semantics, episodes / facts / entities |
| Filters      | `Eq` only (single-column equality)                                       | Additional predicates (ranges, boolean composition)                                     |
| Platforms    | macOS arm64, Linux x86\_64, Linux arm64 (experimental); Windows via WSL2 | Broader hosted-runtime coverage; a real `telys runtime update`                          |

## A richer memory model (planned)

Today a collection is a similarity index: you add records and retrieve the nearest ones. The planned memory model layers meaning on top of that index.

{% hint style="info" %}
Planned — not in `0.1.0b2`. The shapes below are illustrative, not a shipped signature.
{% endhint %}

* **Validity windows and `as_of` reads.** A record could carry a time range for when a fact was true, and a query could ask what memory held as of a given instant — reconstructing a past state, not only the present.
* **Remember / recall semantics.** Higher-level verbs over the raw index: `remember(...)` to write an observation with provenance, `recall(...)` to retrieve with recency and salience factored in, not pure vector distance.
* **Episodes, facts, and entities.** First-class structure — grouping records into episodes, promoting durable statements into facts, and linking them to the entities they describe.

What exists today is only nearest-neighbour retrieval:

```python
from telys import Telys
from telys.embedding import AlgentaMultigramEmbedder

engine = Telys("./memory")
col = engine.open_collection("notes", embedder=AlgentaMultigramEmbedder())

# Shipped surface: similarity + Eq filter, no temporal dimension.
hits = col.search_text("quarterly revenue", top_k=5)
```

There is deliberately **no** `as_of()`, no validity window, and no episode/fact/entity API in the shipped SDK. When the richer model lands it will be additive and versioned.

## Hosted runtime for more platforms (planned)

The signed runtime is downloaded per platform from `packages.telys.ai` and verified before it is trusted.

* **Today**, the hosted installer covers `macos-arm64`, `linux-x86_64`, and `linux-arm64` (experimental). Windows is supported through WSL2; Intel macOS is not yet supported. See [Supported platforms](/operations/supported-platforms.md).
* **Planned**: the hosted download broadens to more targets, and `telys runtime update` — today a stub that prints "not implemented yet" and exits `2` — becomes a real in-place updater that fetches, verifies, and swaps the runtime.

```bash
# Shipped today: offline, file-based install is fully supported.
telys runtime install --file ./telys-runtime.tar

# Planned: telys runtime update currently returns exit 2 (stub).
telys runtime update
```

## Additional filters (planned)

Filtering today is intentionally minimal: `Eq` is the only filter class, and MCP accepts a single-key equality object.

```python
from telys import Eq

# Shipped: equality only.
col.search_text("onboarding", where=Eq("team", "growth"))
```

There are no `And`/`Or`/`Not`, `Ne`/`Gt`/`Lt`/`In`, or range operators anywhere in `0.1.0b2`. Compose a single partition key with [`scope_key`](/understand-telys/partitions-scope-key.md) for a compound scope. Until richer predicates ship, model the axes you filter on into partition keys and equality-matchable metadata.

## Stability while we get there

Telys is in public beta. The on-disk format is versioned (`FORMAT_VERSION = 1`) so storage can evolve without silently breaking your data, and the public SDK surface stays thin over the signed runtime. See [Design principles](/resources/design-principles.md) for the commitments behind the plans above.

## Next steps

* [Design principles](/resources/design-principles.md) — the constraints these plans respect.
* [Changelog](/resources/changelog.md) — what has actually shipped.
* [What is Telys](/start-here/what-is-telys.md) — the product as it exists today.


---

# 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/resources/roadmap.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.