Un motore, radicato in una directory, collegato al tuo processo.
Telys è un motore di memoria e recupero incorporato per agenti AI. Poiché il motore possiede il layout fisico, nearest-neighbours-where-key-equals-x si risolve in una ricerca nella directory più una scansione sequenziale di un blocco contiguo — all'interno del tuo processo, senza chiamate esterne al momento della query.
L'API pubblica è una facade: un motore che gestisce collezioni con nome, ciascuna un indice vettoriale filtrato con id esterni, partition key e colonne di filtro guidate dai metadati, e semantica esplicita di add / upsert / delete.
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
L'ingestione è esplicita. add solleva un'eccezione su un id esistente; upsert assegna a un id esistente una nuova versione visibile sotto MVCC — il motore non mantiene mai due righe fisiche per un singolo id logico.
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)
Ogni query accetta un filtro where colonnare e può restituire un explain plan che nomina la strategia fisica utilizzata. target_recall imposta il livello minimo di recall che il planner deve rispettare; gli scope compositi partizionano su una singola chiave fisica costruita da 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
La manutenzione fa parte della superficie. Le eliminazioni applicano immediatamente un tombstone e vengono rimosse fisicamente alla compattazione; IVF viene costruito per partizione, solo dove una partizione supera il percorso esatto; save è atomico, e la riapertura ripristina i dati, il tuning applicato e lo spazio di embedding.
| Funzionalità | Dettaglio |
|---|---|
| ricerca filtrata | Le query nearest-neighbors-where-key-equals-x si risolvono in una ricerca nella directory più una singola scansione sequenziale di un blocco contiguo — recall 1.0 sul percorso esatto (D≤384; D=768 legge 0.999–0.9995 su pareggi di ordine di riduzione, zero mancanze genuine). Su un sottoinsieme contiguo identico questa scansione pareggia FAISS grezzo: il vantaggio è nel layout, non nel kernel. |
| persistenza | Scritture con WAL, snapshot MVCC, segmenti sigillati. save() esegue il commit atomicamente; open_collection() ripristina i dati, il tuning applicato e lo spazio di embedding. |
| modello temporale | Upsert versionati: un id esistente riceve una nuova versione visibile che sostituisce quella precedente — mai una riga duplicata. I tombstone nascondono immediatamente le righe eliminate; la compattazione le rimuove fisicamente. |
| embedding | Agnostico agli embedding. Porta i tuoi vettori, o collega un EmbeddingProvider / CallableEmbedder. È incluso un embedder bigramma on-device — lessicale, in-process, senza download di modelli. |
| piattaforme | macOS arm64 · Linux x86_64 / arm64 · Windows sotto WSL2. |
| licenza | SDK pubblico Apache-2.0 su PyPI (pip install telys) più un runtime on-device firmato e concesso in licenza, installato tramite telys login. Beta pubblica. |
| latenza misurata | p50/p95 riportati per selettività a recall 1.0, single-thread, in-process, su un rig M4 Max dichiarato — con campioni grezzi e lo script. Vedi la pagina dei benchmark. |
Una facciata pubblica sottile su un runtime firmato.
L'SDK pubblico non contiene alcuna implementazione del motore. Comunica con il runtime attraverso un'unica giuntura immutabile — RuntimeHandle — e il runtime mantiene i propri hot loop in kernel Mojo SIMD: un hot path zero-Python all'interno del tuo processo Python.
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
Le facciate Telys e Collection, Eq e scope_key, le interfacce EmbeddingProvider e Tuner, un runtime loader e la CLI telys. Una release guard verifica che nessun sorgente del motore venga mai incluso nel wheel pubblico.
telys login lo installa
Un singolo accesso provisiona una licenza dispositivo gratuita e scarica il runtime firmato; firma e licenza si riverificano offline. Il runtime contiene l'indice di partizione, MVCC, la compattazione e IVF — ed è necessario per l'esecuzione.
Le partizioni sono contigue
La directory mappa una chiave di partizione al suo blocco; le righe di ciascuna partizione sono memorizzate in modo contiguo. Una query con scope è una singola scansione sequenziale — non uno scatter attraverso un indice che ignora le tue chiavi.
Il tempo è il modello dei dati.
Un vettore più un blob di metadati non è una memoria agente. Il modello di memoria assegna a ogni fatto una finestra di validità, una catena di supersessione esplicita e una vista as_of che ricostruisce ciò che era noto in un dato momento nel tempo reale. È presentato qui per quello che è: la direzione specificata, con il relativo meccanismo di storage già in produzione.
I fatti sono validi su intervalli
Una memoria porta una finestra [valid_from, valid_to) nel tempo reale. Una contraddizione chiude la vecchia finestra invece di eliminare la riga — presente-o-assente non è sufficiente per un agente.
Nessuna sovrascrittura silenziosa
Un fatto correttivo punta al fatto che sostituisce. La catena è esplicita e ricostruibile: ciò che l'agente credeva, e quando ha smesso di crederlo, è una query.
Cosa era noto al tempo T
Una vista as_of ricostruisce esattamente le memorie valide al tempo reale T sotto un dato snapshot MVCC — un recall riproducibile e verificabile a posteriori.
Spec, etichettata come spec.
remember, recall e as_of sono definiti nella bozza MEMORY-SEMANTICS — rappresentano la direzione, non un riferimento API in produzione. Si traducono in meccanismi già disponibili oggi: aggiornamenti versionati, supersessione, tombstone e snapshot MVCC.
Leggi come funziona- add / upsert — un id esistente diventa una nuova versione visibile, mai una riga duplicata
- search / search_text — filtri where=, piani explain, soglie target_recall
- delete — tombstone: nascosto alle letture immediatamente, rimosso alla compattazione
- compact / build_ivf — manutenzione dei segmenti; IVF per partizione sulle partizioni sovradimensionate
- snapshot / save / stats — viste di lettura MVCC, salvataggio durevole atomico, riapertura
- Supersessione MVCC — ogni aggiornamento sostituisce il predecessore; nulla viene sovrascritto silenziosamente