引擎

单一引擎，根植于目录，链入您的进程。

Telys 是面向 AI 智能体的嵌入式记忆与检索引擎。由于引擎掌控物理布局，nearest-neighbours-where-key-equals-x 解析为目录查找加对单个连续块的顺序扫描——在您的进程内完成，查询时无任何外部调用。

02 SDK 接口

公共 API 是一个门面：引擎持有具名集合，每个集合是一个带外部 id、元数据驱动分区键与过滤列的过滤向量索引，并具有明确的 add / upsert / delete 语义。

create + ingest
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

数据摄入是显式的。add 在 id 已存在时抛出异常；upsert 在 MVCC 下为已有 id 创建新的可见版本——引擎不会为同一逻辑 id 保留两行物理数据。

query
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)

每次查询均接受列式 where 过滤，并可返回 explain 计划，说明实际采用的物理策略。target_recall 设定规划器必须满足的召回率下限；复合范围通过 scope_key 构建单一物理键进行分区。

maintain + persist
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

维护操作是接口的一部分。删除立即写入墓碑，并在压缩时物理移除；IVF 按分区构建，仅在分区超出精确路径容量时触发；save 是原子操作，重新打开时可恢复数据、已应用的调优参数及嵌入空间。

03 能力规格
能力详情
过滤搜索nearest-neighbors-where-key-equals-x 解析为目录查找加对连续块的单次顺序扫描——精确路径上 recall 1.0（D≤384；D=768 在归约顺序平局时读取 0.999–0.9995，零真实漏召）。在相同连续子集上，此扫描与原始 FAISS 持平，优势来自布局而非内核。非键过滤降级为 scatter-gather，explain 计划会明确说明。
持久化WAL 支持的写入、MVCC 快照、封存段。save() 原子提交；open_collection() 恢复数据、已应用的调优参数及嵌入空间。
时态模型版本化 upsert：已有 id 获得新的可见版本以取代旧版本——不产生重复行。墓碑立即隐藏已删除行；压缩时物理移除。
嵌入向量与嵌入模型无关。可自带向量，或挂载 EmbeddingProvider / CallableEmbedder。内置设备端二元组嵌入器——词法级别，进程内运行，无需下载模型。
平台macOS arm64 · Linux x86_64 / arm64 · Windows（WSL2）。
许可证发布于 PyPI 的 Apache-2.0 公共 SDK（pip install telys），加上通过 telys login 安装的已签名、已授权设备端运行时。公开测试版。
实测延迟按选择率在 recall 1.0 下报告 p50/p95，单线程、进程内，在已披露的 M4 Max 测试机上测量——附原始样本与脚本。详见基准测试页面。
04 架构

一层轻薄的公开外观，覆于已签名的运行时之上。

公开 SDK 不含任何引擎实现。它通过唯一的冻结接缝——RuntimeHandle——与运行时通信，运行时将热循环保留在 Mojo SIMD 内核中：在你的 Python 进程内，实现零 Python 热路径。

call path
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 scope
SDK 外观层

Telys — Apache-2.0

Telys 与 Collection 外观层、Eq 与 scope_key、EmbeddingProvider 与 Tuner 接口、运行时加载器，以及 telys CLI。发布守卫确保引擎源码永不随公开包分发。

已签名运行时

telys login 完成安装

单次登录即可获取免费设备许可证并拉取已签名运行时；签名与许可证支持离线重验。运行时承载分区索引、MVCC、压缩与 IVF——执行时不可或缺。

物理布局

分区连续存储

目录将分区键映射至其数据块；每个分区的行连续存储。范围查询是一次顺序扫描——而非在无视你的键的索引上散乱跳转。

05 内存模型

时间即数据模型。

向量加元数据块，并不构成智能体记忆。内存模型为每条事实赋予有效时间窗口、显式的取代链，以及 as_of 视图——可重建在某一世界时间点上已知的内容。此处如实呈现：这是既定方向，其存储机制已在底层随版本交付。

有效时间窗口

事实在区间内有效

一条记忆在世界时间上携带 [valid_from, valid_to) 窗口。矛盾发生时关闭旧窗口，而非删除行——对智能体而言，存在与否远远不够。

取代链

无静默覆写

修正事实指向其所替代的事实。链条显式且可重建：智能体曾相信什么、何时停止相信，均可查询。

as_of 重建

T 时刻的已知状态

as_of 视图在给定 MVCC 快照下，精确重建世界时间 T 时有效的记忆——召回结果可复现、可事后审计。

规范，标注为规范。

remember、recall 与 as_of 定义于 MEMORY-SEMANTICS 草案——它们代表方向，而非已交付的 API 参考。它们落地于今日已交付的机制之上：版本化更新、取代、墓碑标记与 MVCC 快照。

阅读工作原理
已在 0.1.0b4 中交付
  • add / upsert — 已有 id 生成新的可见版本，而非重复行
  • search / search_text — where= 过滤器、explain 执行计划、target_recall 下限
  • delete — 墓碑标记：立即对读操作隐藏，压缩时丢弃
  • compact / build_ivf — 段维护；针对超大分区的逐分区 IVF
  • snapshot / save / stats — MVCC 读视图、原子持久化保存、重新打开
  • MVCC 取代 — 每次更新取代其前驱；无任何静默覆写