One engine, rooted at a directory, linked into your process.
Telys is an embedded memory and retrieval engine for AI agents. Because the engine owns the physical layout, nearest-neighbors-where-key-equals-x resolves to a directory lookup plus a sequential scan of one contiguous block — inside your process, with no external calls at query time.
The public API is a facade: an engine holding named collections, each a filtered vector index with external ids, metadata-driven partition keys and filter columns, and explicit add / upsert / delete semantics.
from telys import Telys, scope_key db = Telys("./memory") col = db.create_collection("docs", dim=768, partition_by="tenant_id", filter_columns=["lang"]) col.add(vectors, ids=ids, metadata=metadata) # new rows only — raises on an existing id col.upsert(vectors, ids=ids, metadata=metadata) # existing id → a new visible version
Ingest is explicit. add raises on an existing id; upsert gives an existing id a new visible version under MVCC — the engine never holds two physical rows for one logical id.
hits = col.search(qvec, top_k=10, where={"tenant_id": "acme"}, explain=True) hits["explain"]["plan"] # "PartitionSliceExactF32" # composite scope → one physical partition key sk = scope_key("acme/shop", "payments", "python") res = symbols.search_text("refund pending after migration", top_k=40, where={"scope_key": sk}, explain=True, target_recall=0.98)
Every query takes a columnar where filter and can return an explain plan naming the physical strategy that served it. target_recall sets the recall floor the planner must honor; composite scopes partition on a single physical key built by scope_key.
col.delete(stale_ids) # tombstone — hidden from reads now, dropped at compact() col.compact() col.build_ivf(min_rows=20000, target_recall=0.98) # oversized partitions only snap = col.snapshot() # frozen MVCC read view col.save() # atomic — collection.json is written last, as the commit point col.stats() # partitions · external_ids · embedding_space
Maintenance is part of the surface. Deletes tombstone immediately and are removed physically at compaction; IVF is built per partition, only where a partition outgrows the exact path; save is atomic, and reopening restores the data, the applied tuning, and the embedding space.
| Capability | Detail |
|---|---|
| filtered search | nearest-neighbors-where-key-equals-x resolves to a directory lookup plus one sequential scan of one contiguous block — recall 1.0 on the exact path (D≤384; D=768 reads 0.999–0.9995 on reduction-order ties, zero genuine misses). On an identical contiguous subset this scan ties raw FAISS, so the win is layout, not kernel. |
| persistence | WAL-backed writes, MVCC snapshots, sealed segments. save() commits atomically; open_collection() restores the data, the applied tuning, and the embedding space. |
| temporal model | Versioned upserts: an existing id gets a new visible version that supersedes the old one — never a duplicate row. Tombstones hide deleted rows immediately; compaction removes them physically. |
| embeddings | Embedding-agnostic. Bring your own vectors, or attach an EmbeddingProvider / CallableEmbedder. An on-device bigram embedder is included — lexical, in-process, no model download. |
| platforms | macOS arm64 · Linux x86_64 / arm64 · Windows under WSL2. |
| license | Apache-2.0 public SDK on PyPI (pip install telys) plus a signed, licensed on-device runtime installed by telys login. Public Beta. |
| measured latency | p50/p95 reported per selectivity at recall 1.0, single-thread, in-process, on a disclosed M4 Max rig — with raw samples and the script. See the benchmarks page. |
A thin public facade over a signed runtime.
The public SDK contains no engine implementation. It talks to the runtime across one frozen seam — RuntimeHandle — and the runtime keeps its hot loops in Mojo SIMD kernels: a zero-Python hot path inside your Python process.
Telys / Collection # public SDK facade — no engine code
└─ RuntimeHandle # the frozen SDK–engine seam
└─ signed runtime # hot loops in Mojo SIMD kernels — zero-Python hot path
├─ partition directory # key → contiguous block
└─ contiguous segments # one sequential scan per scopetelys — Apache-2.0
The Telys and Collection facades, Eq and scope_key, the EmbeddingProvider and Tuner interfaces, a runtime loader, and the telys CLI. A release guard checks that no engine source ever ships in the public wheel.
telys login installs it
One sign-in provisions a free device license and fetches the signed runtime; signature and license re-verify offline. The runtime holds the partition index, MVCC, compaction, and IVF — and is required for execution.
Partitions are contiguous
The directory maps a partition key to its block; each partition's rows are stored contiguously. A scoped query is one sequential scan — not a scatter across an index that ignores your keys.
Time is the data model.
A vector plus a metadata blob is not an agent memory. The memory model gives every fact a validity window, an explicit supersession chain, and an as_of view that reconstructs what was known at a point in world-time. It is presented here as what it is: the specified direction, with its storage machinery already shipping underneath.
Facts are valid over intervals
A memory carries a [valid_from, valid_to) window in world-time. A contradiction closes the old window instead of destroying the row — present-or-absent is not enough for an agent.
No silent overwrite
A correcting fact points at the fact it replaces. The chain is explicit and reconstructable: what the agent believed, and when it stopped believing it, is a query.
What was known at T
An as_of view reconstructs exactly the memories valid at world-time T under a given MVCC snapshot — recall that is reproducible and auditable after the fact.
Spec, labeled as spec.
remember, recall, and as_of are defined in the MEMORY-SEMANTICS draft — they are the direction, not shipped API reference. They lower onto machinery that ships today: versioned updates, supersession, tombstones, and MVCC snapshots.
Read how it works- add / upsert — an existing id becomes a new visible version, never a duplicate row
- search / search_text — where= filters, explain plans, target_recall floors
- delete — tombstones: hidden from reads immediately, dropped at compaction
- compact / build_ivf — segment maintenance; per-partition IVF for oversized partitions
- snapshot / save / stats — MVCC read views, atomic durable save, reopen
- MVCC supersession — every update supersedes its predecessor; nothing is silently overwritten