Um motor, enraizado em um diretório, vinculado ao seu processo.
Telys é um motor embarcado de memória e recuperação para agentes de IA. Como o motor controla o layout físico, nearest-neighbours-where-key-equals-x resolve para uma busca em diretório mais um scan sequencial de um bloco contíguo — dentro do seu processo, sem chamadas externas no momento da consulta.
A API pública é uma fachada: um motor que mantém coleções nomeadas, cada uma um índice vetorial filtrado com ids externos, chaves de partição orientadas por metadados, colunas de filtro e 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
A ingestão é explícita. add lança erro em um id existente; upsert atribui a um id existente uma nova versão visível sob MVCC — o motor nunca mantém duas linhas físicas para um 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 aceita um filtro where colunar e pode retornar um plano de explain nomeando a estratégia física que a serviu. target_recall define o piso de recall que o planejador deve respeitar; escopos compostos particionam em uma única chave física construída 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
A manutenção faz parte da superfície. Deleções são marcadas com tombstone imediatamente e removidas fisicamente na compactação; IVF é construído por partição, apenas quando uma partição supera o caminho exato; save é atômico, e reabrir restaura os dados, o ajuste aplicado e o espaço de embeddings.
| Capacidade | Detalhe |
|---|---|
| busca filtrada | Consultas por chave de partição resolvem para uma busca em diretório mais um único scan sequencial de um bloco contíguo — recall 1,0 no caminho exato (D≤384; D=768 lê 0,999–0,9995 em empates de ordem de redução, zero erros genuínos). Sobre um subconjunto contíguo idêntico, este scan empata com o FAISS bruto — o ganho é de layout, não de kernel. |
| persistência | Escritas com WAL, snapshots MVCC, segmentos selados. save() confirma atomicamente; open_collection() restaura os dados, o ajuste aplicado e o espaço de embeddings. |
| modelo temporal | Upserts versionados: um id existente recebe uma nova versão visível que supersede a anterior — nunca uma linha duplicada. Tombstones ocultam linhas deletadas imediatamente; a compactação as remove fisicamente. |
| embeddings | Agnóstico a embeddings. Traga seus próprios vetores ou anexe um EmbeddingProvider / CallableEmbedder. Um embedder bigram no dispositivo está incluído — lexical, in-process, sem download de modelo. |
| plataformas | macOS arm64 · Linux x86_64 / arm64 · Windows via WSL2. |
| licença | SDK público Apache-2.0 no PyPI (pip install telys) mais um runtime on-device assinado e licenciado, instalado por telys login. Beta público. |
| latência medida | p50/p95 reportados por seletividade com recall 1,0, thread única, in-process, em rig M4 Max divulgado — com amostras brutas e o script. Veja a página de benchmarks. |
Uma fachada pública fina sobre um runtime assinado.
O SDK público não contém implementação de engine. Ele se comunica com o runtime por meio de uma única junção imutável — RuntimeHandle — e o runtime mantém seus hot loops em kernels Mojo SIMD: um hot path zero-Python dentro do seu 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
As fachadas Telys e Collection, Eq e scope_key, as interfaces EmbeddingProvider e Tuner, um carregador de runtime e a CLI telys. Um guarda de release verifica que nenhum código-fonte da engine é incluído no wheel público.
telys login o instala
Um único login provisiona uma licença de dispositivo gratuita e obtém o runtime assinado; assinatura e licença são reverificadas offline. O runtime contém o índice de partições, MVCC, compactação e IVF — e é obrigatório para execução.
Partições são contíguas
O diretório mapeia uma chave de partição ao seu bloco; as linhas de cada partição são armazenadas de forma contígua. Uma consulta com escopo é uma única varredura sequencial — não um scatter por um índice que ignora suas chaves.
O tempo é o modelo de dados.
Um vetor mais um blob de metadados não é uma memória de agente. O modelo de memória atribui a cada fato uma janela de validade, uma cadeia de supersessão explícita e uma visão as_of que reconstrói o que era conhecido em um ponto no tempo real. É apresentado aqui pelo que é: a direção especificada, com sua maquinaria de armazenamento já em produção.
Fatos são válidos em intervalos
Uma memória carrega uma janela [valid_from, valid_to) no tempo real. Uma contradição fecha a janela antiga em vez de destruir a linha — presente-ou-ausente não é suficiente para um agente.
Sem sobrescrita silenciosa
Um fato corretivo aponta para o fato que substitui. A cadeia é explícita e reconstituível: o que o agente acreditava, e quando deixou de acreditar, é uma consulta.
O que era conhecido em T
Uma visão as_of reconstrói exatamente as memórias válidas no tempo real T sob um dado snapshot MVCC — uma recuperação reproduzível e auditável após o fato.
Spec, rotulado como spec.
remember, recall e as_of são definidos no rascunho MEMORY-SEMANTICS — são a direção, não a referência de API em produção. Eles se traduzem em maquinaria que já está em produção: atualizações versionadas, supersessão, tombstones e snapshots MVCC.
Leia como funciona- add / upsert — um id existente torna-se uma nova versão visível, nunca uma linha duplicada
- search / search_text — filtros where=, planos explain, pisos target_recall
- delete — tombstones: ocultos das leituras imediatamente, removidos na compactação
- compact / build_ivf — manutenção de segmentos; IVF por partição para partições superdimensionadas
- snapshot / save / stats — visões de leitura MVCC, save durável atômico, reabertura
- Supersessão MVCC — cada atualização supersede seu predecessor; nada é sobrescrito silenciosamente