Un motor, enraizado en un directorio, enlazado dentro de tu proceso.
Telys es un motor embebido de memoria y recuperación para agentes de IA. Dado que el motor controla el diseño físico, vecinos-más-cercanos-donde-clave-es-x se resuelve en una búsqueda de directorio más un escaneo secuencial de un bloque contiguo — dentro de tu proceso, sin llamadas externas en tiempo de consulta.
La API pública es una fachada: un motor que contiene colecciones con nombre, cada una un índice vectorial filtrado con ids externos, claves de partición y columnas de filtro basadas en metadatos, y semántica explícita de 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
La ingesta es explícita. add lanza error sobre un id existente; upsert otorga a un id existente una nueva versión visible bajo MVCC — el motor nunca mantiene dos filas físicas para un id lógico.
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)
Cada consulta acepta un filtro where columnar y puede devolver un plan explain que nombra la estrategia física que la sirvió. target_recall establece el umbral de recall que el planificador debe respetar; los alcances compuestos particionan sobre una única clave física construida por 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
El mantenimiento forma parte de la superficie. Las eliminaciones crean tombstones de inmediato y se eliminan físicamente en la compactación; IVF se construye por partición, solo cuando una partición supera la ruta exacta; save es atómico, y al reabrir se restauran los datos, el ajuste aplicado y el espacio de embeddings.
| Capacidad | Detalle |
|---|---|
| búsqueda filtrada | Las consultas por clave de partición se resuelven en una búsqueda de directorio más un escaneo secuencial de un bloque contiguo — recall 1.0 en la ruta exacta (D≤384; D=768 lee 0.999–0.9995 en empates de orden de reducción, cero errores genuinos). Sobre un subconjunto contiguo idéntico este escaneo iguala a FAISS en bruto, por lo que la ventaja es la disposición, no el kernel. Los filtros fuera de clave retroceden a scatter-gather, y el plan explain lo indica. |
| persistencia | Escrituras respaldadas por WAL, snapshots MVCC, segmentos sellados. save() confirma atómicamente; open_collection() restaura los datos, el ajuste aplicado y el espacio de embeddings. |
| modelo temporal | Upserts versionados: un id existente recibe una nueva versión visible que reemplaza a la anterior — nunca una fila duplicada. Los tombstones ocultan las filas eliminadas de inmediato; la compactación las elimina físicamente. |
| embeddings | Agnóstico a embeddings. Aporta tus propios vectores, o adjunta un EmbeddingProvider / CallableEmbedder. Se incluye un embedder bigrámico en dispositivo — léxico, en proceso, sin descarga de modelo. |
| plataformas | macOS arm64 · Linux x86_64 / arm64 · Windows bajo WSL2. |
| licencia | SDK público Apache-2.0 en PyPI (pip install telys) más un runtime on-device firmado y licenciado, instalado mediante telys login. Beta pública. |
| latencia medida | p50/p95 reportados por selectividad a recall 1.0, hilo único, en proceso, en un equipo M4 Max declarado — con muestras brutas y el script. Ver la página de benchmarks. |
Una fachada pública ligera sobre un runtime firmado.
El SDK público no contiene implementación del motor. Se comunica con el runtime a través de una única costura congelada — RuntimeHandle — y el runtime mantiene sus bucles críticos en kernels SIMD de Mojo: un hot path sin Python dentro de tu proceso 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
Las fachadas Telys y Collection, Eq y scope_key, las interfaces EmbeddingProvider y Tuner, un cargador de runtime y la CLI de telys. Un guardián de release verifica que ningún código fuente del motor se incluya en el wheel público.
telys login lo instala
Un único inicio de sesión aprovisiona una licencia de dispositivo gratuita y descarga el runtime firmado; la firma y la licencia se reverifican sin conexión. El runtime contiene el índice de particiones, MVCC, compactación e IVF — y es necesario para la ejecución.
Las particiones son contiguas
El directorio asigna una clave de partición a su bloque; las filas de cada partición se almacenan de forma contigua. Una consulta con scope es un único escaneo secuencial — no una dispersión sobre un índice que ignora tus claves.
El tiempo es el modelo de datos.
Un vector más un blob de metadatos no es una memoria de agente. El modelo de memoria otorga a cada hecho una ventana de validez, una cadena de supersesión explícita y una vista as_of que reconstruye lo que se conocía en un instante del tiempo real. Se presenta aquí tal como es: la dirección especificada, con su maquinaria de almacenamiento ya en producción.
Los hechos son válidos en intervalos
Una memoria lleva una ventana [valid_from, valid_to) en tiempo real. Una contradicción cierra la ventana anterior en lugar de destruir la fila — presente o ausente no es suficiente para un agente.
Sin sobreescritura silenciosa
Un hecho corrector apunta al hecho que reemplaza. La cadena es explícita y reconstruible: lo que el agente creía, y cuándo dejó de creerlo, es una consulta.
Lo que se conocía en T
Una vista as_of reconstruye exactamente las memorias válidas en el tiempo real T bajo un snapshot MVCC dado — una recuperación reproducible y auditable a posteriori.
Spec, etiquetado como spec.
remember, recall y as_of están definidos en el borrador MEMORY-SEMANTICS — son la dirección, no la referencia de API publicada. Se apoyan en la maquinaria que se entrega hoy: actualizaciones versionadas, supersesión, tombstones y snapshots MVCC.
Leer cómo funciona- add / upsert — un id existente se convierte en una nueva versión visible, nunca en una fila duplicada
- search / search_text — filtros where=, planes explain, umbrales target_recall
- delete — tombstones: ocultos para lecturas de inmediato, eliminados en la compactación
- compact / build_ivf — mantenimiento de segmentos; IVF por partición para particiones sobredimensionadas
- snapshot / save / stats — vistas de lectura MVCC, guardado durable atómico, reapertura
- Supersesión MVCC — cada actualización supersede a su predecesora; nada se sobreescribe silenciosamente