Telys — on-device memory

telys

Telys 的公共 SDK——嵌入式、设备端记忆与检索。进程内运行，查询时无需往返云端。

此软件包包含完整的面向开发者的接口：Telys/Collection 门面、查询/筛选器类型、EmbeddingProvider 接口、Tuner/TuningPlan 接口、完整的 MCP 服务（telys/mcp.py——19 个工具，协议版本 2025-06-18，使用 stdio）、运行时加载器，以及 telys CLI。这些工具所驱动的数值内核（libame_kernel）是单独分发的、经签名的设备端运行时，通过 telys login 获取（免费社区许可证）——与面向托管或签名二进制后端的 MCP 服务采用相同的安排。

安装

作为 CLI 使用（推荐——环境隔离、位于 PATH 中，不绑定到某个 Python 版本）：

pipx install telys

telys login          # sign in → free device license + signed runtime; fully offline thereafter

作为库使用（在你自己的项目中 import telys）：

python -m venv .venv && . .venv/bin/activate
pip install telys

也可以直接运行 pip install --user telys，但 pip 可能会警告用户脚本目录不在 PATH 中（这是 macOS 上 --user 的一个问题）——pipx 可以完全避免此问题。运行时平台：macOS arm64、Linux x86_64/arm64（Windows：请在 WSL2 下运行）。

from telys import Telys
db = Telys("./memory")
col = db.create_collection("docs", dim=768, partition_by="tenant_id")   # dim is arbitrary — 384/768/1024/1536/3072…
col.add(vectors, ids=ids, metadata=metadata)          # bring your own vectors (embedding-agnostic, any dimension)
hits = col.search(qvec, where={"tenant_id": "acme"}, top_k=10, explain=True)

运行时是执行所必需的；嵌入器是可选的——col.add(vectors, …) 和 col.add_texts(…) 都需要运行时，但只有 *_texts 需要嵌入器（可通过 telys.embedding.CallableEmbedder 使用你自己的嵌入器，或使用设备端 bigram 嵌入器）。

本地开发时，请将运行时作为软件包安装，而不是通过 CLI 安装：

pip install "telys[runtime]"   # or: pip install telys-runtime

MCP 服务

telys mcp 会通过标准输入/输出将 Telys 作为 Model Context Protocol 服务运行，向任何 MCP 客户端（Claude Desktop/Code、Cursor、Codex、Qwen Code 等）提供 19 个工具——涵盖完整的记忆功能（CRUD、筛选查询、词法搜索、压缩 / IVF / 调优，以及仓库自动索引器）。 所有操作均在本地离线进行。查看信息（initialize/tools/list）无需凭据；执行记忆工具则需要一次性免费运行 telys login（设备授权，免费社区计划）——此后即可完全离线运行，客户端配置中无需 API 密钥。

pipx install telys
telys login            # free device license + signed on-device runtime
telys runtime verify   # confirm the runtime the tools drive is present
telys mcp              # serve JSON-RPC 2.0 (protocol 2025-06-18) on stdin/stdout

你很少需要手动启动它——telys mcp install 会将服务条目写入你的客户端；也可以自行将此代码块添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "telys": {
      "command": "telys",
      "args": ["mcp"]
    }
  }
}

注册表：官方 MCP 注册表中的 io.github.thyn-ai/telys。服务源代码：packages/telys-sdk/telys/mcp.py。 MCP 文档：docs.telys.ai/mcp。

工具	功能	必需参数
telys_search	对记忆集合进行语义与词法搜索	collection、query
telys_add	添加文本文档（若集合不存在则自动创建）	collection、texts
telys_create_collection	创建集合（预先确定名称和分区键）	name
telys_list_collections	列出活动存储中的已保存集合	—
telys_stats	查看一个集合的行数和索引状态	collection
telys_upsert	按 ID 添加或替换行（幂等写入）	collection、texts、ids
telys_update	重新嵌入或替换已有 ID（严格模式：必须提供 ID）	collection、texts、ids
telys_delete	按 ID 将行标记为删除	collection、ids
telys_ids	列出有效的外部 ID，可按 where 限定范围	collection
telys_count	统计有效行数，可按 where 限定范围	collection
telys_get	按 ID 精确查找行（重新读取仓库源代码片段）	collection、ids
telys_search_lexical	在设备上进行 BM25 关键词搜索	collection、query
telys_compact	清除删除标记，将增量合并到基础布局	collection
telys_build_ivf	构建每个分区的 IVF 索引（按召回率下限校准）	collection
telys_build_lexical	拟合 BM25 词法索引	collection
telys_tune	生成（并可选择应用）调优计划	collection
telys_index_repo	遍历、分块并导入仓库，后续增量刷新	—
telys_repo_search	搜索自动索引的仓库（每次先重新索引，始终保持最新）	query
telys_workspace_info	报告已配置的工作区、repo_id 和文件数	—

每个工具都附带详细说明（功能、适用场景、带默认值的参数和故障模式）以及静态 MCP 注释（readOnlyHint / destructiveHint / idempotentHint / openWorldHint）——所有工具的 openWorldHint: false：该服务不会发出网络请求。列出工具无需凭据，也无需运行时：initialize 和 tools/list 会从静态工具注册表返回结果；只有实际调用工具时才会延迟加载签名运行时。

文档

完整文档请访问 docs.telys.ai：

• 快速入门：创建你的第一个集合
• 处理数据 — 添加、更新或插入、搜索、筛选、快照
• 嵌入 — 内置词法嵌入 + 通过 CallableEmbedder 使用自定义嵌入器
• CLI 参考 · MCP 集成 · 自托管
• SDK API 索引

链接

• 网站：telys.ai · 定价：telys.ai/pricing
• 账户与账单：accounts.thyn.ai
• 文档：docs.telys.ai · PyPI：pypi.org/project/telys